使用说明

Revit的MCP HTTP封装器

针对Revit MCP（模型上下文协议）服务器的HTTP REST API封装器，支持与Microsoft Copilot Studio和Power Automate集成。

🎯 状态：已准备好投入生产（但有局限性）

当前设置已验证的解耦架构，采用按请求执行子进程的方式

✅ 功能特性

按类别进行批量家庭评级
导出CSV文件，可选择17列详细格式或5列快速格式
Copilot Studio 集成（通过 ngrok 隧道）
所有17个MCP工具的REST API端点
健康检查与监测

⚠️ 已知限制

详细模式超时 在 Copilot Studio 中（30-60 秒 vs Azure 约 30 秒的限制） 使用 Power Automate 替代
ngrok免费版 重启后URL发生变化 → 需要更新连接器
专用的 PowerShell 窗口 Flask服务器所需

🏗️ 建筑

Copilot Studio / Power Automate
    ↓ (HTTPS)
Azure API Management
    ↓ (HTTPS)
ngrok Tunnel (Public)
    ↓ (HTTP localhost:5000)
simple_rest_api.py (Flask)
    ↓ (subprocess.run per request)
Node MCP Server (build/index.js)
    ↓ (Socket port 8080)
Revit MCP Plugin
    ↓
Revit 2024

关键设计每个HTTP请求都会通过stdin/stdout管道启动一个新的Node.js进程。这样可以避免子进程持续崩溃，同时保持系统的可靠性。

📚 文档

《部署指南.md》 - 完整的安装指南，附带故障排除方法
POWER_AUTOMATE_INTEGRATION.md 翻译为中文是：“POWER_AUTOMATE 集成.md”（注：这里的“.md”通常表示Markdown格式的文件，但在中文语境下，我们通常不会特别翻译文件扩展名，所以直接保留为“.md”）。不过，为了更自然地表达，也可以翻译为“POWER_AUTOMATE 集成文档.md”或“POWER_AUTOMATE 集成说明文件.md”，具体取决于文件的实际内容和用途 - 长时间操作的超时处理方法
向Copilot添加批量分级功能.md - Copilot Studio 连接器设置
COPILOT_STUDIO_快速入门指南.md - 所有17种工具的快速参考

🚀 快速入门

先决条件

Autodesk Revit 2024（正在运行中，文档已打开）
Python 3.12+（及更高版本） flask 和 flask-cors
Node.js（任意最新版本）
ngrok 账户（免费层级适合测试）
Copilot Studio 访问

安装

# 1. Install Python dependencies
cd C:\Users\ScottM\source\repos\MCP\mcp-wrapper-http
pip install flask flask-cors

# 2. Install ngrok
# Download from https://ngrok.com/download
# Authenticate: ngrok config add-authtoken YOUR_TOKEN

# 3. Verify Revit plugin is installed (already done if you're here)

启动服务器

选项1：使用启动脚本 （推荐）

# Terminal 1: Start Flask server
.\start_server.ps1

# Terminal 2: Start ngrok tunnel
.\start_ngrok.ps1

选项2：手动启动

# Terminal 1: Start Flask server in dedicated window
Start-Process powershell -ArgumentList "-NoExit", "-Command", `
  "cd C:\Users\ScottM\source\repos\MCP\mcp-wrapper-http; python simple_rest_api.py"

# Terminal 2: Start ngrok
ngrok http 5000

测试

# Health check (local)
Invoke-RestMethod -Uri "http://localhost:5000/health"

# Health check (via ngrok)
Invoke-RestMethod -Uri "https://YOUR_NGROK_URL/health"

# Grade families (detailed mode)
$body = @{
    category = "Doors"
    gradeType = "detailed"
    includeTypes = $true
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://localhost:5000/api/tools/grade_all_families_by_category" `
  -Method POST -Body $body -ContentType "application/json" -TimeoutSec 120

预期结果:

{
  "success": true,
  "totalElements": 142,
  "avgScore": 96.4,
  "csvFilePath": "C:\\...\\RevitFamilyGrades_....csv",
  "gradeDistribution": {"A": 132, "D": 10, "F": 0},
  "categories": ["Doors"]
}

🎛️ API 接口端点

核心端点

方法	终点	描述
GET	（可翻译为“获取”或保持原样，根据上下文判断，此处“GET”通常用于网络请求方法，表示获取资源） `/health`	健康检查
GET	（翻译为中文为）	获取
POST	（翻译为中文可保持原样，因为“POST”在中文网络语境中常直接使用，意为“帖子”或“发布”，但此处作为标题或分类时，通常不翻译，直接保留“POST”） `/api/tools/grade_all_families_by_category`	按类别划分等级家族

