Weld MCP server
Commit Sep 2, 2026Creates a local codebase graph to provide AI agents with deterministic repository context, including code, docs, CI, and configuration.
Also known as configflux/weld
- Stars
- 6
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Sep 2, 2026
- License
- Apache-2.0
What is Weld MCP?
Weld creates a local codebase graph to provide AI agents with deterministic repository context, including code, docs, CI, and configuration.
Summary generated from the project's README
About Weld MCP server
Providing AI agents with a deterministic map of a codebase is what weld does for developers working in large or complex repositories. It scans source code, documentation, CI workflows, build files, and runtime configurations to create a local graph stored in a .weld/graph.json file. This allows agents to understand the connections between different parts of a system without having to rediscover the entire repository structure during every new session.
Users interact with the graph through a CLI or an MCP server, making it compatible with agents like Claude Code. The tool supports multiple languages including Python, TypeScript, Go, Rust, C#, C++, and Java. It is designed for local use, keeping all data under the developer's control on their own disk. Because it uses a graph structure rather than fuzzy semantic search, it provides exact nodes and edges with provenance, helping agents follow precise relationships across code, docs, and infrastructure boundaries.
What you can do with it
- 1Analyze cross-repository impactAsk an AI agent to determine how a change in one service affects other parts of a multi-repo system.
- 2Trace service startup flowsRequest a step-by-step trace of how a specific service or capability is initialized within the codebase.
- 3Identify authoritative documentationHave an agent locate the specific documentation that defines a capability or service contract.
- 4Map build and test surfacesDetermine which specific build and test configurations are touched by a proposed code modification.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableconfigflux/weld is public and reachablegithub.com/configflux/weld ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-02github.com/configflux/weld ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubWeld
A local codebase graph for AI coding agents. Weld scans code, docs, CI, build files, runtime configs, and repo boundaries into a deterministic graph. Agents can query this graph through CLI or MCP instead of rediscovering the repository from scratch every session.
The graph lives on disk (.weld/graph.json), stays under your control, and
answers the questions agents and humans repeatedly ask about a codebase: where
a capability lives, which docs are authoritative, what build and test surfaces
a change touches, and what boundaries constrain the implementation.
Evaluators: start with v0.26.0. v0.26.0 is the current recommended starting point. New in this release over the previous one: Next.js app-router routes; a TypeScript/JavaScript surface on which
wd callersandwd impactanswer at function granularity (first-party imports andtsconfigaliases bound to their files, JSX components, default exports, barrels, CommonJS); npm and MSBuild packages in the cross-repo package graph;wd init --refreshmerging newly-wired entries into a hand-edited config; and directory-segment globs and brace groups resolving the same way in every strategy.CHANGELOG.mdhas the full per-release entries.
Try it in 5 minutes → docs/tutorial-5-minutes.md
walks through wd init, discover, brief, query, context, and path
against demo workspaces. Spin up a clean demo with one command:
scripts/create-polyrepo-demo.sh /tmp/weld-polyrepo-demo
# or
scripts/create-monorepo-demo.sh /tmp/weld-monorepo-demo
Each script materializes a self-contained demo directory with seeded source
files, .weld configs, and committed git history -- ready for wd discover.
If you have Weld installed but no source checkout, the same demos are
available through the CLI: wd demo list, wd demo monorepo --init <dir>,
wd demo polyrepo --init <dir>.
Use Weld when…
- your repo is too large for an agent to understand in one pass
- your system spans multiple repositories
- architecture is spread across code, docs, CI, configs, and service contracts
- you want reproducible repo context instead of ad-hoc chat memory
When not to use Weld
- Your repo is small (under ~50 files). An agent can read it end-to-end; a graph adds overhead without payoff.
grepplus your IDE already answers your questions. If nothing is missing from that workflow, Weld has nothing to add.- You only need symbol navigation. Go-to-definition and find-references are an LSP job. Weld covers architecture, contracts, docs, and CI -- not IDE jump-to.
- You expect compiler-grade static analysis. Weld is a pragmatic graph, not a type checker or dataflow engine. It will not catch every reference or prove correctness.
- You do not want repo-local configuration. Weld writes config to
.weld/(discover.yaml,workspaces.yaml,strategies/) and expects that config to be committed alongside your code. Generated graphs (graph.json,agent-graph.json) are gitignored by default; the opt-inwd init --track-graphsteam workflow commits them for warm-CI / warm-MCP setups instead. If even committing config is unacceptable, Weld is the wrong tool.
How Weld compares
Weld is not a replacement for the tools below -- it sits alongside them and gives agents a persistent, queryable map of the repository. Each of these tools is excellent at what it does; Weld adds the connected structure they were not designed to provide.
| Tool | Gives you | Weld adds |
|---|---|---|
| grep / ripgrep | Fast literal and regex search over file contents. | Typed nodes and edges -- a symbol, route, doc, or config is an addressable entity with neighbours, not a line of text. |
| ctags / LSP | Symbol navigation and go-to-definition inside one language. | A cross-language graph that also covers docs, CI, configs, service contracts, and repo boundaries -- surfaces an IDE was never meant to index. |
| Sourcegraph | Hosted code search and references across large fleets of repos. | A local, repo-local graph that lives next to your code. By default Weld tracks only config and lets you opt in (wd init --track-graphs) to commit the generated graph for warm-CI / warm-MCP setups. No server, no indexing fleet; agents query it offline through CLI or MCP. |
| vector DB / RAG | Embedding-based semantic recall over chunks of text. | Deterministic structure. Query results are exact nodes and edges with provenance, not top-k fuzzy matches, so agents can follow relationships instead of guessing. |
| Copilot / Claude Code / OpenCode | In-editor and agentic code generation and chat. | Shared repo context those agents can read through MCP -- the same graph across sessions and tools, instead of each agent rediscovering the repo on every run. |
Key features
- Whole-codebase discovery — not just source code. Covers docs, config, CI workflows, infrastructure, and build files.
- Startup and runtime flow — models common Python, C#/.NET, and C++ entrypoints and connects them to services, boundaries, and deploy/runtime surfaces.
- Config-driven — point
.weld/discover.yamlat your repo and tune what gets extracted. - Multi-language — tree-sitter strategies ship for Python, TypeScript/JS,
Go, Rust, C#, C++, Java, and ROS2. Tree-sitter Python packages are an
optional extra (
pip install configflux-weld[tree-sitter]); without them only Python is extracted natively. See Supported languages for the per-language status and the optional libclang path for C++. - Plugin architecture — drop a
.pyfile in.weld/strategies/to extract anything repo-specific. - Agent Graph — discover agents, skills, prompts, commands, hooks,
instructions, MCP servers, and platform-specific copies into
.weld/agent-graph.json; see the Agent Graph guide for node and edge types, authority/drift, and limitations, and the platform support matrix for tested surfaces. - Agent-native — generates MCP config snippets by default and ships an optional stdio MCP server so Claude Code, Codex, and other agents can query the graph directly.
- Worktree-aware — every read answers from the checkout you are standing
in, and a fresh
git worktree addseeds its graph from a sibling checkout on the first query instead of paying a cold discovery. See Worktrees and multiple checkouts. - Zero external dependencies — runs from a plain checkout with Python >= 3.10. Tree-sitter is optional.
Quickstart
# Install (recommended — see the Install section for alternatives)
uv tool install configflux-weld
# Bootstrap config for your repo
wd init
# Run discovery and save the graph (safe mode by default — see Trust model below)
wd discover --safe --output .weld/graph.json
# Query the graph
wd query "authentication"
wd trace "how does this service start"
wd find "login"
wd context file:src/auth/handler
wd viz --no-open
wd stale
Drop --safe once you trust the repository's project-local strategies and
external-JSON adapters; the Trust model section below explains
what --safe disables and when it is appropriate to remove.
Try it on a real example: examples/04-monorepo-typescript (monorepo) · examples/05-polyrepo (polyrepo federation).
Sample output (wd query "auth" — default human form, trimmed):
# query: auth
matches (1):
1. symbol:src/auth/handler.py:authenticate [type: function]
label: authenticate
confidence: definite
description: Validate a bearer token and return the caller identity.
neighbors (1):
- route:/login [type: route]
Each match shows its confidence (definite / inferred / speculative)
so an agent can weight strong hits over guesses. By default wd query also
hides unresolved-symbol sentinels (call-graph callees that could not be
linked to a definition, origin=unresolved) — they are noise in the result
set. Pass --include-speculative to bring them back. The --json envelope
applies the same default filter, and so does the MCP weld_query tool
(include_speculative: true restores them there) — the two surfaces return the
same matches by construction. Every match still carries its confidence so a
client can weight or discount hits itself.
The description: line above prefers props.description (an LLM enrichment
pass) whenever a match has one. A match with no enrichment yet — the common
case, since enrichment is opt-in — falls back to props.summary instead: a
file's or symbol's own opening doc-comment line (a file node reads its module
docstring — a Python test module's own docstring included, not just the
production code it covers; a symbol node reads its own function/class
docstring or, for Go and Rust, its own ////// doc comment), populated by
wd discover with no enrichment pass required, and rendered as
summary: ... so the two are never confused. wd context's node header, and
the match blocks behind wd callers / wd references, apply the same
precedence. --json and the MCP surfaces are unaffected — both fields are
always present in props already.
wd query and wd context (and their MCP peers weld_query / weld_context)
also bound the read envelope by default so a large graph stays usable on
both surfaces. First the neighborhood is dieted: neighbors that are stdlib
symbols, unresolved sentinels, or speculative external symbols are dropped (real
external package dependencies are kept), dangling edges are removed, and the
fan-out is capped so a hub node cannot blow up the envelope. Then a deterministic
byte budget prunes the lowest-priority survivors until the serialized
envelope fits the agent tool cap. Nothing is hidden silently — the --json
envelope reports neighbors_filtered: true and an omitted_neighbors count by
reason (stdlib, unresolved, external_symbol, fanout_capped, and
size_capped for the byte budget). Pass --full-neighborhood (CLI) or
full_neighborhood: true (MCP) to restore the full, unfiltered neighborhood, or
--full-size / full_size: true to keep the diet but skip the byte budget.
wd brief / weld_brief are bounded the same way: edges are de-dangled to the
nodes the brief actually emits and the byte budget applies (a warnings entry
records any node dropped for size); --full-size / full_size: true returns the
unbounded brief.
The four traversal reads — wd impact, wd callers, wd references, and
wd trace (and their MCP peers) — share the same budget, because a blast radius
or a caller list is exactly the answer that grows without limit on the nodes
worth asking about. Each reports what it dropped rather than truncating quietly:
| Read | Dropped first | Reported in |
|---|---|---|
impact |
farthest hops, then lowest-priority nodes | warnings.size_capped + a warnings.messages entry |
callers |
lowest-priority callers | size_capped |
references |
file hits, then callers (resolved matches last) |
size_capped |
trace |
lowest-priority slice nodes | a warnings entry |
--full-size / full_size: true returns the unbounded payload on every one of
them.
What the budget may never shrink is the verdict. wd impact always reports
risk_level and affected_surface_counts — per-bucket counts of everything the
radius reaches — over the full blast radius, so a bounded payload can never
come back claiming a smaller radius or a lower risk than the change really has.
The surface member lists under affected_surfaces are prunable (they are seven
unbounded node lists, not a summary), and what was dropped from each is reported
in warnings.size_capped.affected_surfaces. The human (non---json) output is
never bounded — a terminal has no tool cap, and the counts are what a reader ran
the command for.
The budget is best-effort, and says so when it falls short: if everything
droppable has been dropped and the payload is still over, warnings
(top-level budget_exceeded on callers / references) carries
budget_exceeded: true plus a message suggesting a narrower question. It is
always present, so a consumer never has to probe for it.
All wd retrieval commands default to human-readable text and accept
--json for the stable JSON envelope. Pass --json when
piping to jq or other scripted consumers. query and context
additionally carry the neighbor-diet annotation (neighbors_filtered +
omitted_neighbors); the rest of the envelope is unchanged.
Sample wd query "auth" --json:
{
"query": "auth",
"matches": [
{
"id": "symbol:src/auth/handler.py:authenticate",
"label": "authenticate",
"type": "function",
"props": {
"file": "src/auth/handler.py",
"exports": ["authenticate"],
"description": "Validate a bearer token and return the caller identity."
}
}
],
"neighbors": [{"id": "route:/login", "type": "route"}],
"edges": [
{"from": "route:/login", "to": "symbol:src/auth/handler.py:authenticate", "type": "calls"}
],
"neighbors_filtered": true,
"omitted_neighbors": {"stdlib": 0, "unresolved": 0, "external_symbol": 0, "fanout_capped": 0, "size_capped": 0}
}
See Install for alternatives (local checkout, pip, raw source).
Agent Graph for AI customizations
Weld also maps the AI customization layer around a repository: agents, skills, instructions, prompts, commands, hooks, MCP servers, tool permissions, and platform variants. The Agent Graph is static and repo-bound; discovery reads known customization files and does not execute project code.
wd agents discover
wd agents list
wd agents audit
wd agents explain planner
wd agents impact .github/agents/planner.agent.md
wd agents plan-change "planner should always include test strategy"
wd agents viz --no-open
Use --json on list, explain, impact, audit, and plan-change for
agent-friendly output. Use wd agents rediscover when you want an explicit
refresh of .weld/agent-graph.json before inspecting the persisted graph.
Use wd agents viz after discovery to open a local read-only browser explorer
for the persisted Agent Graph.
Static discovery and configuration generation are available for several
agent platforms; runtime validation is tracked per client in the
platform support matrix. The
Agent Graph guide documents node and edge types,
authority and drift, and the read-only-first policy.
Agent-first onboarding
If an agent or coding assistant is driving setup, use the short bootstrap path:
uv tool install configflux-weld # recommended — see Install for alternatives
wd prime # show setup status + per-framework surface matrix
wd bootstrap claude # writes .claude/commands/weld.md
wd bootstrap codex # writes .codex/skills/weld/SKILL.md + .codex/config.toml
wd bootstrap copilot # writes .github/skills/weld/SKILL.md + .github/instructions/weld.instructions.md
wd bootstrap cursor # writes .cursor/rules/weld.mdc + .cursor/mcp.json
wd bootstrap aider # writes CONVENTIONS.md + .aider.conf.yml (wiki fallback; no MCP)
wd bootstrap gemini-cli # writes .gemini/skills/weld.md + .gemini/mcp.json
wd bootstrap copilot-cli # writes .copilot/skills/weld.md + .copilot/config.json
Cursor, Gemini CLI, and Copilot CLI register the local weld stdio MCP server
in the host-native config file. Aider has no native MCP protocol, so its
CONVENTIONS.md stanza points at the agent-readable wiki export: run
wd export --format=wiki --output=.weld/wiki and read .weld/wiki/index.md
to navigate the graph.
All seven wd bootstrap frameworks accept opt-out flags:
--no-mcp— skip the MCP pair (.codex/config.tomlfor codex; the.mcp.jsonguidance block for copilot/claude).--no-enrich— write the.cli.mdvariant that omitswd enrich.--cli-only— shorthand for--no-mcp --no-enrich.
To upgrade existing bootstrap files after pulling a new weld release, use the diff-aware upgrade path:
wd bootstrap <framework> --diff— print unified diffs between bundled templates and your on-disk copies without writing. Exits 1 when any file differs, 0 otherwise, so it composes with CI checks.wd bootstrap <framework> --force— overwrite targeted files while still honouring the opt-out (--no-mcp,--no-enrich,--cli-only) and federation template behaviour.
wd prime is idempotent and safe to re-run — it reports what is
already configured and what is still missing. Pass
--agent {auto,claude,codex,copilot,all} to force the active agent's row
into the matrix even when that framework has no files yet (e.g. a Codex user
in a Claude-only checkout sees codex: skill no, mcp no -> wd bootstrap codex
instead of silence). auto is the default and infers the agent from
environment variables such as CODEX_*.
Trust model
Weld's trust posture is explicit and narrow:
- Default: bundled discovery reads source files and writes the local
graph (
.weld/graph.json). It does not execute discovered application code and does not open network connections. - Safe mode: when enabled with
--safe, safe mode disables project-local strategies (.weld/strategies/) and theexternal_jsonadapter forwd discover, and refuses network/LLM enrichment providers forwd enrich. Passwd discover --safeto scan an untrusted repository without executing any code from it; passwd enrich --safeto refuse network egress (every currently registered provider — Anthropic, OpenAI, Ollama, Copilot CLI — is refused). Safe mode produces a stable[weld] safe mode: ...stderr line for each refused path. Enrichment is still available under--safeviawd enrich --agent-direct, which makes no network call at all. - Launch form: the claim above is measured against
wd, the recommended surface. A console script's own directory heads Python's module search path, so the repository being scanned is never on that path and nothing in it can answer an import. The raw-source pathpython -m weldcannot reach zero:-mputs the working directory ahead of the standard library. Weld removes that entry before importing anything of its own, but CPython's-mbootstrap has already imported a handful of standard-library modules — eight on CPython 3.12, among themcollections,threadingandwarnings, with the exact set varying by interpreter version — before any weld code runs, so a repository holding files by those names still gets them executed. That floor is what every-mtarget pays, weld's or the standard library's. Usewd, orPYTHONSAFEPATH=1 python -m weld(Python 3.11+), against a wholly untrusted repository. - Advanced strategies: project-local strategies are Python modules
loaded at discovery time, and
strategy: external_jsonexecutes configured commands fromdiscover.yaml. Only enable these on repositories you trust. - MCP server: the stdio server is launched with
python -m, so it is bound by exactly the Launch form limit above and by nothing worse. Clients start it with the project directory as its working directory, which-mwould put ahead of the standard library on Python's module search path; the server removes that entry before it loads anything of its own, leaving the same interpreter-imposed floor and nothing above it. Launch it withPYTHONSAFEPATH=1(Python 3.11+) in its environment to remove the floor too. See docs/mcp.md for the exact boundary and the configuration snippet.
See SECURITY.md for the full policy and reporting process.
Local telemetry
Weld records the success or failure of every wd CLI invocation and every
MCP tool call to a local-only file. There is no remote endpoint and no
upload — the file never leaves your machine unless you explicitly export
and share it.
What is recorded. Each event is one JSON line with a strict allowlist of fields: subcommand or tool name, exit code, duration in milliseconds, and the exception class name on failure. Paths, query strings, error messages, flag values, and usernames are never recorded. The redaction is enforced at write time, so the file on disk is already safe to attach to a bug report.
Where it lives. In a single repo, the file is
<repo>/.weld/telemetry.jsonl. In a polyrepo workspace, every event from
the root and from any child repo aggregates into
<workspace_root>/.weld/telemetry.jsonl — one shareable artifact per
workspace. Invocations outside any project (for example wd --version in
/tmp) fall back to ${XDG_STATE_HOME:-~/.local/state}/weld/telemetry.jsonl.
The file is gitignored and rotates at 1 MiB to keep the trailing 500 events.
How to opt out. Any one of these disables recording:
WELD_TELEMETRY=off in the environment, the --no-telemetry flag on a
single invocation, or wd telemetry disable to write a persistent sentinel
at the resolved root. Run wd telemetry --help for the full subcommand
surface (status, show, path, export, clear, disable, enable),
and see docs/telemetry.md for the full event
schema and design rationale.
Supported languages
Weld's only built-in extractor is for Python. Every other language
listed below depends on the [tree-sitter] optional extra. Without
it, the tree-sitter strategies silently no-op on ImportError and the
graph will contain zero nodes for those languages — by design, so weld
still runs in a minimal environment. Install the extra to actually use
multi-language support:
uv tool install "configflux-weld[tree-sitter]"
Weld MCP questions
What does Weld scan to build its graph?
Weld scans code, documentation, CI workflows, build files, runtime configurations, and repository boundaries.
Does Weld require an external server or indexing fleet?
No, Weld is a local, repo-local graph that agents query offline through CLI or MCP without needing a hosted server.
Can Weld be used for small repositories?
Weld is not recommended for repositories with fewer than 50 files, as an agent can read them end-to-end without the overhead of a graph.
What programming languages are supported?
Weld supports Python, TypeScript/JavaScript, Go, Rust, C#, C++, Java, and ROS2 via tree-sitter strategies.