@draw-my-architecture/mcp-server

A Model Context Protocol (MCP) server that exposes Draw My Architecture tooling — DSL validation, icon catalogs, and cloud service mapping — to AI assistants and developer tools.

How it works

The server runs as a stdio-based MCP server using @modelcontextprotocol/sdk. It communicates over stdin/stdout, making it compatible with any MCP client (VS Code Copilot, Claude Desktop, MCP Inspector, etc.).

All tool inputs are validated with Zod schemas. Optional request/response logging is controlled via environment variables.

Available tools

| Tool | Description | |---|---| | ping | Health check — returns pong | | server.version | Returns MCP server/package version metadata for client verification | | dsl.getSyntaxReference | Returns the DSL grammar (including note annotations), option enums, rules, and an optional example | | dsl.validate | Parses, validates, and normalizes a DSL string using @draw-my-architecture/diagram-dsl | | icons.catalog | Browse and search the icon catalog across Azure, AWS, and GCP providers | | icons.resolve | Resolve a service name to a canonical icon, asset URL, and component path | | cloud.mapService | Map equivalent services across cloud providers using tier-based matching |

Architecture

index.ts           — entry point, wires StdioServerTransport
server.ts          — creates McpServer, registers all tools
dsl-tools.ts       — dsl.getSyntaxReference + dsl.validate implementations
cloud-map.ts       — cloud.mapService implementation + tier mapping tables

The dsl.validate tool reuses the same parseAzureDsl → validateAzureDsl → normalizeAzureDsl pipeline from packages/diagram-dsl, so its behaviour is always consistent with the web app.

Environment variables

| Variable | Default | Description | |---|---|---| | MCP_SERVER_LOG_IO | false | Enable request/response logging to stderr | | MCP_SERVER_LOG_INCLUDE_PAYLOADS | false | Include full input/output payloads in logs | | MCP_SERVER_LOG_MAX_CHARS | 1000 | Max characters per payload in logs |

When AI_MCP_ENABLED=true is set on the API, the AI workflow calls this server as a prompt-prep context source during diagram generation.

Publishing for external users

To make the MCP server available outside the repo, publish these packages to npm in this order:

1. @draw-my-architecture/diagram-dsl
2. @draw-my-architecture/shared
3. @draw-my-architecture/mcp-server

Suggested release commands from the repo root:

npm run build -w @draw-my-architecture/diagram-dsl
npm run build -w @draw-my-architecture/shared
npm run build -w @draw-my-architecture/mcp-server
npm publish -w @draw-my-architecture/diagram-dsl --access public
npm publish -w @draw-my-architecture/shared --access public
npm publish -w @draw-my-architecture/mcp-server --access public

The published MCP server can then be launched from Copilot with:

{
  "servers": {
    "draw-my-architecture": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@draw-my-architecture/mcp-server"]
    }
  }
}

Running the server

Development (hot reload):

npm run dev -w @draw-my-architecture/mcp-server

Production (after build):

npm run build -w @draw-my-architecture/mcp-server
npm run start -w @draw-my-architecture/mcp-server

Demoing with MCP Inspector

MCP Inspector provides a browser UI for calling tools interactively — no code required.

Step 1 — Build dependencies

npm run build -w @draw-my-architecture/diagram-dsl
npm run build -w @draw-my-architecture/shared

Step 2 — Launch the Inspector

npx @modelcontextprotocol/inspector npx tsx apps/mcp-server/src/index.ts

