loading…
Search for a command to run...
loading…
Knot is a semantic and structural codebase indexer designed for AI coding agents and developers navigating large projects. It combines vector search and graph t
Knot is a semantic and structural codebase indexer designed for AI coding agents and developers navigating large projects. It combines vector search and graph traversal to find code by meaning, analyze impact via reverse dependencies, and explore file architectures.
License: MIT Rust knot MCP server
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++, HTML, and CSS/SCSS, plus Build Systems (Maven pom.xml, Gradle build.gradle, Jenkins pipeline, Cargo.toml), 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:
This dual-database approach powers both:
knot command for terminal and scripting environments
CLI — instant reverse dependency lookup

MCP — JSON-RPC protocol for AI agents
🔍 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. When multiple entities share the same name (e.g., find_nearest_entity_by_line in different files), results are automatically grouped by target showing which specific entity each caller references. Supports cross-repository call resolution via DEPENDS_ON graph edges.explore_file: File anatomy inspection. Quickly see all classes, interfaces, methods, and functions in a file with signatures and documentation.list_repo_dependencies (MCP) / knot deps (CLI): Dependency graph visualization. Show which repositories depend on each other, forward and reverse, with transitive resolution.🏗️ Multi-Language Support
com.example.app.UserService), class inheritance (EXTENDS), interface implementation (IMPLEMENTS), annotation tracking, and field-access method invocation resolution.js, .mjs, .cjs, .jsx)id and class attribute indexing for cross-language CSS searchid and className from React components for unified HTML/CSS discoveryType::method (e.g., KnotMcpHandler::new, WidgetA::new, Logger::new) and qualified calls from top-level functions resolve to the right target by receiver. Braced import/use capture — use foo::{Bar, Baz} and use foo::Bar as Baz produce explicit REFERENCES edges for all imported names, including traits imported solely to bring methods into scope. All Rust entity FQNs are now anchored at the owning crate and module path (e.g. knot::config::Config, knot::pipeline::parser::languages::rust::qualify_rust_fqns), so two crates that declare a type with the same bare name no longer collide. Files outside src/ (tests, benches, examples) receive a __fixture::<path>::<Entity> FQN prefix (e.g. __fixture::tests::testing_files::sample::Config), and files without a Cargo.toml ancestor receive __loose::<path>::<Entity>, preventing name collisions with real source entities. CONTAINS relationships use enclosing_class_fqn for exact disambiguation when multiple entities share the same class name. The on-disk index state file (.knot/index_state.json) carries a version field; opening a state file from an older version prints an error with instructions to run knot-indexer --clean.ValueReference tracking for keyword arguments, class inheritance (EXTENDS), decorator extraction (@property, @staticmethod, @route(...), @dataclass), generic type hints (List[str], Optional[Dict], *args/**kwargs), Py2/Py3 exception syntax compatibility, and self.method() resolution with inherited method walking. Captures class_definition, function_definition (including async via optional async modifier), lambda assignments, and distinguishes methods from functions via parent context detection.def/quoted methods (incl. Spock specs), constructors, closures, script-level variables, fields/properties with visibility modifiers, nested classes, and decorators. Tracks package FQN and enclosing class relationships. Multi-line signatures (closure default params), assignment-vs-declaration disambiguation, innermost assignment for nested closures, UUID collision fix for duplicate method names, find_callers accurately tracks private methods including those in anonymous new AnAction closures.pom.xml (dependencies + plugins via roxmltree), Gradle build.gradle (deps + plugins + tasks), and Jenkinsfile pipeline (stages + steps) extraction.Engine::MyClass::start), class/struct extraction, function/method tracking, macro definition and usage detection (uppercase identifier heuristic), type reference tracking (declarations, new expressions), and full call graph analysis. Supports .c, .h, .cpp, .hpp, .cc, .cxx, .hh, .hxx extensions via tree-sitter-c and tree-sitter-cpp parsers. Includes intelligent auto-detection for .h headers to parse them correctly as C or C++ based on their contents.📚 Rich Comment Extraction
📊 Dual-Database Architecture
🚀 High Performance
--watchbenches/)tests/benchmark_e2e.sh)scripts/compare_perf_metrics.sh)| Component | Version | Notes |
|---|---|---|
| Docker | 20.10+ | For running Qdrant and Neo4j |
| qdrant | 1.x | Vector database (docker) |
| neo4j | 5.x | Graph database (docker) |
Go to the Releases page and download the native executable for your platform.
Install knot binaries (CLI, MCP server, and indexer):
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/knot/releases/latest/download/knot-installer.sh | sh
Download agent-skills guides separately (optional):
curl -sO https://raw.githubusercontent.com/raultov/knot/master/.knot-agent.md && curl -fsSL https://raw.githubusercontent.com/raultov/knot/master/.knot-agent-skills.tar.gz | tar -xz
The first command installs the knot binary to your PATH. The second (optional) downloads the agent skill index (.knot-agent.md) and extracts comprehensive guides for using knot CLI with AI agents and code analysis tools.
Linux Requirements:
For older Linux distributions or Windows, see the Lightweight Clients section below or use Docker (Option B).
Docker images provide universal compatibility for any Linux distribution and Windows.
Build the image:
docker build -t knot:latest . --network=host
Run the indexer:
# Use --network host to connect to databases running on your host machine
docker run --rm \
-v /path/to/your/repo:/workspace \
-e KNOT_REPO_PATH=/workspace \
-e KNOT_NEO4J_PASSWORD=your-password \
--network host \
knot:latest \
knot-indexer
Run the CLI tool:
docker run --rm \
-v /path/to/your/repo:/workspace \
-e KNOT_REPO_PATH=/workspace \
-e KNOT_NEO4J_PASSWORD=your-password \
--network host \
knot:latest \
knot search "user login flow"
Run the MCP server:
docker run --rm \
-e KNOT_REPO_PATH=/workspace \
-e KNOT_NEO4J_PASSWORD=your-password \
--network host \
knot:latest \
knot-mcp
Note: Uses Debian Trixie (glibc 2.38+) and includes ONNX Runtime for full functionality.
For older systems (Debian 12 Bookworm, Ubuntu 22.04) or production deployments that only need to query existing indexes without indexing new code:
Build the lightweight image:
docker build -t knot:clients -f Dockerfile.clients . --network=host
Image size: ~100MB (vs ~160MB for full install)
Run the CLI tool (query existing index):
docker run --rm \
--network host \
knot:clients \
knot callers "MyClass"
Run the MCP server:
docker run --rm \
--network host \
knot:clients \
knot-mcp
Available tools in lightweight mode:
knot search (structural only, no semantic search)knot callers (reverse dependency lookup)knot explore (file structure inspection)Note: Uses Debian Bookworm (glibc 2.35+) and excludes ONNX Runtime, making it compatible with older Linux distributions.
cargo install --git https://github.com/raultov/knot
Full Install (All Binaries):
1. Start infrastructure with Docker:
docker compose up -d
2. Clone and build:
git clone https://github.com/raultov/knot
cd knot
cargo build --release
3. Configure:
mkdir -p ~/.config/knot
cp .env.example ~/.config/knot/.env
$EDITOR ~/.config/knot/.env # Set KNOT_REPO_PATH and Neo4j credentials
4. Index a codebase:
./target/release/knot-indexer
5. Query via CLI:
./target/release/knot search "your query"
For older Linux distributions (e.g. Debian 12 Bookworm, Ubuntu 22.04) or production deployments where you only need the CLI and MCP server (not the indexer), compile without the embedding dependencies:
Build lightweight clients:
cargo build --release --no-default-features --features only-clients
This produces only knot and knot-mcp binaries (~8-10 MB each), excluding the 30+ MB of ONNX Runtime dependencies.
Available tools in lightweight mode:
find_callers: Reverse dependency lookup (graph search). Automatically groups results by target when multiple entities share the same name.explore_file: File structure inspectionsearch_hybrid_context: Semantic search (requires embeddings, not available in this mode)Use case: Query an existing Qdrant + Neo4j index that was built elsewhere, without needing the indexer on your machine.
Docker alternative (for lightweight mode):
docker build -t knot:clients-only -f Dockerfile -f - . << 'EOF'
FROM rust:1.90-slim-bookworm AS builder
WORKDIR /build
COPY . .
RUN cargo build --release --no-default-features --features only-clients
FROM debian:bookworm-slim
COPY --from=builder /build/target/release/knot* /usr/local/bin/
CMD ["knot-mcp"]
EOF
6. Start the MCP server:
./target/release/knot-mcp
Download knot binaries (CLI + MCP server):
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/knot/releases/latest/download/knot-installer.sh | sh
Download agent-skills documentation (index + all guides):
curl -sO https://raw.githubusercontent.com/raultov/knot/master/.knot-agent.md && curl -fsSL https://raw.githubusercontent.com/raultov/knot/master/.knot-agent-skills.tar.gz | tar -xz
Comprehensive documentation for using knot tools. The download above extracts:
For quick reference without downloading, see .knot-agent.md.
The knot CLI provides the same capabilities as the MCP server via command-line commands, making it ideal for:
Three main commands:
knot search — Semantic Code Searchknot search "user authentication" --max-results 10 --repo my-app
Find code entities by meaning, class names, docstrings, or comments.
knot callers — Reverse Dependency Lookupknot callers "LoginService" --repo my-app
Find all code that references a specific entity (dead code detection, impact analysis, call chains). When multiple entities share the same name in different files, results are automatically grouped by target with file locations and signatures.
knot explore — File Structure Inspectionknot explore "src/services/auth.ts" --repo my-app
List all classes, methods, functions in a file with signatures and documentation.
knot deps — Repository Dependency Graphknot deps my-app --depth 2 # Show forward dependencies (transitive)
knot deps my-app --reverse # Show who depends on this repo
Visualize auto-discovered dependencies between indexed repositories with transitive resolution up to 3 levels deep.
For detailed CLI usage guide, see .knot-agent.md — a machine-readable skill that teaches LLMs how to use knot CLI for autonomous code analysis.
# First run: indexes all files
knot-indexer --repo-path /path/to/your/repo --neo4j-password secret
# Subsequent runs: only re-indexes changed files (fast!)
knot-indexer --repo-path /path/to/your/repo --neo4j-password secret
# NEW: Real-time Watch mode
knot-indexer --watch --repo-path /path/to/your/repo --neo4j-password secret
How it works:
.knot/index_state.jsonfastembed model in .knot/fastembed_cache/ to keep the workspace cleanPerformance:
# Force complete re-index (deletes all existing data)
knot-indexer --clean --repo-path /path/to/your/repo --neo4j-password secret
Use --clean when:
To ensure indexer stability, run the E2E integration test suite:
# Run all language E2E tests (Java, TS, JS, HTML, CSS, Kotlin, Rust)
./tests/run_e2e.sh
# Run only Kotlin E2E tests
./tests/run_kotlin_e2e.sh
# Run only Rust E2E tests
./tests/run_rust_e2e.sh
See tests/KOTLIN_E2E_TESTS.md for detailed coverage and troubleshooting.
The MCP server exposes three tools to any compatible AI client:
search_hybrid_contextFind code by meaning or keywords
Query: "How is user authentication implemented?"
Result: All auth-related code, signatures, docstrings, and dependencies
Capabilities:
find_callersFind who calls a specific function
Query: "Find callers of getCurrentTimeInSeconds"
Result: All code that invokes this function + file locations
Advanced: Search by Signature
# Find by full signature (Java)
echo '{"method":"tools/call","params":{"name":"find_callers","arguments":{"entity_name":"registerUser(String"}}}' | knot-mcp
# Find by parameter type (Kotlin)
echo '{"method":"tools/call","params":{"name":"find_callers","arguments":{"entity_name":"findById(Int"}}}' | knot-mcp
# Find by type annotation (TypeScript)
echo '{"method":"tools/call","params":{"name":"find_callers","arguments":{"entity_name":"(EventData"}}}' | knot-mcp
Use Cases:
explore_fileUnderstand file structure
Query: "What's in BrowserService.ts?"
Result: All classes, methods, and functions with signatures and docs
Use Cases:
knot works with any MCP-compatible AI client:
Add to claude_desktop_config.json:
{
"mcpServers": {
"knot": {
"command": "/absolute/path/to/knot/target/release/knot-mcp",
"env": {
"KNOT_REPO_PATH": "/path/to/indexed/repo",
"KNOT_QDRANT_URL": "http://localhost:6334",
"KNOT_NEO4J_URI": "bolt://localhost:7687",
"KNOT_NEO4J_USER": "neo4j",
"KNOT_NEO4J_PASSWORD": "your-password"
}
}
}
}
{
"mcpServers": {
"knot": {
"command": "/absolute/path/to/knot/target/release/knot-mcp",
"env": {
"KNOT_REPO_PATH": "/path/to/indexed/repo",
"KNOT_QDRANT_URL": "http://localhost:6334",
"KNOT_NEO4J_URI": "bolt://localhost:7687",
"KNOT_NEO4J_USER": "neo4j",
"KNOT_NEO4J_PASSWORD": "your-password"
}
}
}
}
Similar JSON configuration in your client's MCP configuration file.
All options can be set via CLI flags, environment variables, or a ~/.config/knot/.env file.
Priority (highest to lowest): CLI flags > environment variables > .env file.
| Env Variable | CLI Flag | Default | Description |
|---|---|---|---|
KNOT_REPO_PATH |
--repo-path |
(required) | Root directory of the repository to index |
KNOT_REPO_NAME |
--repo-name |
(auto-detected) | Repository name for multi-repo isolation (auto-detected from last path component) |
KNOT_QDRANT_URL |
--qdrant-url |
http://localhost:6334 |
Qdrant server URL |
KNOT_QDRANT_COLLECTION |
--qdrant-collection |
knot_entities |
Qdrant collection name |
KNOT_NEO4J_URI |
--neo4j-uri |
bolt://localhost:7687 |
Neo4j Bolt URI |
KNOT_NEO4J_USER |
--neo4j-user |
neo4j |
Neo4j username |
KNOT_NEO4J_PASSWORD |
--neo4j-password |
(required) | Neo4j password |
KNOT_EMBED_DIM |
--embed-dim |
384 |
Embedding vector dimension |
KNOT_BATCH_SIZE |
--batch-size |
64 |
Entities per batch |
KNOT_CLEAN |
--clean |
false |
Force full re-index (delete all existing data) |
KNOT_CUSTOM_CA_CERTS |
--custom-ca-certs |
(none) | Path to CA certificate bundle for corporate SSL proxies |
KNOT_INCLUDE_CONFIG_FILES |
--include-config-files |
false |
Include YAML/JSON/properties/K8s/Helm files in the index |
RUST_LOG |
(env only) | info |
Log level: trace, debug, info, warn, error |
The built-in extraction queries (queries/java.scm, queries/typescript.scm) can be overridden without recompiling:
KNOT_CUSTOM_QUERIES_PATH=/path/to/my/queries ./target/release/knot-indexer
Place java.scm and/or typescript.scm in your custom directory. Missing files fall back to built-in defaults.
In restricted corporate environments with SSL-inspecting proxies, you may need to provide a custom CA certificate bundle so that knot can download the embedding model from HuggingFace.
Via environment variable:
export KNOT_CUSTOM_CA_CERTS=/etc/ssl/certs/corporate-bundle.pem
./target/release/knot-indexer --repo-path /path/to/repo --neo4j-password secret
Via CLI flag:
./target/release/knot-indexer \
--custom-ca-certs /etc/ssl/certs/corporate-bundle.pem \
--repo-path /path/to/repo \
--neo4j-password secret
Via .env file:
echo "KNOT_CUSTOM_CA_CERTS=/etc/ssl/certs/corporate-bundle.pem" >> ~/.config/knot/.env
./target/release/knot-indexer
This works for all three binaries: knot-indexer, knot-mcp, and knot.
Step 1: Index a Java project
./target/release/knot-indexer --repo-path /home/user/my-java-app --neo4j-password secret
Step 2: Query via CLI (Instant search)
./target/release/knot search "authentication logic"
./target/release/knot callers "UserService.login"
Step 3: Start MCP server (For AI Agents)
./target/release/knot-mcp
Step 4: Use with Claude Desktop
knot includes a universal .prompt file in its root directory that automatically configures modern AI coding agents (Cursor, Cline, opencode, Claude, etc.) to use the knot-mcp tools correctly.
The directive explicitly instructs AI agents to prioritize:
search_hybrid_context — for semantic code discovery (instead of grep)find_callers — for reverse dependency analysis (instead of finding references manually)explore_file — for file structure inspection (instead of reading line-by-line)This ensures that when you ask an AI agent to analyze, refactor, or understand your code, it leverages the full power of the vector and graph databases rather than falling back to context-blind regex searches. The .prompt file is universal and tool-agnostic, working with any LLM client that reads codebase directives.
Contributions are welcome! Please ensure:
cargo clippycargo fmtThe project includes a three-level benchmarking framework to validate optimizations and detect regressions:
Level 1 — Unit Benchmarks (Criterion):
cargo bench --bench pipeline_bench # Parse + prepare throughput per language
cargo bench --bench graph_upsert_bench # Neo4j UNWIND batching speedup (needs Neo4j)
cargo bench --bench channel_backpressure_bench # Bounded channel overhead
Level 2 — E2E Integration Benchmarks:
# Full pipeline metrics with memory and per-stage timing
./tests/benchmark_e2e.sh --focus rust_e2e --output-dir /tmp/perf_results
# Compare against baseline (fails CI if tolerance exceeded)
scripts/compare_perf_metrics.sh /tmp/perf_results .perf_metrics/baseline.json
Baseline files: .perf_metrics/baseline.json stores the last known good metrics (committed, updated on main/master merges). Tolerance thresholds in .perf_metrics/threshold_tolerances.json control regression gates (±5% time, ±10% memory by default).
CI Integration: The test-performance job in .github/workflows/ci.yml runs after all E2E correctness tests pass, comparing results against baseline and fails the build on regression.
This project is licensed under the MIT License. See LICENSE for details.
For the full release history see CHANGELOG.md.
For issues, feature requests, or discussions, please open a GitHub issue.
Run in your terminal:
claude mcp add knot -- npx CSA PROJECT - FZCO © 2026 IFZA Business Park, DDP, Premises Number 31174 - 001
Security
Low riskAutomated heuristic from public metadata — not a security guarantee.