# KernelMind MCP

**Evidence-based Linux kernel engineering for AI agents — citations, not hallucinations.**

[![License: GPL v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
[![MCP Compatible](https://img.shields.io/badge/MCP-2.0.0-green.svg)](https://modelcontextprotocol.io)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

KernelMind MCP is a [Model Context Protocol](https://modelcontextprotocol.io) server
that turns the public corpus of Linux kernel knowledge — git history, LKML /
lore.kernel.org, Patchwork, and `Documentation/` — into a queryable, evidence-ranked
knowledge platform for AI coding and planning agents.

Every tool response carries an explicit evidence chain: which commit, which
mailing-list thread, which patch state transition supports the conclusion — plus
explicit *assumptions* and *contradictions* when the evidence is incomplete.
Performance claims are never fabricated; the system flags them
`hardware_validation_required` instead.

## Why

LLMs hallucinate kernel facts — invented signatures, misremembered locking rules,
APIs removed years ago cited as current. KernelMind's contract:

1. Index primary sources, kept current by **incremental** sync (never full rebuild)
2. Fuse dense vectors + BM25 + PostgreSQL full-text via Reciprocal Rank Fusion (k=60)
3. Rank by a fixed evidence hierarchy: commit messages > LKML consensus >
   Documentation/ > maintainer comments > accepted patches > LWN > source code >
   rejected RFCs > vendor trees
4. Return `evidence_sources`, `assumptions`, `contradictions`, and
   `hardware_validation_required` on every engineering conclusion

**Subsystem-agnostic** by design: works identically on mainline, stable, linux-next,
and vendor trees.

## Features & Registered Tools

KernelMind MCP provides 16 specialized, evidence-first engineering tools across 5 categories:

| Category | Available MCP Tools | Description |
|---|---|---|
| **Source Code** | `search_kernel_code`, `lookup_symbol` | Search kernel C source code and lookup symbol definitions with AST tree-sitter chunking |
| **Git Intelligence** | `search_commits`, `get_commit_details`, `get_file_history`, `blame_line_range` | Inspect commit history, blame line ranges, and trace file evolution |
| **Patchwork & LKML** | `search_patches`, `get_patch_details`, `search_lkml`, `get_thread_details` | Query patch discussions, LKML thread consensus, and patch state transitions |
| **Research & Risk** | `analyze_patch_series`, `analyze_subsystem_risk` | Evaluate stability ratings, race/locking risk factors, and hardware validation requirements |
| **Documentation & LWN** | `search_docs`, `get_doc_details`, `search_lwn`, `get_lwn_article` | Search kernel `Documentation/` files and Linux Weekly News articles |

MCP **prompts** implement a 9-stage agent workflow: Knowledge Gathering →
Subsystem Understanding → Architecture Modeling → Maintainer Review →
Hypothesis Generation → Experiment Design → Implementation Planning →
Patch Review → Self-Critique.

## Architecture

```
AI Agent (Opencode / Claude Code / any MCP host)
      │  JSON-RPC 2.0 — stdio (default) or Streamable HTTP
      ▼
MCP Gateway (validation, auth, audit)
      ▼
Tools → Hybrid Search (Qdrant + BM25 + PG FTS, RRF)
      → EvidenceCorrelator (priority tiers, assumptions, contradictions)
      ▼
PostgreSQL · Qdrant · Neo4j · Redis · MinIO
      ▲
Incremental Sync (Celery): git delta · LKML/lore · Patchwork
(state-transition tracking across all 12 patch states) · Documentation/
```

Indexing is kernel-aware: tree-sitter C grammar chunks at function/struct/macro
granularity without splitting function bodies; subsystem attribution is parsed
from `MAINTAINERS` (longest-prefix match) — no hardcoded maps.

Details: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)

## Quick Start

```bash
git clone https://github.com/Reinazhard/kernelmind-mcp.git
cd kernelmind-mcp
cp .env.example .env       # set EMBEDDING_* and any overrides
docker compose up -d --build
curl http://localhost:8080/health
```

### Opencode (`opencode.json`)

```json
{
  "mcp": {
    "kernelmind": {
      "type": "local",
      "command": ["docker", "compose", "exec", "-T", "kernelmind-mcp",
                  ".venv/bin/python", "-m", "kernelmind.server", "--stdio"],
      "enabled": true
    }
  }
}
```

Any stdio MCP client uses the same command. For remote hosts, set
`KERNELMIND_TRANSPORT=streamable-http` and connect to `http://<host>:8080/mcp`.
See [docs/OPENCODE.md](docs/OPENCODE.md) and [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).

## Configuration

All config via environment variables (Pydantic, fail-fast at startup) —
see [`.env.example`](.env.example).

| Variable | Default | Purpose |
|---|---|---|
| `KERNELMIND_TRANSPORT` | `stdio` | `stdio` or `streamable-http` |
| `KERNELMIND_EMBEDDING_BASE_URL` / `KERNELMIND_EMBEDDING_API_KEY` / `KERNELMIND_EMBEDDING_MODEL` | — | Embedding provider (required) |
| `KERNELMIND_POSTGRES_DSN`, `KERNELMIND_QDRANT_URL`, `KERNELMIND_NEO4J_URI`, `KERNELMIND_REDIS_URL`, `KERNELMIND_S3_ENDPOINT` | compose defaults | Storage backends |
| `KERNELMIND_HOST` / `KERNELMIND_PORT` | `0.0.0.0` / `8080` | HTTP Server Bind Address |

## Project Status

Phase completion and known limitations: [docs/PROGRESS.md](docs/PROGRESS.md).
Available tool reference: [docs/TOOLS.md](docs/TOOLS.md).
Deployment guide: [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).

## License

GPL-2.0 — see [LICENSE](LICENSE).