APS MCP Server

APS MCP 服务

一个通过 APS 工具包集成 Autodesk ACC API 的精简 MCP 服务。

视频概览

设置

选项 1：使用 uv（推荐）

1. 如果尚未安装 uv，请先安装：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. 将 .env.sample 复制为 .env，并填写凭据：

   cp .env.sample .env
   

3. 创建并激活虚拟环境：

   uv venv
   # On Windows:
   .venv\Scripts\activate
   # On Unix or MacOS:
   source .venv/bin/activate
   

4. 安装依赖项：

   uv pip install -r requirements.txt
   

5. 运行 MCP 服务：

   python aps_dm_server.py
   

选项 2：使用 pip

1. 将 .env.sample 复制为 .env，并填写凭据：

   cp .env.sample .env
   

2. 创建并激活虚拟环境：

   python -m venv .venv
   # On Windows:
   .venv\Scripts\activate
   # On Unix or MacOS:
   source .venv/bin/activate
   

3. 安装依赖项：

   pip install -r requirements.txt
   

4. 运行 MCP 服务：

   python aps_dm_server.py
   

与 Claude Desktop 集成

要在 Claude Desktop 中使用此 MCP 服务：

1. 确保已安装 Claude Desktop（从 Claude.ai 下载）

2. 打开 Claude Desktop 配置文件：

   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

   如果文件不存在，请创建该文件。

3. 添加相应的配置：

   选项 A：直接使用虚拟环境中的 Python（最可靠）

   {
       "mcpServers": {
           "acc": {
               "command": "/ABSOLUTE/PATH/TO/YOUR/.venv/bin/python",
               "args": [
                   "/ABSOLUTE/PATH/TO/YOUR/aps_dm_server.py"
               ],
               "env": {
                   "PYTHONPATH": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/FOLDER"
               }
           }
       }
   }
   

   将路径替换为环境和项目的绝对路径。

   选项 B：使用 uv

   {
       "mcpServers": {
           "acc": {
               "command": "/ABSOLUTE/PATH/TO/uv",
               "args": [
                   "--directory",
                   "/ABSOLUTE/PATH/TO/YOUR/PROJECT/FOLDER",
                   "run",
                   "aps_dm_server.py"
               ]
           }
       }
   }
   

   在终端中运行 which uv，查找 uv 的绝对路径。

4. 保存文件，并完全重启 Claude Desktop

5. 在 Claude Desktop 中找到锤子图标，以访问 ACC 工具

macOS 专属设置

macOS 用户在与 Claude Desktop 集成时可能会遇到权限问题：

1. 权限问题：如果在日志中看到 Operation not permitted 等错误：

   • 打开“系统偏好设置” →“隐私与安全性” →“完全磁盘访问权限”
   • 点击“+”按钮，添加终端和 Claude 应用

2. 工作目录问题：如果看到有关当前目录不存在的错误：

   • 配置中始终使用绝对路径
   • 考虑将项目存储在权限限制较少的位置（例如“文稿”文件夹）

3. 查找正确的 Python 路径：要获取虚拟环境中 Python 的准确路径：

   source .venv/bin/activate  # Activate your environment first
   which python  # Get the full path
   

4. 查看日志以排查问题：

   tail -n 50 -f ~/Library/Logs/Claude/mcp*.log
   

要求

• Python 3.11 或更高版本
• requirements.txt 中列出的依赖项

系统架构

此 MCP 服务充当 Claude AI 与 Autodesk APS 平台之间的桥梁。下图展示了数据在系统中的流动方式：

1. 向 Claude 提交查询会触发工具选择
2. Claude 向本地服务发送 MCP 请求
3. MCP 服务使用你的凭据连接到 APS/ACC
4. 数据返回给 Claude，由 Claude 处理并格式化结果

可用工具

此 MCP 服务提供以下工具：

• get_hubs：获取所有可用的集线器
• get_projects：获取集线器中的所有项目
• get_project_files：获取项目中特定文件夹内的文件
• get_versions：获取特定项目的版本信息

故障排除

如果 Claude Desktop 集成出现问题：

1. 未显示服务：

   • 检查配置文件语法（有效的 JSON）
   • 所有路径均使用绝对路径
   • 完全重启 Claude Desktop

2. 权限错误：

   • 为终端和 Claude 授予“完全磁盘访问权限”
   • 尝试直接使用 Python，而非通过 uv
   • 尝试将项目移至限制较少的位置

3. 环境错误：

   • 确保已安装所有依赖项
   • 尝试使用虚拟环境中 Python 的直接路径
   • 检查 .env 文件中的 Autodesk 凭据是否正确

4. 检查日志：

   tail -n 50 -f ~/Library/Logs/Claude/mcp*.log
   

5. 手动测试： 直接运行服务，确认其正常工作：

   cd /path/to/your/project
   source .venv/bin/activate
   python aps_dm_server.py
   

与 OpenAI Agents SDK 配合使用

本项目集成了 OpenAI Agents SDK，可让你通过 OpenAI Agent 使用 MCP 服务。

1. 确保 .env 文件中包含你的 OpenAI API 密钥：

   OPENAI_API_KEY=your_openai_api_key
   

2. 安装额外的依赖项：

   uv pip install openai>=1.31.0
   

3. 运行 Agent：

   python main_agent.py
   

这将启动一个交互式会话，你可以向 Agent 询问有关 Autodesk 项目的问题。

依赖项和许可

本项目使用以下开源组件：

• aps-toolkit - Autodesk Platform Services 库（GPL-3.0）
• mcp - 多模态能力协议实现
• python-dotenv - 环境变量管理
• openai 和 openai-agents - OpenAI 集成

由于 aps-toolkit 依赖项的要求，本项目根据 GNU General Public License v3.0 授权。

免责声明

本软件按“原样”提供，不作任何明示或暗示的保证。这是一个仅用于演示的原型。作者对使用本软件可能引发的任何损害或问题概不负责。使用风险由你自行承担。