langgraph-spec-toolkit
Use this MCP server to build and manage LangGraph projects by editing a structured YAML spec, with validation and deterministic Python code generation.
init_project: scaffold a new project with spec.yaml, nodes.py, and init.py, plus optional initial state fields.
add_node / add_edge: add or update nodes and simple/conditional edges; entry point is handled automatically.
remove_node / remove_edge: delete nodes and edges, with cascading cleanup for edges touching a removed node.
set_state_schema: replace the graph's state schema wholesale.
apply_changes: batch multiple mutating operations atomically in one round trip.
get_spec: fetch the full current spec read-only.
validate_graph: check for unreachable nodes, missing paths to END, dangling conditions, duplicate/typo'd ids, and unsafe identifiers.
render_python: deterministically generate idiomatic LangGraph graph.py from the spec, blocking on validation errors.
Enables building LangGraph projects by editing a structured YAML spec, with tools for scaffolding projects, managing nodes, edges, and state schema, validating graph topology, and rendering deterministic Python code.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@langgraph-spec-toolkit Initialize a new LangGraph project and add a node named 'greet'."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
langgraph-spec-toolkit
An MCP server + Claude skill for building LangGraph projects by editing a structured YAML spec — not by regenerating Python from scratch on every turn.
edit spec.yaml (via MCP tools) → validate_graph → render_python → graph.pyGraph topology — nodes, edges, state schema, checkpointer — is data, not
prose. An LLM agent should be able to add a node or rewire an edge with one
small, targeted tool call, not re-emit 150 lines of Python and hope nothing
upstream broke. spec.yaml is the source of truth; graph.py is a
deterministic, regenerable build artifact you never hand-edit.
Quick look

