@stack-scribe/mcp

@stack-scribe/mcp is a Model Context Protocol (MCP) stdio server and Node library for validating Stack Scribe diagrams, searching icon-backed node types, and rendering AWS architecture diagrams to SVG files.

The published package enables the first-party AWS icon pack by default and exposes a stack-scribe-mcp CLI for MCP hosts.

Requirements

• Node.js 20 or newer
• An MCP host that can launch stdio servers
• Filesystem access to the output paths you pass to save_diagram

Install

Use from an MCP host

Most MCP hosts can launch the server directly with npx:

{
  "mcpServers": {
    "stack-scribe": {
      "command": "npx",
      "args": ["-y", "@stack-scribe/mcp"]
    }
  }
}

If you prefer a global install:

npm install -g @stack-scribe/mcp

Then point your MCP host at the installed CLI:

{
  "mcpServers": {
    "stack-scribe": {
      "command": "stack-scribe-mcp"
    }
  }
}

What The Server Exposes

@stack-scribe/mcp is a tool-only MCP server over stdio. It does not expose HTTP endpoints or SVG resources.

Tools

• validate_diagram: Validates a diagram against the Stack Scribe schema and semantic rules.
• save_diagram: Validates, lays out, renders, and writes an SVG file to a server-side path. Returns metadata only, never raw SVG content.
• search_icons: Searches canonical AWS node types, shorthand aliases, and icon file paths.
• list_icon_packs: Lists the icon packs currently enabled by the server.
• get_diagram_schema: Returns the Diagram JSON Schema.

Diagram Example

The server accepts Stack Scribe diagram JSON. Shorthand aliases such as lambda and s3-bucket are normalized through the AWS icon pack.

{
  "title": "Simple API",
  "nodes": [
    {
      "id": "api",
      "type": "aws.networking-content-delivery.api-gateway"
    },
    {
      "id": "fn",
      "type": "lambda"
    },
    {
      "id": "bucket",
      "type": "s3-bucket"
    }
  ],
  "edges": [
    {
      "from": "api",
      "to": "fn",
      "label": "invoke"
    },
    {
      "from": "fn",
      "to": "bucket",
      "label": "write"
    }
  ]
}

Themes

save_diagram and saveDiagramToFile() accept the built-in render themes:

• default
• dark

Notes

• The current bundled icon surface is AWS-only.
• save_diagram writes files on the machine where the MCP server is running.
• Invalid diagrams fail before any SVG is written.
• The library entrypoint is import-safe and does not auto-start the server.