使用说明

@马赫达克万/特工mcp

一个MCP（模型上下文协议）服务器，用于通过OpenAI兼容的API调用AI代理。它允许您使用自定义系统提示、模型和查询运行代理。代理预设以普通Markdown文件的形式存储在本地。会话和内存在SQLite中保持不变，因此代理可以在会话之间维护上下文。

为什么要用这个？

此服务器允许您的主要AI助手（例如Cursor中的Claude或Claude Desktop）将特定任务委托给其他专业模型。它有助于绕过单一模型聊天限制和上下文限制。例如，您可以使用Claude进行常规聊天，但要求它使用以下命令运行深度代码审计 gpt-5.3-codex 随着 xhigh 努力，或向双子座询问具体知识。

它可以与任何与OpenAI兼容的API配合使用，这意味着您可以将其连接到本地服务器（LM Studio、Ollama、vLLM、Kiro、Antigravity）或云提供商和API桥（OpenAI、Groq、Together AI、Copilot API桥）。

配置

将服务器添加到MCP客户端配置中（例如，Claude Desktop、Cursor、VS Code）：

{
  "mcpServers": {
    "agents-mcp": {
      "command": "npx",
      "args": ["-y", "@maehdakvan/agents-mcp"],
      "env": {
        "AGENT_API_BASE": "http://127.0.0.1:3030/v1",
        "AGENT_API_KEY": "optional",
        "AGENT_MODEL": "gpt-5.3-codex"
      }
    }
  }
}

环境变量

变量	默认值	描述
`AGENT_API_BASE`	`http://127.0.0.1:3030/v1`	与OpenAI兼容的API的基本URL。
`AGENT_API_KEY`	`optional`	终结点的API密钥。
`AGENT_MODEL`	`gpt-5.3-codex`	如果请求中未指定，则使用默认模型。
`AGENT_TIMEOUT_MS`	`300000`	请求超时（毫秒）。
`AGENT_ALLOW_CUSTOM_BASE_URL`	`true`	设置为 `false` 以防止呼叫者覆盖基本URL（SSRF保护）。
`AGENT_CONTEXT_WINDOW`	`128000`	上下文窗口管理的令牌预算。
`AGENT_MAX_CONCURRENT`	`10`	同时运行的API请求的最大数目。
`PRESETS_DIR`	`~/.agents-mcp/presets`	存储代理预设的目录。
`AGENT_EMBEDDING_MODEL`	`text-embedding-3-small`	语义向量记忆的嵌入模型。
`AGENT_EMBEDDING_BASE`	`https://api.openai.com/v1`	嵌入端点的基本URL（独立于 `AGENT_API_BASE`).
`AGENT_EMBEDDING_KEY`	回落到 `AGENT_API_KEY`	嵌入终结点的API密钥。
`AGENTS_MCP_DATA_DIR`	`~/.agents-mcp`	SQLite数据库的目录(`agents-mcp.db`).

工具

`run_agent`

完全内联调用任何AI代理——无需预设。提供a system_prompt 定义代理和a query 让它回答。

参数	必填	说明
`query`	✅	用户的请求/任务。
`system_prompt`	✅	定义代理身份和规则的完整系统提示。
`model`		型号名称。默认为 `AGENT_MODEL` 有人。
`base_url`		API基本URL。默认为 `AGENT_API_BASE` 有人。
`effort`		推理努力水平： `low`, `medium`, `high`, `xhigh`.
`response_format`		`"json"` 用于JSON模式，或用于结构化输出的JSON模式字符串。
`thread_id`		多回合对话的线程ID。
`context`		以前消息的JSON数组 `[{role, content}]`.

`run_preset`

调用按名称预设的已保存代理。

参数	必填	说明
`query`	✅	用户的请求/任务。
`preset`	✅	预设名称（不带文件名的文件名 `.md`).
`model`		模型覆盖。
`base_url`		API基本URL覆盖。
`effort`		推理努力优先： `low`, `medium`, `high`, `xhigh`.
`response_format`		覆盖响应格式。
`thread_id`		多回合对话的线程ID。
`context`		以前消息的JSON数组。
`vars`		模板变量的JSON对象 `{{var}}` 系统提示中的占位符。

`run_pipeline`

运行一个连续的预设链，其中每个步骤的输出都会自动作为 query 到下一个。适用于多阶段工作流程（例如，研究→ 草案→ 审查）。

参数	必填	说明
`presets`	✅	按顺序运行的预设名称的JSON数组，例如。 `["researcher", "writer", "reviewer"]`.
`query`	✅	输入到第一个预设值的初始输入。
`thread_id`		传递给链中每个步骤的共享线程ID。
`vars`		应用于链中所有预设的模板变量的JSON对象。

