KernelMind MCP

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

KernelMind MCP is a Model Context Protocol 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.

Related MCP server: github-rag-mcp

Features & Registered Tools

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

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

Quick Start

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)

{
  "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 and docs/DEPLOYMENT.md.

Configuration

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

Project Status

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

License

GPL-2.0 — see LICENSE.