# @draw-my-architecture/mcp-server

> A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes Draw My Architecture tooling — DSL validation, icon catalogs, and cloud service mapping — to AI assistants and developer tools.

Latest version **0.1.9** (published 2026-07-01) · 0 weekly downloads

## Install

```sh
npm install @draw-my-architecture/mcp-server
pnpm add @draw-my-architecture/mcp-server
yarn add @draw-my-architecture/mcp-server
bun add @draw-my-architecture/mcp-server
```

Provides the command `draw-my-architecture-mcp`.

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.9 |
| Published | 2026-07-01 |
| First published | 2026-06-30 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 73 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | petecodes |

## Links

- npm: https://www.npmjs.com/package/@draw-my-architecture/mcp-server
- npm.io page: https://npm.io/package/@draw-my-architecture/mcp-server

## Dependencies (4)

- [zod](https://npm.io/package/zod.md) ^3.25.76
- [@modelcontextprotocol/sdk](https://npm.io/package/@modelcontextprotocol/sdk.md) ^1.29.0
- [@draw-my-architecture/shared](https://npm.io/package/@draw-my-architecture/shared.md) ^0.1.4
- [@draw-my-architecture/diagram-dsl](https://npm.io/package/@draw-my-architecture/diagram-dsl.md) ^0.1.4

## Recent versions

- 0.1.9 (latest) — 2026-07-01
- 0.1.8 — 2026-07-01
- 0.1.7 — 2026-07-01
- 0.1.6 — 2026-07-01
- 0.1.5 — 2026-07-01
- 0.1.4 — 2026-06-30
- 0.1.3 — 2026-06-30
- 0.1.2 — 2026-06-30
- 0.1.1 — 2026-06-30
- 0.1.0 — 2026-06-30

## README

# @draw-my-architecture/mcp-server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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](https://zod.dev) 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:

```bash
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:

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

---

## Running the server

**Development (hot reload):**
```bash
npm run dev -w @draw-my-architecture/mcp-server
```

**Production (after build):**
```bash
npm run build -w @draw-my-architecture/mcp-server
npm run start -w @draw-my-architecture/mcp-server
```

---

## Demoing with MCP Inspector

[MCP Inspector](https://github.com/modelcontextprotocol/inspector) provides a browser UI for calling tools interactively — no code required.

### Step 1 — Build dependencies

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

### Step 2 — Launch the Inspector

```bash
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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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`.

---
_Source: https://npm.io/package/@draw-my-architecture/mcp-server · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._