如果任何步骤返回一个JSON对象 { "status": "failed" }，管道立即停止并出现错误。否则，输出是一个markdown文档，其中每个步骤的结果都在 ## Step N: preset_name 标题。

`run_swarm`

使用Supervisor模式运行非线性代理群。主管预设会动态地将任务路由到工作人员预设，直到它决定目标完成(FINISH).使用 run_pipeline 对于简单的顺序链；使用 run_swarm 用于执行路径事先未知的自适应多代理工作流。

参数	必填	说明
`query`	✅	群体的初始目标或任务。
`supervisor_preset`	✅	Supervisor代理的预设名称（必须返回JSON `next_agent` 和 `task_for_agent`).
`worker_presets`	✅	工作者预设名称的JSON数组，例如。 `["researcher", "coder"]`.
`max_turns`		强制停止前的最大路线转弯数（默认值10，最大值20）。
`thread_id`		群中所有代理的共享线程ID。

主管收到当前状态和可用员工姓名，必须返回 {"next_agent": "<name or FINISH>", "task_for_agent": "..."}.何时 next_agent 是 "FINISH"，群停止并返回最终结果以及所有回合的执行日志。

`save_preset`

将代理预设保存或更新为 .md 文件。

参数	必填	说明
`name`	✅	预设名称，例如。 `"oracle"`.
`system_prompt`	✅	定义代理的完整系统提示。
`description`		简短的单行描述。
`model`		推荐型号。
`effort`		推荐推理努力： `low`, `medium`, `high`, `xhigh`.
`inputs_required`		逗号分隔的必填输入。
`inputs_optional`		逗号分隔的可选输入。
`outputs`		输出格式说明。
`response_format`		响应格式设置。
`api_base`		此预设的API基本URL。
`api_key_env`		API键的环境变量名称。
`overwrite`		设置 `true` 以覆盖现有预设。

`list_presets`

返回所有已保存的预设及其元数据的列表。

`delete_preset`

删除预设 name.

`core_memory_append`

将文本附加到线程的命名内存块。内存块持久化到SQLite，并在每次后续调用该线程时自动注入系统提示符。

参数	必填	说明
`thread_id`	✅	这些记忆所属的线索
`block_name`	✅	内存块的名称（例如。 `user_profile`, `project_context`, `scratchpad`).
`content`	✅	要附加的文本。

`core_memory_replace`

在线程的命名内存块中查找和替换文本。

参数	必填	说明
`thread_id`	✅	这些记忆所属的线索
`block_name`	✅	要编辑的内存块的名称。
`old_text`	✅	要查找的确切文本。
`new_text`	✅	替换文本。

`core_memory_read`

读取线程的所有内存块。返回一个JSON对象 { block_name: content }.

参数	必填	说明
`thread_id`	✅	要读取内存的线程。

资源

agents://presets/{name}：读取已保存预设的原始降价内容。

预设

预设以Markdown文件的形式存储在 PRESETS_DIR。它们支持元数据的YAML frontmatter。在第一次运行时，捆绑的预设会复制到此目录，而不会覆盖现有文件。

代理没有文件访问权限

通过以下方式调用的代理 run_agent 或 run_preset 是无状态LLM调用——它们只接收传入的内容 system_prompt 和 query。他们无法读取文件、浏览文件系统或调用工具。

这意味着 主叫客户 （您或负责协调呼叫的主要人工智能助理）负责收集相关上下文并将其包含在 query例如，在拨打电话之前 oracle 对于代码审计，请自己读取文件并将其内容粘贴到查询中。

重要提示： 因为模型称这些代理 description 每个预设的字段主要是为调用LLM编写的，而不是为人类编写的。它应该包含关键的说明和注释，帮助编排代理准确理解预期的上下文以及如何有效地使用预设。

自主记忆（Letta模式）

当a thread_id 代理可以自主管理自己的内存，而无需来自MCP客户端的显式调用。在内部， callAgent 运行一个ReAct循环（最多3次迭代），其中LLM有两个内部工具： core_memory_append 和 core_memory_replace如果模型决定信息值得记住，它会发出一个工具调用，服务器对SQLite执行它，循环会继续，直到模型产生最终的文本响应。客户只看到最终的答案——中间的工具转弯是不可见的。

语义向量记忆

每个有状态响应都会自动嵌入并存储在 semantic_memory SQLite表。在后续调用中，用户的查询被嵌入，并使用余弦相似度（在纯JS中计算——没有原生向量DB依赖关系）与存储的内存进行比较。前3个最相关的记忆被注入到系统提示中 <semantic_memory> 标签，使代理能够在滑动上下文窗口之外进行长期回忆。

此功能需要 AGENT_EMBEDDING_BASE 端点以支持 /embeddings 路线。如果不这样做，嵌入就会悄无声息地失败，代理会在没有语义召回的情况下继续进行。

