wxgraph-mcp
Provides semantic code graph tools for native WeChat mini-programs, indexing app.json manifests, WXML templates, and JavaScript to answer impact and re-render queries, explain setData propagation, search nodes and data paths, and report parser statistics.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
English | 简体中文
Why WXML needs its own graph
A mini-program is not just JSON and JavaScript. The render behaviour lives in
.wxml templates: {{item.unitPrice}} is fed by a data field, bind:edit="onEdit"
is a handler owned by a page or component, and <price-card price="{{...}}">
crosses a component boundary through a declared property. app.json adds
subpackage routing; usingComponents adds a component registry expressed three
different ways (root-absolute, relative, npm specifier).
Code-graph tooling generally has no WXML grammar, so a mini-program indexes as
loose JSON and JS. That graph looks populated and misses the only edges that
explain a render: which field feeds which binding, which handler owns the
setData, and which element re-renders afterwards. Grep returns every textual
mention; it does not return a path through those hops.
wxgraph parses the manifest, the templates and the scripts, then resolves them
into one graph. The owned edge is rerenders: a setData key resolved through
a data path, a host attribute and (when the value crosses a component boundary)
a declared property, down to a concrete WXML element. Every edge carries
file:line provenance. When a hop does not resolve, no edge is emitted, and
the miss is never silent: impact lists the failed hop with its status and
explain prints every attempt.
Related MCP server: Girder
Quickstart
Requires Node 22 or newer. The repository ships a small synthetic mini-program in
examples/demo so the first result is two commands away.
git clone https://github.com/SuperMarioYL/wxgraph.git
cd wxgraph
npm ci
npm run build
node dist/cli.js build examples/demo
node dist/cli.js impact components/price-cardbuild indexes the project and writes the graph:
1 subpackage · 3 pages · 1 component · 19 wxml nodes · 57 edges · 34ms
wrote examples/demo/.wxgraph/graph.jsonimpact answers the blast-radius question from the graph, with no cd and no
-C: the build recorded the project for the directory it ran in
(.wxgraph/config.json).
components/price-card (component) included by 2 hosts
├─ pages/cart/index.wxml:5 <price-card editing="{{editing}}" price="{{item.unitPrice}}">
│ ← data editing (pages/cart/index.js)
│ ← data items[].unitPrice (pages/cart/index.js)
│ ├─ setData({items, editing}) in onEdit pages/cart/index.js:20 → <text> components/price-card.wxml:2 [via prop:price]
│ └─ setData({items, editing}) in onEdit pages/cart/index.js:20 → <view> components/price-card.wxml:4 [via prop:editing]
└─ pages/order/detail.wxml:4 <price-card price="{{order.total}}">
← data order.total (pages/order/detail.js)
├─ setData({order, order.no, order.total}) in onLoad pages/order/detail.js:11 → <text> components/price-card.wxml:2 [via prop:price]
└─ setData({order.total}) in onEditPrice pages/order/detail.js:17 → <text> components/price-card.wxml:2 [via prop:price]
1 unresolved_setdata site(s):
pages/cart/index.js:12 in onLoad this.setData(<non-literal>)Counts and file:line values are stable for the shipped demo; the build timing
depends on the machine. The full recorded run, including --json, is in
docs/demo-results.json.
npm link (or npm install -g .) puts wxgraph and wxgraph-mcp on your
PATH; the commands above then read wxgraph build examples/demo and so on.
Demo
Reading the answer:
Host lines are the templates that include
components/price-card.pages/cart/index.wxml:5passes two properties;pages/order/detail.wxml:4passes one.← data …is the page data path that feeds the property afterwx:foraliases are resolved (item.unitPricebecomesitems[].unitPrice).setData({…}) in <handler>is one resolved re-render, with the call site and the element it re-renders.[via prop:price]means the value crossed the component's declaredpriceproperty;[via direct]means the element sits in thesetDataowner's own template.unresolved_setdatais not an error and not a guessed edge:onLoadpasses a non-literal object tothis.setData, so the graph records the call site and says which keys it cannot know. A hop that fails to resolve for a different reason (no_binding,unknown_property,no_child_binding) appears above it in anunresolved hop(s)block with the same status and detailexplainuses.
How it works
app.json + *.json ─┐
*.wxml ────────────┼→ parse (manifest | wxml | acorn module→script) → resolve → .wxgraph/graph.json
*.js ──────────────┘ │
├→ wxgraph CLI
└→ wxgraph-mcp (stdio)Six node kinds and eight edge kinds cover the model:
Node | What it records |
| unit id, template path, declared component properties |
| WXML tag, line, owning template, |
| normalised path, e.g. |
| method name, owning unit, line |
| call line and literal keys ( |
| cloud-function name from a |
Edges are contains, includes, in_subpackage, binds, handles,
calls_setdata, invokes, and the owned rerenders. There is no daemon, no
network call and no database: the graph is a JSON file with a source stamp.
Every .js file the project walk sees is parsed — page and component scripts,
utility modules and anything else — because an unreadable helper is still a gap
in the graph. Parsing is ES module first with a per-file classic-script retry;
a file that fails both becomes an unresolved_file warning carrying its parse
error, and wxgraph stats prints how many .js files were seen, parsed and
unresolved, so the miss is never a silent gap. .ts sources are counted in the
same line and warned as unsupported_ts: v0.1 does not analyse them.
Usage
wxgraph init [dir] # find app.json and record the project for this directory
wxgraph build [dir] # index a mini-program; writes .wxgraph/graph.json
wxgraph impact <target> # what re-renders when this changes
wxgraph impact <target> --up # walk the hosts that include this target
wxgraph impact <target> --json # structured result for machines
wxgraph impact <target> -C dir # query a project other than the cwd
wxgraph explain <edge> # every hop behind one setData site or element
wxgraph search <query> # find node ids, data paths and setData keys
wxgraph stats # counts plus what the parser could not read<target> accepts a unit id (components/price-card), a template path
(components/price-card.wxml), or an element id
(components/price-card.wxml:4:view). <edge> accepts a set_data node id
(pages/cart/index:20), a file:line call site (pages/cart/index.js:20), or
an element id. explain prints the resolved hops and the failed ones with their
status: non_literal, no_binding, unknown_property, no_child_binding;
impact prints the failed hops that touch the target under unresolved hop(s).
init writes .wxgraph/config.json in the directory you run it from, with the
project it discovered. build records the same file when the project is not the
cwd, so a query with no -C uses the graph in the cwd, or the project recorded
there by init or the last build.
Query commands verify the graph stamp before answering. A missing or stale graph is refused with one line:
wxgraph: graph is stale (sources changed since the last build) — run wxgraph buildExit codes. 0 on success. 1 for an expected runtime failure — missing or
stale graph, unknown target, unreadable app.json. Those failures are one line
on stderr prefixed wxgraph:, with no stack trace. Command-parser errors (an
unknown command or option) also exit 1.
MCP server
wxgraph-mcp serves the graph over stdio and refuses a stale graph the same way
the CLI does. Any MCP client works — Gemini CLI, Cursor, or your own agent loop.
After npm link (or npm install -g .), point the client at the binary:
{
"mcpServers": {
"wxgraph": {
"command": "wxgraph-mcp",
"args": ["--project", "/absolute/path/to/miniprogram"]
}
}
}Tool | Use it for |
| blast radius of a page, component or element; |
| every hop behind one |
| find a node id by name, path, tag or |
| counts, warnings, unreadable |
| re-index after editing WXML, JSON or JS |
The same routing logic is packaged as a Skill: copy skills/wxgraph into your
agent's skills directory (for example cp -r skills/wxgraph .claude/skills/) and
the agent gets one instruction — query the graph before grepping nine templates.
What v0.1 covers
Implemented, and exercised by the test suite:
Manifests.
app.jsonpages,tabBarentries, bothsubpackagesandsubPackages, each entry'srootandindependentflag.Component registry. Page/component
.jsonusingComponents, every file markedcomponent: true, and app-levelusingComponents. Specifiers resolve as root-absolute, relative, or npm specifier underminiprogram_npm/<pkg>with anode_modules/<pkg>fallback.Templates. Elements with tag and line,
wx:for/wx:for-item/wx:for-index/wx:key,wx:if, slots, bindings in attributes and text, and nested loops. Handler attributes in both spellings — concatenated (bindtap,catchtap) and colon (bind:tap,catch:tap,capture-bind:tap,capture-catch:tap,mut-bind:tap) — normalise to the samehandlesedge with the bare event and the modifier kept separately.Scripts.
Page({...}),Component({ methods: {...} }), handler methods, literal and nested-literalsetDatakeys, non-literalsetDatasites, declared componentproperties, andwx.cloud.callFunctioncall sites. Every.jsfile in the walk is parsed and counted instats;.tsfiles are counted and warned, not analysed.Impact.
setDatakey → data path → host attribute → component property → child binding → element, closed only when every hop resolves. Failed hops are printed, andimpact --upwalks theincludesedges back to every caller.
Not in v0.1 — stated so the graph's silence is not mistaken for an answer:
Native
.wxmlprojects only. Taro, uni-app and kbone compiled output are not analysed..jssources only..tsfiles are counted and warned bywxgraph stats; they are not analysed.No WXSS or layout edges.
Cloud-function bodies are not parsed; only call sites are recorded.
WXML expressions are read for data paths, not evaluated. Ternaries and method calls are not computed.
A resolved edge does not prove a runtime render: a
wx:ifguard can still be false. The graph reports the structural path; the platform decides.No watch mode or incremental reindex. Re-run
wxgraph buildafter edits.
Roadmap
0.1.0 ships the full v0.1 pipeline: the manifest and WXML graph, script
linking, the resolved rerenders closure with impact and explain, and the
agent surface (MCP server, Skill, recorded demo).
Next candidates, in the order they unblock real-repo use:
A fixture corpus from real native mini-programs, starting with the templates the current tests do not cover.
.tspage and component sources.A JSON Schema for
graph.jsonso other tools can consume the graph without vendoring the model.Watch mode on top of the existing source stamp.
Explicitly not planned: a hosted service, a web UI, accounts or telemetry. v0.1 is a local tool with a query surface.
Development
npm run typecheck # tsc --noEmit
npm run build # tsup → dist/cli.js, dist/mcp/server.js
npm test # vitest runThe test suite covers the parsers, the graph builder, the property-hop resolver,
the failed-hop reporting, the caller walk, search, the script/.ts counters, the
stale-stamp contract, and the shipped demo's CLI output. examples/demo is part
of the contract: the CLI tests build it, then query it from the repository root
exactly as the quickstart does.
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Codebase knowledge graph — architectural awareness for AI coding agents via MCP
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
Ask who calls a route, what a change breaks or who reads a field, across a system's repos.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables developer agents to perform semantic codebase search, dependency and impact analysis, cross-file refactoring, and full-stack API tracing through a unified query DSL over a high-performance graph engine.-
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to query a semantic code graph over MCP, retrieving exact function source, definitions, callers/callees, impact analysis, and minimal test selection instead of whole files.15Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to query a precise, local call/type/data graph so they can find who calls what, what breaks when code changes, and which tests to run, with every answer traced to file:line.99 PyPI1Functional Source , Version 1.1, ALv2 Future
- AlicenseNot gradedqualityCmaintenanceEnables coding agents to query a deterministic AST knowledge graph of a codebase over MCP—finding symbols, callers/callees, dependencies, impact, and relevant tests via compact path:line JSON—so they can navigate code without grepping, embeddings, or an LLM.MIT