内容
# aps-mcp-server-nodejs
简单 [模型上下文协议](https://modelcontextprotocol.io) 服务器，使用 Node.js 构建，提供对 [Autodesk 平台服务](https://aps.autodesk.com) API 的访问，并使用 [安全服务帐户](https://aps.autodesk.com/en/docs/ssa/v1/developers_guide/overview/) 进行细粒度访问控制。
[YouTube 视频](https://youtu.be/6DRSR9HlIds)
## 概述
该 MCP 服务器使 AI 助手（例如 GitHub Copilot、Claude 和 Cursor）能够通过自然语言与您的 Autodesk 建设云（ACC）项目进行交互。通过将 AI 聊天界面连接到 APS API，您可以在不离开开发环境的情况下查询项目数据、浏览文件和分析问题。
### 工作原理
模型上下文协议（MCP）创建了一种标准化的方式，供 AI 助手访问外部数据源：
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ VS Code + │ MCP │ aps-mcp-server │ APS │ Autodesk ACC │
│ GitHub Copilot │ ◄─────► │ (Node.js) │ ◄─────► │ 项目 │
└─────────────────┘ stdio └──────────────────┘ API └─────────────────┘
```
1. **AI 客户端**（VS Code/Claude/Cursor）发送自然语言查询
2. **MCP 服务器**使用安全服务帐户凭证将查询转换为 APS API 调用
3. **APS API**从您的 ACC 项目中获取数据
4. **MCP 服务器**将结构化数据返回给 AI 客户端
5. **AI 客户端**格式化并向您呈现信息
### 可用 MCP 工具
该服务器在多个功能区域提供 **18 种工具**：
#### 项目和文件（2 种工具）
| 工具 | 描述 | 参数 | 返回值 |
|------|-------------|------------|---------|
| **getProjectsTool** | 检索所有 ACC 帐户和可访问的项目 | 无 | 帐户和项目列表（ID 和名称） |
| **getFolderContentsTool** | 浏览项目中的文件夹和文件结构 | `accountId`、`projectId`、`folderId`（可选） | 文件夹和文件列表（ID 和显示名称） |
#### 问题管理（7 种工具）
| 工具 | 描述 | 参数 | 返回值 |
|------|-------------|------------|---------|
| **getIssuesTool** | 从项目中获取所有问题 | `projectId` | 问题列表（ID、标题、状态、类型、指派、截止日期和 3D 坐标） |
| **getIssueTypesTool** | 获取可用的问题类型和子类型 | `projectId` | 问题类型列表（用于问题分类） |
| **createIssueTool** | 在项目中创建新问题 | `projectId`、`title`、`issueSubtypeId`、`status` 和许多可选字段 | 创建的问题（包括 ID、显示 ID 和时间戳） |
| **getIssueDetailsTool** | 检索特定问题的详细信息 | `projectId`、`issueId`、`includeComments`、`includeAttachments` | 完整问题详细信息（包括描述、指派人、日期、位置、评论、附件、自定义属性和审计跟踪） |
| **updateIssueTool** | 更新现有问题 | `projectId`、`issueId` 加上要更新的字段 | 更新的问题详细信息 |
| **addIssueCommentTool** | 向问题添加评论 | `projectId`、`issueId`、`body` | 评论确认（ID 和时间戳） |
| **addIssueAttachmentTool** | 添加附件到问题的文档 | `projectId`、`issueId`、`fileName`、`fileUrl` | 文档/指南（占位符 - 需要数据管理 API） |
#### RFI 管理（4 种工具）
| 工具 | 描述 | 参数 | 返回值 |
|------|-------------|------------|---------|
| **listRFIsTool** | 从项目中检索所有 RFI（信息请求） | `projectId`，可选筛选条件：`searchText`、`status`、`assignedTo`、`limit`、`offset` | RFI 列表（ID、标题、问题、状态、指派和截止日期） |
| **getRFITypesTool** | 获取可用的 RFI 类型和类别 | `projectId` | RFI 类型列表（用于分类） |
| **getRFIDetailsTool** | 检索特定 RFI 的详细信息 | `projectId`、`rfiId` | 完整的 RFI 详细信息（包括问题、响应、附件、工作流历史和链接文档） |
| **createRFITool** | 在项目中创建新的 RFI | `projectId`、`title`、`question`、`dueDate`、`assignedTo` 和可选字段 | 创建的 RFI（包括 ID 和时间戳） |
#### 照片管理（2 种工具）- 只读
| 工具 | 描述 | 参数 | 返回值 |
|------|-------------|------------|---------|
| **listPhotosTool** | 检索项目中的照片和视频，并支持筛选 | `projectId`，可选：`createdFrom`、`createdTo`、`mediaType`、`limit`、`offset` | 照片/视频列表（ID、名称、类型、创建时间 和 URL） |
| **getPhotoDetailsTool** | 检索特定照片或视频的详细信息 | `projectId`、`photoId` | 完整的照片/视频详细信息（包括元数据、位置、标签和自定义属性） |
**注意：** 照片工具需要 3 脚 OAuth 认证。在使用这些工具之前，请运行 `npm run oauth-login`。有关详细信息，请参见 [OAUTH_SETUP.md](OAUTH_SETUP.md)。
**重要：** ACC 照片 API v1 是只读的。必须通过 ACC 移动应用或 Web 界面上传照片。
#### 申报管理（3 种工具） ⭐
| 工具 | 描述 | 参数 | 返回值 |
|------|-------------|------------|---------|
| **listSubmittalsTool** | 从项目中检索所有申报，并支持筛选 | `projectId`，可选：`status`、`type`、`assignedTo`、`limit`、`offset` | 申报列表（ID、编号、标题、状态、类型、截止日期 和 指派） |
| **getSubmittalTypesTool** | 获取项目中配置的申报类型 | `projectId` | 申报类型列表（ID、名称、代码 和 工作流） |
| **createSubmittalTool** | 在项目中创建新的申报 | `projectId`、`title`、`submittalTypeId`、`dueDate`，可选：`number`、`description`、`assignedTo`、`status` | 创建的申报（包括 ID、编号、状态 和 时间戳） |
**注意：** 申报工具需要 3 脚 OAuth 认证。在使用这些工具之前，请运行 `npm run oauth-login`。有关详细信息，请参见 [OAUTH_SETUP.md](OAUTH_SETUP.md)。
### VS Code MCP 客户端集成
当您将此服务器与 **VS Code + GitHub Copilot** 一起使用时：
1. **配置**：`.vscode/mcp.json` 文件告诉 VS Code 在哪里找到 MCP 服务器
2. **连接**：VS Code 启动 Node.js 服务器并通过 stdio（标准输入/输出）连接
3. **身份验证**：服务器从 `.env` 使用安全服务帐户凭证进行 API 访问
4. **工具发现**：Copilot 从服务器学习可用工具
5. **自然查询**：您在 Copilot Chat 中使用普通英语提出问题
6. **工具执行**：Copilot 决定调用哪些工具以及使用哪些参数
7. **响应**：结果在聊天界面中格式化和显示
**示例交互：**
```
您： "我可以访问哪些项目？"
Copilot： [调用 getProjectsTool] → "您有 1 个项目：Construction: Sample Project..."
您： "列出所有问题"
Copilot： [调用 getIssuesTool，带有 projectId] → "您有 3 个开放问题..."
您： "显示问题 abc123 的详细信息"
Copilot： [调用 getIssueDetailsTool] → "问题：Concrete Surface Finish... 状态：开放..."
您： "为 2 级重新工作创建一个新问题"
Copilot： [调用 createIssueTool] → "✅ 问题创建成功！ID：xyz789..."
您： "列出项目中的所有 RFI"
Copilot： [调用 listRFIsTool] → "您有 5 个 RFI：2 个开放，3 个已回答..."
您： "创建一个关于混凝土规格的 RFI"
Copilot： [调用 createRFITool] → "✅ RFI 创建成功！ID：rfi-001..."
```
### 与 ACC 原生功能比较
| 功能 | ACC Web 界面 | ACC 项目 Beta | APS MCP 服务器 |
|---------|-------------------|------------------|----------------|
| **访问方式** | Web 浏览器 | Web 浏览器 | IDE 中的 AI 聊天 |
| **查询接口** | GUI 导航 | 对话式 AI | 对话式 AI |
| **集成** | 独立应用 | 独立应用 | 嵌入 VS Code/Claude/Cursor |
| **身份验证** | 用户登录 | 用户登录 | 服务帐户（编程） |
| **数据访问** | 完整的 ACC 功能 | 限于对话上下文 | 基于 API（读/写访问） |
| **自定义** | 固定 UI | 固定 AI 行为 | 自定义工具和脚本 |
| **用例** | 手动项目管理 | 快速查询和协助 | 开发人员工作流和自动化 |
| **多项目** | 在项目之间切换 | 上下文有限 | 访问所有授权项目 |
| **离线模式** | ❌ 否 | ❌ 否 | ❌ 否（需要 API） |
| **文件上传** | ✅ 是 | ✅ 是 | ❌ 否（文件只读） |
| **问题创建** | ✅ 是 | ✅ 是 | ✅ 是（已实现） |
| **实时协作** | ✅ 是 | 有限 | ❌ 否 |
**主要区别：
- **ACC 项目 Beta**：Autodesk 的原生 AI 助手集成到 ACC Web 界面中，适用于项目经理和直接在 ACC 中工作的团队
- **APS MCP 服务器**：开发人员专注的工具，将 ACC 数据带入您的编码环境，适用于：
- 构建自动化脚本
- 创建自定义报告
- 将 ACC 数据与其他系统集成
- 在 IDE 中快速检查项目状态
- 原型设计新的 ACC 集成
**何时使用每个：**
- 使用 **ACC Web 界面** 进行完整的项目管理、文件上传和团队协作
- 在 ACC Web 中使用 **ACC 项目 Beta** 进行快速提问
- 使用 **APS MCP 服务器** 进行开发工作流、自定义自动化和 IDE 原生查询
## 客户价值和用例
### 🎯 价值主张
APS MCP 服务器弥合了建设数据和 AI 驱动的开发工具之间的差距，使客户能够：
1. **减少上下文切换** - 无需离开 IDE 即可访问 ACC 数据
2. **加速开发** - 使用 AI 协助更快地构建集成
3. **提高数据可见性** - 以自然语言对话式查询项目数据
4. **启用自动化** - 为构建自定义工作流和脚本奠定基础
5. **快速原型设计** - 在正式实施之前测试 API 集成
### 👥 目标客户细分
#### 1. **建设技术团队**
构建 ACC 顶层集成的组织：
- **痛点**：手动 API 探索和测试耗时
- **解决方案**：在编写集成代码时以对话方式查询 ACC 数据
- **示例**： "在构建问题跟踪集成时，显示我的问题架构"
#### 2. **BIM/VDC 开发人员**
为建设工作流创建自动化的开发人员：
- **痛点**：在编写自动化脚本之前需要了解项目结构
- **解决方案**：在代码编辑器中探索项目数据、文件夹结构和问题模式
- **示例**： "列出结构文件夹中的所有 RVT 文件"
#### 3. **系统集成商**
连接 ACC 与其他企业系统（ERP、PM 工具）的团队：
- **痛点**：在多个系统之间理解数据模型和测试连接
- **解决方案**：在集成开发期间快速验证和测试数据
- **示例**： "问题中有哪些字段可用？"
#### 4. **DevOps/基础设施团队**
管理 APS 应用程序和监控项目健康的团队：
- **痛点**：需要快速洞察力而无需构建完整仪表盘
- **解决方案**：用于监控和故障排除的临时查询
- **示例**： "生产项目中有多少个开放问题？"
#### 5. **独立开发者/顾问**
构建 APS 解决方案的自由职业者：
- **痛点**：API 探索和测试时间有限
- **解决方案**：快速原型设计和验证想法
- **示例**： 在承诺实施方法之前测试 API 响应
### 💼 现实世界的用例
#### 用例 1：**快速集成开发**
**场景**：开发人员正在构建一个显示项目问题的自定义仪表盘
**传统工作流**：
1. 打开浏览器 → 导航到 APS API 文档
2. 为 API 测试设置 Postman/Insomnia
3. 配置身份验证
4. 手动测试 API 端点
5. 复制响应结构
6. 切换回 IDE
7. 根据手动测试编写代码
**使用 MCP 服务器**：
1. 在 VS Code 中： "显示我的项目有哪些问题？"
2. 在聊天中查看数据结构
3. 询问： "有哪些可用的筛选字段？"
4. 立即开始编写代码，并使用准确的数据模型
5. **节省时间**：每 30-60 分钟的 API 端点 → 2-5 分钟（减少 90%）
#### 用例 2：**项目健康监控**
**场景**：DevOps 团队需要跨多个站点检查项目状态
**查询示例**：
```
"我可以访问哪些项目？"
"列出所有项目中的开放问题"
"显示逾期超过 7 天的问题"
"问题类型中最常见的是什么？"
"获取问题 abc123 的详细信息"
"为混凝土返工创建新问题"
```
**价值**：在构建自定义报告工具之前进行快速健康检查
#### 用例 3：**调试生产问题**
**场景**：支持团队正在调查客户报告的问题
**工作流**：
```
开发者： "项目 X 中有哪些问题类型可用？"
Copilot： [返回实际问题类型]
开发者： "显示过去 24 小时内创建的所有问题"
Copilot： [返回最近的问题及其详细信息]
开发者： "获取问题 abc123 的详细信息"
Copilot： [显示完整的问题信息，包括评论和附件]
开发者： "创建一个测试问题以验证 API"
Copilot： [创建问题并返回确认问题 ID]
开发者： "项目的目录结构是什么？"
Copilot： [显示实际的文件夹层次结构]
```
**价值**：更快的故障排除，实现实时数据访问
#### 用例 4：**数据迁移规划**
**场景**：将数据从旧系统迁移到 ACC
**查询**：
```
"显示所有项目的目录结构"
"问题配置了哪些自定义字段？"
"列出项目中的所有文件类型"
"获取问题样本及其所有字段以了解数据结构"
"创建测试问题以验证目标系统可以接收 ACC 数据"
```
**价值**：在迁移脚本编写前了解目标系统结构
#### 用例 5：**培训和文档**
**场景**：培训新开发人员使用 APS API
**交互式学习**：
```
学员： "我可以从问题中获取什么数据？"
Copilot： [显示实际问题结构和数据]
学员： "如何创建问题？"
Copilot： [演示并显示所需的和可选字段]
学员： "文件夹如何组织？"
Copilot： [使用实时项目数据演示]
```
**价值**：使用真实示例学习，而不是抽象文档
### 🔄 客户工作流示例
#### 适用于建筑技术公司：
```
晨间站会：
项目经理： "今天有什么阻碍我们？"
开发人员： [打开 VS Code] "显示所有高优先级问题"
结果：团队在 5 秒内看到实际阻碍因素
开发过程中：
开发人员： "列出结构文件夹中的所有 .dwg 文件"
Copilot： [返回文件列表]
开发人员： 使用列表构建文件处理自动化
部署前：
开发人员： "这会影响哪些项目？"
Copilot： [列出所有可访问的项目]
开发人员： 计划部署策略
```
#### 系统集成商：
```
发现阶段：
"有哪些问题类型存在？" → 映射到目标系统
"显示所有自定义属性" → 计划数据转换
"列出所有项目按地区分组" → 确定集成工作量
开发阶段：
"获取问题样本数据" → 测试转换逻辑
"目录结构是什么？" → 计划文件同步策略
"显示项目元数据" → 验证连接
测试阶段：
"创建测试问题" → 验证写操作
"获取问题详情" → 验证数据完整性
"列出最近更改" → 验证同步准确性]
```
### 📊 投资回报率和指标
**时间节省**：
- API 探索：30-60 分钟 → 2-5 分钟（减少 90%）
- 数据结构发现：45 分钟 → 5 分钟（减少 89%）
- 集成原型设计：4 小时 → 1 小时（减少 75%）
**生产力提升**：
- 开发者留在 IDE：80% 的上下文切换减少
- 更快的调试：实时数据访问 vs. 手动 API 调用
- 错误减少：AI 协助查询 vs. 手动 Postman 测试
**业务影响**：
- 更快的市场集成
- 新开发人员培训成本降低
- 改善开发人员体验和满意度
- 启用快速原型设计和创新
### 🚀 未来的扩展机会
**计划中的增强功能**：
1. ✅ **问题创建** - 创建新的问题（已实现）
2. ✅ **问题详情** - 获取详细的问题信息（已实现）
3. ⏳ **问题更新** - 更新现有的问题（进行中）
4. ⏳ **问题评论** - 添加评论到问题（进行中）
5. ⏳ **问题附件** - 上传文件到问题（进行中）
6. 🔜 **高级查询**：过滤、排序、聚合数据
7. 🔜 **多项目操作**：跨项目批量查询
8. 🔜 **文件操作**：上传/下载文件
9. 🔜 **Webhook集成**：IDE中的实时通知
10. 🔜 **成本管理**：查询预算和成本数据
11. 🔜 **计划数据**：访问项目时间线和里程碑
12. 🔜 **RFI管理**：查询和管理RFI
13. 🔜 **文档管理**：搜索和分析文档
**扩展用例**：
- ✅ 从自然语言描述中创建问题
- 从代码注释自动创建问题
- IDE中的项目健康仪表盘
- 合规检查和报告
- 向利益相关者自动更新状态
- 集成测试框架
- 带有评论和附件的详细问题分析
### 🎓 客户入门指南
**适用于建筑技术团队**：
1. 设置安全服务账户（15分钟）
2. 在VS Code中配置MCP服务器（5分钟）
3. 开始查询您的项目（立即）
4. 使用自定义工具进行扩展（持续进行）
**适用于顾问/自由职业者**：
1. 用于快速原型设计（第1天）
2. 验证客户需求（第2-3天）
3. 构建生产集成（第1周及以后）
4. 提供更快、更准确的解决方案
**适用于企业团队**：
1. 与2-3名开发人员进行试点（第1周）
2.衡量时间节省和生产力（第2-4周）
3. 推广至整个团队（第2个月）
4. 使用自定义工具进行扩展（持续进行）
### 💡 成功案例（潜在）
**示例1：BIM协调公司**
- **之前**：4小时探索API并构建问题报告器
- **之后**：1小时使用MCP辅助开发
- **结果**：75%时间减少，更快的客户交付
**示例2：建筑软件供应商**
- **之前**：支持团队手动检查API响应
- **之后**：使用自然语言查询进行即时故障排除
- **结果**：60%更快的问题解决
**示例3：企业总承包商**
- **之前**：开发人员构建自定义API测试工具
- **之后**：使用MCP服务器进行所有API探索
- **结果**：消除每月20小时的工具维护
## 开发
### 先决条件
- [Node.js](https://nodejs.org)
- [APS应用程序](https://aps.autodesk.com/en/docs/oauth/v2/tutorials/create-app)（必须是**服务器到服务器**类型）
- [已预配的ACC访问权限](https://get-started.aps.autodesk.com/#provision-access-in-other-products)
### 设置
#### 安全服务账户
我们的MCP服务器将需要一个安全服务账户和私钥。我们将使用https://ssa-manager.autodesk.io来实现：
- 访问https://ssa-manager.autodesk.io并使用您的APS客户端ID和密码登录
- 使用**创建账户名称**按钮创建新的安全服务账户；不要忘记指定名字和姓氏
- 确保在**账户**列表中选择了新账户
- 记录**账户详细信息**下的`serviceAccountId`和`email`值
- 使用**创建密钥**按钮创建新的私钥；会自动下载一个*.pem*文件到您的机器上
- 确保在**密钥**列表中选择了新私钥
- 记录**密钥详细信息**下的`kid`值
#### Autodesk Construction Cloud
- 确保您的APS应用程序已预配ACC访问权限
- 将安全服务账户（前面的`email`值）作为新成员邀请到您选择的ACC项目中
#### 服务器
- 克隆此存储库
- 安装依赖项：`yarn install`
- 在此项目的根文件夹中创建一个`.env`文件，并定义以下环境变量：
- `APS_CLIENT_ID` - 您的APS应用程序客户端ID
- `APS_CLIENT_SECRET` - 您的APS应用程序客户端密码
- `SSA_ID` - 您的服务账户ID（前面的`serviceAccountId`字段）
- `SSA_KEY_ID` - 您的私钥ID（前面的`kid`字段）
- `SSA_KEY_PATH` - 您的下载的*.pem*文件路径
- `.env`文件可能如下所示：
```bash
APS_CLIENT_ID="AhH9..."
APS_CLIENT_SECRET="1FS4..."
SSA_ID="ZCU2TJH5PK8A5KQ9"
SSA_KEY_ID="8a4ee790-3378-44f3-bbab-5acb35ec35ce"
SSA_KEY_PATH="/Users/brozp/aps-mcp-server-nodejs/8a4ee790-3378-44f3-bbab-5acb35ec35ce.pem"
```
## 使用
### MCP检查器
- 运行[模型上下文协议检查器](https://modelcontextprotocol.io/docs/tools/inspector)：`npx @modelcontextprotocol/inspector`
- 点击`连接`以连接到MCP服务器
### Claude Desktop
- 确保您已安装[Claude Desktop](https://claude.ai/download)
- 如果您还没有Claude Desktop配置文件，请创建：
- 在macOS上：_~/Library/Application Support/Claude/claude\_desktop\_config.json_
- 在Windows上：_%APPDATA%\Claude\claude\_desktop\_config.json_
- 将此MCP服务器添加到配置文件中，使用您系统上_server.js_文件的绝对路径，例如：
```json
{
"mcpServers": {
"aps-mcp-server-nodejs": {
"command": "node",
"args": [
"/path/to/aps-mcp-server-nodejs/server.js"
]
}
}
}
```
- 重启Claude Desktop并在**设置** → **开发者**中验证服务器正在运行：
- 打开Claude Desktop并尝试以下一些测试提示：
- 我有哪些ACC项目？
- 给我项目XYZ的所有问题的可视化仪表盘
- 列出我的项目中的所有问题
- 显示文件夹结构
- 获取问题[issue-id]的详细信息
- 创建一个标题为“测试问题”，状态为“打开”的新问题
**示例：可视化仪表盘生成**
Claude可以从您的ACC数据创建交互式可视化和仪表盘：
MCP服务器使Claude能够：
- 从ACC查询实时项目数据
- 生成带有问题统计信息的可视化仪表盘
- 创建按类型、状态等显示问题的图表
- 通过自然对话提供详细的项目洞察
> 有关如何将MCP服务器添加到Claude Desktop的详细信息，请参阅[官方文档](https://modelcontextprotocol.io/quickstart/user)。
### Visual Studio Code & GitHub Copilot
- 确保您已在Visual Studio Code中[启用MCP服务器](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_enable-mcp-support-in-vs-code)
- 在您的workspace中创建_.vscode/mcp.json_文件，并添加以下JSON：
```json
{
"servers": {
"aps-mcp-server-nodejs": {
"type": "stdio",
"command": "node",
"args": [
"/path/to/aps-mcp-server-nodejs/server.js"
]
}
}
}
```
> 有关如何将MCP服务器添加到Visual Studio Code的详细信息，请参阅[文档](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
### Cursor
- 在您的workspace中创建_.cursor/mcp.json_文件，并添加以下JSON：
```json
{
"mcpServers": {
"aps-mcp-server-nodejs": {
"command": "node",
"args": [
"/path/to/aps-mcp-server-nodejs/server.js"
]
}
}
}
```
> 有关如何将MCP服务器添加到Cursor的详细信息，请参阅[文档](https://docs.cursor.com/context/model-context-protocol)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器