使用说明

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 <repo>

向游标添加新的mcp工具

// mcp config json
{
  "mcpServers": {
    "M-docs": {
      "command": "uv",
      "args": ["--directory", "<path_to_clone_of_the_project", "run", "main.py"]
    }
  }
}

或者，您可以将其设置为远程服务器，而无需克隆仓库。

{
  "mcpServers": {
    "m-docs": {

      "url": "https://m-docs.fastmcp.app/mcp",
      "headers": {
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

这将启动服务器，公开以下MCP工具：

convert_markdown_to_postman：将Markdown字符串转换为Postman Collection v2.1 JSON
convert_markdown_file_to_postman：将Markdown文件（按路径）转换为Postman Collection v2.1 JSON
validate_markdown_structure：检查Markdown的结构是否正确，并返回验证信息

📋 示例

输入Markdown(`example.md`)

# Authentication

## Login
**Description:** Get token for auth  
**Save Response Variable:** auth_token

> ```curl
> 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文件中执行请求

🔄 可变流量

检测: {{variable_name}} cURL命令中的模式
集合变量：添加到集合的变量数组中
预请求脚本：验证所需变量是否存在
测试脚本：将响应数据保存到指定变量
用法：后续请求中可用的变量

📄 输出格式

使用以下命令生成标准Postman Collection v2.1 JSON：

集合信息（名称、描述、架构）
有组织的文件夹结构
格式正确的请求，包含完整的URL细分
环境变量
事件脚本（预请求和测试）
与Postman导入兼容

🤝 贡献

分叉存储库
创建要素分支
添加新功能的测试
提交拉取请求

📜 许可证

这个项目是开源的。有关详细信息，请参阅LICENSE文件。