多回合对话

代理通过以下方式支持多回合对话 thread_id 参数。当你通过一个 thread_id，服务器将完整的消息历史记录保存在SQLite中，并自动将其包含在后续调用中。最多保留64个线程（LRU驱逐）。你也可以通过a context 带有显式JSON消息数组的参数 [{role, content}] 用于手动历史记录注射。

持久核心内存

每个线程都有三个默认命名的内存块-- user_profile, project_context，以及 scratchpad --在会议期间幸存下来。每次与代理人通话时 thread_id，非空块呈现为结构化XML，并自动注入系统提示：

<core_memory>
  <user_profile>...</user_profile>
  <project_context>...</project_context>
  <scratchpad>...</scratchpad>
</core_memory>

使用 core_memory_append 和 core_memory_replace 以保持这些块的最新状态。随时用 core_memory_read。您可以在三个默认值之外创建其他命名块。

代币预算管理

服务器自动管理上下文窗口的使用情况，以保持在配置的范围内 AGENT_CONTEXT_WINDOW 限制（默认128K令牌）。预算按邮件类别分配：

类别	分配
系统提示	20%
注入上下文	20%
线程历史	50%
储备	10%

当请求超出预算时，最旧的消息将首先被修剪（新消息优先）。令牌计数通过以下方式使用BPE令牌化 js-tiktoken (o200k_base 编码）以提高准确性 ceil(chars / 4) 如果编码器不可用，则回退。

并发和重试

传出的API请求通过具有可配置并发上限的共享请求池(AGENT_MAX_CONCURRENT，默认值10）。超出限制的请求将排队。在HTTP 429（速率限制）和5xx错误上，失败的请求会自动重试最多3次，具有指数回退和50%随机抖动。

模板变量

预设系统提示可以包含 {{var}} 占位符。通话时 run_preset 或 run_pipeline，通过a vars JSON对象在运行时替换它们。不匹配的占位符保持原样。

捆绑预设

服务器附带了一些内置的预设来帮助您开始：

oracle：深度代码审计、架构规划、根本原因调试。将相关源文件和错误消息粘贴到 query.
readme-writer：重写README文件，使其听起来像真正的人类开发人员。将现有的README和简短的项目描述粘贴到 query.

前端配置

您可以通过在YAML frontmatter中定义参数来灵活配置每个预设。这些参数充当LLM客户端的执行默认值和元数据。

参数	说明
`description`	代理人的简短描述。关键的：这是由调用LLM读取的。包括关于如何/何时使用代理以及它需要什么上下文的重要说明。
`model`	用于该预设的具体模型（例如。， `gpt-4o`, `o3-mini`).覆盖 `AGENT_MODEL` 环境变量。
`effort`	推理努力水平(`low`, `medium`, `high`, `xhigh`).直接翻译为 `reasoning_effort` 对于支持它的模型（例如。， `o1`, `o3-mini`, `gpt-5.3-codex`).
`inputs_required`	逗号分隔的所需输入参数列表（例如。， `query`).作为调用LLM的文件。
`inputs_optional`	逗号分隔的可选输入参数列表（例如。， `model, effort, base_url`).
`outputs`	代理返回内容的简短描述（例如。， `JSON array of vulnerabilities`).帮助调用LLM理解预期的响应格式。
`response_format`	`"json"` 用于JSON模式，或用于结构化输出的JSON模式字符串。
`api_base`	此预设的API基本URL。覆盖 `AGENT_API_BASE`.
`api_key_env`	包含此预设的API密钥的环境变量的名称（例如。， `OPENAI_API_KEY`).

参数解析顺序： 通过调用预设时 run_preset，执行参数(model, effort)按以下优先顺序解决：

传递给的显式参数 run_preset 工具。
预设中定义的Frontmatter值 .md 文件。
环境变量默认值（例如。， AGENT_MODEL).

示例 ~/.agents-mcp/presets/code-reviewer.md:

---
description: Strict TypeScript code reviewer. NOTE: agent has no file access — paste all relevant code, configs, and error messages directly into query.
model: gpt-4o
effort: high
inputs_required: query
---
# code-reviewer

You are a strict TypeScript reviewer. Focus on type safety, edge cases, and security.

还支持传统格式（不带frontmatter），其中第一行是 # name 第二行是 > description.

发展

npm install
npm run dev     # Run with tsx
npm run build   # Compile to dist/
npm run lint    # Run ESLint

使用说明

@马赫达克万/特工mcp

为什么要用这个？

配置

环境变量

工具

run_agent

run_preset

run_pipeline

run_swarm

save_preset

list_presets

delete_preset

core_memory_append

core_memory_replace

core_memory_read

资源

预设