knot

<div align="center"> <a href="https://glama.ai/mcp/servers/raultov/knot"> <img src="https://glama.ai/mcp/servers/raultov/knot/badges/card.svg" alt="knot MCP server" /> </a> </div>

knot is a high-performance codebase indexer that extracts structural and semantic information from source code, enabling AI agents to understand, analyze, and navigate large code repositories. Currently supports Java, Kotlin, TypeScript, JavaScript/Node.js, Rust, Python, Groovy, C/C++, C#, HTML, and CSS/SCSS, plus Build Systems (Maven pom.xml, Gradle build.gradle, Jenkins pipeline, Cargo.toml, MSBuild .csproj + Directory.Packages.props), Configuration Files (YAML, JSON, .properties — optional), Kubernetes + Helm (optional), and Cross-Repo Dependency Linking with full cross-language linking.

For recent release notes see CHANGELOG.md.

The indexer automatically builds:

• Vector Search Database (Qdrant) — semantic understanding via embeddings
• Graph Database (Neo4j) — architectural relationships via call graphs

This dual-database approach powers both:

• MCP (Model Context Protocol) Server — Exposes read-only tools (search, callers, explore, list_files, list_endpoints, repos, deps) to any LLM client (Claude, Gemini, ChatGPT, Cursor, etc.)
• CLI Tool — Standalone knot command for terminal and scripting environments

Knot in action

<div align="center"> <img src="demo-cli.gif" alt="knot CLI demo" width="80%">

CLI — instant reverse dependency lookup

</div> <div align="center"> <img src="demo-mcp.gif" alt="knot MCP demo" width="80%">

MCP — JSON-RPC protocol for AI agents

</div>

---

🧮 Token Efficiency — Measured, Not Claimed

An LLM agent exploring an unfamiliar codebase pays for every byte it reads. Without an index it greps and then reads whole files; with knot it receives a targeted answer. The difference was measured on three real indexed repositories across nine realistic exploration tasks:

| Repo | Lang | Task | knot tokens | Read-the-code tokens | Reduction | |------|------|------|------------:|---------------------:|----------:| | spring-ai | Java | discovery — how does the chat client run the advisor chain? | 677 | 12 262 | 94.5% | | spring-ai | Java | callers — who uses ToolCallingManager? | 3 352 | 43 707 | 92.3% | | spring-ai | Java | explore — structure of DefaultChatClient.java | 4 033 | 9 675 | 58.3% | | puppeteer | TypeScript | discovery — how is a CDP session created? | 389 | 4 706 | 91.7% | | puppeteer | TypeScript | callers — who calls createCDPSession? | 690 | 42 857 | 98.4% | | puppeteer | TypeScript | explore — structure of the Page API | 5 447 | 27 522 | 80.2% | | knot | Rust | discovery — how are call intents resolved? | 765 | 37 110 | 97.9% | | knot | Rust | callers — who calls format_references_result? | 152 | 18 929 | 99.2% | | knot | Rust | explore — structure of the graph query module | 4 761 | 28 281 | 83.2% | | TOTAL | — | 9 tasks | 20 266 | 225 049 | 91.0% |

≈ 11× fewer tokens for the same nine questions — 205 000 tokens saved, enough to keep a long refactoring session inside a single context window. Measured with knot 1.15.1 on 2026-11-01, on a clean index.

<details> <summary><b>Methodology (and how to reproduce it)</b></summary>

Both sides are measured on the exact bytes an LLM would receive as tool output, counted with OpenAI's cl100k_base tokenizer (tiktoken):

| Task | knot side | Read-the-code side | |------|-----------|--------------------| | discovery | knot search "<question>" --repo <r> --output markdown | rg -l <keyword> (candidate list) + full read of the files that actually answer the question | | callers | knot callers "<symbol>" --repo <r> --output markdown | rg -n "\b<symbol>\b" + full read of the first 5 distinct files with hits | | explore | knot explore "<file>" --repo <r> --output markdown | full read of the file |

The baseline is deliberately generous, so the measured saving is a lower bound:

• greps are restricted to the source files of the language (-t java, -t ts, -t rust) — no changelogs, no generated docs, no node_modules;
• for discovery the baseline is given oracle file selection: it reads only the files that answer the question, with zero wasted reads;
• for callers it reads at most 5 files, while a rigorous impact analysis would need every file with a textual hit.

Honest caveats: knot's cost scales with the number of results, not with repo size. callers answers list the references made from production code and count those made from test code (+N in tests, issue #52). Listing them too (include_tests, CLI --include-tests) costs 16 422 / 773 / 1 003 tokens for the three callers rows and brings the total saving to 84.8%: ToolCallingManager has 394 references, 320 of them in tests, and format_references_result is called mostly by unit tests. The explore rows for large files are the least favourable, because signatures plus docstrings are a large fraction of a well-documented file.

