内容
# mdMCP
将 Markdown 文件转变为本地 MCP 服务器，且无任何依赖。
```
pip install mdmcp
```
## 快速开始
**1. 编写工具文件：**
```markdown
## 工具：健康检查
检查一个 URL 是否可达。
### 参数
- url（字符串，必填）：要检查的 URL
### 执行
\```bash
STATUS=$(curl -sf -o /dev/null -w '%{http_code}' -m 5 "$MDMCP_URL")
echo "HTTP $STATUS"
\```
```
**2. 启动服务：**
```bash
mdmcp serve tools.md
```
**3. 连接到 Claude 代码：**
```json
{
"mcpServers": {
"my-tools": {
"command": "mdmcp",
"args": ["serve", "tools.md"]
}
}
}
```
就这样，您的 Markdown 现在是一个 MCP 服务器。
## 工作原理
- `## 工具：名称` 定义一个工具
- `### 参数` 定义输入模式（基于环境变量，无字符串插值）
- `### 执行` 包含一个围栏代码块中的 bash 脚本
- 参数作为 `$MDMCP_<名称>` 环境变量传递
## 命令
```bash
mdmcp list tools.md # 列出可用工具
mdmcp run tools.md tool_name '{}' # 运行一个工具一次
mdmcp serve tools.md # 启动 MCP 标准输入/输出服务器
```
## 安全
- **最小环境**: 仅继承 PATH、HOME、USER、SHELL、LANG、TERM。API 密钥和令牌不会暴露给工具脚本。
- **无字符串插值**: 参数作为环境变量传递，而不是注入 shell 代码。
- **必填参数验证**: 缺少必填参数会在执行前返回错误。
- **超时 + 进程清理**: 30 秒超时，进程组杀死以防止僵尸进程。
## 提示
- 总是在 bash 中引用 `"$MDMCP_VAR"` 以防止单词拆分
- 为可选参数使用 `${MDMCP_VAR:-default}`，并在 bash 端设置默认值
- 您可以在 bash 中使用 `python3 -c` 进行复杂逻辑（参见 `examples/data-tools.md`）
- 在脚本顶部使用 `set -eu` 以确保更安全地执行
## 示例
参见 [`examples/`](examples/) 目录：
- **ops-tools.md** — 磁盘使用情况、端口检查、git 日志、docker 状态、健康检查
- **dev-tools.md** — 查找 TODO、运行 linter、检查端口（来自 Codex 测试）
- **data-tools.md** — CSV 摘要、JSON 检查、文件差异（来自 Gemini 测试）
## 已知限制
- 执行块仅支持 ` ``` ` 围栏（不支持 `~~~`）
- 参数名称必须是 `\w+`（无空格或特殊字符）
- heredoc 中的嵌套 ` ``` ` 将使解析器混淆
- 所有参数值在 bash 中都是字符串；如有需要，请手动强制转换
## 许可证
MIT
