M-docs
一个基于Python的MCP工具，可以将包含分层cURL请求的结构化Markdown文件转换为Postman Collection JSON（模式v2.1）。
✅ 它做什么
- 读取包含cURL请求部分的Markdown文件
- 使用元数据（描述、依赖关系、响应变量）分析每个请求
- 将cURL命令转换为结构化Postman请求
- 使用文件夹、变量和脚本构建完整的Postman Collection JSON
- 通过MCP返回或导出到磁盘
🧩 核心组件
| 模块 | 目的 |
|---|---|
markdown_parser.py | 从结构化Markdown中提取请求+元数据 |
curl_converter.py | 转换cURL命令→ 结构化请求对象 |
postman_builder.py | 创建Postman集合JSON v2.1 |
main.py | 显示MCP集成的命令 |
simple_server.py | 简化的服务器界面 |
cli.py | 命令行界面 |
📝 Markdown格式
结构
# Folder Name (H1 - optional, creates Postman folders)
## Request Name (H2 - required)
**Description:** Brief description of what this request does
**Requires:** comma,separated,variables (optional)
**Save Response Variable:** variable_name (optional)
> ```curl
> curl -X POST https://api.example.com/endpoint \
> -H "Content-Type: application/json" \
> -H "Authorization: Bearer {{auth_token}}" \
> -d '{"key": "value"}'
> ```\[！注意\] 为了避免markdown围栏代码块破坏，我们用>转义了所有内部代码块。
支持的元数据字段
| 字段 | 必填？ | 目的 |
|---|---|---|
| 说明： | ✅ | 请求摘要/文件 |
| 要求： | ❌ | 所需的环境变量（生成预请求脚本） |
| 保存响应变量： | ❌ | 从响应中保存的变量（生成测试脚本） |
可变支持
- cURL中的变量使用
{{variable_name}}自动检测格式 - 在集合中创建Postman环境变量
- 预请求脚本验证所需变量是否存在
- 测试脚本将响应数据保存到指定变量
🚀 用法
作为CLI工具使用
# Convert a markdown file
uv run python cli.py example.md
# With custom options
uv run python cli.py example.md -o my_collection.json --name "My API" --description "Custom description"
# Validate markdown structure only
uv run python cli.py example.md --validate --verbose
# Help
uv run python cli.py --help用作MCP服务器
该项目通过以下方式将其转换和验证工具公开为MCP（Markdown转换平台）工具 FastMCP。您可以将其作为服务器运行，并从任何兼容MCP的客户端使用它。
1.设置MCP服务器
git clone 向游标添加新的mcp工具
// mcp config json
{
"mcpServers": {
"M-docs": {
"command": "uv",
"args": ["--directory", "curl -X POST https://api.example.com/login \ -H "Content-Type: application/json" \ -d '{"username": "test", "password": "1234"}' ```
User Operations
Get User Profile
Description: Fetch user profile Requires: auth_token
``curl curl -X GET https://api.example.com/user/profile \ -H "Authorization: Bearer {{auth_token}}" ``
> \[！注意\]
> 为了避免markdown围栏代码块破坏，我们用>转义了所有内部代码块。
### 生成的邮差收藏
- ✅ 2个文件夹：“身份验证”和“用户操作”
- ✅ 2个具有正确HTTP方法、标头和正文的请求
- ✅ 环境变量 `auth_token` 自动检测
- ✅ 登录请求时的测试脚本，用于从响应中保存令牌
- ✅ 配置文件请求上的预请求脚本，用于验证令牌是否存在
- ✅ JSON正文格式正确，语法突出显示
## 📚 特性
- \[x\] 元数据提取(`**Field:**` 格式）
- \[x\] H1/H2结构的Markdown解析
- \[x\] cURL命令解析（标头、方法、正文、查询参数）
- \[x\] 邮差收藏v2.1 JSON生成
- \[x\] 文件夹组织
- \[x\] 环境变量检测和创建
- \[x\] 生成用于保存响应变量的测试脚本
- \[x\] 生成用于依赖性检查的预请求脚本
- \[x\] 具有验证模式的CLI工具
- \[x\] 错误处理和验证
- \[x\] JSON正文格式和语法突出显示
- \[\]允许动态生成markdown文件
- \[\]直接发布给邮递员
- \[\]允许在markdown文件中执行请求
### 🔄 可变流量
1. **检测**: `{{variable_name}}` cURL命令中的模式
1. **集合变量**：添加到集合的变量数组中
1. **预请求脚本**：验证所需变量是否存在
1. **测试脚本**：将响应数据保存到指定变量
1. **用法**：后续请求中可用的变量
## 📄 输出格式
使用以下命令生成标准Postman Collection v2.1 JSON：
- 集合信息（名称、描述、架构）
- 有组织的文件夹结构
- 格式正确的请求，包含完整的URL细分
- 环境变量
- 事件脚本（预请求和测试）
- 与Postman导入兼容
## 🤝 贡献
1. 分叉存储库
1. 创建要素分支
1. 添加新功能的测试
1. 提交拉取请求
## 📜 许可证
这个项目是开源的。有关详细信息，请参阅LICENSE文件。