用 Markdown 寫 MCP Server：一個 bash runbook 橋接器的誕生

我做了一個工具，讓你用 Markdown 定義 MCP tools。然後讓四個 AI 審查它、測試它、最後以這篇記錄整個過程。

問題

MCP（Model Context Protocol）讓 AI agent 呼叫外部工具。但寫一個 MCP server 需要：Python/Node boilerplate、JSON-RPC 協議、Schema 定義、打包安裝。

對於「讓 Claude Code 跑一行 curl」這種需求，這個門檻不合理。

更具體地說：你團隊的 ops runbook 是 Markdown 寫的，裡面有現成的 shell command。但它永遠只是「給人讀的文件」，不是「AI 可以呼叫的工具」。因為沒有人會為了這個去寫 MCP server。

mdMCP：Markdown 即 MCP Server

## Tool: health_check
Check if a URL is reachable.
### Parameters
- url (string, required): URL to check
- timeout (integer, optional, default: "5"): Timeout in seconds
### Execute
```bash
STATUS=$(curl -sf -o /dev/null -w '%{http_code}' -m "$MDMCP_TIMEOUT" "$MDMCP_URL")
echo "HTTP $STATUS"

```bash
pip install markdown-mcp-server
mdmcp serve tools.md

一個 .md 檔 → 一個 MCP stdio server。參數用環境變數傳遞（$MDMCP_URL），不做 string interpolation。

它不是什麼

在講它是什麼之前，先講清楚它不是什麼：

• 不是 MCP server 的替代品。 複雜邏輯、API 整合、有狀態的工具，請用 Python FastMCP。mdMCP 做不到。
• 不是給 production 用的。 沒有 sandbox、沒有權限管理、沒有 audit log。它是一個 local-only 的橋接器。
• 不是格式創新。 有人會說「這只是 YAML disguised as Markdown」。某種程度上他們是對的。

mdMCP 的定位是：把你已經有的 bash runbook 和 shell script，用最少的改動變成 AI 可呼叫的工具。

四位 AI Coder 的 Dogfood

我讓四位 AI 各寫一份真實的 tool file 來測試：

Codex（GPT-5.5） 寫了 dev-tools —— find TODO、run lint、check port。每個 tool 用 set -eu 開頭，多工具 fallback（lsof → ss → netstat）。評價：「省 70-85% boilerplate」。

Gemini 寫了 data-tools —— CSV 摘要、JSON 查詢。最聰明的發現：在 bash 裡用 python3 -c 內嵌 Python，把覆蓋率從 60% 拉到 90%+。

Grok 被指派做壓力測試，寫了 6 個故意破壞 parser 的毒 tool。找到 5 個邊界問題，其中 3 個已修復。

Qwen 3.6（本機 Ollama）驗證了 SRE runbook 轉換的 workflow。

v0.2.0：回應批評

收到dogfood回饋後，我做了三件事：

1. 型別系統

v0.1.0 所有參數都是 string。v0.2.0 支援 string、integer、number、boolean，帶型別轉換和驗證：

- count (integer, required): Number of items
- verbose (boolean, optional, default: "false"): Verbose output

傳入 "not_a_number" 給 integer 參數 → 直接報錯，不會空字串執行。

2. validate 指令

$ mdmcp validate tools.md
OK: 5 tools, no issues
  disk_usage(path:string)
  port_check(host:string, port:string)
  health_check(url:string, expected:string)

檢查格式、型別、缺漏，在 serve 之前就能抓到問題。

3. 測試

19 個測試覆蓋 parser、型別轉換、execute、env 隔離、完整 MCP 協議。從 0 到 19，至少不再是「toy project without tests」。

安全

mdMCP 用環境變數傳參，不做 template interpolation。但我不會假裝它「安全」：

• env 隔離：只傳 PATH、HOME 等安全 key。API tokens 不會洩漏給 tool script。
• Required 驗證：缺參報錯，不會空字串執行。
• Timeout + 進程清理：30s timeout + process group kill 防 zombie。

但是：它依然在 local machine 上執行 bash。沒有 sandbox，沒有 allowlist。如果你不信任那個 .md 檔，就不要 serve 它。

為什麼是 Markdown

不是因為 Markdown 是最好的 DSL。而是因為：

文件和工具合一。 你的 ops runbook 本來就是 Markdown。加上 ## Tool: 和 ### Execute 標記，它同時成為 AI 的工具。維護一份，不是兩份。

生態系現成。 Git 版控、PR review、語法高亮。工具分發 = git push。

門檻低。 會寫 Markdown + bash 的人 >> 會寫 Python MCP server 的人。

數字

• 400 行 Python，零依賴
• 19 個測試
• 4 種參數型別
• MIT 開源

pip install markdown-mcp-server

GitHub：https://github.com/MakiDevelop/mdmcp

誠實的結論

mdMCP 不會改變世界。它是一個窄用途的橋接器：把你已有的 bash runbook 變成 MCP tool，用最少的改動。

如果你每天寫 Python，FastMCP 更好。如果你需要 production 級的工具，別用 mdMCP。

但如果你有一堆 ops runbook 想讓 AI 呼叫，又不想為每個寫 MCP server —— 這個工具大概能幫上忙。

有時候，最好的工具不是功能最多的，而是改動最少就能用的。

我是江中喬，專注於 AI Agent Architecture、Memory Governance 與 Cognitive Diversity，持續研究如何打造能夠長期協作、可信任且可治理的 AI 系統。