示例请求

POST /api/tools/grade_all_families_by_category
Content-Type: application/json

{
  "category": "Doors",
  "gradeType": "detailed",
  "includeTypes": true,
  "outputPath": ""
}

示例回复

{
  "success": true,
  "totalElements": 142,
  "avgScore": 96.4,
  "csvFilePath": "C:\\Users\\...\\RevitFamilyGrades_....csv",
  "gradeDistribution": {
    "A": 132,
    "B": 0,
    "C": 0,
    "D": 10,
    "F": 0,
    "ERROR": 0
  },
  "categories": ["Doors"],
  "timestamp": "2025-10-15 12:23:51",
  "revitFileName": "Snowdon Towers Sample Architectural"
}

🔧 故障排除

服务器无法启动/立即退出

解决方案必须使用专用的PowerShell窗口（参见 start_server.ps1）

404 页面未找到

检查：

Flask 服务器正在 5000 端口运行
ngrok 正确转发
Copilot 连接器的基础 URL 是 /

Copilot Studio 中出现 500 超时错误

原因详细模式超出了 Azure 的超时限制（~30 秒）
解决方案使用 Power Automate（流程自动化） 相反（见 POWER_AUTOMATE_INTEGRATION.md)

ngrok URL 已更改

解决方案更新 Copilot Studio 连接器主机的 ngrok 新 URL

查看完整的故障排除指南: `DEPLOYMENT_GUIDE.md` 翻译成中文是：“部署指南.md”

📊 测试结果

SnowdonTowers 示例项目：

✅ 142扇门实例已评级
✅ 平均分：96.4/100
✅ 成绩分布：132人得A，10人得D，0人得F
✅ CSV导出成功，包含17列
✅ 评分时间：30-60秒（详细模式）

测试类别:

门：142个实例
Windows：106个实例
家具：数量不一

🏭 生产部署

制作前检查清单

[ ] 用永久解决方案替换ngrok（Azure虚拟机或付费ngrok计划）
[ ] 添加API密钥认证
[ ] 添加速率限制（Flask-Limiter）
[ ] 设置监控（Application Insights）
[ ] 为长时间操作配置 Power Automate 流程
[ ] 创建自动健康检查
[ ] 文档URL更新程序
[ ] 制定备份/故障转移策略
[ ] 测试错误处理和重试逻辑

部署选项

Azure 虚拟机 （建议投入生产）
- 永久公共IP
- 无会话限制
- 对基础设施的全面控制
ngrok付费计划 （8美元/月）
- 静态域
- 没有会话超时
- 快速设置
Cloudflare 隧道 （免费替代方案）
- 比ngrok免费版更持久稳定
- 无会话限制
- 需要Cloudflare账户

🤝 贡献（或“参与贡献”）

这是一个用于Revit MCP集成的工作生产环境设置。欢迎提出改进建议！

关键文件

工作文件 （使用这些）：

simple_rest_api.py - 带有每个请求独立子进程的Flask服务器
start_server.ps1 - 服务器启动脚本
start_ngrok.ps1 - ngrok 启动脚本
DEPLOYMENT_GUIDE.md - 完整的安装设置文档

已弃用文件 （不要使用）：

http_wrapper.py - 子进程持续崩溃
simple_wrapper.py - 相同的崩溃问题
其他实验性包装器

📝 许可证

见许可证

🙏 致谢

基于Anthropic的模型上下文协议（MCP）构建
与 Microsoft Copilot Studio 和 Power Automate 集成
使用ngrok进行公共隧道连接
Autodesk Revit 2024平台

📞 支持

参见文档：

`DEPLOYMENT_GUIDE.md` 翻译为中文是：“部署指南.md” - 完整设置
POWER_AUTOMATE_INTEGRATION.md 翻译为中文是：“POWER_AUTOMATE 集成.md” 或者更自然地表达为：“POWER_AUTOMATE 集成文档.md”。这里，“.md”通常表示这是一个Markdown格式的文件 - 超时解决方案
为Copilot添加批量分级功能.md - Copilot Studio 设置

检查日志：

Revit：（保持原样，因为“Revit”是一个专有名词，通常不翻译，直接使用其原名） C:\Users\ScottM\AppData\Roaming\Autodesk\Revit\Addins\2024\revit_mcp_plugin\Logs\
ngrok: http://localhost:4040（可翻译为：“ngrok 访问地址：http://localhost:4040”）
Flask：在专用的PowerShell窗口中输出控制台信息

