Hegner123 MCP

并发代理MCP服务器

MCP服务器，用于协调处理并行开发任务的多个AI代理。启用原子步骤声明、依赖关系管理、崩溃恢复和跨项目协调。

概述

该MCP服务器为多代理并发开发提供了一个SQLite支持的协调系统。它解决了任务分配中的竞争条件，跟踪代理健康状况，并管理工作项之间的依赖关系。

主要特点：

• ✅ 原子步声明（防止双重赋值）
• ✅ 依赖性跟踪（仅在满足依赖性时工作）
• ✅ 心跳监测（检测崩溃的代理）
• ✅ 多项目协调（全局工作队列）
• ✅ 度量和分析（了解模式）
• ✅ 交易安全（SQLite，WAL模式）

用例

Git工作树协调

多个Claude实例同时处理不同的分支：

Agent 1 → claim_step() → step1/api-add-endpoints
Agent 2 → claim_step() → step2/db-update-schema
Agent 3 → claim_step() → step3/ui-add-forms

2.并行任务执行

在多个代理之间分配任何可并行化的工作：

Agent 1 → Testing module A
Agent 2 → Testing module B
Agent 3 → Documentation updates

3.碰撞恢复

自动检测代理故障并从中恢复：

Agent 1 crashes → heartbeat stops
Monitor detects stale work after 15min
Agent 2 → claim_step() → picks up abandoned work

建筑

数据库： 具有WAL模式的单个SQLite数据库，用于并发访问 地点： ~/.claude/agent-coordination.db 运输： stdio（MCP标准） 查询层： sqlc生成的类型安全Go代码

架构：

• projects -顶级项目
• steps -单个工作项
• dependencies -步骤依赖关系
• agent_events -审计追踪

类型安全：

• 自定义ID类型(ProjectID, StepID)防止混合ID
• 枚举类型(StepStatus, ProjectStatus, EventType)在编译时捕获拼写错误
• sqlc从带注释的SQL生成类型安全的查询函数

安装

先决条件

• 转到1.21+
• SQLite 3.35+（用于WAL模式）

构建

make build
# Binary: ./bin/hq

安装

make install
# Installs to: /usr/local/bin/hq

MCP配置

添加到克劳德代码MCP设置：

用户范围 （推荐-适用于所有Claude实例）：

claude mcp add --scope user --transport stdio hq -- \
  /usr/local/bin/hq

项目范围 （项目特定）：

claude mcp add --scope project --transport stdio hq -- \
  /usr/local/bin/hq

配置文件

如果使用 .mcp.json:

{
  "mcpServers": {
    "hq": {
      "command": "/usr/local/bin/hq",
      "args": [],
      "env": {
        "AGENT_DB_PATH": "${HOME}/.claude/agent-coordination.db"
      }
    }
  }
}

MCP工具

项目管理

create_project

创建一个包含步骤的新项目。

参数：

• name （string）-项目名称
• base_commit （string）-Git提交哈希
• steps （array）-步骤定义数组

步骤定义：

• step_num （数字）-步骤编号（1、2、3…）
• branch （string）-Git分支名称
• scope （string）-作用域（api、ui、db等）
• depends_on （array）-这取决于步骤号数组

例子：

{
  "name": "myapp-auth-feature",
  "base_commit": "abc123",
  "steps": [
    {
      "step_num": 1,
      "branch": "step1/auth-add-jwt-utils",
      "scope": "auth",
      "depends_on": []
    },
    {
      "step_num": 2,
      "branch": "step2/auth-add-middleware",
      "scope": "auth",
      "depends_on": [1]
    }
  ]
}

get_project

获取项目详细信息和所有步骤。

参数：

• name （string）-项目名称

退货：

• 项目信息，包括所有步骤及其当前状态

list_projects

列出所有项目。

参数：

• status （字符串，可选）-按状态（活动、完成、中止）筛选

退货：

• 包含摘要信息的项目数组

步骤操作

claim_step

原子性地声明下一个可用步骤。

参数：

• project （string）-项目名称
• agent_id （string）-代理标识符

退货：

• 步骤详细信息（如果已声明），如果没有可用工作，则为空

例子：

{
  "project": "myapp-auth-feature",
  "agent_id": "agent-1"
}

答复：

{
  "id": 1,
  "step_num": 1,
  "branch": "step1/auth-add-jwt-utils",
  "scope": "auth",
  "status": "claimed",
  "agent_id": "agent-1",
  "claimed_at": "2026-01-18T10:30:00Z"
}

start_step

将声称的步骤标记为正在进行中。

参数：

• step_id （数字）-步骤ID
• worktree （字符串，可选）-工作树路径

heartbeat

更新步进心跳（工作时每30-60秒呼叫一次）。

参数：

• step_id （数字）-步骤ID
• agent_id （string）-代理标识符

complete_step

将步骤标记为已完成。

参数：

• step_id （数字）-步骤ID
• commit_hash （string）-最终git提交哈希
• files_modified （array）-已修改文件路径列表
• notes （字符串，可选）-完成注释

fail_step

将步骤标记为失败。

参数：

• step_id （数字）-步骤ID
• reason （string）-失败原因

get_step

获取步骤详细信息。

参数：

• step_id （数字）-步骤ID

协调

get_available_steps

获取所有可用的步骤（没有不完整的依赖关系）。

参数：

• project （字符串，可选）-按项目筛选
• scope （字符串，可选）-按作用域筛选

