KnowledgeRail

KnowledgeRail is a local-first MCP server that turns project documentation and source code into durable, evidence-backed context for AI agents.

It is designed for agents that need to understand, change, review, or document a codebase without loading the whole repository into the model context. Retrieval is bounded, provenance is preserved, missing evidence is reported explicitly, and difficult queries widen progressively instead of silently losing relevant information.

Current status: stable release 2.6.2. The server uses MCP SDK 2.x and protocol 2026-07-28. It supports explicitly bound or safely inferred local stdio, a self-hosted loopback HTTP gateway, and a local desktop-chat adapter. KnowledgeRail operates no hosted service and does not upload project data. See SELF_HOSTING.md.

What it provides

• Eight domain-oriented tools with validated actions and machine-readable next steps.
• Task-aware hybrid retrieval with lexical, graph, passage, and optional semantic evidence.
• Progressive widening with explicit coverage signals and GAP/unknown reporting.
• Complete source ingestion through bounded segments, a coverage ledger, and durable Evidence IR.
• A deterministic multi-language code index with symbol, reference, route, test, configuration, and database lookup.
• Incremental graph, retrieval, and semantic indexes stored beside the project wiki.
• Contract-driven Markdown deliverables with terminal review, content hashes, and optional caller-authored diagrams.
• Conservative migration of existing v1/v2/v3 wikis and pre-rebrand .llm-wiki metadata.
• Deterministic project binding through explicit Cursor workspace configuration, cwd-aware IDE processes, and terminal agents.
• A local HTTP gateway that keeps concurrent clients and projects isolated per request.
• A desktop-chat workspace catalog with opaque, expiring per-chat bindings.

KnowledgeRail does not call an LLM itself. The connected MCP client chooses and calls the tools. OCR and embeddings are optional external providers configured by the user.

Deterministic code-evidence languages

Code evidence is extracted locally without tree-sitter, native binaries, downloaded grammars, or runtime parser dependencies. Each file is owned by exactly one versioned adapter, so upgrading one language reparses only that language's files. Unsupported or deliberately skipped constructs remain visible through recorded raw-fallback demand rather than being assigned an unreliable anchor.

The extractors are intentionally conservative. LWC HTML templates, Java anonymous classes, dynamic Apex query object names, Rust macro expansion, PHP eval()/string callables and Blade/Twig templates, K&R C definitions, macro-generated C/C++ declarations, complex C++ operator/template metaprogramming, Python lambdas/dynamic definitions/metaclass-generated members, indirect or qualified decorator-generated routes, calls inside f-string interpolations, and notebooks are not guessed. Kotlin computed Ktor paths and string-named Kotest cases are not emitted independently. Salesforce metadata is limited to the explicit SFDX suffix roster; malformed XML falls back to a file module. Ruby metaprogramming, inferred ActiveRecord tables, individual RSpec it blocks, operator methods, and ambiguous plain command-form heredocs or regex literals remain best-effort or out of scope. Headers use the C++ superset adapter. Python uses a separate indentation engine with CPython-compatible tab stops; Ruby uses its own keyword-block engine. Qualified knowledge_code action="symbol" lookups treat ., #, ::, PHP namespace backslashes, and -> as equivalent separators, while returned names retain the language-native form. The pinned golden corpus contains 52 source files, 1,429 source lines, and 199 hand-labeled symbols across twelve language adapters; the mixed-repository benchmark adds two LWC files for 54 files and 1,446 lines overall. Its perfect in-corpus score is a deterministic regression guarantee, not a claim of universal parser accuracy. Code anchors are line-based: trailing-whitespace edits remain fresh, while formatting that inserts or removes lines is deliberately reported as drift because it shifts the cited range. knowledge_admin action="status" reports the extension histogram supplied with recorded grep fallbacks, allowing later language priorities to follow real repository demand.

Requirements

• Node.js 22.12.0 or newer
• npm
• macOS, Windows, or Linux

KnowledgeRail ships no browser or document renderer. Mermaid source remains ordinary Markdown and is rendered only by viewers that support it.

Quick start with npx

Run this from any directory inside the project in a terminal or another client that launches stdio servers with the project as its working directory:

npx -y knowledge-rail@2.6.2

No project path is needed when the MCP client guarantees a project-scoped process cwd or supplies one unambiguous legacy MCP Root. Cursor project setup is explicit because its global MCP process may be shared across windows.

The reviewed package is published to npm. Pin an exact version in persistent configurations; reserve @latest for one-time trials.

Install and run from source

From source

git clone https://github.com/Deviank88/KnowledgeRail.git
cd KnowledgeRail
npm ci
npm run build

Start it from any directory inside the project whose knowledge you want to manage:

cd /path/to/your-project
node /absolute/path/to/KnowledgeRail/dist/index.js

Cursor configuration

Run this once from the project root or any nested directory:

npx -y knowledge-rail@2.6.2 setup cursor

The command discovers the project upward and safely creates or merges .cursor/mcp.json. It preserves other MCP servers and pins an explicit ${workspaceFolder} binding. Re-running it is idempotent.

The equivalent manual project configuration is:

{
  "mcpServers": {
    "knowledge-rail": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "knowledge-rail@2.6.2",
        "--root",
        "${workspaceFolder}"
      ]
    }
  }
}

Keep this file at <project>/.cursor/mcp.json, not in the global ~/.cursor/mcp.json. Recent Cursor releases can reuse a global stdio MCP process whose cwd is the user home or an empty window, so global cwd-based project inference is not a supported bound-workspace configuration. Cursor documents type: "stdio", project configuration, and ${workspaceFolder} interpolation in its MCP guide.

For a source checkout, use the compiled entry point while retaining the explicit workspace root:

{
  "mcpServers": {
    "knowledge-rail": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/absolute/path/to/KnowledgeRail/dist/index.js",
        "--root",
        "${workspaceFolder}"
      ]
    }
  }
}

For a Cursor multi-root workspace, install one project configuration in every root that should expose KnowledgeRail. The server never selects the first open root silently.

Claude Code configuration

From the project, add KnowledgeRail at project scope:

claude mcp add --transport stdio --scope project knowledge-rail -- npx -y knowledge-rail@2.6.2

Read the full README on GitHub →