aha-mcp

# aha-mcp > [!IMPORTANT] > 本仓库已被托管的 [Aha! 远程 MCP 服务器](https://support.aha.io/aha-develop/integrations/mcp-server/remote-mcp-server~7611250482619899159) 取代。 > > 远程 MCP 服务器直接从您的 AI 工具连接到 `https://[your-aha-domain].aha.io/api/v1/mcp`，使用您的 Aha! 权限，并具有更广泛的功能，包括创建和编辑记录。 模型上下文协议（MCP）服务器，用于通过 MCP 访问 Aha! 记录。此集成使您能够直接通过模型上下文协议与 Aha! 功能、需求和页面进行无缝交互。 ## 先决条件 - Node.js v20 或更高版本 - npm（通常与 Node.js 一起提供） - 具有 API 访问权限的 Aha! 账户 ## 安装 ### 使用 npx ```bash npx -y aha-mcp@latest ``` ### 手动安装 ```bash # 克隆仓库 git clone https://github.com/aha-develop/aha-mcp.git cd aha-mcp # 安装依赖项 npm install # 运行服务器 npm run mcp-start ``` ## 身份验证设置 1. 登录您的 Aha! 账户，网址为 `<yourcompany>.aha.io` 2. 访问 [secure.aha.io/settings/api_keys](https://secure.aha.io/settings/api_keys) 3. 点击“创建新的 API 密钥” 4. 立即复制令牌（它不会再次显示） 有关身份验证和 API 使用的更多详细信息，请参阅 [Aha! API 文档](https://www.aha.io/api)。 ## 环境变量 此 MCP 服务器需要以下环境变量： - `AHA_API_TOKEN`：您的 Aha! API 令牌 - `AHA_DOMAIN`：您的 Aha! 域名（例如，yourcompany 如果您访问 aha 在 yourcompany.aha.io） ## IDE 集成 出于安全原因，我们建议使用您首选的安全方法来管理环境变量，而不是在编辑器配置中直接存储 API 令牌。每个编辑器都有不同的安全模型和处理敏感信息的功能。 以下是配置各种编辑器使用 aha-mcp 服务器的示例。您应该根据首选的安全方法提供所需环境变量，调整这些示例。 ### VSCode 以下说明是从 [此处](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) 找到的说明的副本。 将以下内容添加到您的 `.vscode/settings.json` 中，使用您首选的安全方法安全地提供环境变量： ```json { "mcp": { "servers": { "aha-mcp": { "command": "npx", "args": ["-y", "aha-mcp"] // 环境变量应通过您首选的安全方法提供 } } } } ``` ### Cursor 1. 进入 Cursor 设置 > MCP 2. 点击 + 添加新的全局 MCP 服务器 3. 添加类似以下的配置： ```json { "mcpServers": { "aha-mcp": { "command": "npx", "args": ["-y", "aha-mcp"] // 环境变量应通过您首选的安全方法提供 } } } ``` ### Cline 在您的 `cline_mcp_settings.json` 中添加一个配置，通过 Cline MCP 服务器设置： ```json { "mcpServers": { "aha-mcp": { "command": "npx", "args": ["-y", "aha-mcp"] // 环境变量应通过您首选的安全方法提供 } } } ``` ### RooCode 通过以下方式打开 MCP 设置： - 点击“编辑 MCP 设置”在 RooCode 设置中，或 - 在 VS Code 的命令调色板中使用“RooCode：打开 MCP 配置”命令 然后添加： ```json { "mcpServers": { "aha-mcp": { "command": "npx", "args": ["-y", "aha-mcp"] // 环境变量应通过您首选的安全方法提供 } } } ``` ### Claude Desktop 在您的 `claude_desktop_config.json` 中添加一个配置： ```json { "mcpServers": { "aha-mcp": { "command": "npx", "args": ["-y", "aha-mcp"] // 环境变量应通过您首选的安全方法提供 } } } ``` ## 可用的 MCP 工具 ### 1. get_record 通过引用编号检索 Aha! 功能或需求。 **参数：** - `reference`（必填）：功能或需求的引用编号（例如，“DEVELOP-123”） **示例：** ```json { "reference": "DEVELOP-123" } ``` **响应：** ```json { "reference_num": "DEVELOP-123", "name": "功能名称", "description": "功能描述", "workflow_status": { "name": "开发中", "id": "123456" } } ``` ### 2. get_page 通过引用编号获取 Aha! 页面。 **参数：** - `reference`（必填）：页面的引用编号（例如，“ABC-N-213”） - `includeParent`（可选）：包括父页面信息。默认为 false。 **示例：** ```json { "reference": "ABC-N-213", "includeParent": true } ``` **响应：** ```json { "reference_num": "ABC-N-213", "name": "页面标题", "body": "页面内容", "parent": { "reference_num": "ABC-N-200", "name": "父页面" } } ``` ### 3. search_documents 搜索 Aha! 文档。 **参数：** - `query`（必填）：搜索查询字符串 - `searchableType`（可选）：要搜索的文档类型（例如，“页面”）。默认为“页面” **示例：** ```json { "query": "产品路线图", "searchableType": "页面" } ``` **响应：** ```json { "results": [ { "reference_num": "ABC-N-123", "name": "产品路线图 2025", "type": "页面", "url": "https://company.aha.io/pages/ABC-N-123" } ], "total_results": 1 } ``` ## 示例查询 - “获取功能 DEVELOP-123” - “获取产品路线图页面 ABC-N-213” - “搜索关于启动计划的页面” - “获取需求 ADT-123-1” - “查找所有提及 Q2 目标的页面” ## 配置选项 | 变量 | 描述 | 默认值 | | --------------- | ------------------------------------------ | -------- | | `AHA_API_TOKEN` | 您的 Aha! API 令牌 | 必需 | | `AHA_DOMAIN` | 您的 Aha! 域名（例如，yourcompany.aha.io） | 必需 | | `LOG_LEVEL` | 日志级别（debug，info，warn，error） | info | | `PORT` | SSE 传输端口 | 3000 | | `TRANSPORT` | 传输类型（stdio 或 sse） | stdio | ## 故障排除 <details> <summary>常见问题</summary> 1. 身份验证错误： - 验证您的 API 令牌是否正确并正确设置在您的环境中 - 确保令牌在 Aha! 中具有必要的权限 - 确认您正在使用正确的 Aha! 域名 2. 服务器无法启动： - 确保所有依赖项都已安装 - 检查 Node.js 版本是否为 v20 或更高版本 - 验证 TypeScript 编译是否成功 - 确认环境变量是否正确设置并且可访问 3. 连接问题： - 检查您的网络连接 - 验证您的 Aha! 域名是否可访问 - 确保您的 API 令牌未过期 4. API 请求失败： - 检查引用编号是否正确 - 验证 searchable 类型是否有效 - 确保您具有访问所请求资源的权限 5. 环境变量问题： - 确保环境变量正确设置并且可访问到 MCP 服务器 - 检查您的安全存储方法是否正确配置 - 验证环境变量是否正在传递到 MCP 服务器进程 </details>