knowledge-base-mcp

An MCP server exposing a knowledge base to LLM clients through tools, resources, and prompts.

Layout

knowledge_base_mcp/
├── __init__.py
├── __main__.py         # `python -m knowledge_base_mcp`
├── context.py            # AppContext + app_lifespan (constructs the store)
├── server.py               # FastMCP instance, CLI entry point (main)
├── tools.py                  # @mcp.tool() definitions (add_document, search)
├── resources.py                 # @mcp.resource() definitions (get_document)
├── prompts.py                      # @mcp.prompt() definitions
└── store/                            # pluggable persistence layer
    ├── __init__.py                      # create_store() factory
    ├── base.py                            # KnowledgeBaseStore Protocol
    └── sqlite.py                            # SQLite reference implementation
tests/
├── conftest.py       # shared anyio_backend fixture
├── unit/               # SqliteKnowledgeBaseStore, in isolation
├── integration/          # tools/resources via an in-memory MCP session
└── e2e/                     # real subprocess over stdio (not in the default run)

See docs/specs/knowledge-base-store.md for the design and docs/adrs/ for why things are the way they are.

Setup

uv sync

Run

uv run knowledge-base-mcp                      # stdio transport (default)
uv run knowledge-base-mcp --transport streamable-http --port 8000

Or inspect it interactively with the MCP Inspector:

uv run mcp dev knowledge_base_mcp/server.py

Test

uv run pytest                      # unit + integration, gated at 90% coverage
uv run pytest tests/e2e --no-cov     # e2e: spawns the real server subprocess over stdio

uv run pytest fails outright if coverage drops below 90% (--cov-fail-under=90 in pyproject.toml). tests/e2e is excluded from that default run (see testpaths) since it's slower and its coverage isn't collected in-process.

Lint / type-check

uv run ruff check .
uv run pyright