# Knot > High-performance Rust MCP server that indexes codebases via vector + graph databases for AI coding agents - **Type:** MCP server - **Install:** `agentstack add mcp-raultov-knot` - **Verified:** Pending review - **Seller:** [raultov](https://agentstack.voostack.com/s/raultov) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [raultov](https://github.com/raultov) - **Source:** https://github.com/raultov/knot - **Website:** https://www.knot.kz ## Install ```sh agentstack add mcp-raultov-knot ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # knot [](https://opensource.org/licenses/MIT) [](https://www.rust-lang.org) [](https://glama.ai/mcp/servers/raultov/knot) **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](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 three tools to any LLM client (Claude, Gemini, ChatGPT, Cursor, etc.) - **CLI Tool** — Standalone `knot` command for terminal and scripting environments ### Knot in action **CLI** — instant reverse dependency lookup **MCP** — JSON-RPC protocol for AI agents --- ## ✨ 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. 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. - **`list_repositories`** / **`knot repos`**: Repository inventory. List every indexed repository along with its entity count, file count, build system, and primary language. Supports optional case-insensitive name filtering via `--filter` (CLI) or `filter` parameter (MCP). Useful for orientation, sanity-checking indexing runs, and discovering which languages and build systems are present in the workspace. **🏗️ Multi-Language Support** - **Java**: Full AST extraction with package-aware FQN resolution (e.g., `com.example.app.UserService`), class inheritance (`EXTENDS`), interface implementation (`IMPLEMENTS`), annotation tracking, and field-access method invocation resolution - **Kotlin**: Complete support for Kotlin codebases with classes, interfaces, objects, companion objects, functions, methods, and properties. Fully compatible with tree-sitter-kotlin-ng grammar. - **TypeScript/TSX/CTS**: Complete support for modern JavaScript/TypeScript codebases, including CommonJS TypeScript files - **JavaScript/Node.js**: Vanilla JS, Node.js, and module systems (`.js`, `.mjs`, `.cjs`, `.jsx`) - **Hybrid Web Ecosystem**: Cross-language linking between JavaScript, HTML, and CSS for full-stack SPA analysis - **HTML**: Custom elements (Web Components, Angular), `id` and `class` attribute indexing for cross-language CSS search - **JSX/TSX Attributes**: Extracts `id` and `className` from React components for unified HTML/CSS discovery - **CSS/SCSS**: Stylesheet indexing with class/ID selector extraction and variable tracking (CSS/SCSS variables, mixins, functions) - **Rust**: Struct, enum, union, trait, function, method, module extraction with trait implementation tracking (IMPLEMENTS relationships) and macro invocation references. Methods are indexed with the qualified FQN `Type::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::::` FQN prefix (e.g. `__fixture::tests::testing_files::sample::Config`), and files without a `Cargo.toml` ancestor receive `__loose::::`, 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`. - **Python**: Full Python extraction with class, function, method support, constants, module-level imports, `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. **Class instantiation (`ClassName(...)`) is automatically redirected to `ClassName.__init__`** so `find_callers ClassName.__init__` lists every constructor call site (with fallback to inherited `__init__` via the extends chain); only class/struct kinds trigger the redirect — functions keep the legacy behavior. - **Groovy**: Full Groovy language support via hybrid tree-sitter + ad-hoc lexical parser. Extracts classes, interfaces, traits, enums, typed/`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. - **Build Systems**: Maven `pom.xml` (dependencies + plugins via roxmltree), Gradle `build.gradle` (deps + plugins + tasks), and `Jenkinsfile` pipeline (stages + steps) extraction. - **Cargo.toml**: Rust package manager support with package metadata, features, workspace members, and multi-format dependency parsing (simple, table, git, path). - **Configuration Files**: YAML (.yml/.yaml), JSON (.json), and Java Properties (.properties) with leaf-key granularity. Special handling for package.json (npm dependencies as BuildDependency, scripts as ConfigProperty). - **Kubernetes + Helm**: K8s manifest parsing (Deployment, Service, ConfigMap, Secret, Ingress, Namespace) with label/annotation tracking and cross-resource references. Helm chart indexing (Chart.yaml metadata, values.yaml key-value pairs, template variable extraction via {{ .Values.X }}). - **C/C++**: Complete C/C++ support with namespace-aware FQN resolution (`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. - **Markdown**: Documentation indexing with `MarkdownDocument` (one per `.md`/`.markdown` file) and `MarkdownSection` (one per ATX heading H1–H6). Section bodies — including paragraphs, fenced code blocks, lists, and tables — are captured into `embed_text` for full semantic search over documentation content, not just heading titles. FQNs are hierarchical and file-scoped (e.g. `README.md::Setup > Installation > Linux`), so same-named headings in different files or under different parents disambiguate cleanly. Section boundaries respect heading depth: a section's body extends until the next heading of equal or higher level, ensuring `### Linux` under `## Installation` does not bleed into a sibling `## Configuration`. Headings with inline markdown (backticks, em-dash, links, emoji) parse without losing their bodies, and real `start_line`/`end_line` positions are computed via tree-sitter for each section. **📚 Rich Comment Extraction** - Captures docstrings (JavaDoc, JSDoc) preceding declarations - Extracts inline comments within method/function bodies - Respects nesting boundaries (class comments don't capture method comments) - Intelligently aggregates comment blocks **📊 Dual-Database Architecture** - **Qdrant**: Vector search for semantic code understanding - **Neo4j**: Graph relationships for structural navigation **🚀 High Performance** - **Parallel Streaming Pipeline**: Overlaps CPU-bound embedding with I/O-bound ingestion via MPSC channels - **Incremental Indexing**: Uses SHA-256 hashes to skip unchanged files - **Real-time Watch Mode**: Automatically re-indexes changed files in seconds via `--watch` - **CPU Parallelism**: AST extraction via Rayon - **Scalable**: Configurable batch processing and constant memory footprint (~2GB) regardless of repository size - **Performance Benchmarking**: Three-level validation framework - *Unit benchmarks*: Criterion-based benchmarks for parse, embed, and graph write throughput (`benches/`) - *E2E benchmarks*: Full pipeline metrics capture with per-stage timing (`tests/benchmark_e2e.sh`) - *CI regression tracking*: Automated baseline comparison against tolerance thresholds (`scripts/compare_perf_metrics.sh`) --- ## 🛠️ Installation ### Prerequisites | Component | Version | Notes | |--------------|---------|-----------------------------------| | Docker | 20.10+ | For running Qdrant and Neo4j | | qdrant | 1.x | Vector database (docker) | | neo4j | 5.x | Graph database (docker) | ### Option A: Pre-compiled Binaries (macOS & Modern Linux) Go to the [Releases](https://github.com/raultov/knot/releases) page and download the native executable for your platform. **Install knot binaries (CLI, MCP server, and indexer):** ```bash curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/knot/releases/latest/download/knot-installer.sh | sh ``` **Install agent-skills for your AI (Optional):** Paste this into your LLM agent (Claude Code, OpenCode, Cursor, etc.): > Install the knot agent skills by following the instructions at: https://raw.githubusercontent.com/raultov/knot/master/README.md The first command installs the `knot` binary to your PATH. The second (optional) allows your AI assistant to automatically download the agent skill index (`.knot-agent.md`) and run the installer to extract comprehensive guides for using knot CLI with AI agents and code analysis tools. **System Requirements:** - **Linux**: glibc 2.38+ (Ubuntu 24.04+, Debian 13+, Fedora 39+, Arch) - **macOS**: Modern versions supported - **Windows**: Use Docker (Option B) ### Option B: Docker (Universal Compatibility) Docker images provide universal compatibility for **any Linux distribution** and **Windows**. #### Docker Installation (All Binaries) **Build the image:** ```bash docker build -t knot:latest . --network=host ``` **Run the indexer:** ```bash # 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:** ```bash 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:** ```bash 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. --- ### Option C: Install via Cargo ```bash cargo install --git https://github.com/raultov/knot ``` ### Option D: Build from Source **1. Start infrastructure with Docker:** ```bash docker compose up -d ``` **2. Clone and build:** ```bash git clone https://github.com/raultov/knot cd knot cargo build --release ``` **3. Configure:** ```bash 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:** ```bash ./target/release/knot-indexer ``` **5. Query via CLI:** ```bash ./target/release/knot search "your query" ``` **6. Start the MCP server:** ```bash ./target/release/knot-mcp ``` --- ## 📖 Usage ### 🤖 Install Agent Skills (For AI Agents) **Option A: Let an LLM do it** Paste this into any LLM agent (Claude Code, OpenCode, Cursor, etc.): > Install the knot agent skills by following the instructions at: https://raw.githubusercontent.com/raultov/knot/master/README.md **Option B: Terminal (Manual)** ```bash curl -sO https://raw.githubusercontent.com/raultov/knot/master/.knot-agent.md && curl -fsSL https://raw.githubusercontent.com/raultov/knot/master/scripts/install-agent-skills.sh | bash ``` ### 📥 Quick Downloads (Binaries) **Download knot binaries (CLI + MCP server):** ```bash curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/knot/releases/latest/download/knot-installer.sh | sh ``` ### 📖 Agent-Skills Guides Comprehensive documentation for using knot tools. The agent skills installer extracts: - **search.md** — Semantic code discovery guide with examples - **callers.md** — Reverse dependency lookup with critical usage rules - **explore.md** — File anatomy inspection guide - **deps.md** — Repository dependency graph guide - **repos.md** — Indexed repository inventory - **workflows.md** — Common patterns and best practices For quick reference without downloading, see [`.knot-agent.md`](.knot-agent.md). --- ### Using the CLI The **knot CLI** provides the same capabilities as the MCP server via command-line commands, making it ideal for: - Terminal-only environments - Bash scripting and automation - CI/CD pipelines - Direct integration with other tools **Three main commands:** #### `knot search` — Semantic Code Search ```bash knot search "user authentication" --max-results 10 --repo my-app ``` Find code entities by meaning, class names, docstrings, or comments. #### `knot callers` — Reverse Dependency Lookup ```bash knot 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 Inspection ```bash knot explore "src/services/auth.ts" --repo my-app ``` List all classes, methods, functions in a file with signatures and documentation. #### `knot deps` — Repository Dependen … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [raultov](https://github.com/raultov) - **Source:** [raultov/knot](https://github.com/raultov/knot) - **License:** MIT - **Homepage:** https://www.knot.kz Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** yes - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-raultov-knot - Seller: https://agentstack.voostack.com/s/raultov - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.