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.8.0. 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.

In the table below, imports means extracted specifiers. Incoming import relations additionally resolve project-local declarations or paths: JS/TS, Python, Java/Kotlin, C#, PHP, Go and Rust, C/C++ headers, and supported LWC virtual imports. Ruby retains stem matching. Ambiguities and unsupported conventions remain visible limitations; see module reference coverage.

Adapter	Files	Indexed constructs
TypeScript / JavaScript / LWC	.ts, .tsx, .mts, .cts, .js, .jsx, .mjs, .cjs, .js-meta.xml	Classes, functions, methods, tests, routes, imports, calls, LWC decorators and component targets.
Java	.java	Classes, interfaces, enums, records, methods, Javadoc, JUnit markers, Spring routes, imports.
Kotlin	.kt, .kts	Classes, objects and companions, top-level/member/extension functions, properties, KDoc, JUnit/Kotest markers, Spring and literal Ktor routes.
Apex	.cls, .trigger	Classes, methods, tests, REST resources, trigger events, and static SOQL/SOSL object references.
Salesforce metadata	.object-meta.xml, .field-meta.xml, .validationRule-meta.xml, .flow-meta.xml, .permissionset-meta.xml	SFDX objects, fields, validation rules, flows, permission sets, formulas, calls, and Apex-compatible database references.
C#	.cs	Namespaces, types, methods, properties, XML docs, test attributes, ASP.NET controller and minimal-API routes; nested quoted strings inside interpolations are masked without losing following code.
Go	.go	Functions, receiver methods, structs/interfaces, Go doc comments, tests, imports, and common router calls.
Rust	.rs	Functions, types, traits, modules, impl methods, tests, imports, and macro_rules! names.
PHP	.php	Namespaces, types, functions/methods, PHPUnit markers, Laravel/Symfony routes, configuration and database references; HTML outside PHP tags is inert.
C	.c	Function definitions including pointer-return forms, doc comments, and includes.
C++	.cpp, .cc, .cxx, .h, .hpp, .hh	Functions, constructors, classes/structs, namespaces, qualified methods, doc comments, and includes.
Python	.py, .pyi	Indentation-aware modules, classes, nested functions/methods, docstrings, decorators, tests, FastAPI/Flask/Django routes, imports, calls, configuration and database references.
Ruby	.rb, .rake	Keyword-delimited classes/modules/methods, RDoc comments, RSpec/Minitest markers, Rails/Sinatra routes, imports, configuration and explicit database references.

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.

Interpreting module references

Use knowledge_code action="references" with the indexed module's symbol_id to retrieve import edges. The adapter's imports list records source specifiers; a returned import relation is the resolver's connection to a module in this project. JS/TS uses unambiguous relative paths, supported extension substitutions, and declared paths/baseUrl from the nearest tsconfig.json or jsconfig.json, including one local extends level. Python resolves absolute dotted names from both the repository root and the importing file's directory, so src/cli.py can import its sibling src/orders_cli.py. Package __init__.py and relative imports are supported; conflicting candidates remain unresolved. A verified regular-package chain also supplies Python's source root. Java/Kotlin/PHP use declared qualified names; C# namespaces and Go package directories can identify several contributing files. Go uses go.mod identities and nested module boundaries when available. Known manifests are checked on reference queries; newly added nested manifests require knowledge_code action="update" path="<directory>/go.mod" or an index rebuild. Projects without discovered Go manifests retain suffix matching for compatibility. C/C++ links the included header, and Rust resolves supported crate/module paths. LWC can link Apex methods, schema declarations and local component bundles. These static rules do not execute build tools or resolve arbitrary external packages. Ruby and custom adapters without a resolver retain stem matching, including its false positives and missing load-path checks. An empty reference list does not prove that a module is unused. Inspect the extracted specifier and use a qualified symbol lookup or read the source when an import edge is missing; treat heuristic edges as candidates to verify. See the import resolution contract for supported cases and limitations.

When a knowledge claim explains code, record its indexed code://repo/...#symbol-... resource as the Evidence IR target.codeResourceUri. Synthesis then places a direct code link and line range on the wiki page if anchor capture succeeds; claims without code evidence do not receive a fabricated link. The stored hash and parser version support drift checks. See the workflow and verified examples.

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.8.0

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.8.0 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.8.0",
        "--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.8.0

Claude Code writes the shared project entry to .mcp.json and launches the local server in project context. Use claude mcp list to verify the connection. The command shape and project scope follow the official Claude Code MCP guide.

Other IDE and terminal clients

