Skip to content

README.md

Latest commit

 

History

History
162 lines (120 loc) · 4.63 KB

README.md

File metadata and controls

162 lines (120 loc) · 4.63 KB

Knowledge MCP

An MCP server that provides structured access to documentation with semantic search, model-authored articles, and a metadata system. Built on FastMCP, SQLite + sqlite-vec, and the nomic-embed-text-v1.5 embedding model.

Installation

With pipx (recommended)

pipx install https://github.com/jameseperry/KnowledgeDB.git

Or from a local clone:

pipx install https://github.com/jameseperry/KnowledgeDB.git
cd Knowledge-MCP
pipx install .

This installs two commands:

  • knowledge-mcp — the MCP server
  • knowledge-index — CLI for indexing and search

AMD GPU support (ROCm)

By default, the sentence-transformers dependency pulls in a CPU-only PyTorch build. To use AMD GPUs for local embedding generation, install PyTorch with ROCm support before installing Knowledge MCP:

# Create the pipx environment first, then inject the ROCm torch build
pipx install .
pipx inject knowledge-mcp torch torchvision --pip-args="--index-url https://download.pytorch.org/whl/rocm6.3"

Note: Check pytorch.org/get-started/locally for the latest ROCm wheel URL matching your driver version.

Alternatively, you can skip local GPU inference entirely and use a remote embedding API (see Remote embeddings below).

Configuration

Create a knowledge_config.json file:

{
    "knowledge_bases": [
        {"label": "my_docs", "path": "/path/to/docs"}
    ],
    "extensions": [".md", ".txt", ".rst"],
    "embedding": {
        "backend": "local",
        "model_name": "nomic-ai/nomic-embed-text-v1.5",
        "dimensions": 768
    }
}

Each knowledge base is a directory containing documents. The server creates a knowledge.db SQLite database and an articles/ directory inside each KB path.

Remote embeddings

To use a remote embedding API instead of local inference (no GPU required):

{
    "knowledge_bases": [
        {"label": "my_docs", "path": "/path/to/docs"}
    ],
    "embedding": {
        "backend": "remote",
        "model_name": "Nomic-Embed-Text-v1.5",
        "dimensions": 768,
        "api_url": "https://your-embedding-api/v1/embeddings",
        "batch_size": 128,
        "max_concurrent": 4
    }
}

The remote backend posts to any OpenAI-compatible embeddings endpoint. Set ANTHROPIC_CUSTOM_HEADERS for any extra headers (comma-separated key:value pairs).

Indexing

Build the search index before using the server:

knowledge-index index --config knowledge_config.json

Flags:

  • --full — re-index all files (default: incremental, only changed files)
  • --kb LABEL — index a single knowledge base
  • -v / --verbose — show per-file details

Other subcommands:

knowledge-index search "your query" --config knowledge_config.json
knowledge-index files --config knowledge_config.json

MCP server

VS Code (Copilot)

Add to .vscode/mcp.json:

{
    "servers": {
        "kb": {
            "type": "stdio",
            "command": "knowledge-mcp",
            "args": ["--config", "/absolute/path/to/knowledge_config.json"]
        }
    }
}

If you installed with pipx, the knowledge-mcp command is on your PATH. Otherwise use the full path (e.g. ~/.local/pipx/venvs/knowledge-mcp/bin/knowledge-mcp).

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
    "mcpServers": {
        "knowledge": {
            "command": "knowledge-mcp",
            "args": ["--config", "/absolute/path/to/knowledge_config.json"]
        }
    }
}

Transport options

knowledge-mcp --config knowledge_config.json                          # stdio (default)
knowledge-mcp --config knowledge_config.json --transport http         # streamable HTTP
knowledge-mcp --config knowledge_config.json --transport sse          # SSE

HTTP/SSE transports accept --host (default 127.0.0.1) and --port (default 8766).

Tools

Tool Description
browse List knowledge bases or directory contents
outline Heading hierarchy for a document
read Read a file or a specific section
search Semantic search across indexed content
grep Exact text or regex search
list_docs Browse document metadata by tag or root path
set_metadata Annotate documents/sections with summaries and tags
write_article Create or update model-authored articles
delete_article Remove an article
index_status Per-KB index statistics