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.

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

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.

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. Available tool reference: docs/TOOLS.md. Deployment guide: docs/DEPLOYMENT.md.

License

GPL-2.0 — see LICENSE.