Aha.io

Aha MCP 服务

一个 Model Context Protocol（MCP）服务，可与 Aha.io 产品管理平台无缝集成。具备离线数据库同步、用于语义搜索的向量嵌入，以及全面的工作流自动化功能。

🔧 客户端配置

MCP Registry

此服务已发布到官方 MCP Registry， 名称为 io.github.cedricziel/aha-mcp，因此，能浏览 Registry 的客户端可以直接安装， 无需进行下方任何配置：

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.cedricziel/aha-mcp"

Registry 仅保存元数据。其条目指向下方介绍的三种制品——npm 软件包、ghcr.io 镜像和 .mcpb 桌面扩展——客户端会选择自己能够运行的制品。无论选择哪种方式，服务都需要 AHA_COMPANY 和 AHA_TOKEN。

Claude Desktop 扩展（最简单）

从最新版本 下载 aha-mcp-v<version>.mcpb 并用 Claude Desktop 打开，随后它会提示你输入 Aha.io 子域名和 API 令牌。无需配置 Node.js 或 Docker，也无需手动编辑 JSON。

此扩展提供 54 个可直接查询 Aha.io 的工具，因此结果始终是最新的，且不会在本地存储任何内容。跨记录搜索由 Aha.io 自身的索引提供支持——详见 搜索。

Claude Desktop 配置

如要在 Claude Desktop 中使用此 MCP 服务，请将以下内容添加到 claude_desktop_config.json：

使用 npx：

{
  "mcpServers": {
    "aha": {
      "command": "npx",
      "args": ["@cedricziel/aha-mcp"],
      "env": {
        "AHA_COMPANY": "your-company",
        "AHA_TOKEN": "your-api-token"
      }
    }
  }
}

使用 Docker：

{
  "mcpServers": {
    "aha": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "AHA_COMPANY=your-company",
        "-e", "AHA_TOKEN=your-api-token",
        "ghcr.io/cedricziel/aha-mcp"
      ]
    }
  }
}

**注意：**请将 your-company 和 your-api-token 替换为你的实际 Aha.io 子域名和 API 令牌。

🚀 开始使用

使用 npx 快速启动

无需全局安装，即可直接使用 npx 运行 MCP 服务：

# Set environment variables
export AHA_COMPANY="your-company"  # Your Aha.io subdomain
export AHA_TOKEN="your-api-token"   # Your Aha.io API token

# Run the server
npx @cedricziel/aha-mcp

使用 Docker 快速启动

你也可以使用 Docker 运行 MCP 服务：

# Set environment variables
export AHA_COMPANY="your-company"  # Your Aha.io subdomain
export AHA_TOKEN="your-api-token"   # Your Aha.io API token

# Run in stdio mode (default)
docker run --rm -e AHA_COMPANY="$AHA_COMPANY" -e AHA_TOKEN="$AHA_TOKEN" ghcr.io/cedricziel/aha-mcp

# Run in Streamable HTTP mode (recommended for remote access)
docker run --rm -p 3001:3001 -e AHA_COMPANY="$AHA_COMPANY" -e AHA_TOKEN="$AHA_TOKEN" ghcr.io/cedricziel/aha-mcp --mode streamable-http

开发环境设置

1. 如果尚未安装，请安装 Bun：

   curl -fsSL https://bun.sh/install | bash
   

2. 安装依赖项：

   bun install
   

3. 配置环境变量：

   export AHA_COMPANY="your-company"  # Your Aha.io subdomain
   export AHA_TOKEN="your-api-token"   # Your Aha.io API token
   

4. 启动服务：

   # Start the stdio server (for MCP clients - default)
   bun start
   
   # Or start with Streamable HTTP (recommended for remote access)
   bun start -- --mode streamable-http
   
   # Or start the HTTP server (legacy entry point)
   bun run start:http
   

5. 如需在开发时自动重新加载：

   # Development mode with stdio
   bun run dev
   
   # Development mode with Streamable HTTP
   bun run dev -- --mode streamable-http
   
   # Development mode with HTTP (legacy)
   bun run dev:http
   

🔌 Aha.io 集成

此 MCP 服务通过实时 API 访问和离线数据库同步，与 Aha.io 进行混合式集成。服务会自动使用 Aha.io 数据维护本地 SQLite 数据库，从而实现更快的查询、离线访问和高级语义搜索功能。

架构概览

• 混合数据访问：实时 API 调用 + 用于提升性能的离线 SQLite 数据库
• 后台同步：将 Aha.io 实体自动同步到本地数据库
• 向量嵌入：使用句子转换器和 SQLite 向量扩展进行语义搜索
• 实时进度：通过详细的进度跟踪监控后台任务
• 配置管理：无需重启服务即可在运行时修改配置

配置

Aha.io 集成可通过多种方式配置，优先级顺序如下：

1. 环境变量（最高优先级）
2. 配置文件（~/.aha-mcp-config.json）
3. 默认值（最低优先级）

环境变量

