weavatrix

Weavatrix — native MCP repository intelligence

Give your coding agent repository evidence before it starts guessing.

Weavatrix is the native MCP product for repository intelligence. It gives Codex, Claude Code, and other coding agents 47 read-only operations over one revision-bound evidence graph: impact, architecture, APIs, Git history, duplicates, dead code, search, semantic links, and temporal memory.

It does not answer from a larger grep or an invented confidence score. Every bounded result can carry the repository revision, file, line, extractor, evidence kind, and confidence that produced it.

This npm package is the convenient prebuilt distribution of the same native product published on crates.io as weavatrix. It is not a separate JavaScript engine; both registry packages run the same Rust adapter and engine. The separately versioned weavatrix-js package is a legacy compatibility implementation and is not bundled here.

Install in 30 seconds

npx -y weavatrix mcp .

Or install the same native MCP product through Cargo:

cargo install weavatrix
weavatrix mcp .

Codex

[mcp_servers.weavatrix]
command = "npx"
args = ["-y", "weavatrix", "mcp", "."]

Claude Code

claude mcp add weavatrix -- npx -y weavatrix mcp .

Profiles expose bounded views of the same engine:

npx -y weavatrix mcp . --profile=all
npx -y weavatrix mcp . --profile=code
npx -y weavatrix mcp . --profile=seo

The package contains native binaries for Windows x64/arm64, macOS x64/arm64, and glibc Linux x64/arm64. It has no install script and performs no runtime download.

Halve every answer on a client that reads structured output

An MCP result carries the payload twice: once as structuredContent, and once mirrored into a text block for clients that read only content. The mirror is the pretty-printed copy, so it is the larger of the two.

npx -y weavatrix mcp . --output-format=structured

Measured on run_audit over a real repository, the response falls from 8931 to 3589 bytes, 59.8% smaller. Whether a client reads structured output does not change between calls, so it is chosen once at startup rather than restated as an argument on every call; WEAVATRIX_OUTPUT_FORMAT=structured does the same, and a call that names its own output_format still wins.

json is the default and keeps the mirror, because a client that ignores structuredContent would otherwise see an empty result.

What an agent can ask

What breaks if I change src/auth/middleware.ts?
Trace POST /api/orders through this backend and its clients.
Which production symbols are dead, and what evidence proves it?
Show duplicate implementations but suppress router boilerplate.
Which dependency violates .weavatrix/architecture.json?
Find every GraphQL, gRPC, Kafka, RabbitMQ, NATS, JMS, SQS, or SNS
contract affected by this branch.
Build the smallest source bundle needed to edit this symbol safely.
Show me this file as it was two commits ago, without a checkout.

See it answer

Real answers from Weavatrix analyzing its own repository at commit ec8bf30, abridged (…) and with the local root shortened. Reproduce any of them with weavatrix tool <name> . '<arguments>'.

Orient in one call — and know exactly which repository and revision answered:

{"name": "graph_stats", "arguments": {}}

{
  "nodes": 1294,
  "edges": 2771,
  "freshness": {"state": "CURRENT", "source_revision": "sha256:dd3d96d3…"},
  "relations": {"calls": 651, "contains": 1271, "imports": 419, "references": 314, "…": "…"},
  "repository_context": {
    "root": "…/weavatrix",
    "git_head": "ec8bf3041588623f23ec5e7ebbaff3a333da9ca7",
    "scan_revision": "sha256:dd3d96d3…",
    "graph_age_seconds": 0
  }
}

Every answer carries that repository_context block. Add "expected_repository": "weavatrix" to any call and a server that was retargeted elsewhere fails loudly instead of answering about the wrong repository.

Blast radius before you edit:

{"name": "get_dependents", "arguments": {"label": "file:src/mcp/server/mod.rs", "max_nodes": 6}}

{
  "dependents": [
    {"distance": 1, "node": {"id": "file:src/main.rs", "language": "rust"}},
    {"distance": 1, "node": {"id": "file:src/mcp/mod.rs"}},
    {"distance": 1, "node": {"id": "file:src/mcp/server/tests/catalog.rs"}},
    {"…": "…"}
  ]
}

The file as it was — no checkout (git_read_blob):

{"name": "git_read_blob", "arguments": {"path": "Cargo.toml", "revision": "HEAD~3", "max_bytes": 400}}

{
  "path": "Cargo.toml",
  "revision": "70b5bc788a10ec89ab28b9ecbc005e3b9c7f9829",
  "oid": "f5f54bac00a4feb6e965c0d87c5c6d4d25782e91",
  "kind": "utf8-text",
  "lines": ["[package]", "name = \"weavatrix\"", "version = \"1.9.2\"", "…"],
  "size_bytes": 1224,
  "returned_bytes": 400,
  "truncated": true
}

