内容
# 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>
MCP 市场