aps-mcp-server-gen

APS MCP 服务生成器

此技能可创建一个完整可用的 MCP 服务项目，并连接到 Autodesk Platform Services（APS）。请严格按照以下步骤操作。

步骤 1 — 收集需求

如果用户尚未回答，请一次性询问以下三个问题：

1. 语言 — Node.js/TypeScript、.NET/C#，还是 Python？
2. 传输方式 — 本地（STDIO，适用于 Claude Desktop 或类似客户端），还是云端（Streamable HTTP，适用于 Web 部署）？
3. 身份验证 — 使用哪种 APS 身份验证模式？
   • 2-legged OAuth — 应用访问自己的资源；无需用户登录（注意：这是旧模式，但仍受支持）
   • Secure Service Accounts（SSA） — 自动化的服务到服务模式；代表真实用户执行操作，无需交互式登录
   • 3-legged OAuth — 用户通过浏览器登录；服务代表用户执行操作

如果用户的请求已明确说明某项选择（例如，“Python FastMCP 服务”），则跳过对应问题。

步骤 2 — 加载参考文档

编写任何文件之前，先加载适用的参考文档：

• Node.js → 阅读 references/nodejs.md
• .NET → 阅读 references/dotnet.md
• Python → 阅读 references/python.md
• 2-legged OAuth → 阅读 references/auth-2lo.md
• Secure Service Accounts → 阅读 references/auth-ssa.md
• 3-legged OAuth → 阅读 references/auth-3lo.md
• STDIO → 阅读 references/transport-stdio.md
• Streamable HTTP → 阅读 references/transport-http.md
• 始终 → 阅读 references/testing.md

步骤 3 — 确认输出目录

询问或确认项目的创建位置（默认：当前目录下的 ./aps-mcp-server）。

步骤 4 — 搭建项目框架

创建项目所需的每个文件。不要留下占位 TODO；应生成完整、可运行的代码。严格使用参考文件中的模式。

要创建的文件（所有语言）

文件	用途
.env.example	包含所有必需的环境变量、占位值和注释
README.md	设置、运行、MCP 客户端配置和测试说明
主服务文件	特定语言的入口点
工具文件	至少一个 APS 工具示例（例如，列出 OSS 存储桶）
身份验证辅助文件	所选身份验证类型的令牌获取逻辑
测试文件	使用模拟 APS 调用的单元测试（参见 testing.md）

特定语言的附加文件

• Node.js：package.json、tsconfig.json（如使用 TypeScript）、vitest 开发依赖项
• .NET：.csproj、appsettings.json、使用 xUnit + NSubstitute 的 *.Tests 项目
• Python：pyproject.toml（由 uv 管理）、pytest + pytest-asyncio 开发依赖项

步骤 5 — 搭建完成后的说明

创建文件后，告知用户：

1. 如何安装依赖项（包括测试依赖项）
2. 如何填写 .env（说明每种凭据需要访问哪些 APS 门户页面）
3. 如何运行单元测试（无需凭据）
4. 如何运行服务
5. 如何通过 MCP 客户端连接服务（Claude Desktop 配置或 Inspector URL）
6. 如何使用 MCP Inspector 运行交互式冒烟测试

核心规则

• 绝不要实现令牌透传。 MCP 服务必须自行通过 APS 进行身份验证——绝不能接受来自 MCP 客户端的 APS 令牌并将其转发。
• 始终缓存令牌。 每次调用 APS 前都要检查令牌是否过期；并提前刷新（至少在过期前 60 s）。
• 区分 STDIO 与无状态 HTTP。 STDIO 服务本质上是单会话的。除非选择需要通过有状态会话跟踪每位用户令牌的三方 OAuth，否则 Streamable HTTP 服务应默认采用无状态模式（不使用会话 ID）。
• 工具描述很重要。 为每个工具编写清晰的文档字符串或描述——大模型会根据这些信息判断何时调用各个工具。
• 当数据可能以编程方式使用（例如由 UI 组件使用）时，Node.js 工具应同时返回 content 和 structuredContent。 Python FastMCP 会根据返回类型自动推断结构化输出。