Revit MCP Copilot Integration

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 接口端点

核心端点

示例请求

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更新程序
• \[ \] 制定备份/故障转移策略
• \[ \] 测试错误处理和重试逻辑

部署选项

1. Azure 虚拟机 （建议投入生产）

- 永久公共IP - 无会话限制 - 对基础设施的全面控制

1. ngrok付费计划 （8美元/月）

- 静态域 - 没有会话超时 - 快速设置

1. 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

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服务器正在运行并有响应

## 做出贡献

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

## 许可证

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

## 相关的

- [模型上下文协议规范](https://modelcontextprotocol.io/specification/)
- [MCP服务器目录](https://github.com/modelcontextprotocol/servers)
- [MCP Python SDK（MCP Python软件开发工具包）](https://github.com/modelcontextprotocol/python-sdk)