weavatrix-js

name	weavatrix-js
description	Use the Weavatrix MCP as a reusable local repository-intelligence layer: understand unfamiliar applications with a bounded code graph, reduce repeated context, review Health, dead code, duplicates and history, trace endpoints and blast radius, enforce target architecture, and verify changes before a PR.

weavatrix MCP

Structure-analysis tools over a prebuilt code graph plus the weavatrix analysis engines. The default offline profile contains no HTTP tool and permits repository switching only through an explicit local open_repo call. Use pinned when a shared MCP process must never change or inspect outside its startup repository.

Step 0 — if the tools are missing

Tools are named mcp__weavatrix__…. If none are available, ask the user to register the server (claude mcp add -s user weavatrix-js -- npx -y weavatrix-js <repoRoot>; Codex: codex mcp add weavatrix-js -- npx -y weavatrix-js <repoRoot>), then retry.

First compare the selected profile with the graph_stats runtime line. Expected catalogs are 31 tools for pinned and 34 for offline. Weavatrix refuses initialize, tools/list, and tool calls when the running package version differs from the package.json version on disk, with a loud STALE_RUNTIME error; restart/reconnect rather than using an old daemon. WEAVATRIX_ALLOW_STALE_RUNTIME=1 is only for deliberate source development. A custom capability list needs crossrepo for trace_api_contract. Legacy network profile names fail loudly and direct the user to the separate weavatrix-online package.

Profiles use the same npm package and binary:

• offline (default): all local analysis and explicit open_repo; no HTTP tools.
• pinned: local analysis with no open_repo, no global/cross-repository graph access, and no HTTP tools.

Intent router

Weavatrix is not one report or three fixed workflows. Its 34 methods expose different bounded views and analyses over the same reusable graph. Start from the task and choose the smallest sufficient projection; expand only when the answer requires it.

Graph views and application understanding

• Confirm repository, graph freshness and build mode: graph_stats; use rebuild_graph only for a reported fallback/error or an intentional mode/precision change.
• Switch or inventory local repositories: list_known_repos -> open_repo -> graph_stats.
• See production module topology: module_map; use this first for a large unfamiliar application.
• See discovered communities and their members: list_communities -> get_community.
• Find high-coupling hubs: god_nodes; repeated call sites do not inflate unique connectivity.
• Inspect one graph entity: get_node; pass an exact node ID when labels are ambiguous.
• Inspect direct one-hop relations: get_neighbors; do not confuse it with transitive impact.
• Find a connectivity path between two concepts: shortest_path. It traverses the graph as undirected reachability, so it is not proof of call/dependency direction; confirm direction with get_neighbors and read_source.
• Explore an unknown entry point or architectural question: query_graph; pin seed_files or exact seed_symbols when known. Use relation_filter plus flow_direction for a bounded event, worker, queue, cron, CLI, or data-flow view; keep a broad natural-language result as orientation evidence.
• Inspect one exact symbol deeply: context_bundle for the bounded edit workset; inspect_symbol for the raw point query and on-demand JS/TS reference evidence.
• Confirm graph evidence in source: read_source; use search_code only for a narrow regex/glob check. Search is supporting evidence, not the repository-intelligence layer.

Runtime, API and change scenarios

• Inventory HTTP routes: list_endpoints for declared/reachable composed paths and mount proof.
• Trace one endpoint through the application: trace_endpoint for route -> handler -> bounded downstream call flow with edge-centered excerpts.
• Trace an API contract across repositories: list_known_repos -> trace_api_contract with an explicit backend/client set; prefer this over separate per-repository endpoint/search passes when a backend change may affect registered clients, and inspect each graph reconciliation state before using the verdict.
• Measure one symbol's transitive blast radius: get_dependents.
• Review the current branch, diff, or external patch: change_impact; its explicit baseline parameter is base, not the base_ref used by audit/diff/verification tools. It distinguishes additive exports from signature/body/removal risk and separates runtime/type-only radius plus available measured coverage or explicitly static reachability.
• Compare structural graph revisions: graph_diff base_ref=<merge-base> for module edges, cycles, orphans and lost callers; without base_ref, compare the last rebuild snapshots.
• Use behavioral history: git_history for churn x connectivity, hidden co-change and expected test/source coupling from bounded local Git numstat evidence.
• Plan and verify a serious change or pre-commit gate: verified_change task=<same-task> phase=plan base_ref=<merge-base> -> edit -> verified_change task=<same-task> phase=verify base_ref=<same-ref>. It composes exact context, impact, graph, architecture, duplicate, optional API and test proof into one PASS/BLOCKED/UNKNOWN envelope. It is a proof layer around an agent's edit, not a source editor or hidden auto-fix.

Health, debt and testing scenarios