• AHA_COMPANY：你的 Aha.io 子域名（例如，mycompany.aha.io 中的 mycompany）
• AHA_TOKEN：你的 Aha.io API 令牌（用于 API 令牌身份验证）
• AHA_ACCESS_TOKEN：你的 OAuth 2.0 访问令牌（用于 OAuth 身份验证）
• MCP_TRANSPORT_MODE：传输模式（stdio 或 streamable-http）
• MCP_PORT：基于 HTTP 的模式所用端口号（默认值：3001）
• MCP_HOST：基于 HTTP 的模式所用主机地址（默认值：0.0.0.0）
• MCP_AUTH_TOKEN：基于 HTTP 的模式所用身份验证令牌（可选）
• MCP_TOOL_RATE_LIMIT_PER_MINUTE：每分钟允许的工具调用次数（默认值：120，设为 0 可禁用）

传输模式

服务器支持两种传输模式：

1. stdio：用于 MCP 客户端集成的标准输入/输出模式（默认）
2. streamable-http：HTTP 传输（MCP 协议 2025-06-18），适用于远程客户端和 Web 客户端

使用示例：

# Stdio mode (default)
aha-mcp

# Streamable HTTP mode
aha-mcp --mode streamable-http --port 3001

已移除：sse 传输模式已在 MCP 规范 2025-03-26 中弃用，并已移除。现在，MCP_TRANSPORT_MODE=sse 和 --mode sse 会回退到 streamable-http，并显示警告，因此现有配置仍可正常启动。

身份验证（HTTP 传输）

streamable-http 传输支持可选的 Bearer 令牌身份验证：

环境变量配置

# Set authentication token
export MCP_AUTH_TOKEN="your-secure-token-here"

# Start server with authentication
aha-mcp --mode streamable-http --port 3001

客户端身份验证

启用身份验证后，客户端必须在 Authorization 标头中包含 Bearer 令牌。所有 MCP 流量都通过单一的 /mcp 端点传输：

curl -X POST \
     -H "Authorization: Bearer your-secure-token-here" \
     -H "Content-Type: application/json" \
     -H "MCP-Protocol-Version: 2025-06-18" \
     -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' \
     http://localhost:3001/mcp

大多数调用方应使用 MCP 客户端库，而非原始 HTTP；构造传输时，将令牌作为 Authorization 标头传入。

安全说明

• **选择启用：**身份验证为可选项。如果未设置 MCP_AUTH_TOKEN，则允许所有请求。
• **令牌安全：**使用强随机生成的令牌（至少 8 个字符）。
• **HTTPS：**在生产环境中，始终使用 HTTPS 保护传输中的令牌。
• **令牌存储：**配置文件中的令牌会经过混淆处理（以 base64 编码），但应将其视为敏感数据。

检查身份验证状态

curl http://localhost:3001/

# Response includes:
# {
#   "authentication": {
#     "enabled": true,
#     "type": "Bearer token"
#   }
# }

配置管理工具

服务器提供三个用于配置管理的 MCP 工具：

1. configure_server：在运行时更新服务器设置
2. get_server_config：查看当前配置和验证状态
3. test_configuration：使用当前设置测试 API 连通性

这些工具让你无需重启服务器即可管理配置，便于在不同的 Aha.io 账户之间切换或更新凭据。

数据库同步

服务器会在本地 SQLite 数据库中保存你的 Aha.io 数据，以提升性能并支持离线访问。

同步管理工具

• aha_sync_start：开始在后台同步指定的实体类型
• aha_sync_status：检查同步作业的状态和进度
• aha_sync_stop：停止正在运行的同步作业
• aha_sync_pause：暂停同步作业（之后可恢复）
• aha_sync_resume：恢复已暂停的同步作业
• aha_sync_history：查看同步操作的详细历史记录
• aha_sync_health：获取同步服务的整体健康状态
• aha_database_health：检查数据库连通性和统计信息
• aha_database_cleanup：清理旧的同步作业并优化数据库

同步功能

• **实体类型：**同步功能、产品、创意、史诗、计划、发布、目标、用户、评论
• **进度跟踪：**实时更新进度并提供详细统计信息
• **错误处理：**提供全面的错误日志记录和恢复机制
• **批处理：**可配置批次大小，以获得最佳性能
• **增量更新：**支持通过 updatedSince 筛选，仅同步近期更改
• **并发操作：**可同时运行多个同步作业

同步工作流示例

# Start syncing features and products
aha_sync_start --entities features,products --batchSize 50

# Check progress
aha_sync_status --jobId sync-abc123

# View sync history
aha_sync_history --jobId sync-abc123 --limit 20

# Check overall health
aha_sync_health

语义搜索与嵌入

服务器使用向量嵌入提供高级语义搜索功能。

嵌入管理工具

• aha_generate_embeddings：为实体文本内容生成向量嵌入
• aha_embedding_status：检查嵌入生成作业的状态
• aha_semantic_search：使用自然语言查询搜索实体
• aha_generate_entity_embedding：为特定实体生成嵌入
• aha_find_similar：查找与给定实体相似的实体
• aha_pause_embeddings：暂停嵌入生成作业
• aha_stop_embeddings：停止嵌入生成作业

语义搜索功能

