KiraHub MCP服务器

模型上下文协议（MCP）服务器，用于将KiraHub与Claude Code和其他MCP兼容客户端集成。

特性

此MCP服务器通过标准化的工具调用提供对KiraHub任务管理功能的全面访问：

任务管理

get_ext_task -从队列中获取下一个任务
索赔任务 -要求完成一项任务
完成任务 -通过自动验证问答标记任务已完成
创建任务 -创建新任务
update_task -更新任务详细信息
get_task_details -获取完整的任务信息

Epic管理

列表_图片 -列出项目史诗
获取图片 -通过任务获得史诗般的细节
创建图片 -创建新史诗
update_图片 -更新史诗细节

工作记录

add_working_note -添加todo/bug/edge_case/优化注释
resolve_working_note -将笔记标记为已解决
升级_工作_注意 -将注释升级到新任务
get_task_notes -获取任务的所有笔记

项目知识

获取项目知识 -搜索项目知识库
add_project_知识 -添加知识条目

Plan Wiki集成（PlanCreator）

get_plan_overview -通过史诗和统计数据获取项目计划概述
list_plan_tasks -列出项目计划中的所有任务
get_plan_task_details -从计划维基获取详细的任务文档
搜索计划任务 -在计划wiki中搜索任务

自动验证对话

这 complete_task 该工具自动处理多圈验证：

完成任务：呼叫 complete_task 带有task_id
验证问题：如果KiraHub需要验证，则响应包含一个问题
回答问题：呼叫 complete_task 再次给出答案 message 参数
重复：继续回答问题，直到验证完成
结果：最终响应显示验证结果（通过/失败）和分数

验证流程示例

# Step 1: Complete task
complete_task(task_id="AUTH-5")
→ Response: "Task completion noted. I have a few questions...
   **Validation Question 1** (architecture):
   Which OAuth 2.0 flow(s) did you implement and why?
   **To answer this question, call complete_task again with the answer in the message parameter.**"

# Step 2: Answer question
complete_task(message="I implemented OAuth 2.0 Authorization Code flow with PKCE...")
→ Response: "Answer recorded. Next question:
   **Validation Question 2** (best_practice):
   How did you implement token refresh and rotation?
   **To answer this question, call complete_task again with the answer in the message parameter.**"

# Step 3: Answer next question
complete_task(message="Refresh token rotation is implemented with a 7-day rotation window...")
→ Response: "Validation complete! ✅ All questions answered satisfactorily
   **Validation PASSED** - Score: 85%"

安装

KiraHub MCP服务器可以作为npm包使用，可以直接与 npx:

# No installation needed! Use with npx:
npx -y @pendingspark/kirahub-mcp@latest

# Or install globally:
npm install -g @pendingspark/kirahub-mcp

# Or install locally for development:
git clone https://github.com/PendingSpark/kirahub-mcp.git
cd kirahub-mcp
npm install
npm run build

获取API密钥

选项1：使用仪表板（推荐）

启动KiraHub：

   cd kirahub
   make up

打开仪表板：

导航至http://localhost并使用以下方式登录：

- 电子邮件： demo@kirahub.com - 密码： demo123

创建API密钥：

- 首选设置 → API密钥 - 点击 生成新密钥 - 填写表格： - 键名: Claude Code Agent - 代理ID: claude-code-mcp - 项目分配：选择一个项目或保留为“所有项目” - 能力：选择所有功能（或根据需要进行自定义） - 点击 生成密钥 - 复制API密钥 （你不会再看到它了！）

更新您的MCP配置 使用生成的API密钥（请参阅下面的使用部分）

使用Claude代码

完整安装指南

按照以下步骤将KiraHub与Claude Code集成：

步骤1：获取API密钥

使用仪表板（上面的选项1）创建API键。

步骤2：配置Claude代码

查找您的Claude Code配置目录：

- macOS： ~/Library/Application Support/Claude/ - Linux： ~/.config/Claude/ - 窗户： %APPDATA%\Claude\

创建或编辑 .mcp.json 在项目根目录中 （推荐）或在Claude配置目录中：

   {
     "mcpServers": {
       "kirahub": {
         "command": "npx",
         "args": [
           "-y",
           "@pendingspark/kirahub-mcp@latest"
         ],
         "env": {
           "KIRAHUB_API_URL": "http://localhost",
           "KIRAHUB_API_KEY": "kh_live_your-api-key-here"
         }
       }
     }
   }

重要提示：

- 替换 kh_live_your-api-key-here 使用您生成的API密钥 - API密钥以 kh_live_ - 这 @latest 标签确保您始终获得最新版本

重新启动Claude代码 加载MCP服务器