• Run a whole-repository Health review: run_audit debt=all, then read its capability matrix. STRUCTURE CHECKED and DEPENDENCIES CHECKED do not imply runtime or concurrency correctness.
• Gate only newly introduced branch debt: run_audit base_ref=<merge-base> debt=new; old debt in a changed file remains existing.
• Review dependency declarations/imports: run_audit category=dependencies; it includes missing, unused, duplicate, unresolved-import and lockfile-drift evidence without relabelling identities. Maven/Gradle imports are mapped to exact artifact ownership when the referenced class is present in an already installed local JAR. Missing artifacts, ambiguous class owners, version catalogs or dynamic build logic remain PARTIAL/NOT_SUPPORTED, never a false clean 0 declared / 0 external.
• Review dependency integrity: run_audit category=dependencies; vulnerability and malware review are explicit weavatrix-online workflows and are absent from this local package.
  • Review dead files, functions, methods and symbols: find_dead_code; every result remains a review candidate with framework/dynamic/public-API caveats, never an auto-delete verdict.
  • Trace dynamic GraphQL/gRPC/Kafka contracts: export a source-free weavatrix.transport-runtime.v1 JSON report (normalized observations or OTLP resourceSpans) to .weavatrix/transport-runtime.json, rebuild the graph, and call trace_api_contract. Only a fresh report whose repositoryRevision matches graphRevision and whose observation maps to the dynamic file/line resolves that UNKNOWN; missing capture remains unknown.
• Review clone families or same-name divergence: find_duplicates; framework router boilerplate and immutable declarative catalog shapes stay suppressed unless explicitly included.
• Map measured coverage or honest static test reachability: coverage_map; unavailable measured coverage is not 0%.
• Prioritize local performance-review candidates: hot_path_review; confirm with a profiler or benchmark before changing runtime behavior.

Intended architecture

• Read or establish intended architecture: get_architecture_contract. A returned starter adapts to Maven/Gradle source roots and monorepos and proposes product-code territories plus observed dependency directions labelled OBSERVED_NOT_ENFORCED; oversized Java branches split only at real child packages. Only runtime-cycle and 300-line file guards are active by default; generic complexity/cohesion thresholds are CANDIDATE_NOT_ENFORCED. None becomes policy automatically.
• Bootstrap local policy safely: get_architecture_contract action=preview with an optional reviewed candidate_contract and baseline_mode=none|accept-current; inspect the exact content, verification and patch, then call action=approve confirm_token=<exact-token>. Approval creates only a missing .weavatrix/architecture.json, rechecks graph identity, and never overwrites policy.
• Select rules before editing: prepare_change; enforce the ratchet after editing: verify_architecture.
• Understand or request an exception: explain_architecture_violation -> propose_architecture_exception; proposals never mutate policy automatically. After human approval, the owner must add the returned proposal to the local contract's exceptions; remote governance belongs to weavatrix-online.

Across every scenario, treat PARTIAL, UNAVAILABLE, OFF, NOT_SUPPORTED, NOT_CHECKED, ERROR, or capped evidence as incomplete rather than success. Java and Rust exact language-server providers are not bundled, so their edges never become EXACT_LSP even when a mixed repository has a complete TypeScript/JavaScript overlay. Java and Go receiver-type call edges are parser-resolved and explicitly INFERRED; Go resolution uses parameter, local, constructor-return, imported and struct-field types. These edges improve cross-file flow without claiming compiler-exact overload, interface dispatch, reflection, or runtime behavior.

Ground rules

• No hidden source mutation: Weavatrix builds derived graph/cache artifacts and can run explicitly authorized tests, but it does not edit repository source, auto-delete debt, merge clones, or rewrite architecture policy. The coding agent remains responsible for the change and its tests.

• Evidence, not verdicts: treat audit, hub, orphan and duplicate output as hypotheses. Confirm a finding in source and check framework/runtime conventions before deleting, merging or redesigning code. A same-name/different-body pair is a divergence candidate, not proof of duplication.

• Freshness: the graph is always fresh at answer time — no watcher process and no manual refresh step exists or is needed. Every graph/health call runs a debounced Git freshness probe and, when the repository changed, refreshes before answering (bounded incremental reparse of changed files plus reverse importers for JS/TS; full rebuild for config/export-surface/barrel changes and other languages). Cross-repository tracing reconciles every selected registered graph the same way. Read the structured refresh / graphReconciliation status: none, incremental, full, or explicitly PARTIAL. Use rebuild_graph only when automatic reconciliation reports a fallback/error or when intentionally changing build mode. A normal open_repo builds missing graphs and upgrades legacy schemas; build:false deliberately refuses that upgrade.

• Ambiguity: get_node/get_neighbors/get_dependents disclose matched N nodes; using the best-connected — read that note before trusting the answer; pass an exact node id to pin it.

• Runtime versus compile time: keep runtime cycles separate from TypeScript type-only and language compile-only coupling (Rust mod/use/pub use, Java imports). module_map, change_impact and graph_diff label the distinction; god_nodes ranks unique connectivity and reports repeated references separately. Do not schedule a runtime-cycle refactor from compile-time-only edges.