• 向量存储：使用 sqlite-vec 扩展将嵌入向量存储在 SQLite 中
• 多种模型：支持不同的嵌入模型（默认：all-MiniLM-L6-v2）
• 相似度搜索：支持可配置阈值的余弦相似度搜索
• 跨实体搜索：查找不同实体类型中的相似内容
• 实时生成：在后台生成嵌入向量，并跟踪进度

嵌入工作流示例

# Generate embeddings for features and ideas
aha_generate_embeddings --entities features,ideas --batchSize 25

# Search for similar content
aha_semantic_search --query "user authentication security" --threshold 0.7

# Find similar features to a specific feature
aha_find_similar --entityType features --entityId FEAT-123 --limit 5

# Check embedding job progress
aha_embedding_status --jobId embed-xyz789

可用资源

**破坏性变更：**许多集合资源（如 aha_features 这类精简索引列表，以及 aha_ideas 这类仅包含少量标量列的资源）现在返回 text/markdown——根据记录类型返回链接列表或表格——而不再返回 JSON 数组。过去会将这些集合的内容解析为 JSON 的内容都需要进行调整。包含更丰富嵌套数据的集合（aha_goals、aha_initiatives、评论资源等）不受影响；与所有单条记录资源（如 aha://feature/{id}）一样，它们仍然返回 application/json。

单个实体资源

• aha_idea：使用 aha://idea/{id} 访问单条 idea
• aha_feature：使用 aha://feature/{id} 访问单条 feature
• aha_user：使用 aha://user/{id} 访问单个用户
• aha_epic：使用 aha://epic/{id} 访问单条 epic
• aha_product：使用 aha://product/{id} 访问单个产品
• aha_initiative：使用 aha://initiative/{id} 访问单条 initiative
• aha_requirement：使用 aha://requirement/{id} 访问单条 requirement
• aha_competitor：使用 aha://competitor/{id} 访问单个竞争对手
• aha_todo：使用 aha://todo/{id} 访问单条待办事项

集合资源

• aha_features：使用 aha://features?query=...&tag=...，可选筛选条件，列出 features
• aha_users：使用 aha://users 列出所有用户
• aha_epics：使用 aha://epics/{product_id} 列出某个产品的 epics
• aha_products：使用 aha://products?updatedSince=... 列出所有产品
• aha_initiatives：使用 aha://initiatives?query=...&onlyActive=true 列出所有 initiatives
• aha_ideas：使用 aha://ideas?query=...&status=...&category=... 列出全局所有 ideas
• aha_ideas_by_product：使用 aha://ideas/{product_id}?query=...&spam=false&sort=recent 列出某个产品的 ideas
• aha_competitors：使用 aha://competitors/{product_id} 列出某个产品的竞争对手
• aha_product_releases：使用 aha://releases/{product_id}?query=...&status=... 列出某个产品的发布版本
• aha_initiative_epics：使用 aha://initiative/{initiative_id}/epics 列出某个 initiative 的 epics

评论资源

• aha_feature_comments：使用 aha://comments/feature/{feature_id} 访问某个 feature 的评论
• aha_epic_comments：使用 aha://comments/epic/{epic_id} 访问某个 epic 的评论
• aha_idea_comments：使用 aha://comments/idea/{idea_id} 访问某个 idea 的内部评论
• aha_idea_portal_comments：使用 aha://idea-comments/{idea_id} 访问某个 idea 的ideas-portal评论——这些评论与上面的记录不同，包括客户撰写的所有内容
• aha_initiative_comments：使用 aha://comments/initiative/{initiative_id} 访问某个 initiative 的评论
• aha_product_comments：使用 aha://comments/product/{product_id} 访问某个产品的评论
• aha_goal_comments：使用 aha://comments/goal/{goal_id} 访问某个目标的评论
• aha_release_comments：使用 aha://comments/release/{release_id} 访问某个发布版本的评论
• aha_release_phase_comments：使用 aha://comments/release-phase/{release_phase_id} 访问某个发布阶段的评论
• aha_requirement_comments：使用 aha://comments/requirement/{requirement_id} 访问某个 requirement 的评论
• aha_todo_comments：使用 aha://comments/todo/{todo_id} 访问某条待办事项的评论

目标资源

• aha_goal：使用 aha://goal/{goal_id} 访问单个目标
• aha_goals：使用 aha://goals 列出所有目标
• aha_goal_epics：使用 aha://goal/{goal_id}/epics 访问与目标关联的史诗
• aha_goal_key_results：使用 aha://goal/{goal_id}/key_results 访问目标的关键结果
• aha_key_result：使用 aha://key_result/{id} 访问单个关键结果

发布资源

• aha_release：使用 aha://release/{release_id} 访问单个发布
• aha_releases：使用 aha://releases 列出所有发布
• aha_release_features：使用 aha://release/{release_id}/features 访问与发布关联的功能
• aha_release_epics：使用 aha://release/{release_id}/epics 访问与发布关联的史诗
• aha_release_phase：使用 aha://release-phase/{release_phase_id} 访问单个发布阶段
• aha_release_phases：使用 aha://release-phases 列出所有发布阶段

自定义字段资源

