Knowledge MCP Server

A vendor-neutral Knowledge MCP server for Codex, OpenCode, Claude Code, Gemini CLI, and other MCP-compatible clients.

Overview

This server provides a stable MCP interface for knowledge retrieval across repositories. The MCP contract remains stable while storage, search, embedding, indexing, and transport implementations can be replaced independently.

Features

Stable MCP Contract v1: knowledge_search, knowledge_get, knowledge_list
Vendor-Neutral Architecture: Ports and adapters pattern
Hybrid Retrieval: Lexical (SQLite FTS) + Optional Semantic (Qdrant)
Docker Support: Multi-stage BuildKit builds, multi-platform (amd64/arm64)

Quick Start

Prerequisites

Python 3.12+
uv package manager
Docker (optional, for containerized deployment)

Local Development

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run the server (stdio mode)
uv run python -m knowledge_mcp

# Run with HTTP transport
TRANSPORT=http uv run python -m knowledge_mcp

Docker Deployment

# Build image
make docker-build

# Start container
make docker-up

# View logs
make docker-logs

# Stop container
make docker-down

Project Structure

knowledge-mcp/
├── src/knowledge_mcp/     # Main package
│   ├── __init__.py
│   ├── __main__.py        # CLI entrypoint
│   └── server.py          # Server implementation
├── tests/                 # Test suite
├── docs/                  # Documentation
│   ├── decisions/         # Architecture Decision Records
│   └── contracts/         # MCP contract definitions
├── Dockerfile
├── docker-compose.yml
├── Makefile
└── pyproject.toml

Architecture

The server follows the ports and adapters (hexagonal) architecture:

MCP / CLI / watcher entrypoints
               |
               v
       application services
               |
               v
         domain and ports
               ^
               |
  infrastructure adapters

Domain and application packages never import infrastructure, MCP SDK, or provider-specific types.

MCP Contract v1

Tools

Tool	Description
`knowledge_search`	Search knowledge with scope, filters, and limits
`knowledge_get`	Retrieve exact document or section by ID
`knowledge_list`	List documents with prefix and depth filtering

Resources

URI	Description
`knowledge://system/status`	Server status and health
`knowledge://documents/{document_id}`	Document content resource

Knowledge Routing

Mode	Use Case
`LOCAL_ONLY`	Explicit target, one repository, low architectural risk
`MCP_REPO`	Ambiguous location, multiple layers
`MCP_GLOBAL`	Cross-repository, architecture, security

Configuration

See .env.example for available configuration options.

Key Settings

TRANSPORT: stdio, http, or sse
KNOWLEDGE_ROOT: Path to knowledge sources
LEXICAL_PROVIDER: sqlite_fts (default), or disabled
SEMANTIC_PROVIDER: disabled (Phase 8: qdrant)

Development

Quality Gates

# Format check
uv run ruff format --check .

# Lint check
uv run ruff check .

# Type check
uv run pyright

# All checks
make test-ci

Phase Implementation

This project follows a phased implementation approach. See the implementation plan for details.

License

MIT

Knowledge MCP Server