{
"markdown": "# Weavatrix — native MCP repository intelligence\n\n![\"Weavatrix](\"plugins/weavatrix/assets/logo.svg\")
\n\n[](https://github.com/Weavatrix/weavatrix/actions/workflows/ci.yml)\n[](https://www.npmjs.com/package/weavatrix)\n[](https://crates.io/crates/weavatrix)\n[](https://crates.io/crates/weavatrix-rust)\n[](LICENSE)\n\nPart of the [Weavatrix ecosystem](https://weavatrix.com/ecosystem): evidence infrastructure for AI software agents.\n\n**Give your coding agent repository evidence before it starts guessing.**\n\nWeavatrix is the native MCP product for repository intelligence. It gives\nCodex, Claude Code, and other coding agents 44 read-only operations over one\nrevision-bound evidence graph: impact, architecture, APIs, Git history,\nduplicates, dead code, search, semantic links, and temporal memory.\n\nIt does not answer from a larger grep or an invented confidence score. Every\nbounded result can carry the repository revision, file, line, extractor,\nevidence kind, and confidence that produced it.\n\n### Ecosystem place (UNDERSTAND)\n\n```text\nWeavatrix (this) — code facts\n │\n ▼\nWeavatrix Loom — semantic composition (capabilities, registry, compile → Rust)\n │\n ▼\nRealforge — artifact construction (scaffold / package / deploy)\n```\n\n| Product | Owns | Does **not** own |\n| --- | --- | --- |\n| **Weavatrix** (this) | Repository / code graph, symbols, deps, search, impact | Capability interchange **Registry**, WVX project graph |\n| **[Weavatrix Loom](https://github.com/Weavatrix/weavatrix-loom)** | Capability · Implementation · evidence · GraphPatch · semantic compiler | Deep repo indexing (that stays here) |\n| **[FerroSift](https://github.com/sergii-ziborov/ferrosift)** | Deterministic transform recipes/ops | Capability Registry; code intelligence |\n| **[Cortex Loom](https://github.com/sergii-ziborov/cortex-loom)** | Agent workflow / context budgets | Code index; Loom admit policy |\n\nLoom **consumes** Weavatrix facts for semantic classification (e.g. “this `fn`\nis a candidate for `data.json.parse@1`”). Loom must not grow a second product\ncode indexer. Normative Loom side: [ADR-0012](https://github.com/Weavatrix/weavatrix-loom/blob/main/docs/adr/0012-ecosystem-boundaries.md).\n\nThe same source is distributed in two forms:\n\n| Distribution | Install | Best for |\n| --- | --- | --- |\n| `weavatrix` on crates.io | `cargo install weavatrix` | Rust-first environments and source builds |\n| `weavatrix` on npm | `npx -y weavatrix mcp .` | Ready-made cross-platform binaries without a Rust toolchain |\n\nThe npm package exists for convenience; it does not contain a different\nJavaScript engine. Both distributions run the same native adapter and the same\n`weavatrix-rust` analysis engine. The separately versioned `weavatrix-js`\npackage is the legacy JavaScript implementation used for compatibility and\nhistorical baselines; it is not bundled into `weavatrix`.\n\n## Install as a plugin\n\nThe repository ships one plugin bundle for Cursor, Codex, Claude Code, and\nGrok Build. Each client starts the published native npm distribution and loads\nthe same read-only MCP tools. Its optional Weavatrix skill activates only for\ntasks that benefit from indexed, cross-file evidence; detailed tool routing is\nloaded separately when needed.\n\n### Cursor plugin\n\nSearch for **Weavatrix** in Cursor's Plugins view after its marketplace review\nis complete. The bundle can be tested before listing by copying or linking\n[`plugins/weavatrix`](plugins/weavatrix) to\n`~/.cursor/plugins/local/weavatrix` and reloading the Cursor window.\n\n### Codex plugin\n\n```sh\ncodex plugin marketplace add Weavatrix/weavatrix --sparse .agents/plugins plugins/weavatrix\ncodex plugin add weavatrix@weavatrix\n```\n\n### Claude Code plugin\n\n```sh\nclaude plugin marketplace add Weavatrix/weavatrix --sparse .claude-plugin plugins\nclaude plugin install weavatrix@weavatrix\n```\n\n### Grok Build plugin\n\n```sh\ngrok plugin marketplace add Weavatrix/weavatrix\n```\n\nOpen `/marketplace` and install Weavatrix. Grok also accepts the plugin\ndirectly with\n`grok plugin install Weavatrix/weavatrix#plugins/weavatrix`.\n\n## Install in 30 seconds\n\nRun the convenient prebuilt npm distribution:\n\n```sh\nnpx -y weavatrix mcp .\n```\n\nOr install the same MCP product through Cargo:\n\n```sh\ncargo install weavatrix\nweavatrix mcp .\n```\n\n### Codex\n\n```toml\n# ~/.codex/config.toml\n[mcp_servers.weavatrix]\ncommand = \"npx\"\nargs = [\"-y\", \"weavatrix\", \"mcp\", \".\"]\n```\n\n### Claude Code\n\n```sh\nclaude mcp add weavatrix -- npx -y weavatrix mcp .\n```\n\n### Grok\n\n```sh\ngrok mcp add weavatrix -- npx -y weavatrix mcp .\n```\n\nEverything after `--` is the server command, so `-y` reaches `npx` instead of\nGrok. The equivalent hand-written entry:\n\n```toml\n# ~/.grok/config.toml\n[mcp_servers.weavatrix]\ncommand = \"npx\"\nargs = [\"-y\", \"weavatrix\", \"mcp\", \".\"]\nstartup_timeout_sec = 120\n```\n\nThe package unpacks to roughly 40 MB, so the first `npx` launch can spend\nlonger fetching it than Grok's 30-second default startup timeout allows.\n`startup_timeout_sec` covers that once; `npm i -g weavatrix` or\n`cargo install weavatrix` removes the cold start for every later session.\n\nUse `--scope project` to write `.grok/config.toml` inside a repository instead,\nso a clone carries the server with it.\n\n### Cursor\n\n```json\n// ~/.cursor/mcp.json\n{\n \"mcpServers\": {\n \"weavatrix\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"weavatrix\", \"mcp\", \".\"]\n }\n }\n}\n```\n\nProfiles expose bounded views of the same engine:\n\n```sh\nnpx -y weavatrix mcp . --profile=all\nnpx -y weavatrix mcp . --profile=code\nnpx -y weavatrix mcp . --profile=seo\n```\n\nThe npm package contains native binaries for Windows x64/arm64, macOS\nx64/arm64, and glibc Linux x64/arm64. It has no install script and performs no\nruntime download.\n\n### Halve every answer on a client that reads structured output\n\nAn MCP result carries the payload twice: once as `structuredContent`, and once\nmirrored into a text block for clients that read only `content`. The mirror is\nthe pretty-printed copy, so it is the larger of the two.\n\n```sh\nnpx -y weavatrix mcp . --output-format=structured\n```\n\nMeasured on `run_audit` over a real repository, the response falls from 8931 to\n3589 bytes, **59.8% smaller**. Whether a client reads structured output does\nnot change between calls, so it is chosen once at startup rather than restated\nas an argument on every call; `WEAVATRIX_OUTPUT_FORMAT=structured` does the\nsame where a flag is awkward, and a call that names its own `output_format`\nstill wins.\n\n`json` is the default and keeps the mirror, because a client that ignores\n`structuredContent` would otherwise see an empty result. `text` returns the\nconcise text block alone.\n\n## What an agent can ask\n\n```text\nWhat breaks if I change src/auth/middleware.ts?\nTrace POST /api/orders through this backend and its clients.\nWhich production symbols are dead, and what evidence proves it?\nShow duplicate implementations but suppress router boilerplate.\nWhich dependency violates .weavatrix/architecture.json?\nFind every GraphQL, gRPC, Kafka, RabbitMQ, NATS, JMS, SQS, or SNS\ncontract affected by this branch.\nBuild the smallest source bundle needed to edit this symbol safely.\nShow me this file as it was two commits ago, without a checkout.\nSuggest internal links without mixing inferred SEO relationships into\nthe deterministic code graph.\n```\n\nThe graph is built once per revision. Impact, API traces, health findings,\narchitecture checks, clone families, and context bundles therefore agree about\nrepository identity instead of recomputing incompatible partial views.\n\n## See it answer\n\nReal answers from Weavatrix analyzing its own repository at commit\n`ec8bf30`, abridged (`…`) and with the local root shortened. Reproduce any of\nthem with `weavatrix tool . ''`.\n\n**Orient in one call** — and know exactly which repository and revision\nanswered:\n\n```json\n{\"name\": \"graph_stats\", \"arguments\": {}}\n```\n\n```json\n{\n \"nodes\": 1294,\n \"edges\": 2771,\n \"freshness\": {\"state\": \"CURRENT\", \"source_revision\": \"sha256:dd3d96d3…\"},\n \"relations\": {\"calls\": 651, \"contains\": 1271, \"imports\": 419, \"references\": 314, \"…\": \"…\"},\n \"repository_context\": {\n \"root\": \"…/weavatrix\",\n \"git_head\": \"ec8bf3041588623f23ec5e7ebbaff3a333da9ca7\",\n \"scan_revision\": \"sha256:dd3d96d3…\",\n \"graph_age_seconds\": 0\n }\n}\n```\n\nEvery answer carries that `repository_context` block. Add\n`\"expected_repository\": \"weavatrix\"` to any call and a server that was\nretargeted elsewhere fails loudly instead of answering about the wrong\nrepository.\n\n**Blast radius before you edit:**\n\n```json\n{\"name\": \"get_dependents\", \"arguments\": {\"label\": \"file:src/mcp/server/mod.rs\", \"max_nodes\": 6}}\n```\n\n```json\n{\n \"dependents\": [\n {\"distance\": 1, \"node\": {\"id\": \"file:src/main.rs\", \"language\": \"rust\"}},\n {\"distance\": 1, \"node\": {\"id\": \"file:src/mcp/mod.rs\"}},\n {\"distance\": 1, \"node\": {\"id\": \"file:src/mcp/server/tests/catalog.rs\"}},\n {\"…\": \"…\"}\n ]\n}\n```\n\n**The file as it was — no checkout** (`git_read_blob`):\n\n```json\n{\"name\": \"git_read_blob\", \"arguments\": {\"path\": \"Cargo.toml\", \"revision\": \"HEAD~3\", \"max_bytes\": 400}}\n```\n\n```json\n{\n \"path\": \"Cargo.toml\",\n \"revision\": \"70b5bc788a10ec89ab28b9ecbc005e3b9c7f9829\",\n \"oid\": \"f5f54bac00a4feb6e965c0d87c5c6d4d25782e91\",\n \"kind\": \"utf8-text\",\n \"lines\": [\"[package]\", \"name = \\\"weavatrix\\\"\", \"version = \\\"1.9.2\\\"\", \"…\"],\n \"size_bytes\": 1224,\n \"returned_bytes\": 400,\n \"truncated\": true\n}\n```\n\nThree commits before `ec8bf30` this package was 1.9.2; the agent reads that\nfollow-up to a diff without touching the worktree. Binary blobs fail closed\ninstead of being decoded into garbage.\n\n## The 44 read-only operations\n\n| Workflow | Operations |\n| --- | --- |\n| Graph orientation | `graph_stats`, `get_node`, `get_neighbors`, `query_graph`, `god_nodes`, `shortest_path`, `get_community`, `list_communities`, `module_map`, `build_graph` |\n| Change impact | `get_dependents`, `change_impact`, `select_tests`, `verified_change`, `prepare_change`, `graph_diff` |\n| Exact source context | `search_code`, `read_source`, `inspect_symbol`, `context_bundle`, `map_stacktrace` |\n| Health and quality | `find_duplicates`, `find_dead_code`, `run_audit`, `coverage_map`, `hot_path_review` |\n| APIs and transports | `list_endpoints`, `trace_endpoint`, `trace_api_contract` |\n| Architecture | `get_architecture_contract`, `verify_architecture`, `verify_capabilities`, `explain_architecture_violation`, `propose_architecture_exception` |\n| Git and repositories | `git_history`, `git_read_blob`, `cross_repo_git`, `open_repo`, `list_known_repos`, `rebuild_graph` |\n| Native extensions | `vector_search`, `semantic_link`, `seo_link_suggestions`, `memory_context` |\n\nEvery operation is read-only with respect to the analyzed repository.\nPagination and explicit limits bound large neighborhoods, histories, searches,\nand contract inventories.\n\n## Languages and repository surfaces\n\nThe engine recognizes 24 named surfaces across 65 registered extensions.\nSupport is evidence-specific: lossless tokenization is not presented as typed\nsemantic resolution.\n\n| Group | Surfaces |\n| --- | --- |\n| Code | Rust; JavaScript/JSX; TypeScript/TSX; Python; Go; Java; C#; C; C++; SQL; Bash/Zsh; Swift; Solidity |\n| Contracts and configuration | GraphQL; Protobuf/gRPC; JSON/JSONC; YAML/Kubernetes; Terraform/HCL; XML |\n| Documents and UI | HTML/Vue/Svelte; CSS/SCSS/Sass/Less; Markdown/MDX; reStructuredText; AsciiDoc |\n\nCross-surface passes connect HTTP routes and calls, GraphQL operations and\nschema types, gRPC services and streaming modes, and Kafka, RabbitMQ/AMQP, JMS,\nNATS, SQS, and SNS producers and consumers. Package manifests, lockfiles,\ncoverage artifacts, and architecture contracts become evidence too.\n\nDynamic dispatch that cannot be proved stays unresolved. Static reachability is\nnot called measured coverage, and absent optional evidence remains explicitly\nabsent.\n\n## Product boundary\n\nWeavatrix is deliberately split into a protocol-independent engine and a thin\nproduct adapter:\n\n```text\ncoding agent\n |\n | MCP over stdio\n v\nweavatrix 1.10.0\n profile catalog · session refresh · filesystem watcher · MCP framing\n |\n v\nweavatrix-rust 2.9.0\n typed graph · analysis pipeline · 44 read-only operations\n |\n +-- weavatrix-scan repository discovery and selection\n +-- weavatrix-parse lossless tokenization and structural facts\n +-- weavatrix-graph graph model and algorithms\n +-- weavatrix-git direct Git-object evidence\n +-- weavatrix-search bounded content and index search\n +-- vector / clone / semantic / memory components\n```\n\nThis repository owns the MCP transport, watcher, native npm packaging, and\nclient-facing identity `weavatrix`. The\n[`weavatrix-rust`](https://github.com/Weavatrix/weavatrix-rust) crate owns\nthe reusable engine and standalone diagnostic CLI; it is not an MCP server.\nIts separate binary therefore reports `weavatrix-rust ` from\n`--version`, while this product reports both the `weavatrix` product version\nand its embedded engine version.\n\nRust applications that want to embed the engine should depend on the crate:\n\n```toml\n[dependencies]\nweavatrix-rust = \"2\"\n```\n\n```rust\nuse weavatrix_rust::{Weavatrix, operations};\n\nlet mut engine = Weavatrix::open(\".\")?;\nlet result = operations::call(\n &mut engine,\n \"change_impact\",\n blazingly_json::json!({\"target\": \"src/auth.rs\"}),\n)?;\n# Ok::<(), weavatrix_rust::Error>(())\n```\n\n## Release evidence\n\nThe release gate measures the installed npm boundary, not an in-process\nmicrobenchmark. Each side is packed, installed into an isolated npm root, and\nstarted with empty HOME, XDG, AppData, and graph caches. The harness validates\npackage/native/initialize identity, advertised operations, successful MCP\nresults, and process cleanup.\n\nThe packaged 1.2.0 product, backed by `weavatrix-rust` 2.1.1, was measured on\n2026-08-03 against installed `weavatrix-js` 0.3.15 on the same real\nJavaScript service repository (2,165 nodes / 5,712 edges), three paired fresh\nprocesses per tool with alternating start order:\n\n| Installed boundary | Rust 1.2.0 | JavaScript 0.3.15 | Ratio |\n| --- | ---: | ---: | ---: |\n| Cold boundary median (spawn to first tool result) | **157.34 ms** | 5,068.22 ms | **32.21x** |\n| Paired cold speedup, median of 6 pairs | - | - | **32.06x** |\n| Warm tools/call median | **7.94 ms** | 292.55 ms | **36.85x** |\n\nBoth release thresholds (24x cold, 30x warm) passed, and the paired cold\nmedian sits slightly above the 30.34x recorded for the 1.0.0 baseline, so the\nthree new tools, token budgets, and dependency-injection evidence did not\nregress the installed boundary. Raw evidence and methodology live in\n[`benchmark-results`](benchmark-results/) and\n[`docs/benchmarks.md`](docs/benchmarks.md).\n\n## Safety and determinism\n\n- read-only MCP surface;\n- no source-writing operation;\n- no execution of repository code;\n- no spawned `git`, `rg`, language server, Node, or Python from the native\n engine;\n- no network path in repository analysis;\n- no npm install script or post-install binary download;\n- bounded files, bytes, results, histories, and pagination;\n- stable ordering and revision provenance;\n- `unsafe` Rust forbidden in first-party engine crates;\n- MIT license for the product, engine, and maintained first-party components.\n\nFilesystem watching only invalidates derived state. The next operation performs\na bounded refresh; it never edits the repository. Watching costs constant\nmemory: every event is classified as it arrives and collapses into one pending\nchange flag, so build output churning under `target/` or `node_modules/` never\naccumulates in a server that is sitting idle between tool calls.\n\n## Architecture and development\n\nThe product adapter follows ports and adapters:\n\n```text\ninbound MCP server\n |\napplication session\n |\nrepository + change-monitor ports\n |\nweavatrix-rust adapter · notify adapter\n```\n\n`mcport` is isolated to the inbound server. The application layer sees neither\nMCP frames nor `notify` events, and the engine sees neither dependency.\n\nLocal gates:\n\n```sh\ncargo fmt --all -- --check\ncargo clippy --all-targets -- -D warnings\ncargo test --all-targets\n```\n\nNative npm artifacts are built by `scripts/build-npm-packages.mjs`; publication\nis performed by the protected GitHub Actions workflow after all platform\nbinaries, identity checks, package checks, and installed-boundary gates pass.\n\n## Documentation\n\n- [Getting started](docs/getting-started.md)\n- [Tool reference](docs/tool-reference.md)\n- [Evidence model](docs/evidence-model.md)\n- [Language support](docs/language-support.md)\n- [MCP product architecture](docs/mcp-and-standalone.md)\n- [npm distribution](docs/npm-distribution.md)\n- [Dependencies](docs/dependencies.md)\n- [Benchmarks](docs/benchmarks.md)\n- [Engine API and architecture](https://github.com/Weavatrix/weavatrix-rust)\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
"bytes": 17310,
"sha": "6477a38ceffa668f9dee93f659ea37997017906c19fe0a14f0dd47add2ded5d5",
"repo_slug": "weavatrix/weavatrix",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_weavatrix_weavatrix_87b4bd41/readme"
}