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.

Related MCP server: mcp-docs

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

Resources

Knowledge Routing

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