• aha_custom_fields：使用 aha://custom-fields 列出所有自定义字段定义
• aha_custom_field_options：使用 aha://custom-field/{custom_field_id}/options 访问自定义字段的选项

资源 URI 示例

# Individual Entity Resources
aha://idea/IDEA-123               # Get specific idea
aha://feature/PROJ-456            # Get specific feature
aha://user/USER-789               # Get specific user
aha://epic/EPIC-101               # Get specific epic
aha://product/PROD-001            # Get specific product
aha://initiative/INIT-202         # Get specific initiative
aha://requirement/REQ-666         # Get specific requirement
aha://competitor/COMP-444         # Get specific competitor
aha://todo/TODO-777               # Get specific todo

# Collection Resources (enhanced with filtering)
aha://features?query=auth&tag=api&[email protected] # Search features
aha://users                       # List all users
aha://epics/PROJ-001              # List epics for product
aha://products?updatedSince=2024-01-01T00:00:00Z # List products with filter
aha://initiatives?query=mobile&onlyActive=true&[email protected] # Search initiatives
aha://ideas?query=nodejs&status=new&category=enhancement # List ideas globally with filters
aha://ideas/PROJ-001?query=search&spam=false&sort=recent&tag=enhancement # List ideas with filters
aha://competitors/PROJ-001        # List competitors for product
aha://releases/PROJ-001?query=mobile&status=shipped # List releases for product
aha://initiative/INIT-123/epics   # List epics for initiative

# Comment Resources
aha://comments/feature/PRJ1-123   # Get comments for feature
aha://comments/epic/EPIC-123      # Get comments for epic
aha://comments/idea/IDEA-456      # Get an idea's internal comments
aha://idea-comments/IDEA-456      # Get an idea's ideas-portal comments
aha://comments/initiative/INIT-789 # Get comments for initiative
aha://comments/product/PROD-001   # Get comments for product
aha://comments/goal/GOAL-555      # Get comments for goal
aha://comments/release/REL-333    # Get comments for release
aha://comments/release-phase/RP-444 # Get comments for release phase
aha://comments/requirement/REQ-666 # Get comments for requirement
aha://comments/todo/TODO-777      # Get comments for todo

# Goal Resources
aha://goal/GOAL-123               # Get specific goal
aha://goals                       # List all goals
aha://goal/GOAL-456/epics         # Get epics for goal
aha://goal/GOAL-456/key_results   # Get key results for goal
aha://key_result/PRJ1-G-3-KR-1    # Get specific key result

# Release Resources
aha://release/REL-123             # Get specific release
aha://releases                    # List all releases
aha://release/REL-456/features    # Get features for release
aha://release/REL-456/epics       # Get epics for release
aha://release-phase/RP-123        # Get specific release phase
aha://release-phases              # List all release phases

# Custom Fields Resources
aha://custom-fields               # List all custom field definitions
aha://custom-field/CF-123/options # Get options for custom field

可用工具

注意：列表操作通过 MCP 资源处理。工具涵盖搜索、读取单条记录、写入操作和关系管理。

记录读取工具

• aha_get_feature：读取一项功能，包括工作流状态、发布、负责人、标签、评分和自定义字段值
• aha_get_epic：读取一个史诗
• aha_get_idea：读取一个创意
• aha_get_initiative：读取一个计划
• aha_get_release：读取一个发布
• aha_get_goal：读取一个目标，包括其时间范围、进度来源、成功指标和关键结果摘要
• aha_get_key_result：读取一个关键结果，包括其状态以及起始、当前和目标指标

这些工具会将完整记录作为 structuredContent 返回。它们有意重复了 aha://feature/{id} 等资源已有的功能：客户端可以自行决定是否向模型提供资源，而有些客户端不会提供——在这些客户端中，这里的所有读取操作都无法使用，导致写入工具无法查看自己即将替换的内容。aha_search 不能替代这些工具，因为它无法返回单条记录的字段。

集合读取工具

• aha_list_release_features：列出分配给某个发布的功能，并为每项功能提供链接和 Aha 给出的发布总数
• aha_list_release_epics：列出分配给某个发布的史诗，并为每个史诗提供链接和 Aha 给出的发布总数
• aha_list_key_results：列出某个目标的关键结果，包括状态、进度和指标
• aha_list_comments：列出记录上的评论；对于创意，会列出两条评论流

这两个发布工具是枚举某个发布内容的唯一方式。aha_search 按相关性排序，搜索命中时不返回发布归属信息，也无法要求返回某个范围内的每条记录，因此根据搜索结果整理的发布列表并不完整——而且其中没有任何信息会说明这一点。之所以列出这两种类型，是因为各个工作区组织发布的方式并不相同：通过史诗规划的发布不会出现在功能工具的结果中。每个工具每页请求 200 条记录（Aha 对功能的默认值是 30；史诗路由的默认值未经测量，因此该工具不会依赖它），并且始终返回 Aha 的分页块，调用方因此可以判断列表是完整的，还是仅为更长列表的开头。Aha 在这些端点上只返回身份字段，因此如需查看单条记录的状态，请使用 aha_get_feature 或 aha_get_epic。

写入操作工具

