MCP 串接說明 — drawmiat

MCP 串接指南

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

快速開始（三步驟）

第一步：選擇連線方式

drawmiat 對外提供四種 transport，大多數情況請選 Streamable HTTP（包含 Antigravity、Claude Code、Claude Desktop、OpenCode、Cursor 等現代 MCP client）。

方式	URL / 指令	適用場景
Streamable HTTP（推薦）	`https://miat.thesmart.cc/mcp`	Antigravity、Claude Code、Claude Desktop、OpenCode、Cursor、任何符合 MCP 2025-06-18 spec 的 HTTP client
Streamable HTTP（alias）	`https://miat.thesmart.cc/mcp/http`	同上，與舊文件相容；行為與 `/mcp` 完全等價
SSE（legacy）	`https://miat.thesmart.cc/mcp/sse`	只支援舊版 SSE transport 的 client（建議優先試 Streamable HTTP）
stdio（本機）	`python3 /path/to/drawmiat/mcp_server.py`	在 server 機器上本機直連，不走網路

技術細節：Streamable HTTP 為 stateful 模式 — initialize POST 回應會帶 Mcp-Session-Id header，後續 POST/GET/DELETE 必須回送同一個 session id。Antigravity 等 client 會自動處理這一段，使用者不需手動操作。

第二步：設定您的 AI 工具

方式 A：Streamable HTTP 遠端連線（推薦）

把下面這個 URL 填入 client 的 MCP 設定即可：

URL：https://miat.thesmart.cc/mcp

Antigravity — 在 MCP server 設定中加入 server，URL 填上 https://miat.thesmart.cc/mcp。Antigravity 會自動使用 Streamable HTTP transport 並處理 Mcp-Session-Id 驗證。
若你看到的是 JSON 形式的 config，格式為：

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

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

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

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

Claude Desktop — 在 claude_desktop_config.json 加入：

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

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

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

Cursor — 在 ~/.cursor/mcp.json（或專案的 .cursor/mcp.json）加入：

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

方式 B：SSE（legacy，僅當 client 不支援 Streamable HTTP 時使用）

SSE endpoint：https://miat.thesmart.cc/mcp/sse

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

方式 C：stdio 本機連線

適合在自己電腦上跑一份 drawmiat、要把它接給本機 AI 工具的使用者：

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

# 2. 安裝依賴
pip install mcp

# 3. 在 AI 工具中設定 MCP

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

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

OpenCode：

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

第三步：開始使用

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

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

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

MCP 提供的工具

`validate_diagram` — 驗證 JSON

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

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

`generate_diagram` — 生成 SVG

將 JSON 渲染成 SVG 圖表。

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

建議流程

先呼叫 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 JSON，包括：

IEEE 1320.1 / IEC 60848 標準規範
JSON Schema 定義與範例
IDEF0 ↔ Grafcet 追蹤性規範

下載 miatdiagram Skill

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

API 狀態

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

GET https://miat.thesmart.cc/mcp/info

回傳範例：

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

注意：/mcp 本身（不含 /info）是 Streamable HTTP MCP endpoint，不是 health check URL。直接 GET 它且沒有帶 Accept: text/event-stream 會回 MCP 協定錯誤 -32600 Not Acceptable，這是正常行為，代表 server 健在；要看 health JSON 請打 /mcp/info。

常見問題

Q: reload 後看不到 drawmiat 工具？

確認 .mcp.json 在專案根目錄
確認 transport type 設定正確：Streamable HTTP 用 "type": "http"（Claude Code/Desktop）或 "type": "remote"（OpenCode）；SSE 用 "type": "sse"
用 curl -s https://miat.thesmart.cc/mcp/info 測試 server 健康狀態（200 + JSON 表示健在）
用 curl -s -X POST https://miat.thesmart.cc/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' -i | grep -i mcp-session-id 測試 Streamable HTTP（成功會看到 mcp-session-id header）

Q: client 一直在 /mcp 與 /mcp/ 之間 307 redirect 迴圈？

請更新 client 至支援 MCP 2025-06-18 spec 的版本。drawmiat 已將 /mcp、/mcp/、/mcp/http、/mcp/http/ 全部註冊為精確路徑，不會發出 307
建議 URL 寫成 無尾斜線的 https://miat.thesmart.cc/mcp

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

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

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

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

原始碼

https://github.com/Raw1mage/drawmiat

drawmiat