内容
# APS MCP 服务器适用于 Claude
一个 [模型上下文协议](https://modelcontextprotocol.io/) (MCP) 标准输入/输出服务器，为 **Claude 代码** 提供访问您的 **Autodesk 建设云 (ACC)** 环境的权限，通过 **Autodesk 平台服务 (APS) API** — 即支撑 ACC 和 Forma 的 REST API。 通过自然语言对话管理用户、审计权限和探索项目。
---
## 先决条件
- Python 3.11+
- 已安装 [Claude 代码](https://docs.anthropic.com/en/docs/claude-code)
- 一个带有客户端 ID 和客户端密钥的 **APS 应用** （[在这里创建](https://aps.autodesk.com/myapps)）
- 一个 Autodesk 账户，拥有您的 ACC 中心的 **账户管理员** 访问权限
---
## 身份验证
服务器使用 **两种 OAuth 流** ，均由相同的 APS 应用凭证支持。
### 2-腿 OAuth（客户端凭证）
用于不需要用户上下文的账户级操作：列出所有账户用户、查找公司、为批量操作解析用户列表。
- **工作原理：** 服务器直接用您的客户端 ID + 密钥交换访问令牌。无需浏览器登录。令牌在每个进程中缓存在内存中。
- **所需范围：** `account:read`
- **使用场景：** `list_account_users` 、 `list_project_companies` 、 `list_account_companies` 和中心目录写入工具（`bulk_add_hub_users` 、 `bulk_add_hub_companies` 、 `deactivate_hub_users` 、 `deactivate_hub_companies` ）
### 3-腿 OAuth（用户上下文）
用于所有项目、文件夹和权限操作 — API 代表您（登录的 Autodesk 用户）执行操作。
- **工作原理：** 在首次使用时，会自动打开一个浏览器窗口。您使用 Autodesk 账户登录并授予同意。令牌缓存在 `tokens.json` 中并自动刷新。您只需在约 14 天不活动后重新授权。
- **所需范围：** `data:read` 、 `account:read` 、 `account:write` （用于批量用户管理工具）
- **使用场景：** 所有导航、文件夹和权限工具；所有批量用户写入操作
---
## 设置您的 APS 应用
### 1. 创建应用
1. 前往 [aps.autodesk.com/myapps](https://aps.autodesk.com/myapps) 并点击 **创建应用** 。
2. 在 **API 访问** 下，启用：
- 数据管理 API
- ACC 账户管理员 API
- BIM 360 API
3. 添加 `http://localhost:8080/oauth/callback` 作为允许的 **回调 URL** 。
4. 复制您的 **客户端 ID** 和 **客户端密钥** 。
### 2. 在您的 ACC 中心注册应用为自定义集成
在应用可以访问您中心的數據之前，账户管理员必须注册它：
1. 打开 **ACC** 并前往 **账户管理员 → 自定义集成** 。
2. 点击 **添加自定义集成** 。
3. 输入您的 **客户端 ID** 并按照提示将应用链接到您的中心。
如果缺少此步骤，API 调用将返回 403 错误，即使凭证有效。
---
## 安装
```bash
git clone https://github.com/lfcastel/Forma-MCP.git
cd Forma-MCP
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate
pip install -r requirements.txt
```
---
## 在 Claude 代码中配置
将服务器添加到 `~/.claude.json` 中的 Claude 代码用户配置中。调整路径到您克隆此仓库的位置：
```json
"mcpServers": {
"aps": {
"type": "stdio",
"command": "/path/to/forma-mcp/.venv/bin/python",
"args": ["/path/to/forma-mcp/aps_mcp.py"],
"env": {
"APS_CLIENT_ID": "your_client_id",
"APS_CLIENT_SECRET": "your_client_secret"
}
}
}
```
**Windows 路径** — 使用正斜杠或转义的反斜杠：
```
C:/Users/YourName/Documents/forma-mcp/.venv/Scripts/python.exe
```
重启 Claude 代码后保存，然后运行 `claude mcp list` — `aps` 应该显示为已连接。
---
## 工具参考
> **同一区域中的多个中心？** 每个工具都接受一个可选的 `hub_name` 参数（部分匹配，不区分大小写）。在您的账户中有多个 EMEA 中心并且需要定位特定中心时传递它 — 例如 `hub_name: "My Company - EU Hub"` 。如果没有它，则使用为该区域返回的第一个中心。
>
> **粘贴项目 ID 或 ACC URL。** 每个单项目工具还接受一个可选的 `project` 参数 — 项目 **名称** 、项目 **ID** （ `b.xxxx` 或裸 UUID）或 **完整的 ACC URL** 。当它包含 ID/URL 时，工具在一次管理员 API 调用中固定确切的拥有中心（无需区域猜测，无需错误中心风险），因此您永远不需要 `hub_name` 。旧的 `project_name` 参数作为仅名称的别名继续有效。使用独立的 `resolve_project` 工具将其中任何一个转换为 `{project_id, hub_id, hub_name, region, platform}` 。
>
> **批量用户工具（ `project_names` 数组）。** `bulk_assign_users` 、 `update_user_roles` 、 `bulk_assign_company_users` 和 `remove_users_from_projects` 以相同的方式解析每个条目 — 每个名称、项目 ID 或 ACC URL 都在 **所有** 中心进行匹配，因此非默认 EMEA 中心的项目无需 `hub_name` 即可解析。跨中心发生真正的同名冲突时会引发明确的歧义错误（传递 ID/URL 或 `hub_name` 以消除歧义）。
### 导航和文件探索
| 工具 | 功能 | 认证 |
|------|-------------|------|
| `list_hubs` | 列出您账户中的所有 ACC / BIM360 中心 | 3-腿 OAuth |
| `list_projects` | 列出中心中的所有项目 | 3-腿 OAuth |
| `resolve_project` | 从名称、ID （ `b.xxx`/裸 UUID）或 ACC URL 解析项目 → 项目 + 所属中心，一次调用 | 2-腿 OAuth（ID/URL）/ 3-腿 OAuth（名称） |
| `list_top_folders` | 列出项目中的顶级文件夹 | 3-腿 OAuth |
| `list_folder_contents` | 列出给定路径下的文件和子文件夹 | 3-腿 OAuth |
| `rename_folder` | 按显示名称路径重命名文件夹 | 3-腿 OAuth |
| `rename_file` | 通过创建新版本重命名文件（无需重新上传） | 3-腿 OAuth |
| `create_folder` | 在现有父文件夹中创建新文件夹 | 3-腿 OAuth |
| `move_file` | 将文件移动到另一个文件夹（更改其父文件夹；无需重新上传） | 3-腿 OAuth |
| `move_folder` | 将文件夹（及其内容）移动到另一个父文件夹 | 3-腿 OAuth |
| `find_files` | 在项目中按名称搜索文件 | 3-腿 OAuth |
| `list_all_files` | 递归列出项目（或文件夹 + 子文件夹）中的 **所有** 文件，带有完整路径 | 3-腿 OAuth |
| `export_deliverables_manifest` | 文件名仅递归列表（去重、排序、无元数据），用于与外部交付列表进行交叉检查 | 3-腿 OAuth |
| `find_folder` | 在项目中按名称搜索文件夹 | 3-腿 OAuth |
| `delete_folder` | 软删除（隐藏）空文件夹 | 3-腿 OAuth |
| `find_recent_activity` | 显示给定日期后修改的文件 | 3-腿 OAuth |
### 用户和成员管理
| 工具 | 功能 | 认证 |
|------|-------------|------|
| `list_project_members` | 列出项目的所有成员及其角色 | 3-腿 OAuth |
| `list_account_users` | 列出 ACC 账户中的所有用户 | 2-腿 OAuth |
| `list_project_roles` | 列出项目中定义的所有角色 | 3-腿 OAuth |
| `list_project_companies` | 列出链接到项目的公司 | 2-腿 OAuth |
| `list_account_companies` | 列出中心目录（账户级）中的每个公司，带有 ID、行业、状态 | 2-腿 OAuth |
### 权限
| 工具 | 功能 | 认证 |
|------|-------------|------|
| `export_permission_matrix` | 导出文件夹树的完整权限矩阵 | 3-腿 OAuth |
| `apply_permission_changes` | 将批量权限更改应用于文件夹 | 3-腿 OAuth |
### 角色和数据导出
| 工具 | 功能 | 认证 |
|------|-------------|------|
| `create_role_data_export` | 触发 Data Connector `admin` 导出以解析完整的项目角色目录（ID ↔ 名称，**包括空角色** ） — 用于将用户分配给未使用的角色或标记 `export_permission_matrix` | 3-腿 OAuth |
| `get_data_connector_requests` | 轮询和下载已完成的 Data Connector 导出；返回 `role_id → name` 映射 | 3-腿 OAuth |
### 批量用户管理
所有五个批量工具默认 **`dry_run: true`** — Claude 始终在进行任何更改之前显示预览。每次实时执行时都会写入时间戳审计 CSV （ `audit_<operation>_<timestamp>.csv` ）。
| 工具 | 功能 | 认证 |
|------|-------------|------|
| `bulk_assign_users` | 将用户列表添加到一个或多个项目中，带有指定的角色（s） | 3-腿 OAuth + `account:write` |
| `update_user_roles` | 更新现有项目成员的角色（s） | 3-腿 OAuth + `account:write` |
| `remove_users_from_projects` | 从一个或多个项目中删除用户 | 3-腿 OAuth + `account:write` |
| `clone_user_access` | 复制一个用户的完整项目访问权限（所有角色）到另一个用户 | 3-腿 OAuth + `account:write` |
| `bulk_assign_company_users` | 将 ACC 公司的所有成员添加到项目中 | 3-腿 OAuth + `account:write` |
> **每个用户的多个角色。** `bulk_assign_users` 、 `update_user_roles` 和 `bulk_assign_company_users` 接受 `default_role` （和每个 `role_overrides` 值）为单个角色或 **列表** — 例如 `default_role: ["BIM Coordinator", "EXT Architect"]` — 一次将多个角色分配给用户（API 的 `roleIds` 是数组）。每个条目是一个角色 **名称** 或原始角色 **ID** 。 `clone_user_access` 复制 **所有** 项目的引用用户角色。
### 中心级目录和入职
这些操作在 **中心成员/公司目录** （账户级别）上，而不是在单个项目上 — 入职步骤必须在用户可以分配到项目之前发生。所有四个默认 **`dry_run: true`** ，在实时运行中写入时间戳审计 CSV ，批量导入 ≤50 个 API 调用，并支持 `response_detail` 。与上面的批量工具不同，批量工具将 **已存在** 的中心成员分配给项目。
| 工具 | 功能 | 认证 |
|------|-------------|------|
| `bulk_add_hub_users` | 批量将用户添加到中心，每个用户带有公司（必填）+ 可选的默认角色；幂等（ `already_exists` ） | 2-腿 OAuth （ `account:write` ） |
| `bulk_add_hub_companies` | 将合作伙伴公司导入中心目录（必填名称 + 行业）；幂等（ `already_exists` ） | 2-腿 OAuth （ `account:write` ） |
| `deactivate_hub_users` | 软关闭中心用户（ `status: inactive` ； API 没有硬删除） | 2-腿 OAuth （ `account:write` ） |
| `deactivate_hub_companies` | 在中心目录中停用公司（ `status: inactive` ） | 2-腿 OAuth （ `account:write` ） |
> **入职，而不是项目分配。** `bulk_add_hub_users` 创建中心账户； `bulk_assign_users` 授予项目访问权限。典型的加入流程是： `bulk_add_hub_companies` （如果公司是新的）→ `bulk_add_hub_users` → `bulk_assign_users` 。 `bulk_add_hub_users` 将 `company_name` 解析为中心目录，如果公司尚不存在则出错，因此请先创建它。
### 批量文件夹操作
用于大规模重组文件夹结构的三个可组合基元（例如，在一个项目中为数百个建筑文件夹标准化子文件夹）。它们故意 **简单和通用** — Claude 实例执行编排和判断（审计 → 决定要创建/删除的内容 → 暴露异常和卡住的文件）；没有重组策略内置于工具中。两个变更工具默认 **`dry_run: true`** 。
| 工具 | 功能 | 认证 |
|------|-------------|------|
| `bulk_list_folder_contents` | 审计引擎（只读）：列出许多文件夹的直接内容 — 或一个父文件夹的每个子文件夹 — 在一次调用中，返回子文件夹（名称 + ID）和文件 | 3-腿 OAuth |
| `audit_folder_naming_standards` | 命名约定审计（只读）：遍历文件夹子树（或整个项目）并报告每个文件夹执行的命名标准，按标准分组，并标记没有标准的 folders | 3-腿 OAuth |
| `bulk_create_folders` | 幂等批量创建： `{parent, name}` 项； `skip_if_exists` （默认）报告 `exists` 而不是重复 | 3-腿 OAuth |
| `bulk_delete_folders` | 文件安全批量软删除：从不删除具有任何文件的子树的 folders — 将其报告为 `skipped_has_files` ，带有 `file_count` + `sample_files` | 3-腿 OAuth |
| `bulk_move_files` | 批量将文件移动到新文件夹（无需重新上传）；幂等（ `already_there` ）； 403 错误的 C4R 模型报告为 `skipped_unmovable` | 3-腿 OAuth |
| `bulk_move_folders` | 批量将文件夹（及其内容）移动到新父文件夹下；幂等（ `already_there` ） | 3-腿 OAuth |
> **文件安全性是绝对的。** `bulk_delete_folders` 应用与单个 `delete_folder` 相同的文件树检查，并且仅软删除（管理员可逆）。 `skipped_has_files` 行是“卡住”的文件（通常是 API 无法移动的云工作共享 Revit/C4R 模型），供人类在 ACC UI 中重新定位。两个变更工具支持 `continue_on_error` （默认为 true ）、 `max_concurrency` 限制（默认为 8 ）并在批量中间生存令牌过期（401 触发一次性令牌刷新）。
#### 输出详细程度 — `response_detail`
`bulk_move_files` 、 `bulk_move_folders` 、 `bulk_delete_folders` 、 `bulk_list_folder_contents` 和 `audit_folder_naming_standards` 接受一个 `response_detail` 参数，该参数在不更改工具执行的情况下，调整返回的 `results` 数组 **。**
| 值 | 返回 |
|-------|---------|
| `full` | 每一行（旧行为 — 丢弃任何内容）。 |
| `changes` *(默认)* | 摘要 + 仅需要关注的行 — 移动保留 `error` / `skipped_unmovable` / `not_found` ；删除保留 `skipped_has_files` / `error` ；内容审计仅保留具有文件或子文件夹的文件夹；命名标准审计仅保留没有标准的 folders 。成功/无操作噪音（ `moved` 、 `already_there` 、 `deleted` 、空文件夹，已有标准的文件夹）被丢弃。 |
| `summary` | 仅摘要计数 — 省略单个项目 `results` 数组。 **永远不会丢失失败：** 任何锁定/不可移动/卡住的行（或无标准的文件夹）仍在小 `failures` 数组下显示（以及内容审计的单独 `errors` 数组始终存在）。 |
`changes` 是默认的，因为在典型的批量中，几乎所有操作都成功且静默，只有锁定/冲突情况需要操作 — 返回这些操作的大部分令牌节省。传递 `response_detail: "full"` 以获得旧的回声所有行为。
> **精简审计 — `fields` 。** `bulk_list_folder_contents` 还接受 `fields: ["files", "subfolders"]` 以限制每个文件夹行仅限于这些部分。当给定 `fields` 时，文件条目以精简形式返回（仅 `id` + `name` ，丢弃 `last_modified` / `created_by` ） — 理想情况下，您只需要 URN 将其直接馈送到 `bulk_move_files` 调用中。
> **命名约定在一个传递中 — `include_naming_standard` 。** 文件夹的 `folders/{f}/contents` 载荷已经带有每个子文件夹的分配命名标准，因此 `bulk_list_folder_contents` 可以免费显示它：传递 `include_naming_standard: true` ，每个子文件夹行都会获得一个 `naming_standard_ids` 列表（空 = 无）。在您需要列表 **和** 约定时使用此功能，而不是再次调用 `audit_folder_naming_standards` （这将重新获取相同的端点）。如果您想要一个 *递归的* 、项目范围的汇总，按标准分组；如果您想要此标志，则调用 `audit_folder_naming_standards` 。
### 问题
读取和创建 ACC **问题** （问题模块）。所有五个问题都是用户范围的（3-腿 OAuth），并使用固定的 `x-ads-region: EMEA` 头与 `construction/issues/v1` API 交互。 `create_issue` **立即发布** （无 `dry_run` ）。API 使用与 UI 不同的名称：类别是 **类型** ，而 UI 类型是 **子类型** — `list_issue_types` 返回两者。 不兼容于 BIM 360 项目；带有工作表相关问题（Build Sheets）的问题不会返回。
| 工具 | 功能 | 认证 |
|------|-------------|------|
| `list_issues` | 列出问题（带有通用筛选器：状态、搜索、指派人、日期、类型/子类型、链接的文件 URN、已删除）；自动分页； `fields` 使每一行变薄 | 3-腿 OAuth |
| `get_issue` | 通过 `issue_id` （UUID）或 `display_id` （友好编号）获取一个问题 | 3-腿 OAuth |
| `create_issue` | 创建一个问题 — 需要 `title` 、 `issue_subtype_id` 、 `status` ；立即发布 | 3-腿 OAuth （ `data:write` ） |
| `update_issue` | 更新一个问题（编辑字段、更改状态、重新指派）通过 `issue_id` / `display_id` ；仅发布您提供的字段 | 3-腿 OAuth （ `data:write` ） |
| `list_issue_types` | 列出问题类别 + 它们的类型（带有 3 个字符的代码） — 有效的 `issue_subtype_id` 和解码类型 UUID 的来源 | 3-腿 OAuth |
| `list_issue_attribute_definitions` | 列出项目自定义字段（ID、标题、数据类型、下拉选项） | 3-腿 OAuth |
| `list_issue_attribute_mappings` | 列出哪些自定义字段被分配给哪些类别/类型 | 3-腿 OAuth |
> **获取有效的 `issue_subtype_id` 。** 先调用 `list_issue_types` ；每个类别都带有 `subtypes` 数组，其 `id` 是 `create_issue` 所需的。指派人、观察者、根本原因和位置 ID **无法** 通过问题 API 发现 — 按 Autodesk 建议，使用数据连接器提取它们。
> **解决一个问题。** `get_issue` 和 `update_issue` 接受问题 UUID （ `issue_id` ）或用户可见编号 （ `display_id` ，例如 191），因此您可以说“标记问题 191 为已关闭”。注意 ACC 问题 API （v1） **没有删除端点** — 问题只能在 ACC UI 中删除（通过 API， `deleted` 是只读的），因此没有 `delete_issue` 工具。 `list_issues` 仍然可以通过 `deleted: true` 在 UI 中显示已删除的问题。
### 审批工作流
阅读和创建ACC **审批工作流** （Reviews模块 — 可重复使用的步骤/审阅者/持续时间定义，用于驱动文件审阅）。所有工作流都是用户范围的（3-legged），并调用 `construction/reviews/v1` API，带有固定的 `x-ads-region: EMEA` 头部。适用于批量配置工作流 — 例如，读取工作流的Excel模板并将它们推送到ACC。不兼容于BIM 360项目。
| 工具 | 功能 | 认证 |
|------|-------------|------|
| `list_workflows` | 列出审批工作流；按 `status` （默认为ACTIVE / INACTIVE）或 `initiator` ； `sort` ；自动分页 | 3-legged |
| `get_workflow` | 通过 `workflow_id` （UUID）或 `name` 获取工作流 | 3-legged |
| `create_workflow` | 创建工作流 — `name` + `steps` 必需；立即发布（无 `dry_run` ） | 3-legged（`data:write` ） |
| `bulk_create_workflows` | 从规格列表（Excel批量）创建多个工作流； `dry_run` 默认，审计CSV，有限并发，每行结果 | 3-legged（`data:write` ） |
> **审阅者通过姓名指定，解析为Autodesk ID。** Reviews API通过 `autodeskId` 标识每个审阅者/批准者。 `create_workflow` / `bulk_create_workflows` 接受友好的 `reviewer_users` （姓名或电子邮件）， `reviewer_roles` （角色名称）和 `reviewer_companies` （公司名称）每个步骤；原始 `autodeskId` 值也会传递，未解析的引用会大声失败。 **用户** 从项目成员解析 — `list_project_members` / `list_project_roles` 现在包括一个 `autodesk_id` 字段，以便您看到它们。 **角色和公司** 更复杂：它们使用单独的数字ID空间，Autodesk不为其公开查找API，因此工具从项目的 **现有** 工作流中收集角色/公司名称→ID。尚未在任何工作流中使用的角色或公司无法通过名称解析 — 读取一个并使用 `get_workflow` 传递原始数字 `autodeskId` 。
> **单个与批量。** `create_workflow` 立即发布一个工作流（像 `create_issue` 一样）。 `bulk_create_workflows` 是可预览的批量：它解析审阅者目录一次，默认为 `dry_run=true` （ `would_create` ），将名称冲突映射到 `already_exists` （409）每行，并在实时运行上编写时间戳审计CSV。范围是列表+获取+创建 — Reviews API不公开工作流更新/删除路由。
---
## 工具和API端点
所有工具按功能分组，每个工具调用的APS API端点。
```mermaid
flowchart LR
classDef tool fill:#F0F4FF,stroke:#6C8EBF,color:#333
classDef get fill:#1A6FAF,stroke:#145A8B,color:#fff
classDef post fill:#1E7E34,stroke:#155724,color:#fff
classDef patch fill:#E67E22,stroke:#CA6F1E,color:#fff
classDef del fill:#C0392B,stroke:#962D22,color:#fff
subgraph NAV["导航和文件 · 3-legged OAuth"]
T1(list_hubs)
T2(list_projects)
T38(resolve_project)
T3(list_top_folders)
T4(list_folder_contents)
T20(rename_folder)
T21(rename_file)
T22(create_folder)
T25(move_file)
T26(move_folder)
T5(find_recent_activity)
T6(find_files)
T39(list_all_files)
T40(export_deliverables_manifest)
T23(find_folder)
T24(delete_folder)
end
subgraph UMEM["用户信息 · 3-legged + 2-legged"]
T7(list_project_members)
T8(list_account_users)
T9(list_project_roles)
T10(list_project_companies)
T33(list_account_companies)
end
subgraph PERMS["权限 · 3-legged OAuth"]
T11(export_permission_matrix)
T12(apply_permission_changes)
end
subgraph ROLES["角色导出 · 3-legged OAuth"]
T13(create_role_data_export)
T14(get_data_connector_requests)
end
subgraph BULK["批量用户管理 · 3-legged + account:write · 默认dry_run=true"]
T15(bulk_assign_users)
T16(update_user_roles)
T17(remove_users_from_projects)
T18(clone_user_access)
T19(bulk_assign_company_users)
end
subgraph HUBDIR["Hub目录和入职 · 2-legged account:write · 默认dry_run=true"]
T34(bulk_add_hub_users)
T35(bulk_add_hub_companies)
T36(deactivate_hub_users)
T37(deactivate_hub_companies)
end
subgraph BULKF["批量文件夹操作 · 3-legged OAuth · 默认dry_run=true"]
T27(bulk_list_folder_contents)
T28(bulk_create_folders)
T29(bulk_delete_folders)
T30(bulk_move_files)
T31(bulk_move_folders)
T32(audit_folder_naming_standards)
end
subgraph ISSUES["问题 · 3-legged OAuth · x-ads-region: EMEA"]
T41(list_issues)
T42(create_issue)
T43(list_issue_types)
T44(list_issue_attribute_definitions)
T45(list_issue_attribute_mappings)
T46(get_issue)
T47(update_issue)
end
subgraph WORKFLOWS["审批工作流 · Reviews · 3-legged OAuth · x-ads-region: EMEA"]
T48(list_workflows)
T49(get_workflow)
T50(create_workflow)
T51(bulk_create_workflows)
end
E1["GET /project/v1/hubs"]
E2["GET /project/v1/hubs/{hub}/projects"]
E3["GET /project/v1/.../projects/{p}/topFolders"]
E4["GET /data/v1/projects/{p}/folders/{f}/contents"]
E5["GET /construction/admin/v1/projects/{p}/users"]
E6["GET /hq/v1/accounts/{a}/users"]
E7["GET /projects/{p}/users"]
E8["GET /hq/v1/accounts/{a}/projects/{p}/companies"]
E9["GET /bim360/docs/v1/.../folders/{f}/permissions"]
E10["POST .../permissions:batch-create"]
E11["POST .../permissions:batch-delete"]
E12["POST /data-connector/v1/accounts/{a}/requests"]
E13["GET .../requests/{r}/jobs + ZIP download"]
E14["POST /construction/admin/v2/projects/{p}/users:import"]
E15["PATCH /construction/admin/v1/projects/{p}/users/{u}"]
E16["DELETE /construction/admin/v1/projects/{p}/users/{u}"]
E17["PATCH /data/v1/projects/{p}/folders/{f}"]
E18["POST /data/v1/projects/{p}/versions?copyFrom=..."]
E19["POST /data/v1/projects/{p}/folders"]
E20["PATCH /data/v1/projects/{p}/items/{i}"]
E21["GET /data/v1/projects/{p}/folders/{f}"]
E22["GET /construction/admin/v1/accounts/{a}/companies"]
E23["POST /hq/v1/accounts/{a}/users/import"]
E24["POST /hq/v1/accounts/{a}/companies/import"]
E25["PATCH /hq/v1/accounts/{a}/users/{u}"]
E26["PATCH /hq/v1/accounts/{a}/companies/{c}"]
E27["GET /construction/admin/v1/projects/{p}?fields=accountId,name,platform"]
E28["GET /construction/issues/v1/projects/{p}/issues"]
E29["POST /construction/issues/v1/projects/{p}/issues"]
E30["GET /construction/issues/v1/projects/{p}/issue-types"]
E31["GET /construction/issues/v1/projects/{p}/issue-attribute-definitions"]
E32["GET /construction/issues/v1/projects/{p}/issue-attribute-mappings"]
E33["GET /construction/issues/v1/projects/{p}/issues/{i}"]
E34["PATCH /construction/issues/v1/projects/{p}/issues/{i}"]
E35["GET /construction/reviews/v1/projects/{p}/workflows"]
E36["GET /construction/reviews/v1/projects/{p}/workflows/{w}"]
E37["POST /construction/reviews/v1/projects/{p}/workflows"]
T1 --> E1
T2 --> E2
T38 --> E27
T38 --> E1
T38 --> E2
T3 --> E3
T4 --> E4
T20 --> E17
T21 --> E18
T22 --> E19
T25 --> E20
T26 --> E17
T5 --> E4
T6 --> E4
T39 --> E3
T39 --> E4
T40 --> E3
T40 --> E4
T23 --> E4
T24 --> E17
T7 --> E5
T7 --> E6
T8 --> E6
T9 --> E7
T10 --> E8
T11 --> E9
T12 --> E10
T12 --> E11
T13 --> E12
T14 --> E13
T15 --> E14
T16 --> E15
T17 --> E16
T18 --> E5
T18 --> E14
T19 --> E6
T19 --> E14
T33 --> E22
T34 --> E22
T34 --> E6
T34 --> E23
T35 --> E22
T35 --> E24
T36 --> E6
T36 --> E25
T37 --> E22
T37 --> E26
T27 --> E4
T28 --> E4
T28 --> E19
T29 --> E4
T29 --> E17
T30 --> E4
T30 --> E20
T31 --> E4
T31 --> E17
T32 --> E3
T32 --> E4
T32 --> E21
T41 --> E28
T42 --> E29
T43 --> E30
T44 --> E31
T45 --> E32
T46 --> E33
T47 --> E34
T48 --> E35
T49 --> E35
T49 --> E36
T50 --> E37
T50 --> E5
T50 --> E8
T51 --> E37
T51 --> E5
T51 --> E8
class T1,T2,T3,T4,T5,T6,T7,T8,T9,T10,T11,T12,T13,T14,T15,T16,T17,T18,T19,T20,T21,T22,T23,T24,T25,T26,T27,T28,T29,T30,T31,T32,T33,T34,T35,T36,T37,T38,T39,T40,T41,T42,T43,T44,T45,T46,T47,T48,T49,T50,T51 tool
class E1,E2,E3,E4,E5,E6,E7,E8,E9,E13,E21,E22,E27,E28,E30,E31,E32,E33,E35,E36 get
class E10,E11,E12,E14,E18,E19,E23,E24,E29,E37 post
class E15,E17,E20,E25,E26,E34 patch
class E16 del
<font color="#1A6FAF">蓝色</font>：GET — 只读
<font color="#1E7E34">绿色</font>：POST — 创建/批量导入
<font color="#E67E22">橙色</font>：PATCH — 更新
<font color="#C0392B">红色</font>：DELETE — 删除
<font color="#ADD8E6">浅蓝色</font>：MCP工具节点
---
## 示例提示
### 导航和搜索
```
列出我的所有ACC中心
显示我中心的所有项目
显示"My Company - EU Hub"中心的所有项目
解析https://acc.autodesk.eu/docs/files/projects/<project-id> — 它在哪个中心？
列出项目 b.<project-id> 的顶级文件夹（粘贴ID，无需中心名称）
"Northgate Tower" 的顶级文件夹是什么？
列出"Northgate Tower"中的"Project Files/Drawings/Structural"的内容
列出"Northgate Tower"中心"My Company - EU Hub"中的"Project Files/Drawings"的内容
在"Northgate Tower"中找到所有名为"facade"的文件
列出"Northgate Tower"中的所有文件
列出"Northgate Tower"中"Project Files/Drawings"下的所有文件（包括子文件夹）
"Northgate Tower"中哪些文件在过去7天内被修改了？
```
### 用户和访问管理
```
"Riverside Bridge"项目的成员是谁？
列出账户中所有为Acme Engineering工作的用户
"Central Station"项目有哪些角色？
```
### 中心入职（始终在执行前预览）```
列出中心目录中的所有公司
将john.doe@acme.com和jane.roe@acme.com添加到中心下的"Acme Engineering"公司
将名为"Beta Builders"（Electrical）的新公司导入中心
中心中停用leaver@acme.com
```
### 批量操作（始终在执行前预览）```
将Acme Engineering的所有用户添加到"Northgate Tower"项目中作为Design Team成员
克隆john.doe@example.com的项目访问权限并赋予jane.smith@example.com
从所有项目中移除alice@contractor.com
将"Central Station"项目中Acme Engineering成员的角色更新为Viewer
显示将Acme Engineering添加到"Riverside Bridge"项目的dry run结果
```
### 权限审计```
导出"Northgate Tower"中Project Files的完整权限矩阵
```
### 命名约定审计
```
哪些文件夹在"Northgate Tower"中具有命名标准分配，哪些没有？
在"Northgate Tower"中审计"Project Files/Drawings"的文件夹命名约定
仅显示"Northgate Tower"中没有命名标准的文件夹
```
### 问题
```
列出"Northgate Tower"中的所有开放问题
显示"Northgate Tower"中的问题类别和类型
查找在<autodesk-id>在"Central Station"中分配给哪些问题在下个月内到期？
问题在"Riverside Bridge"中定义了哪些自定义字段？
在"Northgate Tower"中创建一个问题，标题为“ L2上的板条开裂”，状态为打开，使用“缺陷”类型
显示"Northgate Tower"中的问题191
将"Northgate Tower"中的问题191标记为已关闭
```
### 审批工作流
```
列出"Northgate Tower"中的审批工作流
显示"Northgate Tower"中的"设计审查"工作流
在"Northgate Tower"中创建一个名为"IFC Sign-off"的审批工作流，其中包含一个审批步骤，Alice和"BIM Manager"角色审查，持续5个工作日
读取workflows.xlsx并将每个行推入"Northgate Tower"（先预览，然后创建）
```
---
## 安全和凭证
- **3-legged OAuth** — 用户令牌在第一次浏览器登录后缓存在 `tokens.json` 中。 该文件列在 `.gitignore` 中 — 永远不要提交它。
- **2-legged OAuth** — 使用您的APS Client ID和Secret（存储在 `~/.claude.json` 中，Claude Code的配置）。令牌由此凭证派生，并在运行时缓存 **仅在内存中** — 它永远不会写入磁盘。
- 每个用户都使用 **他们自己的Autodesk帐户** 进行3-legged OAuth验证。 服务器使用他们的权限进行操作，而不是使用提升的应用程序级权限。
- 批量写入工具默认为 `dry_run: true` — 如果没有明确确认，则不会进行任何更改。
---
## 故障排除
| 症状 | 可能原因 | 修复 |
|---------|-------------|-----|
| 任何API调用均为403 | 应用程序未在中心注册为自定义集成 | 帐户管理员必须通过 **ACC帐户管理员→自定义集成** 添加 |
| 文件夹或权限调用为403 | 令牌过期 | 删除 `tokens.json` 以强制重新登录 |
| MCP服务器未列出 | 配置路径错误或虚拟环境未设置 | 运行 `claude mcp list` ；检查 `~/.claude.json` 中的路径 |
| 浏览器未打开登录 | 端口8080已被占用 | 释放端口8080并重试 |
| 公司未找到 | 尚未添加到ACC帐户 | 通过 `bulk_add_hub_companies` 添加，或帐户管理员通过 **ACC帐户管理员→公司** 添加 |
| 公司不在项目中 | 已添加到帐户但未链接到项目 | 项目管理员通过 **ACC管理员→项目管理员→公司** 添加 |
```
---
## 已知限制
- **用户上次活动日期** — `last_sign_in` 字段仅针对 **BIM360项目** 填充。 基础ACC帐户管理员API不会为Forma项目返回此字段，因此活动时间戳将为空。
- **APS速率/配额限制** — Autodesk对每个应用程序的API配额强制执行限制。 当其中一个限制被击中时，工具会返回一个干净的 `quota_exceeded` 结果（HTTP 429），并带有 `Retry-After` 提示 — 等待建议的时间并重试。 暂时的速率峰值会自动重试几次，短暂停顿后重试； 仅持久性配额错误才会显示给你。
- **Cloud-workshared Revit模型无法通过API移动** — C4R模型（ `C4RModel` ）在移动时返回403，无法通过编程方式重新定位。 在 `bulk_delete_folders` 重新组织过程中，它们是保持文件夹不被删除的原因：它被报告为 `skipped_has_files` ，因此人类可以在Revit/ACC UI中先移动它们。
- **没有对中心用户或公司进行硬删除** — HQ API仅支持软退出，因此 `deactivate_hub_users` / `deactivate_hub_companies` 将 `status: inactive` 而不是删除记录。 停用的条目在帐户目录中仍然可见（作为非活动状态）。
- **中心入职无法授予帐户管理员权限** — `bulk_add_hub_users` 设置每个用户的公司和（可选的）默认角色，但基础 `users/import` 端点无法将某人提升到 **帐户管理员** ；在ACC UI中执行此操作。
- **问题无法通过API删除** — ACC问题API（v1）没有公开删除路由： `deleted` 在更新端点上是只读的（PATCH {"deleted": true}返回400），原始HTTP DELETE被拒绝（403）。因此，没有 `delete_issue` 工具 — 问题只能在ACC UI中删除。 `list_issues` 仍然可以通过 `deleted: true` 表面删除的问题。
- **空项目角色不可见；角色分配不可预先检查** — ACC没有项目角色目录端点，因此 `list_project_roles` （和批量用户工具中的角色名称解析）源自当前成员持有的角色 — 分配给没有人角色的角色不会出现。 由于这个原因，批量用户工具 **不** 预先拒绝角色：解析为成员持有的角色的值被原样使用，其他值被传递到ACC API进行验证（无效值在API中失败）。 要为 **空/新建** 角色分配第一个人，请传递该角色的 **ID** 而不是其名称。 发现空角色ID的可靠方法是 **数据连接器管理员** 导出，它包含完整的项目角色目录（不仅是成员角色）：为项目调用 `create_role_data_export` ，然后使用返回的 `request_id` 调用 `get_data_connector_requests` — 它轮询作业并返回 `{role_id: role_name}` 映射，包括空角色。 （数据连接器按中心限制为24个作业/24小时，因此请一次导出您需要的每个 `role_id` 并重用它们。）或者，ID也可以来自 `list_project_roles` 在角色已经有成员的项目上，或者来自 `get_workflow` 候选者。
```
---
## 许可
在 [GNU Lesser General Public License v3.0](https://www.gnu.org/licenses/lgpl-3.0.html) （LGPL-3.0）下许可。
---
## 贡献
```bash
git clone https://github.com/lfcastel/Forma-MCP.git
cd Forma-MCP
python -m venv .venv && .venv\Scripts\activate # Windows
pip install -r requirements.txt
python -m pytest tests/ -v # 所有测试必须通过后才能推送
```
所有更改都经过拉取请求。 GitHub Actions在每个PR上自动运行测试套件 — PR在CI变为绿色之前无法合并。
> **一次性仓库设置（仅限所有者）：** 在第一次CI运行完成后，进入 **设置→分支→添加规则** 以获取 `main` ，勾选 *需要状态检查通过* ，并选择 `test` 作业。
## 仓库布局
```
forma-mcp/
├── aps_mcp.py # MCP服务器 — 51种工具
├── tests/ # pytest测试套件
├── .github/workflows/ci.yml # GitHub Actions CI
├── requirements.txt
├── README.md
└── .gitignore
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器