MCP 串接說明 — drawmiat

MCP 串接指南

drawmiat 提供 MCP (Model Context Protocol) 介面，讓您的 AI 助手（如 Claude、GPT、Gemini）可以直接呼叫本平台來驗證 JSON 結構和生成 IDEF0 / Grafcet / C4 SVG 圖表。

快速開始（三步驟）

第一步：選擇連線方式

方式	適用場景	設定
SSE（推薦）	遠端連線、任何支援 MCP 的 AI 工具	填入網址即可，不需安裝任何東西
stdio	本機 AI 工具（OpenCode、Claude Code）	需要在本機安裝 Python + drawmiat

第二步：設定您的 AI 工具

方式 A：SSE 遠端連線（最簡單）

只需要把以下 SSE 網址填入您的 AI 工具的 MCP 設定中：

SSE 端點：https://miat.thesmart.cc/mcp/sse

OpenCode — 在 ~/.config/opencode/opencode.json 加入：

{
  "mcp": {
    "drawmiat": {
      "type": "remote",
      "url": "https://miat.thesmart.cc/mcp/sse",
      "enabled": true
    }
  }
}

Claude Code — 在專案根目錄建立 .mcp.json：

{
  "mcpServers": {
    "drawmiat": {
      "type": "sse",
      "url": "https://miat.thesmart.cc/mcp/sse"
    }
  }
}

儲存後在 Claude Code 中 reload（或執行 /mcp 確認連線狀態）。成功時會看到兩個工具可用：mcp__drawmiat__validate_diagram 和 mcp__drawmiat__generate_diagram。

Claude Desktop — 在 claude_desktop_config.json 加入：

{
  "mcpServers": {
    "drawmiat": {
      "url": "https://miat.thesmart.cc/mcp/sse"
    }
  }
}

方式 B：stdio 本機連線

適合在自己電腦上安裝 drawmiat 的使用者：

# 1. 取得原始碼
git clone https://github.com/Raw1mage/drawmiat.git

# 2. 安裝依賴
pip install mcp

# 3. 在 AI 工具中設定 MCP

OpenCode：

{
  "mcp": {
    "drawmiat": {
      "type": "local",
      "command": ["python3", "-u", "/path/to/drawmiat/mcp_server.py"],
      "enabled": true
    }
  }
}

Claude Code — 在專案根目錄的 .mcp.json 中：

{
  "mcpServers": {
    "drawmiat": {
      "type": "stdio",
      "command": "python3",
      "args": ["-u", "/path/to/drawmiat/mcp_server.py"]
    }
  }
}

第三步：開始使用

設定完成後，在您的 AI 對話中直接說：

「幫我畫一個採購流程的 IDEF0 圖」
「把這個控制邏輯轉成 Grafcet 順序功能圖」
「驗證這段 IDEF0 JSON 有沒有錯誤」
「幫我產生一張 C4 container diagram」

AI 會自動呼叫 drawmiat 的工具來驗證和生成圖表。

MCP 提供的工具

`validate_diagram` — 驗證 JSON

檢查 JSON 結構是否符合 IDEF0 / Grafcet / C4 規範，回傳錯誤和警告。

參數	必填	說明
`diagram_type`	是	`"idef0"`、`"grafcet"` 或 `"c4"`
`json_payload`	是	JSON 字串

`generate_diagram` — 生成 SVG

將 JSON 渲染成 SVG 圖表。

參數	必填	說明
`diagram_type`	是	`"idef0"`、`"grafcet"` 或 `"c4"`
`json_payload`	是	JSON 字串
`output_dir`	否	儲存 SVG 的資料夾路徑

C4 重點欄位

欄位	說明
`diagram_level`	`context` / `container` / `component`
`diagram_layout`	`top_down` / `left_right`（c4sharp-style layout hint）
`scope`	指定 in-scope software system 或 container
`containers[].type`	例如 `api`、`database`、`queue`、`spa`
`components[].type`	例如 `database`、`queue`
`relationships[].position`	`down` / `up` / `left` / `right` / `neighbor` / `none`