For a client that explicitly guarantees one stdio process per project with the project as cwd, the minimal server configuration remains:

{
  "mcpServers": {
    "knowledge-rail": {
      "command": "npx",
      "args": ["-y", "knowledge-rail@2.8.0"]
    }
  }
}

If the client does not guarantee that cwd contract, pass an absolute --root in its project-scoped configuration. Do not place a repository-specific absolute root in a global configuration.

The workspace precedence is explicit --root; one unambiguous legacy MCP Root; WIKI_ROOT for compatibility; the nearest existing KnowledgeRail marker; the nearest project/VCS marker; finally a safe non-empty cwd. Filesystem roots, the user home, package caches, and known Claude/Cursor application directories fail closed.

Inspect the exact choice without starting MCP:

npx -y knowledge-rail@2.8.0 doctor
npx -y knowledge-rail@2.8.0 doctor --root /absolute/project/path

The command prints the canonical root and its resolution source, or exits non-zero with corrective guidance.

Claude Desktop and other context-free desktop chats

A desktop chat does not open a filesystem folder, so it cannot safely infer a project from its process cwd. The preferred installation is the self-contained MCP Bundle (.mcpb): it avoids npm/network resolution on every Claude launch and follows Claude Desktop's current local-extension path.

For a source/release checkout, build the deterministic bundle:

npm run mcpb:build

Then install artifacts/knowledge-rail-2.8.0.mcpb from Claude Desktop → Settings → Extensions → Advanced settings → Install Extension. The bundle contains the compiled server and its production dependencies, starts the desktop adapter directly, and does not require a project path. See Anthropic's local MCP server guide and the MCP Bundle specification.

The manual local-development configuration remains available for hosts that have not adopted MCP Bundles:

{
  "mcpServers": {
    "knowledge-rail": {
      "command": "npx",
      "args": ["-y", "knowledge-rail@2.8.0", "desktop"]
    }
  }
}

For a source checkout, use node /absolute/path/to/KnowledgeRail/dist/index.js desktop. The adapter discovers or starts the protected loopback gateway automatically and exposes knowledge_workspace in addition to the eight domain tools.

In a new chat, ask KnowledgeRail to list workspaces, choose one entry, and confirm read or write access. The returned opaque binding belongs to that conversation and must accompany its later domain calls. For compatibility with desktop hosts that expose only textual tool results, knowledge_workspace returns the same binding in both its declared structured output and a workspace_binding: ... text line. Two chats can select different customers/projects concurrently. Start a new chat when changing customer workspace: filesystem access is isolated, but information already present in conversation history cannot be removed by the server.

Projects opened successfully by an IDE/terminal are added to the local catalog automatically without changing their clean eight-tool workflow. Operators can also manage catalog metadata locally:

npx -y knowledge-rail@2.8.0 workspace list
npx -y knowledge-rail@2.8.0 workspace register
npx -y knowledge-rail@2.8.0 workspace register /absolute/project/path
npx -y knowledge-rail@2.8.0 workspace unregister ws_example

Registration never copies, uploads, scans the disk, or deletes project files. workspace register without a path discovers only upward from cwd.

Local self-hosted HTTP gateway

Start one gateway for many concurrent local clients and workspaces:

npx -y knowledge-rail@2.8.0 --transport http

The default endpoint is http://127.0.0.1:3333/mcp; liveness only is available at /healthz. MCP requests require the random credential stored in the OS-protected per-user KnowledgeRail state directory. The desktop adapter reads it automatically, so it never belongs in project configuration or a repository.

The gateway does not have a current root. Every filesystem-capable request must resolve a valid opaque binding before the first path access. Bindings are scoped, expiring, revocable, and invalidated on gateway restart. Resource links are workspace-qualified and revalidated when read.

The shipped gateway deliberately rejects non-loopback binding. It is local self-hosting, not public OAuth or hostile-user multi-tenancy. claude.ai and Claude remote custom connectors cannot use a localhost endpoint because those connections originate from the provider cloud; Claude Desktop local MCP uses the desktop adapter above.

Client context	Entry point	Workspace behavior	Tool catalog
Cursor	default stdio	explicit project-scoped ${workspaceFolder} binding	8 domain tools
Claude Code, cwd-aware IDE or terminal agent	default stdio	automatic from a project process cwd or one legacy Root	8 domain tools
Claude Desktop/local desktop chat	desktop	user chooses an approved catalog entry per chat	knowledge_workspace + 8 domain tools
Generic trusted local HTTP client	--transport http	binding supplied on every filesystem-capable request	knowledge_workspace + 8 domain tools