自定义主机和端口

运行 `python http_wrapper.py --host 0.0.0.0 --port 8080` 并同时运行 `python your-mcp-server.py`

运行命令：python http_wrapper.py --port 3000 然后执行 npx -y @modelcontextprotocol/server-filesystem 。


### Command Line Options

--host HOST 绑定的主机（默认：127.0.0.1 - 仅限本地主机）使用 0.0.0.0 允许网络访问 --port PORT 绑定的端口（默认：5000） --debug 启用 Flask 调试模式


## API Reference

### Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/mcp` | Main JSON-RPC endpoint |
| `GET` | `/mcp` | Server-Sent Events streaming |
| `GET` | `/health` | Health check |

### Supported MCP Methods

- `initialize` - MCP handshake and capability negotiation
- `tools/list` - List available tools
- `tools/call` - Execute a tool
- `prompts/list` - List available prompts
- `prompts/get` - Retrieve a prompt
- `resources/list` - List available resources
- `resources/read` - Read a resource

## Usage Examples

### 1. Initialize Connection

```bash
curl -X POST http://127.0.0.1:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {"tools": {}, "prompts": {}, "resources": {}},
      "clientInfo": {"name": "my-client", "version": "1.0.0"}
    },
    "id": 1
  }'

2. 列出可用工具

curl -X POST http://127.0.0.1:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 2}'

3. 调用工具

curl -X POST http://127.0.0.1:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "read_file",
      "arguments": {"path": "/path/to/file.txt"}
    },
    "id": 3
  }'

4. 获取提示

curl -X POST http://127.0.0.1:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "prompts/get",
    "params": {
      "name": "code_review",
      "arguments": {"language": "python"}
    },
    "id": 4
  }'

5. 阅读资源

curl -X POST http://127.0.0.1:5000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "resources/read",
    "params": {
      "uri": "file:///path/to/resource.txt"
    },
    "id": 5
  }'

6. 服务器发送事件流

curl -H "Accept: text/event-stream" http://127.0.0.1:5000/mcp

7. 健康检查

curl http://127.0.0.1:5000/health

会话管理

使用可选的 Mcp-Session-Id 头部信息用于维护会话状态：

curl -X POST http://127.0.0.1:5000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: unique-session-123" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

响应格式

所有响应均遵循JSON-RPC 2.0格式：

成功响应

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [...]
  },
  "id": 1
}

错误响应

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": "Unknown method: invalid/method"
  },
  "id": 1
}

常见错误代码

代码	消息	描述
`-32700`	解析错误	无效的JSON
`-32600`	请求无效	JSON-RPC 格式错误
`-32601`	未找到方法	未知的MCP方法
`-32602`	无效参数	缺失/无效的参数
`-32603`	内部错误	服务器端错误

使用流行MCP服务器的示例

文件系统服务器

# Install and run
npm install -g @modelcontextprotocol/server-filesystem
python http_wrapper.py -- npx @modelcontextprotocol/server-filesystem /path/to/directory

SQLite 服务器

# Install and run
npm install -g @modelcontextprotocol/server-sqlite
python http_wrapper.py -- npx @modelcontextprotocol/server-sqlite /path/to/database.db

Git 服务器

# Install and run
npm install -g @modelcontextprotocol/server-git
python http_wrapper.py -- npx @modelcontextprotocol/server-git --repository /path/to/repo

安全考量

默认绑定到本地主机服务器绑定到 127.0.0.1 出于安全考虑，作为默认设置
来源验证验证 Origin 当提供时，包含头部信息
网络访问使用 --host 0.0.0.0 仅当需要网络访问时
输入验证所有JSON-RPC请求均经过验证
错误处理敏感信息不会在错误消息中暴露

故障排除

端口已被占用

❌ Error: Port 5000 is already in use!

Suggestions:
  • Try a different port: --port 5001
  • Check what's using port 5000: netstat -tulpn | grep 5000
  • Kill the conflicting process if it's safe to do so

MCP服务器无法启动

检查MCP服务器命令是否正确
验证MCP服务器可执行文件是否在您的PATH环境变量中
查看控制台输出，寻找MCP服务器的错误信息

连接问题

验证主机和端口是否正确
如果从另一台机器访问，请检查防火墙设置
确保MCP服务器正在运行并有响应

做出贡献

为仓库创建分支
创建一个特性分支
做出你的更改
彻底测试
提交拉取请求

许可证

这个项目是开源的。请查阅许可证文件以获取详细信息。