Four tool calls, zero hand-written Python for the graph wiring itself.
(Regenerate with vhs .github/assets/demo.tape — see that file for a
vhs 0.12.0 bug you may need to work around.)
$ uv run python .github/assets/demo.py
1) init_project - scaffold spec.yaml, nodes.py
2) apply_changes - nodes + edges wired in one round trip
3) validate_graph - catch problems before any code is emitted
ok=True issues=0
4) render_python - deterministic codegen, no LLM involved
wrote demo_graph/graph.py
$ cat demo_graph/graph.py
"""Auto-generated by langgraph-spec-toolkit — DO NOT EDIT BY HAND.
Regenerate with the `render_python` MCP tool after changing spec.yaml.
Source spec: demo_graph
"""
from langgraph.graph import StateGraph, START, END
from typing import TypedDict
from . import nodes
class GraphState(TypedDict):
pass
def build_graph():
workflow = StateGraph(GraphState)
workflow.add_node('greet', nodes.greet)
workflow.add_node('respond', nodes.respond)
workflow.add_edge(START, 'greet')
workflow.add_edge('greet', 'respond')
workflow.add_edge('respond', END)
return workflow.compile()Related MCP server: Oplink
Table of contents
Why
Real-world cost. Measured on a real Claude Code session's
/costoutput (not a synthetic estimate), in a fresh session with no prior history: building a small 2-node graph from scratch cost $0.1267 hand-writinggraph.pydirectly, vs. $0.1291 through this toolkit's MCP tools (usingapply_changesto wire nodes/edges in one call) — roughly at parity for this small, from-scratch case, which is close to the toolkit's least favorable scenario since there's no existing complexity yet for hand-written regeneration to be expensive.Error rate. Free-form Python regeneration risks silently dropping an edge, mistyping a state key, or producing an unreachable node. A structured spec can be validated before any code is emitted.
Diffability.
spec.yamlchanges are small, reviewable diffs. A regenerated file's diff is often the whole file.
Installation
Requires Python 3.11+ and uv (which provides
uvx).
Via uvx (recommended — no clone, no local install; uvx fetches
langgraph-spec-toolkit
from PyPI and runs it on demand):
{
"mcpServers": {
"langgraph-spec-toolkit": {
"command": "uvx",
"args": ["langgraph-spec-toolkit"]
}
}
}From source (if you're developing on the toolkit itself):
git clone <this-repo>
cd langgraph-spec-toolkit
uv sync{
"mcpServers": {
"langgraph-spec-toolkit": {
"command": "uv",
"args": ["run", "--directory", "/path/to/langgraph-spec-toolkit", "python", "-m", "mcp_server.server"]
}
}
}Runtime dependencies are intentionally minimal: mcp, jinja2, pyyaml.
render_python's output imports langgraph (and langchain-core, if
your state uses message types) — those are dependencies of the project
you're generating, not of this toolkit.
Usage
Either config above starts the MCP server (it speaks MCP over stdio) the moment your client connects — there's no separate "run the server" step to do by hand. If you want to smoke-test it directly:
uv run python -m mcp_server.server # from a source checkout
uvx langgraph-spec-toolkit # from PyPIThen drive it through the tools below — or point Claude at skill/SKILL.md
and let it drive itself. A typical session:
init_project(project_dir="my_graph", name="my_graph")
apply_changes(project_dir="my_graph", operations=[
{"op": "add_node", "id": "start"},
{"op": "add_node", "id": "respond"},
{"op": "add_edge", "from_": "start", "to": "respond"},
{"op": "add_edge", "from_": "respond", "to": "END"},
])
validate_graph(project_dir="my_graph") # -> ok: true
render_python(project_dir="my_graph") # -> writes my_graph/graph.py...then write start/respond in my_graph/nodes.py and you have a
runnable graph.
The spec format
spec.yaml:
name: simple_chatbot
entry_point: greet
state:
- name: messages
type: list[BaseMessage]
reducer: add_messages
default: []
nodes:
- id: greet
type: python
config:
function: greet # callable in nodes.py; defaults to the node id
- id: chatbot
type: python
config:
function: chatbot
- id: tools
type: python
config:
function: call_tools
edges:
- from: greet
to: chatbot
- from: chatbot
condition: route_after_chatbot # router fn in nodes.py
paths:
continue: tools
end: END
- from: tools
to: chatbot
checkpointer:
type: none # none | memory | sqlite | postgresNode and router bodies are not generated — render_python only owns
topology, state, and wiring. You write the callables in the project's
nodes.py, named to match config.function / condition. This keeps
codegen deterministic: the same spec always renders to the same Python, and
business logic never gets silently rewritten on a regen.
type on a state field is a raw Python type expression. A handful of
common symbols — BaseMessage, AnyMessage, HumanMessage, AIMessage,
SystemMessage, ToolMessage, ChatMessage, plus Any / Optional /
Sequence / Union / Literal from typing — are recognized by name and
auto-imported in the rendered file. reducer similarly recognizes
add_messages and add / operator.add as built-ins; anything else is
assumed to be a function you define in reducers.py.
MCP tools
Tool | Purpose |
| Scaffold |
| Add/update a node. The first node added becomes |
| Add a simple ( |
| Remove a node; cascades to delete edges touching it. |
| Remove edge(s) from a source, optionally to one target. |
| Replace the state schema wholesale. |
| Apply several |
| Read-only fetch of the full current spec. |
| Run static checks; returns |
| Emit |
Note: edges use the parameter name
from_, notfrom— the latter is a reserved word in Python. It still round-trips through thefrom:key inspec.yaml.
Note: the mutating tools (
add_node,add_edge,remove_node,remove_edge,set_state_schema,apply_changes) return a compactsummary(node/edge/state counts, entry point, checkpointer type) rather than the full spec — echoing the whole graph back on every small edit would grow with graph size and quietly erode the token savings this toolkit exists for. Callget_specwhen you actually need the full picture.
Prefer
apply_changesover separate calls whenever wiring more than one node/edge at once (e.g. a whole tool-calling loop) — it's the same edit, one round trip instead of several. See Why for the measured real-world cost. Each operation is a dict with an"op"key plus that operation's normal arguments, e.g.{"op": "add_node", "id": "tools", "config": {...}}— see the tool's own description for the full list.entry_pointis set automatically (the first node added, orentry_point: trueon a lateradd_nodeop) — don't add an edge from"START"yourself, even though renderedgraph.pycontains one; that edge is derived fromentry_point, not wired as a spec edge.
Validation
validate_graph checks for:
Unreachable nodes — no path from
entry_point.Missing path to
END— a node that can never terminate the graph.Dangling conditions — a conditional edge with no
paths, or apathstarget that isn't a real node id (orEND).State/id typos — duplicate node ids, duplicate state field names, an
entry_pointthat doesn't match any node id, an unknown checkpointer type.Unsafe identifiers —
config.function, a conditional edge'scondition, a state field'sname, and a non-builtinreducerare all spliced into the generated Python unquoted (e.g.nodes.<function>), so each must be a valid Python identifier; a state field'stypemust at least parse as a Python expression. This is a correctness and safety check — it's the boundary that keeps a bad spec value from becoming arbitrary code ingraph.py.
render_python refuses to emit code while validation errors are present;
warnings (like an unreachable node) don't block rendering.
Example
examples/simple_chatbot has a spec with a
message-reducer state field, a linear edge, and a conditional tool-call
loop, plus the generated graph.py — diff the two to see exactly what
codegen does. It's been exercised end-to-end against a real langgraph +
langchain-core install to confirm the generated wiring executes, not just
that it parses.
Development
uv sync
uv run python -m mcp_server.server # smoke-test the server starts
uv run pytest # run the test suite
uv run ruff check . # lintThe test suite (tests/) covers spec.py (dataclasses, YAML round-trips),
validator/ (every check, including the identifier/injection-safety ones),
renderer/ (codegen against the committed example, plus each reducer/
checkpointer variant), every MCP tool's run() function, and MCP tool
registration itself. New tools or spec fields should come with tests in
the matching file.
CI (.github/workflows/ci.yml) runs lint and the test suite (on Python
3.11 and 3.12) on every push and pull request against main.
Releasing
Publishing to PyPI (.github/workflows/publish.yml) uses
Trusted Publishing — no API
token is stored in this repo. One-time setup (maintainers only):
On pypi.org, add a trusted publisher for this project: owner
mkrishna-gs, repolanggraph-spec-toolkit, workflowpublish.yml, environmentpypi. (If the project doesn't exist on PyPI yet, PyPI supports adding a trusted publisher for a not-yet-published project name — it claims the name on first publish.)In this repo's GitHub settings, create an environment named
pypi(optionally with required reviewers, for an extra manual gate before every publish).
After that, cutting a release is the whole process:
Bump
versioninpyproject.toml.Tag and push, then publish a GitHub Release from that tag (or use
gh release create).publish.ymlbuilds the sdist/wheel and publishes them automatically.
Contributing
Issues and pull requests are welcome — see
CONTRIBUTING.md for the project layout, dev setup, and
the checklist to run through before opening a PR.
License
Available Tools
10 toolsadd_edgeA
Add an edge between nodes.
Simple edge: set to (a node id, or "END").
Conditional edge: set condition (the name of a router function in
nodes.py) and paths (a mapping of the router's return value to a
target node id or "END").
Inputs: from_ (required), project_dir (required), to, paths, +1 more. Returns: object
add_nodeB
Add or update a node. config['function'] names the callable in nodes.py (defaults to the node id if omitted).
The first node added to a project becomes the entry point automatically; pass entry_point=True to (re)designate a later node instead.
Inputs: id (required), project_dir (required), type, config, +1 more. Returns: object
apply_changesA
Apply several spec edits in one call instead of one add_node/add_edge/... call each.
Prefer this over separate calls whenever wiring more than one node/edge at once (e.g. adding a whole tool-calling loop) — it's the same edit, one round trip instead of several.
operations is a list, applied in order against one loaded spec and
saved once at the end. Nothing is written if any operation is invalid
(bad op name, missing required field, dangling reference) — the whole
batch is atomic. Each entry is a dict with an "op" key plus that
operation's normal arguments:
{"op": "add_node", "id": "tools", "config": {"function": "call_tools"}} {"op": "add_edge", "from_": "chatbot", "condition": "route", "paths": {"continue": "tools", "end": "END"}} {"op": "add_edge", "from_": "tools", "to": "chatbot"} {"op": "remove_node", "id": "..."} {"op": "remove_edge", "from_": "...", "to": "..."} {"op": "set_state_schema", "fields": [...]}
entry_point is set automatically (the first node added, or pass entry_point=true on a later add_node op) — don't add an edge from "START" yourself, even though rendered graph.py contains one; that edge is derived from entry_point, not wired as a spec edge.
Returns a compact summary (counts), like the other mutating tools — call get_spec if you need the full picture afterward.
Inputs: operations (required), project_dir (required). Returns: object
get_specA
Read-only fetch of the full current spec.
Mutating tools (add_node, add_edge, remove_node, remove_edge, set_state_schema) return a compact summary (counts), not the full spec, to keep per-edit response cost flat as the graph grows. Call this when you actually need the whole picture.
Inputs: project_dir (required). Returns: object
init_projectA
Create a new spec-driven LangGraph project: spec.yaml, nodes.py stub, init.py.
project_dir: directory to create/use (created if missing; error if a spec.yaml already exists there). name: project/graph name, stored in spec.yaml. state_fields: optional initial state fields, each {name, type, reducer?, default?}.
Inputs: name (required), project_dir (required), state_fields. Returns: object
remove_edgeA
Remove edge(s) from a source node. Omit to to remove all edges from that source.
Inputs: from_ (required), project_dir (required), to. Returns: object
remove_nodeA
Remove a node, cascading to delete any edges that touch it.
Inputs: id (required), project_dir (required). Returns: object
render_pythonA
Render the current spec into idiomatic LangGraph Python (graph.py by default).
Deterministic Jinja2 templating — no LLM involved, same spec always produces the same code. Blocks if the spec has validation errors (warnings still allow rendering).
Inputs: project_dir (required), output_path. Returns: object
set_state_schemaA
Replace the graph's state schema wholesale.
Each field: {name, type, reducer?, default?}. type is a raw Python
type expression (e.g. "str", "list[str]"); reducer names a reducer
function (e.g. "add_messages", or a custom name defined in reducers.py).
Inputs: fields (required), project_dir (required). Returns: object
validate_graphA
Check the spec for unreachable nodes, missing paths to END, dangling conditions/edges, and duplicate/typo'd ids. Returns ok=False if any errors (as opposed to warnings) are found.
Inputs: project_dir (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct operation: adding/removing nodes and edges, setting schema, fetching the spec, validating, rendering, initializing, and batch-applying changes. Even apply_changes is clearly scoped as a batch wrapper with explicit op names, so no tool is easily confused with another.
All tool names follow a consistent snake_case verb_noun pattern: add_node, remove_edge, set_state_schema, get_spec, validate_graph, render_python, init_project, apply_changes. There are no style deviations or vague verbs.
Ten tools is well-scoped for a LangGraph spec toolkit. Each tool covers a necessary piece of the workflow without redundancy, and the count supports both simple edits and batching without feeling bloated.
The toolkit covers the full graph-building lifecycle: project creation, node and edge CRUD, state schema management, validation, rendering to Python, and full-spec inspection. The batch apply_changes tool also fills the practical gap of multi-edit workflows.
Maintenance
Related MCP Connectors
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Generate a typed SDK, CLI, and MCP server from any OpenAPI or GraphQL spec, and keep them current.
Create and manage Mermaid.js flowcharts and diagrams with AI agents via MCP.
Live, editable canvas for AI agents — author graphs via MCP, then watch and reroute runs live.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables orchestration of MCP tool calls through declarative YAML-defined directed graphs with data transformation, conditional routing, and observable execution flows.28 npm23MIT
- AlicenseNot gradedqualityDmaintenanceEnables creating no-code agent workflows by combining multiple MCP servers into unified YAML-defined tools. Supports parameterized prompts and scripted steps, exposing a single MCP endpoint that orchestrates external servers like Chrome DevTools and shadcn.9MIT
- AlicenseNot gradedqualityDmaintenanceEnables multi-model leader-worker agent orchestration, workflow execution, and deterministic validation via structured MCP tools.Apache 2.0
- AlicenseAqualityBmaintenanceA local, auditable multi-model workflow engine that lets you define YAML graphs for orchestrating LLM agents across vendors, with MCP tools for validation, dry-runs, execution, and human approval, all fully observable in a local web interface.83Apache 2.0