• aha_create_feature_comment：在一项功能上创建评论
• aha_create_initiative_in_product：在指定产品中创建计划

评论工具

• aha_list_comments：读取评论；可考虑区分内部评论流和门户评论流
• aha_create_comment：向受支持的记录添加内部评论
• aha_update_comment：使用评论 ID 替换内部评论正文
• aha_delete_comment：使用评论 ID 删除内部评论
• aha_create_idea_portal_comment：添加可明确设置可见性的门户评论
• aha_delete_idea_portal_comment：使用创意 ID 和评论 ID 删除门户评论

评论的 body 可接受原始 HTML，例如 <p>A <strong>formatted</strong> reply.</p>， 也可接受纯文本。Markdown 不会转换。请直接发送 HTML，不要将标签转义为 <p>，也不要将其包在代码围栏中。服务端会保留发送给 Aha 的正文； 简短文本预览会移除标签，而 structuredContent 会保留返回的正文。 使用 aha_list_comments 返回的评论 source 来选择内部评论或门户评论工具。 不支持编辑门户评论正文，因为 Aha 记录的更新端点仅用于垃圾评论和可见性更改。

功能的 CRUD 工具

• aha_create_feature：在指定版本中创建功能
• aha_update_feature：更新功能
• aha_delete_feature：删除功能
• aha_update_feature_progress：更新功能进度
• aha_update_feature_score：更新功能评分
• aha_update_feature_custom_fields：更新功能的自定义字段

史诗的 CRUD 工具

• aha_update_epic：更新史诗
• aha_delete_epic：删除史诗
• aha_create_epic_in_product：在指定产品中创建史诗
• aha_create_epic_in_release：在指定版本中创建史诗

创意的 CRUD 工具

• aha_create_idea：在产品中创建创意
• aha_create_idea_with_category：创建带类别的创意
• aha_create_idea_with_score：创建带评分的创意
• aha_update_idea：更新创意的工作流状态和其他字段
• aha_delete_idea：删除创意

更新创意前，请先使用 aha_get_idea 读取它。状态名称取决于工作区； 请准确使用预期状态，例如：

{
  "ideaId": "PRJ1-I-7",
  "ideaData": { "idea": { "workflow_status": "Product Evaluating" } }
}

将此传递给 aha_update_idea。省略 ideaData.idea 中的字段将保持不变。

目标和关键结果工具（OKR）

• aha_create_goal：在工作区中创建目标（Objective）
• aha_update_goal：更新目标的名称、描述、成功指标、状态、时间范围或进度
• aha_delete_goal：删除目标及其包含的关键结果
• aha_list_key_results：列出目标的关键结果，包括状态、进度和指标
• aha_create_key_result：在目标下创建关键结果
• aha_update_key_result：更新关键结果的状态以及起始、当前或目标指标
• aha_delete_key_result：删除关键结果

与其他 API 相比，这些工具有三点不同，均通过实时账户进行了验证：

• 目标的创建和删除均限定在工作区范围内。 POST /products/{id}/goals 和 DELETE /products/{id}/goals/{id} 是 Aha 提供的唯一路由，因此这两个工具都需要 工作区 ID——aha_get_goal 会以 product_id 的形式返回该 ID。更新操作不需要它。
• 关键结果没有 url。 与其他所有记录类型不同，独立记录既没有 url，也没有 resource，因此每个工具返回的 aha://key_result/{id} 资源链接是客户端唯一可跟随的指针。
• 目标没有顶层工作流状态。 它位于 success_metric.workflow_status 下，这正是 Aha UI 显示的目标状态。

竞争对手管理工具

• aha_create_competitor：在产品中创建竞争对手
• aha_update_competitor：更新竞争对手
• aha_delete_competitor：删除竞争对手

门户集成工具

• aha_create_idea_by_portal_user：由门户用户创建创意
• aha_create_idea_with_portal_settings：使用增强的门户设置创建创意

关系管理工具

• aha_associate_feature_with_epic：将功能关联到史诗
• aha_move_feature_to_release：将功能移动到其他版本
• aha_associate_feature_with_goals：将功能关联到多个目标
• aha_update_feature_tags：更新功能的标签

注意：按照设计，两种接口都提供读取功能：

• 资源涵盖完整的读取范围——所有实体类型，支持通过 URI 参数进行筛选，并提供列表和单条记录
• 工具涵盖写入（创建/更新/删除）、关系管理（关联/移动）、搜索，以及对写入频率最高的五种类型进行单条记录读取

这种重叠是有意为之。资源提供了更丰富的读取范围，但 MCP 规范将是否向模型开放资源的决定权留给了各个客户端，而仅支持工具的客户端很常见。对于提供写入工具的类型，保留通过工具进行读取的能力，才能避免 Agent 更改自己无法查看的字段。

🚀 第 8 阶段 - 完整 CRUD 操作与高级功能

MCP 服务现在为 Aha.io 实体提供全面的生命周期管理，包括完整的 CRUD 操作、门户集成和高级工作流功能：

第 8A 阶段 - 核心 CRUD 操作（18 个工具）

功能管理（6 个工具）