Platform state locations are %LOCALAPPDATA%\KnowledgeRail on Windows, ~/Library/Application Support/KnowledgeRail on macOS, and ${XDG_STATE_HOME:-~/.local/state}/knowledge-rail on Linux. Set KNOWLEDGE_RAIL_STATE_DIR only for controlled testing or an intentional custom local installation. Docker/devcontainers and WSL have separate filesystems and therefore separate catalogs unless their state and project mounts are explicitly shared.

Operating-system notes

• Windows: if an MCP host does not resolve npm command shims, use "command": "npx.cmd"; escape backslashes in JSON paths (C:\\Tools\\KnowledgeRail\\dist\\index.js). PowerShell operator commands use the same CLI arguments shown above. Drive-letter case and junction/real paths are canonicalized before binding.
• macOS: the state directory is inside Library/Application Support, not the opened repository.
• Linux: XDG_STATE_HOME is honored. No browser sandbox configuration is required.
• WSL and containers: run the MCP process in the same filesystem environment as the project. A Windows Claude Desktop process and a WSL-only localhost/state directory are distinct unless an explicit bridge is configured.

Agent workflow

KnowledgeRail exposes eight stable tools. Agents choose a domain directly and use its mode or action; no menu, profile, session scope, or legacy alias is required.

Tool	Operations
knowledge_context	task, bounded page list, query-required search, and graph.
knowledge_page	Read, write, edit, move, delete, and append the durable log.
knowledge_files	List, read, and normalize controlled source files.
knowledge_ingest	start, next, apply_claims, record_segment, source_status, evidence_status, finalize, report, and recovery actions.
knowledge_code	Maintain and query deterministic code evidence.
knowledge_document_context	Plan any document profile and compile section-specific evidence.
knowledge_document	Write and review Markdown deliverables.
knowledge_admin	Initialize, report status, verify/rebuild checkpoints, lint, detect code-evidence drift, and migrate KnowledgeRail data.

Every successful operation returns a machine-readable state and either one nextAction or null. nextAction identifies the next tool, action, required arguments, and safe suggested arguments. Optional guidance and resultText complete the shared output envelope. Clients that only render text also receive concise Next: and Guidance: lines when applicable.

How it works

KnowledgeRail separates context retrieval, durable memory, source ingestion, code evidence, and document production so an agent can enter at the operation it needs without learning an internal menu or carrying session state:

task objective
    ↓
knowledge_context ──→ ranked evidence links + coverage gaps
    ↓                              ↓
resources/read              bounded widening, if needed
    ↓
agent reasoning and project work
    ├──→ knowledge_page / knowledge_code
    ├──→ knowledge_ingest ──→ Evidence IR ──→ canonical wiki
    └──→ knowledge_document_context ──→ knowledge_document

For a normal task, the agent calls knowledge_context mode="task" with a concrete objective. KnowledgeRail searches the canonical wiki and its derived lexical, graph, passage, code, and optional semantic indexes, ranks the available evidence, and returns a compact context envelope. Large page bodies are exposed as knowledge-rail:// links instead of being inserted wholesale into the response; the client reads only the selected passages. Coverage is assessed over both the full retrieved candidate set and the smaller display set. The full pool distinguishes truly missing evidence from evidence that is merely budget_limited; progressive widening stops only when the evidence returned to the model is sufficient. If the token budget alone excluded relevant evidence, the returned nextAction proposes one bounded widening step. Missing, stale, contradictory, or unresolved evidence remains an explicit gap and is never filled by guessing.

Decision pages are ordinary canonical wiki knowledge and already participate in that retrieval. Each page stays bounded to one coherent flow, component, or project context. Candidate prior choices are exposed in the structured decisions and changeImpact.decisions fields, but the agent inspects their metadata and materializes only a resource link that actually matches the task—normally the selected passage, or that single bounded page when no reliable passage exists. Detailed retrieval safeguards are included in the task response only when decision candidates exist, avoiding a large fixed instruction cost for unrelated sessions. The agent never loads every decision page, and the absence of a matching decision is normal rather than a coverage gap. When the human-model discussion reaches a clearly accepted, durable project choice, the agent closes the loop at task completion: it rereads and reuses the decision page for the same context (or creates a separate page for a different one), updates the current choice and concise rationale, appends a dated history note describing what changed and why, and writes one DECISION log entry. Proposals, unresolved options, incidental implementation details, raw conversation, hidden chain-of-thought, and secrets are never decision memory. The page remains valid if the independent log append must be retried. No decision means no write; an analysis-only or otherwise unauthorized session reports the proposed update instead of mutating the wiki.