C4 範例

{
  "diagram_title": "Container diagram for Example System",
  "diagram_level": "container",
  "diagram_layout": "left_right",
  "scope": {"type": "software_system", "id": "SYS1"},
  "persons": [
    {"id": "P1", "name": "User", "description": "Uses the system.", "external": true}
  ],
  "systems": [
    {"id": "SYS1", "name": "Example System", "description": "Core product.", "external": false},
    {"id": "SYS2", "name": "Billing Platform", "description": "External billing service.", "external": true}
  ],
  "containers": [
    {"id": "CT1", "type": "api", "name": "Backend API", "technology": "Python FastAPI", "description": "Provides application services.", "systemRef": "SYS1"},
    {"id": "CT2", "type": "database", "name": "Main Database", "technology": "PostgreSQL", "description": "Stores persistent data.", "systemRef": "SYS1"}
  ],
  "components": [],
  "relationships": [
    {"id": "R1", "source": "P1", "target": "CT1", "description": "Uses", "technology": "HTTPS", "position": "left"},
    {"id": "R2", "source": "CT1", "target": "CT2", "description": "Reads/Writes", "technology": "SQL/TCP", "position": "neighbor"},
    {"id": "R3", "source": "CT1", "target": "SYS2", "description": "Requests billing", "technology": "REST/HTTPS", "position": "right"}
  ]
}

建議流程

先呼叫 validate_diagram 檢查 JSON
修正報告的問題
呼叫 generate_diagram 生成圖表

IDEF0 箭頭類型速查

type	ICOM	進入方向	語意
`input`	I	左側	被轉換的資料或材料
`control`	C	上方	治理條件（企業管理：負責人員）
`output`	O	右側	活動產出的結果
`mechanism`	M	下方	執行資源（企業管理：時程）
`call`	—	下方	呼叫其他活動（跨圖參考）

箭頭 source / target 格式

端點	格式	範例
外部	`EXTERNAL`	`"source": "EXTERNAL"`
活動輸入	`A1:input`	`"target": "A1:input"`
活動輸出	`A1:output`	`"source": "A1:output"`
活動控制	`A1:control`	`"target": "A1:control"`
活動機制	`A1:mechanism`	`"target": "A1:mechanism"`

搭配 miatdiagram Skill

若您的 AI 工具支援 Skill / 技能包，建議安裝 miatdiagram skill。它會教導 AI 如何正確生成 IDEF0、Grafcet 與 C4 JSON，包括：

IEEE 1320.1 / IEC 60848 標準規範
JSON Schema 定義與範例
IDEF0 ↔ Grafcet 追蹤性規範
官方 C4 level / scope / relationship 建模規則

下載 miatdiagram Skill

解壓至 ~/.config/opencode/skills/ 即可使用。

API 狀態

可以透過以下網址確認 MCP server 是否運作正常：

GET /mcp/

回傳範例：

{
  "status": "ok",
  "server": "drawmiat",
  "version": "2.0.0",
  "transports": {
    "sse": "/mcp/sse",
    "stdio": "python3 mcp_server.py"
  },
  "tools": ["validate_diagram", "generate_diagram"]
}

常見問題

Q: reload 後看不到 drawmiat 工具？

確認 .mcp.json 在專案根目錄
確認 SSE 方式有設定 "type": "sse"
用 curl -s -o /dev/null -w "%{http_code}" https://miat.thesmart.cc/mcp/sse 測試伺服器是否可達

Q: generate_diagram 沒有實際寫入檔案？

MCP 回傳的 SVG 在 response 中，用 Write 工具手動存檔即可

Q: 同一個活動多條同方向箭頭被合併顯示？

這是渲染器行為，JSON 中仍維持獨立箭頭，語意正確

原始碼

https://github.com/Raw1mage/drawmiat

drawmiat