• aha_create_feature：在版本中创建功能
• aha_update_feature：更新现有功能
• aha_delete_feature：删除功能
• aha_update_feature_progress：更新功能进度（0-100%）
• aha_update_feature_score：更新功能评分
• aha_update_feature_custom_fields：更新功能自定义字段

史诗管理（2 个工具）

• aha_update_epic：更新现有史诗
• aha_delete_epic：删除史诗

创意管理（5 个工具）

• aha_create_idea：在产品中创建创意
• aha_create_idea_with_category：创建带类别的创意
• aha_create_idea_with_score：创建带评分的创意
• aha_update_idea：更新创意的工作流状态和其他字段
• aha_delete_idea：删除创意

第 8B 阶段 - 竞争对手管理（3 个工具）

竞争对手管理（3 个工具）

• aha_create_competitor：在产品中创建竞争对手
• aha_update_competitor：更新现有竞争对手
• aha_delete_competitor：删除竞争对手

注意：现在通过 MCP 资源（aha_initiative、aha_initiatives、aha_initiative_comments、aha_initiative_epics）处理计划数据访问，以便更清晰地区分读写操作。

第 8C 阶段 - 门户集成与高级功能（2 个工具）

门户集成

• aha_create_idea_by_portal_user：由门户用户创建创意
• aha_create_idea_with_portal_settings：使用门户设置创建创意

增强的筛选与资源

• 计划筛选：通过 query、updatedSince、assignedToUser、onlyActive 参数增强筛选功能
• 门户配置：支持 skip_portal 和 submitted_idea_portal_id 设置
• 全面的实体覆盖：为功能、史诗、创意和竞争对手提供完整的 CRUD 操作

技术成果

• 54 个 MCP 工具，全部直接查询 Aha.io，不使用本地状态
• 17 个已列出的 MCP 资源，涵盖实体集合，另有模板化资源 URI
• 17 个领域专用提示词（工作流自动化）
• 36 个核心 CRUD 和写入操作工具，用于完整的生命周期管理，包括 OKR（目标和关键结果）
• 基于 Aha 自身索引的跨记录搜索，涵盖 20 种记录类型
• 7 个单记录读取工具，这样在不显示资源的客户端上，写入操作也可以与记录的当前状态进行核对
• 支持读取和写入 Aha 支持的每种记录类型的评论；想法的 ideas-portal 对话则作为独立信息流处理
• 目标和关键结果 CRUD，因此季度 OKR 循环可以通过服务端运行，而不必使用 Aha UI
• 5 个服务端配置工具，用于运行时配置
• 534 项测试全部通过，服务覆盖全面
• 无原生依赖，因此只要 Node 能运行，服务就能运行
• 全面的错误处理，并进行适当的 Zod 模式验证

🔍 搜索

aha_search 通过 GraphQL API（POST /api/v2/graphql，searchDocuments）查询 Aha.io 自身的搜索索引。不进行任何本地缓存，因此结果始终是最新的，也不需要原生依赖或可写存储。

// Everything matching "alerting", any record type
{ "query": "alerting" }

// Ideas only, within one workspace
{ "query": "alerting", "recordTypes": ["Idea"], "workspaceId": "7387509120724661690" }

// Sweep a workspace broadly: alternatives, because there is no match-all
{ "query": "a* OR e* OR i* OR o* OR u*", "recordTypes": ["Idea"], "workspaceId": "7387509120724661690" }

**匹配内容：**记录名称和描述。评论正文也会参与匹配，并显示为链接到父记录的 Comment 命中项。

**查询语法：**使用 term* 进行前缀匹配，支持 AND / OR / NOT，以及 "带引号的短语"。

**不支持匹配全部内容的查询。**单独使用 * 会被拒绝：Aha 单独处理时会为其返回任意子集，与 workspaceId 组合时则什么也不返回——空结果看起来就像工作区为空。请搜索具体词语，或使用列表资源（aha://features、aha://ideas/{product_id}）枚举工作区，而不要搜索整个工作区。

**命中项包含：**名称、类型、reference_num、内部 ID、工作区、绝对 URL 和 updated_at。想法命中项还包含门户 votes 和 endorsements；可评分类型则包含其 Aha.io score，因此无需再次调用即可按需求对想法排序。可作为资源读取的类型命中项——feature、epic、idea、initiative、goal、key result、release、requirement、competitor——会附带 resource_link；其他记录可通过 URL 访问。

**请完整引用参考编号。**工作区前缀是编号的一部分：IDEASVOC-I-9930 可识别一个想法，I-9930 无法识别任何内容；而 Aha 对截断形式返回的 404 看起来像记录不存在，而不是编号输入有误。

**不会返回的内容：**工作流状态、所属发布版本、受派人或自定义字段值。如需这些信息，请读取记录本身：

{ "featureId": "PRJ1-123" }   // aha_get_feature — full record, including custom fields

记录类型（recordTypes，省略则搜索所有类型）：

BusinessModel · Comment · Competitor · Epic · Feature · Goal · Idea · IdeaOrganization
IdeaTheme · IdeaUser · Initiative · KeyResult · Page · Persona · Project · Release
ReleasePhase · Requirement · StrategicPositioning · Task