Open the printed URL (typically http://localhost:5173) in your browser.

Step 3 — Connect

Click Connect in the top-left. The status indicator turns green when connected.

Note: The Inspector has a built-in Ping button that sends a protocol-level ping (MCP handshake). This always returns {} and is separate from the ping tool listed under the Tools tab.

Step 4 — Try the tools

ping

Click ping → Run Tool. Returns pong (or pong: <message> if a message is provided).

server.version

Click server.version → Run Tool. Returns JSON including serverName, serverVersion, and package identity so you can confirm the MCP release currently connected.

dsl.getSyntaxReference

Set includeExample → true → Run Tool. Returns the full DSL grammar with a working example diagram.

dsl.validate

Paste a DSL string into the dsl field. Example valid DSL with a note:

diagram main label="My App" provider=azure
group rg groupKind=resourceGroup
node api appService group=rg
node db sqlDatabase group=rg
edge api -> db kind=dataFlow
note n1 label="Primary data store" attachTo=db

Set includeNormalized → true → Run Tool. Returns isValid: true and the normalized DSL.

To test error handling, introduce a typo — for example, change edge to dge:

diagram main label="My App" provider=azure
group rg groupKind=resourceGroup
node api appService group=rg
node db sqlDatabase group=rg
dge api -> db kind=dataFlow

The tool call itself succeeds (the MCP tool ran without crashing), but the response contains isValid: false with:

{
  "isValid": false,
  "errors": [
    {
      "severity": "error",
      "code": "UNKNOWN_STATEMENT",
      "message": "Unknown statement 'dge'. Expected one of: diagram, group, node, edge, meta.",
      "location": { "line": 5, "column": 1, "length": 3 }
    }
  ],
  "warnings": []
}

Tool success vs DSL validity are separate. A successful tool call means the tool ran correctly. Check isValid in the response to know whether the DSL itself is valid.

icons.catalog

Set provider → azure and query → storage → Run Tool. Returns matching icon entries with serviceKey, componentName, and modulePath.

cloud.mapService

Map Azure Functions to its AWS equivalent:

• sourceProvider → azure
• targetProvider → aws
• serviceKey → functionApp

Returns mappedServiceKey: "lambda" with confidence: "high".

Using with VS Code Copilot

Step 1 — Add the MCP config

If you are setting this up from scratch, create these two files:

1. .mcp.json at the repo root for Copilot CLI
2. .vscode/mcp.json for VS Code Copilot Chat

For this repository, the MCP config is committed in both places:

• .mcp.json at the repo root for Copilot CLI
• .vscode/mcp.json for VS Code Copilot Chat

Both files use the same local dev server entry:

{
  "servers": {
    "draw-my-architecture": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "apps/mcp-server/src/index.ts"]
    }
  }
}

For external users, publish the MCP server and point the config at the package instead:

{
  "servers": {
    "draw-my-architecture": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@draw-my-architecture/mcp-server"]
    }
  }
}

Copilot CLI uses .mcp.json (or .github/mcp.json) for MCP server configuration, while VS Code Copilot Chat reads .vscode/mcp.json in this repo. In both cases, the client starts the MCP server automatically when Copilot needs it.

Step 2 — Reload VS Code

Run Developer: Reload Window (Ctrl+Shift+P → type "Reload Window") to pick up the new MCP config.

Step 3 — Confirm the tools are available

Open Copilot Chat (Ctrl+Alt+I). Click the tools icon (🔧) in the chat input bar — you should see the draw-my-architecture server and its tools listed.

Step 4 — Use it in chat

Copilot will invoke the tools automatically when relevant. You can also prompt it directly:

Validate DSL:

"Validate this DSL: diagram main provider=azure \n node api appService"

Get the DSL syntax:

"Show me the Draw My Architecture DSL syntax reference"

Look up an icon:

"What icons are available for Azure storage?"

Map a service across clouds:

"What is the AWS equivalent of Azure Function Apps?"

Note: Just like the MCP Inspector, a successful tool invocation means the tool ran — check isValid in the response to know whether the DSL itself passed validation.

Quick tutorial — test in GitHub Copilot Chat (VS Code)

Use these steps to verify the MCP server in VS Code:

1. Make sure both config files exist:
   • .mcp.json at the repo root
   • .vscode/mcp.json in the .vscode folder
2. Reload VS Code with Developer: Reload Window.
3. Open Copilot Chat (Ctrl+Alt+I).
4. Click the tools icon (🔧) and confirm draw-my-architecture appears.
5. Send a simple health check:
   • Ping the draw-my-architecture MCP server
6. Ask for the DSL syntax:
   • Show me the Draw My Architecture DSL syntax reference
7. Ask it to validate DSL:
   • Validate this DSL: diagram main provider=azure node api appService
8. Ask for an icon lookup:
   • Use the draw-my-architecture MCP server to list icons for Azure storage
9. Ask for a cloud mapping:
   • Use the draw-my-architecture MCP server to map Azure Function Apps to AWS

Expected results:

• The server appears in the tools list.
• ping returns pong.
• dsl.validate returns isValid: true for valid DSL and isValid: false with errors for invalid DSL.
• icons.catalog and cloud.mapService return matching results instead of errors.

Tip: If Copilot answers from general knowledge instead of calling the tool, make the request more explicit by naming the server or tool, for example: Use draw-my-architecture to list Azure storage icons or Use draw-my-architecture to map Azure Function Apps to AWS.