步骤3：验证设置

在Claude Code中，尝试：

"Get my next task"

如果成功，克劳德将使用 get_next_task 工具，并向您展示分配项目中的任务！

配置选项

选项A：项目根配置（推荐）

地方 .mcp.json 在您的项目根目录中。这将使MCP配置与您的项目保持一致。

选项B：全局配置

地方 .mcp.json 在Claude的配置目录中。这使得MCP服务器在所有项目中都可用。

选项C：使用特定版本

对于生产或固定到特定版本：

{
  "mcpServers": {
    "kirahub": {
      "command": "npx",
      "args": [
        "-y",
        "@pendingspark/kirahub-mcp@0.1.0"
      ],
      "env": {
        "KIRAHUB_API_URL": "http://localhost",
        "KIRAHUB_API_KEY": "kh_live_your-api-key-here"
      }
    }
  }
}

规划Wiki集成设置

Plan Wiki集成允许代理在KiraHub中管理任务时从PlanCreator访问详细的任务文档。这为每个任务提供了丰富的上下文和说明。

先决条件

PlanCreator必须正在运行 旁边KiraHub
项目范围的API密钥 代理人需要访问计划文档

逐步设置

步骤1：验证PlanCreator是否正在运行

# Check if PlanCreator is accessible
curl http://localhost/api/wiki/health

# Should return: {"status":"ok"}

步骤2：将Plan Wiki URL添加到MCP配置中

更新您的 .mcp.json 包括 PLAN_EDITOR_API_URL 环境变量：

{
  "mcpServers": {
    "kirahub": {
      "command": "npx",
      "args": [
        "-y",
        "@pendingspark/kirahub-mcp@latest"
      ],
      "env": {
        "KIRAHUB_API_URL": "http://localhost",
        "KIRAHUB_API_KEY": "kh_live_your-api-key-here",
        "PLAN_EDITOR_API_URL": "http://localhost/api/wiki"
      }
    }
  }
}

重要提示： 这 PLAN_EDITOR_API_URL 应指向wiki API端点，通常 http://localhost/api/wiki.

步骤3：创建项目范围的API密钥

计划Wiki集成需要 项目范围API密钥 因此，代理可以访问其分配项目的计划文档。

选项A：使用仪表板

导航至http://localhost并登录
首选设置 → API密钥
点击 生成新密钥
填写表格：

- 键名: claude-code-project-beta （或您的项目名称） - 代理ID: claude-code-mcp - 项目分配: 选择特定项目 （例如，“Beta项目”） - 能力：选择全部或根据需要进行自定义

点击 生成密钥
复制API密钥 立即（格式： kh_live_...)

选项B：使用API

#!/bin/bash
# Get JWT token
TOKEN=$(curl -s -X POST http://localhost/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@kirahub.com","password":"demo123"}' | jq -r '.token')

# Get project UUID (replace "project-beta" with your project slug)
PROJECT_ID=$(curl -s -X GET http://localhost/api/projects \
  -H "Authorization: Bearer $TOKEN" | jq -r '.[] | select(.slug == "project-beta") | .id')

# Create API key
curl -s -X POST http://localhost/api/agent-api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{
    \"keyName\": \"claude-code-project-beta\",
    \"agentId\": \"claude-code-mcp\",
    \"projectId\": \"$PROJECT_ID\",
    \"capabilities\": []
  }" | jq '.'

步骤4：使用新的API密钥更新MCP配置

替换您的中的API密钥 .mcp.json 使用新创建的项目范围键：

{
  "mcpServers": {
    "kirahub": {
      "command": "npx",
      "args": [
        "-y",
        "@pendingspark/kirahub-mcp@latest"
      ],
      "env": {
        "KIRAHUB_API_URL": "http://localhost",
        "KIRAHUB_API_KEY": "kh_live_ee805f5304771831c9d10db36733803e6ec8f6a243c0fc0eb8859cc8c70d0419",
        "PLAN_EDITOR_API_URL": "http://localhost/api/wiki"
      }
    }
  }
}

步骤5：重新启动Claude代码

更新配置后，重新启动Claude Code以加载新设置。

步骤6：测试计划Wiki集成

测试与自然语言命令的集成：

You: "Get my next task and show me the detailed plan documentation"

Claude will:
1. Call get_next_task to fetch a task from KiraHub
2. Automatically call get_plan_task_details to fetch detailed instructions from Plan Wiki
3. Present both the task summary and detailed documentation

规划Wiki工作流示例

以下是使用Plan Wiki集成的典型工作流程：