退货：

• 所有（或筛选）项目中的可用步骤数组

detect_stale_work

查找心跳停止（代理崩溃）的步骤。

参数：

• timeout_minutes （数字，默认值：15）-自上次心跳后的分钟数

退货：

• 一系列可能被放弃的步骤

recover_step

恢复一个过时的步骤（重置为not_started）。

参数：

• step_id （数字）-步骤ID

分析

get_metrics

获取项目和代理指标。

参数：

• project （字符串，可选）-按项目筛选
• agent_id （字符串，可选）-按代理筛选

退货：

• 完成时间、步骤数、范围细分

get_agent_events

获取代理活动日志。

参数：

• agent_id （字符串，可选）-按代理筛选
• project （字符串，可选）-按项目筛选
• limit （数字，默认值：100）-要返回的最大事件数

使用示例

基本工作树工作流

1.创建项目：

await mcp.call("create_project", {
  name: "myapp-auth",
  base_commit: "abc123",
  steps: [
    { step_num: 1, branch: "step1/auth-add-jwt-utils", scope: "auth", depends_on: [] },
    { step_num: 2, branch: "step2/auth-add-middleware", scope: "auth", depends_on: [1] },
    { step_num: 3, branch: "step3/api-add-endpoints", scope: "api", depends_on: [1, 2] }
  ]
});

2.代理人索赔工作：

const step = await mcp.call("claim_step", {
  project: "myapp-auth",
  agent_id: "agent-1"
});
// Returns: { step_num: 1, branch: "step1/auth-add-jwt-utils", ... }

3.代理人开始工作：

await mcp.call("start_step", {
  step_id: step.id,
  worktree: "/Users/home/myapp-step1-auth-add-jwt-utils"
});

4.代理在工作时发送心跳：

// Every 30 seconds
setInterval(() => {
  await mcp.call("heartbeat", {
    step_id: step.id,
    agent_id: "agent-1"
  });
}, 30000);

5.代理人完成工作：

await mcp.call("complete_step", {
  step_id: step.id,
  commit_hash: "def456",
  files_modified: ["src/utils/jwt.go", "src/utils/jwt_test.go"],
  notes: "JWT signing and validation complete"
});

6.下一代理要求步骤2：

const nextStep = await mcp.call("claim_step", {
  project: "myapp-auth",
  agent_id: "agent-2"
});
// Returns: { step_num: 2, branch: "step2/auth-add-middleware", ... }
// (step 1 dependency satisfied)

故障恢复

监控陈旧工作：

const staleSteps = await mcp.call("detect_stale_work", {
  timeout_minutes: 15
});

for (const step of staleSteps) {
  console.log(`Stale: ${step.branch} (agent: ${step.agent_id})`);

  // Recover it
  await mcp.call("recover_step", { step_id: step.id });
}

跨项目工作队列

从任何项目中获取下一个可用工作：

const availableSteps = await mcp.call("get_available_steps", {});
// Returns all steps ready to work on across all projects

// Prioritize UI work
const uiWork = await mcp.call("get_available_steps", {
  scope: "ui"
});

指标

项目完成时间：

const metrics = await mcp.call("get_metrics", {
  project: "myapp-auth"
});
// { total_steps: 5, completed: 3, avg_time_hours: 2.5, ... }

代理生产力：

const agentMetrics = await mcp.call("get_metrics", {
  agent_id: "agent-1"
});
// { steps_completed: 10, avg_time_hours: 1.8, scopes: {...} }

发展

运行测试

make test

运行服务器（开发模式）

make dev
# Runs with verbose logging

数据库管理

查看数据库：

sqlite3 ~/.claude/agent-coordination.db

常见问题：

-- Active projects
SELECT * FROM projects WHERE status = 'active';

-- All steps in a project
SELECT * FROM steps WHERE project_id = 1;

-- Available work
SELECT s.* FROM steps s
LEFT JOIN dependencies d ON s.id = d.step_id
LEFT JOIN steps ds ON d.depends_on_step_id = ds.id
WHERE s.status = 'not_started'
AND (ds.status = 'completed' OR ds.id IS NULL);

-- Agent activity
SELECT * FROM agent_events ORDER BY timestamp DESC LIMIT 20;

重置数据库：

rm ~/.claude/agent-coordination.db
# Will be recreated on next server start

故障排除

“数据库已锁定”

• 检查WAL模式是否启用： PRAGMA journal_mode; 应返回 wal
• 增加繁忙超时： PRAGMA busy_timeout=5000;
• 确保没有长时间运行的事务

未检测到损坏的工作

• 检查心跳间隔（应为30-60s）
• 验证timeout_minutes参数
• 检查agent_events表中的心跳条目

未声明的步骤

• 验证是否满足依赖关系
• 检查步骤状态（应 not_started)
• 确保没有其他代理人认领

演出

测试方法：

• 1000个并发代理
• 100个项目10000步
• \<10ms平均索赔步延迟
• WAL模式优雅地处理并发写入

SQLite限制：

• 最大并发读者数：无限制
• 最大并发作者数：1（通过WAL排队）
• 数据库大小：实际上不受限制
• 性能：适用于\<1M行

许可证

麻省理工学院

另见

• SCHEMA.md -详细的数据库架构
• 建筑.md -系统设计细节
• ~/.claude/WORKTREE.md -Git工作树工作流文档