分页：perPage 接受 10–200，默认值为 20；Aha 会将低于 10 的值提升至 10。total_count 的计数上限为 10,000，并通过 total_count_is_capped: true 标明已达到上限。

使用 scripts/check-graphql.ts 确认你的账户和令牌能够访问哪些内容：

AHA_COMPANY=mycompany AHA_TOKEN=... bun run scripts/check-graphql.ts

为什么不使用本地嵌入？

早期版本会将 Aha 同步到 SQLite，并使用本地“语义搜索”对结果排序。此功能现已移除。其嵌入函数通过 Math.sin() 对字符代码进行哈希，因此不包含任何语义信号，且相似度分数无法解释。它还依赖原生 sqlite3 模块和可写数据目录，这导致它在打包安装中无法运行。Aha 的服务端索引基于关键词，但真实有效、始终保持最新，而且无需上述所有机制。

Aha 也在 https://<yourcompany>.aha.io/api/v1/mcp 上托管自己的 MCP 服务。

🛠️ 添加自定义工具和资源

向 MCP 服务添加自定义工具、资源或提示词时：

1. 在所有资源、工具和提示词名称中使用下划线（_），而不要使用连字符（-）

   // Good: Uses underscores
   server.tool(
     "my_custom_tool",
     "Description of my custom tool",
     {
       param_name: z.string().describe("Parameter description")
     },
     async (params) => {
       // Tool implementation
     }
   );
   
   // Bad: Uses hyphens, may cause issues with Cursor
   server.tool(
     "my-custom-tool",
     "Description of my custom tool",
     {
       param-name: z.string().describe("Parameter description")
     },
     async (params) => {
       // Tool implementation
     }
   );
   

2. 此命名约定可确保与 Cursor 及其他与 MCP 服务交互的 AI 工具兼容

🐳 Docker 用法

Docker 镜像

Aha MCP 服务以 Docker 镜像的形式发布在 GitHub Container Registry 上：

• GitHub Container Registry：ghcr.io/cedricziel/aha-mcp

使用 Docker 运行

基本用法

# Run in stdio mode (default)
docker run --rm \
  -e AHA_COMPANY="your-company" \
  -e AHA_TOKEN="your-api-token" \
  ghcr.io/cedricziel/aha-mcp

# Run in Streamable HTTP mode
docker run --rm \
  -p 3001:3001 \
  -e AHA_COMPANY="your-company" \
  -e AHA_TOKEN="your-api-token" \
  ghcr.io/cedricziel/aha-mcp --mode streamable-http

# Run in Streamable HTTP mode with authentication
docker run --rm \
  -p 3001:3001 \
  -e AHA_COMPANY="your-company" \
  -e AHA_TOKEN="your-api-token" \
  -e MCP_AUTH_TOKEN="your-secure-token" \
  ghcr.io/cedricziel/aha-mcp --mode streamable-http

持久化配置

如需在多次运行之间保留配置：

# Create a named volume for configuration
docker volume create aha-mcp-config

# Run with persistent configuration
docker run --rm \
  -v aha-mcp-config:/home/mcp/.config \
  -e AHA_COMPANY="your-company" \
  -e AHA_TOKEN="your-api-token" \
  ghcr.io/cedricziel/aha-mcp

使用 Docker Compose

仓库中包含 docker-compose.yml 文件，方便进行设置：

# Copy the example environment file
cp .env.example .env

# Edit .env with your credentials
AHA_COMPANY=your-company
AHA_TOKEN=your-api-token

# Run in stdio mode
docker-compose --profile stdio up

# Run in Streamable HTTP mode
docker-compose --profile http up

# Run in detached mode
docker-compose --profile http up -d

.env 文件示例：

AHA_COMPANY=mycompany
AHA_TOKEN=your-api-token-here
MCP_AUTH_TOKEN=your-secure-token-here

Docker 环境变量

Docker 镜像支持与 npm 包相同的所有环境变量：

变量	描述	默认值
AHA_COMPANY	Aha.io 公司子域名	-
AHA_TOKEN	Aha.io API 令牌	-
MCP_TRANSPORT_MODE	传输模式（stdio 或 streamable-http）	stdio
MCP_PORT	streamable-http 模式的端口	3001
MCP_HOST	streamable-http 模式的主机	0.0.0.0
MCP_AUTH_TOKEN	streamable-http 传输的 Bearer 令牌	-
MCP_TOOL_RATE_LIMIT_PER_MINUTE	每分钟允许的工具调用次数（0 表示禁用）	120
MCP_CONFIG_DIR	配置目录	/home/mcp/.config

健康检查

Docker 镜像为 streamable-http 模式配置了健康检查：

# Check if the HTTP server is healthy
curl http://localhost:3001/health

# Get detailed server status
curl http://localhost:3001/status

从源代码构建

如需在本地构建 Docker 镜像：

# Build the image
npm run docker:build

# Test the image
npm run docker:test

# Run the image
npm run docker:run

# Run in Streamable HTTP mode
npm run docker:run:http

多架构支持

Docker 镜像针对多种架构构建：

