# 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

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

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

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