# knowledge-base-mcp

An [MCP](https://modelcontextprotocol.io) 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](docs/specs/knowledge-base-store.md) for the design and [docs/adrs/](docs/adrs/) for why things are the way they are.

## Setup

```bash
uv sync
```

## Run

```bash
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](https://github.com/modelcontextprotocol/inspector):

```bash
uv run mcp dev knowledge_base_mcp/server.py
```

## Test

```bash
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

```bash
uv run ruff check .
uv run pyright
```