KnowledgeRail

<p align="center">
  <img src="https://cdn.jsdelivr.net/npm/knowledge-rail@2.6.0/assets/knowledge-rail-logo.png" alt="KnowledgeRail logo" width="180">
</p>

<h1 align="center">KnowledgeRail</h1>

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.0`. The server uses MCP SDK `2.x` and protocol `2026-07-28`. It supports path-free 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](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.
- Automatic per-process workspace binding for IDEs 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.

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

## 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 you opened in VS Code, Cursor, a terminal, or another context-aware coding client:

```bash
npx -y knowledge-rail@2.6.0
```

No project path is needed in the persistent MCP configuration. KnowledgeRail discovers the opened project independently for each process, so project X and project Y can be used at the same time by different agent sessions.

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

```bash
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:

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

## IDE, Cursor and terminal configuration

Use the standard `stdio` server shape once. Do not hard-code one repository:

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

For a source checkout, replace `knowledge-rail` with Node and the compiled entry point:

```json
{
  "mcpServers": {
    "knowledge-rail": {
      "command": "node",
      "args": ["/absolute/path/to/KnowledgeRail/dist/index.js"]
    }
  }
}
```

The workspace is resolved separately for every launched server with this precedence: 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 desktop-application directories fail closed. `--root <absolute-path>` remains an operator troubleshooting override, not normal configuration.

When a client has multiple open roots, its integration must launch KnowledgeRail with the active project as cwd (or expose one unambiguous legacy Root). KnowledgeRail never chooses the first root silently and never sends an IDE user through the desktop workspace selector.

## 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. Configure the local adapter once:

```json
{
  "mcpServers": {
    "knowledge-rail": {
      "command": "npx",
      "args": ["-y", "knowledge-rail@2.6.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