Three commits before ec8bf30 this package was 1.9.2; the agent reads that follow-up to a diff without touching the worktree. Binary blobs fail closed instead of being decoded into garbage.

The 47 read-only operations

Workflow	Operations
Graph orientation	graph_stats, get_node, get_neighbors, query_graph, god_nodes, shortest_path, get_community, list_communities, module_map, build_graph
Change impact	get_dependents, change_impact, select_tests, verified_change, prepare_change, graph_diff
Exact source context	search_code, read_source, inspect_symbol, go_to_definition, find_references, context_bundle, map_stacktrace
Health and quality	find_duplicates, find_dead_code, run_audit, coverage_map, hot_path_review, perf_attribution
APIs and transports	list_endpoints, trace_endpoint, trace_api_contract
Architecture	get_architecture_contract, verify_architecture, verify_capabilities, explain_architecture_violation, propose_architecture_exception
Git and repositories	git_history, git_read_blob, cross_repo_git, open_repo, list_known_repos, rebuild_graph
Native extensions	vector_search, semantic_link, seo_link_suggestions, memory_context

Every operation is read-only with respect to the analyzed repository. Pagination and explicit limits bound large neighborhoods, histories, searches, and contract inventories.

24 repository surfaces

Group	Surfaces
Code	Rust; JavaScript/JSX; TypeScript/TSX; Python; Go; Java; C#; C; C++; SQL; Bash/Zsh; Swift; Solidity
Contracts and configuration	GraphQL; Protobuf/gRPC; JSON/JSONC; YAML/Kubernetes; Terraform/HCL; XML
Documents and UI	HTML/Vue/Svelte; CSS/SCSS/Sass/Less; Markdown/MDX; reStructuredText; AsciiDoc

Cross-surface analysis connects HTTP, GraphQL, gRPC, Kafka, RabbitMQ/AMQP, JMS, NATS, SQS, and SNS evidence. Dynamic dispatch that cannot be proved stays unresolved; static reachability is never presented as measured coverage.

Product and engine are separate

coding agent
    |
    | MCP over stdio
    v
weavatrix 1.11.0
    profile catalog · refresh · watcher · MCP framing
    |
    v
weavatrix-rust 2.10.0
    typed graph · analysis · 47 read-only operations

This npm product owns MCP transport and native distribution. The weavatrix-rust crate is the reusable protocol-independent engine; it is not an MCP server. Its standalone diagnostic therefore reports weavatrix-rust <engine-version>, while this MCP product reports both its product and embedded-engine identities.

You do not need the server to use the engines

The layers underneath are separately released npm packages with their own repositories, licenses, and TypeScript types. Each one is a native library you can require directly, with no MCP server, no agent, and no dependency on any other Weavatrix package:

Package	What it does on its own
weavatrix-scan	Deterministic repository manifests: normalized paths, sizes, hashes, one revision, typed skip evidence.
weavatrix-parse	Lossless tokenization and structural facts for 25 languages, with exact spans.
weavatrix-graph	A directed graph with provenance on every edge, plus BFS, SCC, topological sort, and PageRank.
weavatrix-memory	Bitemporal, evidence-carrying agent memory with a hard token budget and an audit receipt.
weavatrix-search	Bounded ignore-aware content search, plus a persistent index updated from watcher events.
weavatrix-search-vector	Persistent, mutable vector search with metadata filters and an exact oracle.
weavatrix-clone	Type-1/2/3 clone detection with per-pair evidence and JSON, SARIF, and BigCloneEval output.

Their Node and Bun benchmarks against the JavaScript library each would otherwise replace live in one place, with the rules written down and the losing rows kept: weavatrix-benchmarks.

Release evidence

The installed-package benchmark packs both products, installs them into isolated npm roots, starts fresh MCP processes with empty caches, and validates identity, advertised operations, results, and cleanup.

The packaged 1.2.0 product (weavatrix-rust 2.1.1) was measured on 2026-08-03 against installed weavatrix-js 0.3.15 on a real JavaScript service repository: paired cold-boundary median 32.06x (spawn to first tool result: 157.34 ms vs 5,068.22 ms) and warm tools/call median 36.85x (7.94 ms vs 292.55 ms), passing the 24x cold and 30x warm release thresholds and sitting slightly above the 30.34x recorded for the 1.0.0 baseline.

Full evidence and methodology: benchmarks.

Safety

• read-only MCP surface;
• no repository-code execution or source writes;
• no network path in analysis;
• no npm install script or runtime binary download;
• bounded inputs, outputs, histories, and pagination;
• stable ordering and revision provenance;
• unsafe Rust forbidden in first-party engine crates;
• MIT licensed.

Links

• Source and issues
• Engine API
• Tool reference
• Language support
• Architecture
• Benchmarks

License

MIT.