• linux/amd64（x86_64）
• linux/arm64（Apple Silicon、ARM64）

Docker 会自动拉取适用于你平台的镜像。

Docker 安全性

Docker 镜像遵循安全最佳实践：

• 以非 root 用户（mcp）运行
• 使用精简的 Alpine Linux 基础镜像
• 包含 tini，以正确处理信号
• 配置目录具有适当的权限
• 使用多阶段构建来缩小攻击面

🏗️ 开发

提交规范

本项目使用 Conventional Commits 来确保提交消息格式一致，并支持自动版本管理。

提交消息格式：

<type>(<scope>): <subject>

<body>

<footer>

类型：

• feat：新功能
• fix：修复错误
• docs：仅修改文档
• style：不影响代码含义的更改
• refactor：既不修复错误也不添加功能的代码更改
• perf：提升性能的代码更改
• test：添加缺失的测试或修正现有测试
• build：影响构建系统或外部依赖项的更改
• ci：更改 CI 配置文件和脚本
• chore：其他不修改 src 或 test 文件的更改

示例：

feat: add new MCP tool for listing projects
fix: resolve authentication issue with API tokens
docs: update README with installation instructions
feat!: change API response format (breaking change)

每次提交时以及在 CI 中，都会使用 commitlint 验证提交消息。

测试

本地测试

运行测试套件：

# Run all tests
bun test

# Run tests in watch mode
bun run test:watch

# Run tests with coverage
bun test --coverage

Docker 测试

Docker 环境包含测试所需的所有依赖项：

# Test the Docker build
docker build -t aha-mcp-test .

# Run tests inside Docker container
docker run --rm aha-mcp-test bun test

# Test with environment variables
docker run --rm \
  -e AHA_COMPANY="test-company" \
  -e AHA_TOKEN="test-token" \
  aha-mcp-test bun test

# Verify all dependencies are available
docker run --rm aha-mcp-test bun install --dry-run

# Test database functionality (SQLite)
docker run --rm aha-mcp-test node -e "
  const sqlite3 = require('sqlite3');
  const db = new sqlite3.Database(':memory:');
  console.log('SQLite available:', !!db);
  db.close();
"

# Test if sqlite-vec extension loads (graceful fallback if not available)
docker run --rm aha-mcp-test bun run start --help

测试数据库功能

Docker 环境包含：

• SQLite3：核心数据库功能
• Node.js sqlite 包：数据库驱动程序和实用工具
• 平稳回退：在测试环境中会抑制 sqlite-vec 扩展警告
• 临时数据库：每项测试都使用独立的临时数据库文件
• 妥善清理：测试后会清理数据库连接和文件

验证 Docker 环境

# Check all key components are available
docker run --rm aha-mcp-test sh -c "
  echo 'Checking Bun...'; bun --version
  echo 'Checking Node.js...'; node --version  
  echo 'Checking SQLite...'; node -e 'console.log(require(\"sqlite3\"))'
  echo 'Checking dependencies...'; bun install --dry-run
  echo 'Running basic tests...'; bun test --reporter=dot
"

# Test MCP server startup
docker run --rm -d --name aha-test \
  -e AHA_COMPANY="test" \
  -e AHA_TOKEN="test" \
  aha-mcp-test

# Check if server started successfully
docker logs aha-test

# Cleanup
docker stop aha-test

Docker 环境支持完整的测试套件，包括：

• 194+ 个测试用例，覆盖所有服务
• 数据库服务测试（25 个测试用例）
• 后台同步服务测试（16 个测试用例）
• MCP 可访问性测试（172 个测试用例）
• 在测试模式下会自动抑制 SQLite 扩展警告

构建

构建生产版本：

# Build stdio server
bun run build

# Build HTTP server
bun run build:http

发布

自动发布流程（推荐）

本项目使用 release-please 自动管理版本和发布：

1. 使用 Conventional Commits 格式进行更改：

   • feat: 表示新功能（次版本号递增）
   • fix: 表示错误修复（补丁版本号递增）
   • feat!: 或 fix!: 表示有破坏性更改（主版本号递增）

2. 推送到 main —— release-please 将自动：

   • 创建一个包含更新后的版本号和变更日志的发布 PR
   • 发布 PR 合并后，创建 GitHub 发布版本
   • 此发布版本将触发自动发布到 npm、ghcr.io 和 MCP Registry

   注册表任务最后运行，因为注册表会通过读取已发布的构件来验证所有权：npm 包中的 mcpName、镜像上的 io.modelcontextprotocol.server.name 标签，以及附加到发布版本的 .mcpb 资源的 SHA-256。该任务使用 GitHub OIDC 进行身份验证，因此无需在任何地方存储注册表凭据。

手动发布

手动发布软件包：

# 1. Ensure you're logged in to npm
npm login

# 2. Build the package
bun run build

# 3. Publish to npm
npm publish --access public

注意：请确保在仓库设置中配置 NPM_TOKEN 密钥，以便自动发布。

📚 文档

• CLAUDE.md - 使用此仓库时为 Claude Code 提供的开发指南
• MCP 文档 - 官方 Model Context Protocol 文档

📄 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。