• Edge provenance: distinguish how an edge was established from legacy confidence. The parser emits EXTRACTED, RESOLVED, and ; the bundled bounded TypeScript/JavaScript language server emits only for references it confirms. means evidence disagrees. Treat , , , , and as review signals rather than compiler-exact facts; an count or revision-mismatched overlay in requires a rebuild before precision-sensitive work.

Recipes

• Proof-carrying refactor: verified_change task=<same-task> phase=plan base_ref=<merge-base> -> edit -> verified_change task=<same-task> phase=verify base_ref=<same-ref> tests=[{"script":"test","args":[...]}]. Repeat task on both calls; it is required and is not retained between invocations. Add run_tests:true only when test execution was authorized. BLOCKED means an evidenced ratchet or test failure; UNKNOWN means at least one required proof is incomplete.

• Orient in the configured repo: module_map → list_communities → god_nodes. Hub ranking is production-only by default; use include_classified:true only when tests/generated/build surfaces are deliberately part of the question.

• Refactor safety for one symbol: context_bundle → optional inspect_symbol when raw LSP occurrences, ambiguity details or the larger source window are needed → get_dependents → coverage_map (low coverage × many dependents ⇒ write tests first) → edit → verified_change task=<task> phase=verify base_ref=<merge-base>.

• Performance review: hot_path_review → inspect its local evidence with read_source → use get_dependents for change risk → confirm with the repository's profiler/benchmark before editing.

• Pre-PR review of your current changes: change_impact (auto merge-base; includes uncommitted and untracked work, coverage attached, untested hotspots called out) → drill with get_dependents.

• Impact of a PR that is NOT checked out: pass its changed-file list explicitly — change_impact files=[…] — same blast-radius + coverage view, no checkout.

• Validate a refactor structurally: call graph_diff base_ref=HEAD~1 (or main / origin/main) to build an immutable baseline without checkout and compare it with the current graph. Alternatively, edit → rebuild_graph, then use graph_diff without base_ref to compare graph.prev.json with the rebuilt graph. Either route can be scoped by ; look for cycle, module-dependency and orphan drift rather than raw edge counts.

Repository-specific conventions

Weavatrix understands nearest workspace manifests, nested tsconfig/jsconfig aliases, framework-owned runtime peers such as Next.js + react-dom, generated NAPI-RS platform loaders, and Next.js App Router route exports. Use repository-root .weavatrix.json to correct ambiguous production classification without deleting graph evidence:

{
  "classify": {
    "generated": ["src/generated/**"],
    "test": ["qa/**"],
    "product": ["benchmarks/core/**"]
  },
  "exclude": ["resources/snapshots/**"]
}

Use generated / test (or e2e, mock, story, docs, benchmark, temp) for non-production code, top-level exclude for resource/catalog roots that should stay visible in the graph but not drive production-first Health/query ranking, and product only to opt a verified benchmark/temp path back into production review. product does not override an explicit generated/test classification or exclude. Use .weavatrixignore instead only when a path must be removed consistently from graph, audit and duplicate scans.

For project-specific entry points, reusable template catalogs, or Python dependencies supplied by an external runtime, add .weavatrix-deps.json at the repository root:

{
  "entrypoints": ["scripts/publish-release.mjs"],
  "nonRuntimeRoots": ["library", "catalogs/examples"],
  "python": {
    "managedDependencies": ["numpy", "openvino-genai"],
    "ignoreDependencies": ["vendor-sdk"]
  }
}

Keep exceptions narrow. nonRuntimeRoots (alias templateRoots) marks reusable examples that are not one deployed application. It suppresses orphan/dead/unused-export noise and missing/unresolved dependency findings when every use is inside those roots; graph edges, cycles and boundaries remain visible. managedDependencies documents modules provided outside the repo's Python manifest; ignoreDependencies suppresses intentionally unresolved imports.

Online extensions

This package is the MIT, network-free core. If refresh_advisories, online_status, preview_sync, pull_architecture_contract or sync_graph is required, use the separately installed weavatrix-online MCP and follow its skill. Do not attempt to enable a legacy profile here: the online, osv, hosted and full names fail loudly and cannot add network code to this artifact.

Troubleshooting

• Graph unavailable → rebuild_graph; normal graph/health calls automatically refresh an existing graph and report none, incremental, or full. open_repo can select another valid repository path unless the registration deliberately omitted retarget.
• An Online-only tool is unavailable → keep this core registration network-free and configure the separate weavatrix-online MCP only when the user actually wants Cloud or Enterprise integration.
• No coverage report → run the repo's own tests with coverage (vitest run --coverage, jest --coverage, pytest --cov --cov-report=json, go test -coverprofile=coverage.out), then re-call.
• change_impact says files are "not in the graph" → they're new/renamed; rebuild_graph and retry.