You: "Get the next task"
Claude: [Calls get_next_task]
        "Task AUTH-5: Implement OAuth Authentication
         Description: Set up OAuth 2.0 authentication flow
         Wiki: http://localhost/wiki?project=project-beta&task=auth-oauth"

You: "Show me the detailed plan for this task"
Claude: [Calls get_plan_task_details with task description]
        "# OAuth Authentication Implementation

         ## Overview
         Implement OAuth 2.0 authorization code flow with PKCE...

         ## Technical Requirements
         - Support for multiple OAuth providers (Google, GitHub)
         - PKCE for mobile apps
         - Refresh token rotation

         ## Implementation Steps
         1. Create OAuth provider configuration
         2. Implement authorization endpoint
         3. Implement token exchange
         ..."

You: "What other tasks are in the plan related to auth?"
Claude: [Calls search_plan_tasks with query="auth"]
        "Found 3 related tasks:
         1. AUTH-5: OAuth Authentication
         2. AUTH-6: Session Management
         3. AUTH-7: API Key Validation"

计划Wiki工具参考

get_plan_overview

获取项目计划的高级概述，包括史诗和统计数据。

参数：

project_id （可选）：项目ID（默认为代理分配的项目）

退货：

项目名称、描述、版本
带有描述的史诗列表
任务总数
项目概述标记

例子：

get_plan_overview({ project_id: "89bc9621-ac3a-4b0f-b69f-9de10358de2c" })

list_plan_tasks

使用元数据列出项目计划中的所有任务。

参数：

project_id （必填）：项目ID

退货：

包含id、标题、描述、标签和依赖关系的任务摘要数组

例子：

list_plan_tasks({ project_id: "89bc9621-ac3a-4b0f-b69f-9de10358de2c" })

get_plan_task_details

获取特定计划任务的完整详细文档。

参数：

task_id （必填）：计划中的任务ID或标题

退货：

在markdown中完成任务文档
任务元数据（类型、标签、依赖关系）
如果任务属于史诗，则提供史诗信息
项目概述摘录

例子：

// Automatically extracts wiki URL from KiraHub task description
get_plan_task_details({ task_id: "AUTH-5" })

// Or directly with plan task ID
get_plan_task_details({ task_id: "implement-oauth" })

注：此工具可以从KiraHub任务描述中提取计划信息，其中包含以下格式的wiki URL： http://localhost/wiki?project={project_id}&task={task_id}

搜索计划任务

按关键字在计划wiki中搜索任务。

参数：

query （必填）：搜索字符串
project_id （可选）：项目ID（默认为代理分配的项目）

退货：

匹配任务数组（最多10个结果）
每个结果包括id、标题、描述、标签、文件名

例子：

search_plan_tasks({
  query: "authentication",
  project_id: "89bc9621-ac3a-4b0f-b69f-9de10358de2c"
})

Wiki集成故障排除计划

“未启用计划编辑器集成”

原因： PLAN_EDITOR_API_URL 未设置或设置为“禁用”/“无”

修复：

"env": {
  "PLAN_EDITOR_API_URL": "http://localhost/api/wiki"
}

“无法验证项目访问权限”（401）

原因： API密钥未传递给PlanCreator，或者PlanCreator无法使用KiraHub进行验证

修复：

请确保您的API密钥有效： curl http://localhost/api/agents/verify -H "x-api-key: kh_live_..."
检查KiraHub日志中的代理验证错误
验证PlanCreator是否可以访问KiraHub API

“无法验证项目访问权限”（403）

原因： 您的API密钥分配给了与您尝试访问的项目不同的项目

修复：

检查API密钥的项目分配：

- 仪表盘→ 设置→ API密钥→ 勾选“项目”栏

要么：

- 为正确的项目创建新的API密钥 - 创建“所有项目”API密钥（安全性较低，但更灵活）

“在任务描述中找不到wiki链接”

原因： KiraHub任务的描述中没有wiki URL

修复：

确保以以下格式使用wiki URL创建任务： http://localhost/wiki?project={project_id}&task={task_id}
或使用 list_plan_tasks 和 get_plan_task_details 使用明确的任务ID

PlanCreator没有响应

检查PlanCreator是否正在运行：

# Test health endpoint
curl http://localhost/api/wiki/health

# Check Kubernetes pods
kubectl get pods | grep plancreator

API密钥适用于KiraHub，但不适用于PlanCreator

原因： PlanCreator通过致电KiraHub验证代理 /api/agents/verify 终点。网络连接或API密钥格式可能错误。

调试：

# Test agent verification endpoint
curl -s http://localhost/api/agents/verify \
  -H "x-api-key: kh_live_your-key-here" | jq '.'

# Should return agent details including projectId

Claude代码中的示例用法

