@dachengzhihui/keyan-agent-mcp

通过 MCP(Model Context Protocol)把 keyan-agent 的 admin API 暴露给本地 Claude Code 等 AI 客户端。

让 AI 在对话里直接为你完成 keyan-agent 的配置:建 handler、agent、skill,并 test-run 验证。

实际场景:你在 Claude Code 里说「帮我建一个每周分析进度的 handler,接现有 progress-reviewer agent」——Claude Code 通过本 MCP 工具,从读 wiki 学规范 → 写脚本 → test-run 验证 → enable 全流程跑完,配置即能力闭环到 AI 端。

安装 & 配置

无需手动安装。在你的 Claude Code config(~/.config/claude-code/mcp.json 或 IDE 配置)加:

{
  "mcpServers": {
    "keyan-agent": {
      "command": "npx",
      "args": ["-y", "@dachengzhihui/keyan-agent-mcp"],
      "env": {
        "AGENT_BASE_URL": "https://agent.your-company.com",
        "AGENT_ADMIN_TOKEN": "your-admin-token"
      }
    }
  }
}

启动 Claude Code,MCP server 自动作为子进程跑起来。

环境变量

| 名 | 必填 | 默认 | 说明 | |---|---|---|---| | AGENT_BASE_URL | ✅ | — | keyan-agent admin endpoint,如 https://agent.example.com(末尾不带 /) | | AGENT_ADMIN_TOKEN | ✅ | — | admin 鉴权 token,对应 agent 端 env AGENT_ADMIN_TOKEN | | AGENT_REQUEST_TIMEOUT_MS | ❌ | 30000 | HTTP 请求超时,毫秒 |

启动时本 MCP 会先 ping ${AGENT_BASE_URL}/admin/api/healthz 验证连通,失败立即报错让你检查配置(避免 fail-late)。

给 Claude Code 装上对应 skill(强烈建议)

npm 包内含一份 SKILL.md,教 Claude 正确顺序用本 MCP 工具(先 wiki / handler 必 test-run / agent 默认 enabled 创建后立刻 disable / skill name 命名规则等)。安装到 Claude Code 全局或项目 skills 目录:

# 全局(Claude Code 所有会话生效)
mkdir -p ~/.claude/skills/keyan-agent
cp "$(npm root -g)/@dachengzhihui/keyan-agent-mcp/SKILL.md" ~/.claude/skills/keyan-agent/SKILL.md

# 或项目级(只在本项目目录里生效)
mkdir -p .claude/skills/keyan-agent
cp "$(npm explore @dachengzhihui/keyan-agent-mcp -- pwd)/SKILL.md" .claude/skills/keyan-agent/SKILL.md

装完后 Claude 看到本 MCP 工具时会自动应用该 skill 教的规范,创建 handler/agent/skill 不再需要你每次重复解释流程。

工具清单(v0.1,共 23 个)

系统了解(AI 起步先调)

• wiki_list —— 列 agent admin wiki 文章
• wiki_read(slug) —— 读完整 markdown
• tools_list_available —— 列 in-process 工具 + 外部 MCP server

Handler 编排

• handler_list / handler_get(key) / handler_list_versions(key)
• handler_create(key, code, name, description)
• handler_update(key, code, name?, description?)
• handler_enable(key) / handler_disable(key)
• handler_test_run(key, params)
• handler_create_and_test_run(key, code, name, description, test_params) —— 复合:create → test-run 一气;默认创建后 enabled=false,需显式 handler_enable

Agent 编排

• agent_list / agent_get(id)
• agent_create(...) / agent_update(id, ...)
• agent_enable(id) / agent_disable(id)

Skill 编排

• skill_list / skill_get(name) / skill_create(name, content) / skill_update(name, content)

调试

• runs_list_for_handler(handler_key, limit?)

显式不暴露(v0.1)

• 删除操作(防 AI 失手;请去 admin UI 走人审)
• schedule_* / mcp_server_* / task_*(低频运维,人配更稳)
• 完整 trace 拉取(数据量大,admin UI 看)

安全 & 鉴权

• 本 MCP server 是个 thin HTTP 客户端;没有任何秘密内置,所有凭证由你的 Claude Code config env 提供
• agent 端走 Authorization: Bearer ${AGENT_ADMIN_TOKEN},与 admin UI 的 cookie session 路径并行,两条路径互不影响
• token 等同 admin 全权(handler 可写 = 主机 RCE 等级)。仅在受信任的内部环境分发,定期轮换
• 后续 keyan-agent 会加多 token 表 + 自主创建 token + scope 限制,届时本 MCP 配的 token 可独立轮换

开发

pnpm install
pnpm typecheck
pnpm test
pnpm build          # → dist/
pnpm dev            # tsx src/index.ts(stdio,本地手动 wire 进 Claude Code 用)

License

MIT