MCP Server (@specgraph/mcp)

Spec Graph is designed to be written and consumed primarily by AI agents.
Humans should still understand the file format and graph mechanics, but day-to-day authoring is best done through agent tooling.

The recommended interface is the Spec Graph MCP server: @specgraph/mcp.

Why MCP?

With MCP, your coding agent can:

• initialize a new spec graph
• validate graph + nodes
• query nodes/edges/subgraphs
• perform safe graph writes (node/edge add/update/remove)

This gives you structured, graph-aware edits instead of ad-hoc JSON file manipulation.

Run the Server

npx @specgraph/mcp --repo-dir /path/to/repo

--repo-dir should be the repository root that contains your specgraph/ directory.

Configure in an MCP Client

Example MCP config:

{
  "mcpServers": {
    "specgraph": {
      "command": "npx",
      "args": ["@specgraph/mcp", "--repo-dir", "."]
    }
  }
}

LLM Context Files

For agent bootstrapping and retrieval workflows, the site publishes both summary and full-context text files:

• llms.txt — concise overview
• llms-full.txt — complete docs bundle

See LLM Context Files for usage details.

Tool Surface (@specgraph/mcp@0.5.x)

Shared Definitions

Most tools use these common field definitions:

• directory (optional string): spec graph directory relative to --repo-dir (defaults to specgraph)
• node_id, feature_id, group_id, source, target: node IDs with pattern ^[A-Z][A-Z0-9-]{0,79}$
• edge_type: one of contains, depends_on, constrains, implements, derived_from, verified_by, supersedes

add_node and update_node accept node as a typed union:

• feature and layer require id, type, title, description
• behavior requires id, type, title, expectation, verification
• behavior authoring convention: include constraints explicitly; use [] if none apply (schema still allows omission)
• contract types (foundation, decision, domain, policy, design_token, ui_contract, api_contract, data_model, artifact, equivalence_contract, pipeline) require id, type, title, statement, verification
• decision additionally requires category and metadata.rationale
• policy additionally requires severity

Optional node fields include links, metadata, and type-specific fields (for example category, severity, pins, artifact, constraints).

Initialization and Validation

init_specgraph

Creates graph.json and optionally a root feature node.

Input:

{
  "directory": "specgraph",
  "specgraph_version": "1.0.0",
  "root_feature": {
    "id": "ROOT",
    "title": "Root Feature",
    "description": "Top-level feature for this spec graph."
  }
}

validate_specgraph

Validates graph + nodes against schemas and structural rules.

Input:

{
  "directory": "specgraph"
}

Checks include:

• missing targets
• self-references
• depends_on cycles
• dependency inversion guard (layer -> depends_on -> feature is invalid)
• foundation dependency guard (foundation -> depends_on -> layer/feature/behavior is invalid)
• propagated layer decision ambiguity detection

Query Tools

list_nodes

Lists node summaries (id, type, title, status) plus count.

Input:

{
  "directory": "specgraph"
}

get_node

Returns the full JSON object for one node.

Input:

{
  "directory": "specgraph",
  "node_id": "AUTH-01"
}

get_upstream_context (recommended)

Returns all upstream nodes that influence a target node, with reason labels.

Input:

{
  "directory": "specgraph",
  "node_id": "AUTH-01"
}

Includes:

• transitive depends_on nodes
• direct and inherited constraining nodes (via contains propagation)
• contains ancestors
• direct implements/verified_by/derived_from references
• inbound supersedes references

Compatibility alias: get_affecting_nodes.

list_dependencies

Lists direct depends_on dependencies for a node.

Input:

{
  "directory": "specgraph",
  "node_id": "AUTH-01"
}

list_dependencies_full

Returns transitive depends_on closure with explicit normative layer-propagated guidance and informational-only non-layer dependency context.

Input:

{
  "directory": "specgraph",
  "node_id": "AUTH-01"
}

get_effective_constraints

Computes effective normative guidance for a target node:

• direct/inherited constrains via contains ancestry
• transitive layer-originated propagation over depends_on
• propagated decision ambiguity reporting

Input:

{
  "directory": "specgraph",
  "node_id": "AUTH-01"
}

get_group_subgraph

Returns a grouping node (feature or layer) plus all reachable contains descendants.

Input:

{
  "directory": "specgraph",
  "group_id": "PLATFORM"
}

get_feature_subgraph

Backward-compatible feature-only alias for group subgraph retrieval.

Input:

{
  "directory": "specgraph",
  "feature_id": "AUTH"
}

list_edges

Lists all graph edges as {source, target, edge_type}.

Input:

{
  "directory": "specgraph"
}

search_nodes

Fuzzy-searches on id, title, core text fields, and metadata context such as rationale.

Input:

{
  "directory": "specgraph",
  "query": "token refresh"
}

Write Tools

All writes are validated against canonical Spec Graph JSON Schemas before persistence.

add_node

Adds a new node. Fails if ID already exists.

Input example:

{
  "directory": "specgraph",
  "node": {
    "id": "AUTH-01",
    "type": "behavior",
    "title": "Reject invalid credentials",
    "expectation": "When credentials are invalid, login is rejected with a generic error.",
    "constraints": ["Response does not reveal whether username exists"],
    "verification": "pytest tests/auth/test_reject_invalid_credentials.py -k AUTH_01"
  }
}

update_node

Replaces an existing node.

Important: this is full replacement, not partial patch. Send the complete node object, including all required fields for that node type.

Input example:

{
  "directory": "specgraph",
  "node": {
    "id": "AUTH-01",
    "type": "behavior",
    "title": "Reject invalid credentials",
    "expectation": "When credentials are invalid, login is rejected with a generic error and no user detail leakage.",
    "verification": "pytest tests/auth/test_reject_invalid_credentials.py -k AUTH_01",
    "constraints": ["Response does not reveal whether username exists"]
  }
}

remove_node

Removes a node and scrubs inbound references from other node link arrays.

Input:

{
  "directory": "specgraph",
  "node_id": "AUTH-01"
}

add_edge

Adds one typed edge from source to target.

Input:

{
  "directory": "specgraph",
  "source": "AUTH",
  "target": "AUTH-01",
  "edge_type": "contains"
}

remove_edge

Removes one typed edge from source to target.

Input:

{
  "directory": "specgraph",
  "source": "AUTH",
  "target": "AUTH-01",
  "edge_type": "contains"
}

Backward Compatibility Note

As of 0.3.x, the server exposes explicit tools listed above.

• removed: query_specgraph (operation-dispatch wrapper)
• removed: write_specgraph (operation-dispatch wrapper)

Recommended Workflow

1. Ask your agent to initialize or update the graph through MCP tools.
2. Ask your agent to run validate_specgraph after each graph change.
3. Keep manual JSON edits for debugging/learning, not primary authoring.

Schema Version and Overrides

By default, the MCP package uses bundled canonical schemas.
For advanced cases, it supports environment overrides:

• SPECGRAPH_MCP_SCHEMA_DIR
• SPECGRAPH_MCP_SCHEMA_BASE_URL
• SPECGRAPH_MCP_GRAPH_SCHEMA
• SPECGRAPH_MCP_NODE_SCHEMA