How the answers shrank on the same snapshots (knot tokens, 9 tasks): 59 579 with knot 1.12.4, 53 806 with 1.14.1 (compact search and explore answers, #50) and 28 373 with 1.15.0 (compact callers answers, #52), all on an index built incrementally that still held the stale entities of #53; 20 266 with 1.15.1 after a --clean re-index. The callers rows alone went from 29 772 to 4 194 tokens. The clean re-index also changed rows of repositories without stale entities (re-computed embeddings and edges), by a few hundred tokens.

Repositories measured (as indexed): spring-ai 2 490 files / 27 775 entities (commit b6b5767), puppeteer 1 286 files / 11 733 entities (08e7b1a), knot 390 files / 5 956 entities (421b515). Raw measurements are stored in .perf_metrics/token_savings.json.

pip install tiktoken            # optional: falls back to a chars/4 estimate
# edit the `root` paths in scripts/token_savings_tasks.json to match your checkouts
python3 scripts/token_savings_benchmark.py \
  --config scripts/token_savings_tasks.json \
  --save-json .perf_metrics/token_savings.json

The task definitions live in scripts/token_savings_tasks.json and the harness in scripts/token_savings_benchmark.py; point them at any repository you have indexed to measure your own codebase.

</details>

---

✨ Key Features

🔍 Code Intelligence Tools

• search_hybrid_context: Semantic + structural search. Find code by meaning, class name, method signature, docstrings, or comments. Returns full context including dependencies.
• find_callers: Reverse dependency lookup. Identify dead code, perform impact analysis, or understand the full call chain of any function/method. Whenever the query resolves to more than one entity sharing the same name (e.g., find_nearest_entity_by_line in different files), results are automatically grouped by target (### Target: <fqn> at <file>:<line>) showing which specific entity each caller references — including when only one of the homonyms has callers. A genuinely single-target resolution keeps the concise ungrouped form. Supports cross-repository call resolution via DEPENDS_ON graph edges. A call whose receiver type is declared in the caller's own repository never binds to a dependency's same-named type, even when the local member is not indexed (macro-generated, derived, annotation-processed): it stays unresolved instead. Likewise, a call on a type no indexed repository declares (JDK, standard library, third-party package: String.valueOf(..), a field typed ModelMapper) never binds to a repository method that merely shares the callee's name. In Java and Kotlin, an unqualified type name — a call receiver, a receiver named after its type (config → Config), an extends or a type reference — resolves through the caller file's imports: a single-type import (or Kotlin as alias) first, then the file's own package, then on-demand imports (com.x.*), so same-named types of different packages are never mixed up; an import of a type no indexed repository declares leaves the call unresolved. For JVM languages (Java/Kotlin/Groovy) it also surfaces method-level OVERRIDES edges bidirectionally — an Overridden by group listing subtype implementations/overrides and an Overrides group listing the supertype methods a method implements/overrides — plus a Dispatched calls group listing callers that reach the queried method through dynamic dispatch (bound to an override or to the supertype method), so an interface method called only through its implementation (or vice versa) is never reported as unused.
• explore_file: File anatomy inspection. Quickly see all classes, interfaces, methods, functions, constants, and other entities in a file with signatures and documentation. Attribute-usage markup tokens (html_class, html_id) are summarized in a separate section by default to avoid cluttering code lists; use --include-markup (CLI) or include_markup: true (MCP) to list them in full. Structured content returns markup_count and markup_references alongside ambiguous_path_candidates.
• list_repo_dependencies (MCP) / knot deps (CLI): Dependency graph visualization. Show which repositories depend on each other, forward and reverse, with transitive resolution.
• list_files (MCP) / knot files (CLI): Read-only file enumeration with entity counts, deterministically ordered. Accepts an optional path — a repo-relative directory prefix matched on a path boundary (src/api never matches src/api-notes.md) or a glob (src/**/*_test.rs). Prefixes and globs alike page the repository file list in pages of 2000 entries with per-page boundary filtering, ensuring no valid candidates are dropped. When output exceeds 2000 matches, a truncation notice is displayed below the table reporting the exact pre-truncation match count when known (or an explicit lower bound when the scan stopped early). JSON output carries total_matches and total_is_lower_bound. Pair with the new --path/path scope on search_hybrid_context to restrict a semantic search to a subtree.
• list_endpoints (MCP) / knot endpoints (CLI): HTTP endpoint catalogue. Lists the endpoints Java and Kotlin code serves — JAX-RS (class/method @Path + @GET/@POST/…) and Spring MVC (class @RequestMapping + @GetMapping/… or @RequestMapping(method = …)) — as <METHOD> <path> with the handler method each one routes to. Class and method paths are joined, path arrays expand, path-variable patterns are dropped ({id: [0-9]+} → {id}), and string constants resolve whether declared in the same file or in another file of the repository (found through imports and package; Kotlin const val templates included). Filters: method (case-insensitive; ANY, a @RequestMapping without method, matches every method) and path (segment-wise prefix where an endpoint's {variable} segment matches any value, so a concrete URL such as /api/owners/42 finds GET /api/owners/{id}). Each endpoint is an http_endpoint entity linked to its handler by a ROUTES_TO edge: find_callers on a handler lists it under HTTP routes (a handler reached only over HTTP is never reported as unused), explore_file groups a resource's endpoints under HTTP Endpoints, and search_hybrid_context finds them by