配置后，您可以使用自然语言命令和Claude Code：

You: "Get my next task and start working on it"
Claude: [Calls get_next_task and claim_task tools]
        "I've claimed task AUTH-5: Implement OAuth authentication.
         This task requires implementing OAuth 2.0 with PKCE..."

You: "Mark this task as complete"
Claude: [Calls complete_task tool]
        "KiraHub is asking validation questions.
         Question 1 (architecture): Which OAuth 2.0 flow(s) did you implement?"

You: "I implemented Authorization Code flow with PKCE"
Claude: [Calls complete_task with your answer]
        "Question 2 (best_practice): How did you implement token refresh?"

You: "Using refresh token rotation with 7-day window"
Claude: [Calls complete_task with your answer]
        "Validation passed! ✅ Score: 85%
         The task has been marked as completed."

工具参考

任务管理工具

get_ext_task

根据优先级和依赖关系从队列中获取下一个任务。

参数：

project_id （可选）：按项目筛选任务

例子：

get_next_task({ project_id: "proj-123" })

索赔任务

要求一项任务来处理它。

参数：

task_id （必填）：要索赔的任务的ID

例子：

claim_task({ task_id: "AUTH-5" })

完成任务

将任务标记为已完成。处理自动验证问答。

参数：

task_id （可选）：要完成的任务的ID
message （可选）：验证问题的答案

示例：

// Initial completion
complete_task({ task_id: "AUTH-5" })

// Answer validation question
complete_task({ message: "I implemented OAuth 2.0 with PKCE..." })

创建任务

创建新任务。

参数：

title （必填）：任务标题
description （可选）：任务描述
project_id （可选）：项目ID
epic_id （可选）：史诗ID
tags （可选）：标签数组

例子：

create_task({
  title: "Implement login page",
  description: "Create login UI with OAuth",
  project_id: "proj-123",
  tags: ["frontend", "auth"]
})

update_task

更新任务详细信息。

参数：

task_id （必填）：任务ID
title （可选）：新标题
description （可选）：新描述
status （可选）：新状态（新/正在进行/已阻止/已完成）
tags （可选）：新标签

例子：

update_task({
  task_id: "AUTH-5",
  status: "in-progress",
  tags: ["backend", "auth", "oauth"]
})

get_task_details

获取任务的详细信息。

参数：

task_id （必填）：任务ID

例子：

get_task_details({ task_id: "AUTH-5" })

Epic管理工具

列表_图片

列出一个项目的所有史诗。

参数：

project_id （必填）：项目ID

例子：

list_epics({ project_id: "proj-123" })

获取图片

获取所有任务的史诗般的细节。

参数：

epic_id （必填）：Epic ID

例子：

get_epic({ epic_id: "PROJ-1" })

创建图片

创造一部新的史诗。

参数：

project_id （必填）：项目ID
name （必填）：史诗名称
description （可选）：史诗般的描述

例子：

create_epic({
  project_id: "proj-123",
  name: "Authentication System",
  description: "Complete OAuth 2.0 implementation"
})

update_图片

更新史诗般的细节。

参数：

epic_id （必填）：Epic ID
name （可选）：新名称
description （可选）：新描述
status （可选）：新状态（活动/存档）

例子：

update_epic({
  epic_id: "PROJ-1",
  status: "archived"
})

工作笔记工具

add_working_note

向任务添加工作注释。

参数：

task_id （必填）：任务ID
note （必填）：备注内容
type （必填）：笔记类型（todo/bug/edge_case/优化）
priority （必填）：优先级（must_fix/should_fix/nice_to_have）

例子：

add_working_note({
  task_id: "AUTH-5",
  note: "Need to handle token expiry edge case",
  type: "edge_case",
  priority: "must_fix"
})

resolve_working_note

将工作笔记标记为已解决。

参数：

task_id （必填）：任务ID
note_id （必填）：备注ID

例子：

resolve_working_note({
  task_id: "AUTH-5",
  note_id: "note-123"
})

升级_工作_注意

将工作笔记升级为新任务。

参数：

task_id （必填）：当前任务ID
note_id （必填）：注意ID升级
epic_id （可选）：新任务的Epic ID

例子：

escalate_working_note({
  task_id: "AUTH-5",
  note_id: "note-123",
  epic_id: "PROJ-1"
})

get_task_notes

获取任务的所有工作笔记。

参数：

task_id （必填）：任务ID

例子：

get_task_notes({ task_id: "AUTH-5" })

项目知识工具

获取项目知识

搜索项目知识库。

参数：

project_id （必填）：项目ID
search （可选）：搜索查询
type （可选）：知识类型筛选器

例子：

