AI导哈

代理MCP服务器

一个基于Go的MCP服务器，通过stdio/JSON-RPC暴露两个工具，支持Markdown定义的代理角色和可插拔的运行器。

  • by kevincatino
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 kevincatino/subagents-mcp

使用说明

子代理MCP服务器（Go）

在stdio/JSON-RPC上运行1.23 MCP服务器，暴露出两个由Markdown定义的角色（YAML frontmatter）和可插拔运行器（Codex、Copilot、Gemini或Cursor-CLI）支持的工具。

概述

  • 工具： list_agents 和 delegate_task 注册日期 tools/list 和 tools/call.
  • 跑步者：离开 --runner 取消设置以尝试所有可用的CLI（Codex→ 副驾驶→ 双子座→ 默认情况下为光标）。通过 --runner <name> 通过以下方式固定首选CLI，同时仍允许配置回退 --runner-config.
  • 显式模型路由：当代理声明 model，跑步者支持必须明确列出在 --runner-config未知/未映射的模型会快速失败，并出现明显的选择器错误。
  • 代理来源：绝对Markdown文件 --agents-dir；每个文件都包含用于元数据的YAML frontmatter(description，可选 model)以及身体中的角色内容（或 persona 在前台）。
  • 护栏：代理目录和委托工作目录的绝对、现有、非根路径；相对路径被拒绝。
  • 协议：MCP 2024-11-05使用服务器信息和工具功能初始化响应。

项目结构

  • cmd/subagents –入口点解析标志和连接服务器。
  • internal/agents –代理模型和Markdown frontmatter存储库加载器。
  • internal/mcp JSON-RPC处理程序、工具模式、服务器循环、MCP错误。
  • internal/runner –代理运行器接口以及Codex、Copilot、Gemini和Cursor实现。
  • internal/validate –路径验证助手（绝对、存在、非根）。
  • internal/logging –zap记录器设置。
  • examples/agents –示例代理Markdown定义。

安装和设置

建议通过Go进行（全局）安装：

make install                         # go install ./cmd/subagents
echo 'export PATH="$(go env GOPATH)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc                      # pick up the PATH change
subagents --help

这将CLI编译为 $(go env GOPATH)/bin，Go工具已经期望将其放在您的PATH中。重新运行 make install 每当你提交新的提交时。

替代方案：保留一个repo本地二进制文件，并将该目录添加到PATH中：

make build-local                     # emits ./bin/subagents
echo 'export PATH="/absolute/path/to/subagents-mcp/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
subagents --help

如果你不想碰，这很方便 $(go env GOPATH)/bin；只要确保仓库在PATH入口点的任何地方都保持不变。

前提条件：

  • 转到1.23+
  • PATH上的Codex CLI并经过身份验证（用于 --runner codex)
  • PATH上的GitHub Copilot CLI并经过身份验证（用于 --runner copilot)
  • Gemini CLI位于PATH上并经过身份验证（用于 --runner gemini)
  • PATH上的游标代理CLI并经过身份验证(curl https://cursor.com/install -fsS | bash那么 cursor-agent login 或出口 CURSOR_API_KEY)for --runner cursor

用法

运行服务器（自动选择运行程序）：

./subagents --agents-dir /abs/path/to/agents

更喜欢特定的跑步者（Copilot示例）：

./subagents --agents-dir /abs/path/to/agents --runner copilot

其他跑步者示例：

./subagents --agents-dir /abs/path/to/agents --runner gemini
./subagents --agents-dir /abs/path/to/agents --runner cursor

代理文件示例(/abs/path/to/agents/docs-fetcher.md):

---
description: "Docs excerpt fetcher"
model: "gpt-4o-mini"
---

You are a relentless documentation analyst who finds the smallest official
excerpts needed to answer the question, cites sources, and keeps summaries
short and precise.

委托合同：

  • tools/call 随着 name: "delegate_task" 和论点：
    {
  "agent": "docs-fetcher",
  "task": "summarize latest release notes",
  "working_directory": "/absolute/workspace/path"
}
    退货 {"content":[{"type":"text","text":"<final output>"}]}. 跑步者提示信封的结构如下：
    You are subagent "<name>".

Description: <description>

Persona:
<persona>

Task:
<task>
  • tools/call 随着 name: "list_agents" 回报 {"content":[{"type":"text","text":"{\"agents\":[...]}"}]} （JSON字符串 name 和 description 仅）。
  • tools/call 随着 name: "expand_prompt" （也称为 prompt_expansion)和论点：
    {
  "command": "research",
  "input": "LLM routing frameworks"
}
    退货 {"prompt":"<expanded prompt text>"} 并且该提示必须被视为用户的明确指示，应逐字遵循。

路径规则：

  • --agents-dir 和 working_directory 必须是绝对的、现有的目录，不能是 /；符号链接已解析。

建筑

简要概述生活 docs/architecture.md.

文档

  • docs/architecture.md
  • docs/api.md
  • docs/modules.md
  • docs/setup.md
  • docs/research/ （例如。， 2025-12-01-cursor-agent-cli.md, 2025-12-02-cursor-cli-models.md)
  • docs/decisions.md

技术栈

  • 转到1.23
  • zap用于结构化JSON日志
  • gopk.in/yaml.v3用于代理解析
  • Codex CLI（只读exec）、GitHub Copilot CLI（非交互式提示模式）、Gemini CLI（JSON输出模式）、Cursor代理CLI（文本模式自动化）

相关 MCP