Skip to main content
Glama
wxgraph-mcp

wxgraph-mcp

by SuperMarioYL

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-card

build indexes the project and writes the graph:

1 subpackage · 3 pages · 1 component · 19 wxml nodes · 57 edges · 34ms
wrote examples/demo/.wxgraph/graph.json

impact 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

Terminal recording: wxgraph build examples/demo reports one subpackage, three pages, one component, 19 WXML nodes and 57 edges. Then wxgraph impact components/price-card lists two host templates and the two component nodes re-rendered by onEdit's setData: the price text via prop:price and the edit mask via prop:editing.

Reading the answer:

  • Host lines are the templates that include components/price-card. pages/cart/index.wxml:5 passes two properties; pages/order/detail.wxml:4 passes one.

  • ← data … is the page data path that feeds the property after wx:for aliases are resolved (item.unitPrice becomes items[].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 declared price property; [via direct] means the element sits in the setData owner's own template.

  • unresolved_setdata is not an error and not a guessed edge: onLoad passes a non-literal object to this.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 an unresolved hop(s) block with the same status and detail explain uses.

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

page / component

unit id, template path, declared component properties

element

WXML tag, line, owning template, wx:for scope

data_field

normalised path, e.g. items[].unitPrice

handler

method name, owning unit, line

set_data

call line and literal keys (null when the argument is not an object literal)

cloud_fn

cloud-function name from a wx.cloud.callFunction call site

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 build

Exit 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

wxgraph_impact

blast radius of a page, component or element; json: true for machines, up: true to walk hosts

wxgraph_explain

every hop behind one setData site or element, including failed hops

wxgraph_search

find a node id by name, path, tag or setData key

wxgraph_stats

counts, warnings, unreadable .js files, unanalysed .ts files, unresolved components

wxgraph_build

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.json pages, tabBar entries, both subpackages and subPackages, each entry's root and independent flag.

  • Component registry. Page/component .json usingComponents, every file marked component: true, and app-level usingComponents. Specifiers resolve as root-absolute, relative, or npm specifier under miniprogram_npm/<pkg> with a node_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 same handles edge with the bare event and the modifier kept separately.

  • Scripts. Page({...}), Component({ methods: {...} }), handler methods, literal and nested-literal setData keys, non-literal setData sites, declared component properties, and wx.cloud.callFunction call sites. Every .js file in the walk is parsed and counted in stats; .ts files are counted and warned, not analysed.

  • Impact. setData key → data path → host attribute → component property → child binding → element, closed only when every hop resolves. Failed hops are printed, and impact --up walks the includes edges back to every caller.

Not in v0.1 — stated so the graph's silence is not mistaken for an answer:

  • Native .wxml projects only. Taro, uni-app and kbone compiled output are not analysed.

  • .js sources only. .ts files are counted and warned by wxgraph 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:if guard can still be false. The graph reports the structural path; the platform decides.

  • No watch mode or incremental reindex. Re-run wxgraph build after 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.

  • .ts page and component sources.

  • A JSON Schema for graph.json so 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 run

The 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…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      15
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 PyPI
      1
      Functional Source , Version 1.1, ALv2 Future
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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