get_project_knowledge({
  project_id: "proj-123",
  search: "OAuth authentication",
  type: "architecture"
})

add_project_知识

添加新的知识条目。

参数：

project_id （必填）：项目ID
knowledge_type （必填）：类型（架构/最佳实践/规范等）
title （必填）：知识标题
content （必填）：知识内容
tags （可选）：标签数组

例子：

add_project_knowledge({
  project_id: "proj-123",
  knowledge_type: "best_practice",
  title: "OAuth Token Storage",
  content: "Store tokens in httpOnly cookies with SameSite=Strict...",
  tags: ["auth", "security"]
})

发展

构建

npm run build

观看模式

npm run dev

本地测试

选项1：使用npx（快速测试）

# Make sure KiraHub is running
KIRAHUB_API_URL=http://localhost \
KIRAHUB_API_KEY=your-api-key \
npx -y @pendingspark/kirahub-mcp@latest

方案2：地方发展

# Clone and build from source
git clone https://github.com/PendingSpark/kirahub-mcp.git
cd kirahub-mcp
npm install
npm run build

# Test the local build
KIRAHUB_API_URL=http://localhost \
KIRAHUB_API_KEY=your-api-key \
node dist/index.js

故障排除

“错误：需要KIRAHUB_API_KEY环境变量”

设置 KIRAHUB_API_KEY 在你的 .env 文件或MCP配置。

连接错误

验证KiraHub是否正在运行： curl http://localhost:3000/api/health
检查 KIRAHUB_API_URL 是正确的
验证API密钥是否有效

“未找到可用任务”

检查项目分配： 您的API密钥可能被分配给特定的项目

- 前往仪表盘→ 设置→ API密钥 - 检查您的代理人的“项目”栏 - 如果分配给一个项目，您将只能看到该项目中的任务

在指定的项目中创建任务：

- 使用 create_task 或通过仪表板创建任务 - 确保他们和你的代理人在同一个项目中

更改项目分配：

- 删除当前API密钥 - 使用“所有项目”或其他项目创建一个新项目

未出现验证问题

确保任务具有相关标签
检查项目是否有具有匹配标签的知识库条目
验证知识库是否已填充： get_project_knowledge(project_id="...")

代理从错误的项目中获取任务

在仪表板中检查API密钥的项目分配
更新API密钥或使用正确的项目创建新密钥
记住：如果 projectId 如果已设置，则代理只能看到该项目中的任务

建筑

MCP服务器由以下部分组成：

index.ts -带工具处理程序的主MCP服务器
a2a-client.ts -A2A协议客户端包装器
MCP-SDK -处理与Claude Code的stdio通信

服务器将MCP工具调用转换为A2A协议消息，将其发送到KiraHub，并以Claude Code理解的格式返回响应。

Kirahub MCP

快速接入

详细介绍

KiraHub MCP服务器

特性

任务管理

Epic管理

工作记录

项目知识

Plan Wiki集成（PlanCreator）

自动验证对话

验证流程示例

安装

获取API密钥

选项1：使用仪表板（推荐）

使用Claude代码

完整安装指南

步骤1：获取API密钥

步骤2：配置Claude代码

步骤3：验证设置

配置选项

选项A：项目根配置（推荐）

选项B：全局配置

选项C：使用特定版本

规划Wiki集成设置

先决条件

逐步设置

步骤1：验证PlanCreator是否正在运行

步骤2：将Plan Wiki URL添加到MCP配置中

步骤3：创建项目范围的API密钥

步骤4：使用新的API密钥更新MCP配置

步骤5：重新启动Claude代码

步骤6：测试计划Wiki集成

规划Wiki工作流示例

计划Wiki工具参考

get_plan_overview

list_plan_tasks

get_plan_task_details

搜索计划任务

Wiki集成故障排除计划

“未启用计划编辑器集成”

“无法验证项目访问权限”（401）

“无法验证项目访问权限”（403）

“在任务描述中找不到wiki链接”

PlanCreator没有响应

API密钥适用于KiraHub，但不适用于PlanCreator

Claude代码中的示例用法

工具参考

任务管理工具

get_ext_task

索赔任务

完成任务

创建任务

update_task

get_task_details

Epic管理工具

列表_图片

获取图片

创建图片

update_图片

工作笔记工具

add_working_note

resolve_working_note

升级_工作_注意

get_task_notes

项目知识工具

获取项目知识

add_project_知识

发展

构建

观看模式

本地测试

故障排除

“错误：需要KIRAHUB_API_KEY环境变量”

连接错误

“未找到可用任务”

未出现验证问题

代理从错误的项目中获取任务

建筑

相关文档