@graphseq/mcp

Local stdio MCP server so Cursor, Claude Code, and Claude Desktop can compile Graphseq diagrams from repository context.

The host model already has the repo. This server does not call an LLM. It exposes catalog, validation, auto-layout, and export so the agent can iterate until the JSON is valid.

Install (Cursor)

1. Sign in to Graphseq → Settings → MCP → Create MCP key. Copy the mcp.json snippet (the key is inside) into .cursor/mcp.json or Cursor Settings → MCP.

{
  "mcpServers": {
    "graphseq": {
      "command": "npx",
      "args": ["-y", "@graphseq/mcp"],
      "env": {
        "GRAPHSEQ_API_URL": "<GRAPHSEQ_API_URL>",
        "GRAPHSEQ_API_KEY": "<GRAPHSEQ_API_KEY>"
      }
    }
  }
}

2. In the target repo, ask the agent to call install_skill. That writes .cursor/skills/graphseq/SKILL.md so later chats emit SemanticGraphInput and call materialize. Use scope: "user" to install for every Cursor project on this machine (~/.cursor/skills/graphseq/SKILL.md).

Without the env vars, compile/export still work; cloud save tools do not.

Claude Desktop / Claude Code

Same npx -y @graphseq/mcp command and env. Claude Code: .mcp.json in the repo or user config. Claude Desktop: Settings → MCP. install_skill writes the Cursor skill path; copy skill/SKILL.md into .claude/skills/graphseq/ for Claude Code.

Tools

| Tool | Purpose | |---|---| | get_conventions | Schema, catalog, readability rules, few-shots | | list_node_types | Allowed node type ids | | validate_semantic_graph | Check SemanticGraphInput only | | materialize | Expand + repair + auto-layout + validate | | materialize_edit | Same, keeping positions when ids match | | to_semantic | Strip a full document back to semantic JSON | | export_diagram | Mermaid / PlantUML / Graphviz preview | | install_skill | Write the Cursor Graphseq skill (project or user) | | list_cloud_files | List files in the Graphseq account (API key) | | get_cloud_file | Download a cloud DiagramDocument | | create_cloud_file | Save a new file and return editorUrl | | update_cloud_file | Replace an existing cloud snapshot |

Resources: graphseq://prompt-context, graphseq://catalog, graphseq://schema/semantic, graphseq://samples/semantic-api-db.

Prompts: graphseq-from-repo, graphseq-update.

Typical loop

1. Agent reads the user's repo.
2. install_skill if the Cursor skill is missing.
3. get_conventions
4. Emit SemanticGraphInput (no positions / sizes / ports / routes).
5. materialize — on { ok: false, errors }, fix and retry.
6. create_cloud_file (if an API key is configured) or write a .graphseq.json.

To update an existing file: to_semantic → edit → materialize_edit with the original document as baseline.