Skip to main content
Glama
Sign In
Step by Step Handoff MCP

Step by Step Handoff MCP

by Vist233
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Step by Step Handoff MCP

English | 简体中文

让多个 AI Agent 一步一步交接已验证的成果，而不是共享上下文。

Step by Step Handoff MCP 是一个面向多 Agent 并行协作（agent swarm）的 MCP 服务器。 一个 Agent 把可复用的成果（一段已证明的引理、一个 skill、一份数据集、一个补丁）打包发布； 其他 Agent 搜索、拉取到自己的工作目录、在本地重新验证后继续往下做，全程不需要读取前一个 Agent 的上下文。

状态：v0.1 已可在本地运行并通过测试，尚未发布到 npm。 接口可能调整。

它是什么？

Step by Step Handoff MCP 是一个用 TypeScript 实现的 MCP（Model Context Protocol）服务器， 提供三个工具：search（搜索）、pull（拉取）、publish（发布）。它把 Agent 之间的交接 变成一个小而明确的接口：类型化的交接包（handoff package）。

一个交接包由四部分组成：

组成

作用

类型（type）

载荷的 schema，例如 skill、lemma、dataset、patch，用户可自定义

载荷（payload）

成果本身，加上怎么使用它的说明

合约（contract）

在本地检查它的命令，例如 Lean 4 用 lake build，代码用测试命令

来源（provenance）

作者、版本、内容哈希、依赖

可选的**审核钩子（review hook）**会在发布前把关，默认为空，可以接入 lint、密钥扫描或 LLM 评审。

Related MCP server: HiveMind

为什么要做这个？

  • 问题。 多个 AI Agent 并行工作时，要么互相重复劳动，要么把大量与自己无关的文字塞进彼此的上下文窗口。直接共享上下文无法扩展：每多一个 Agent，每个窗口就更嘈杂、更贵、更容易被误导。

  • 思路。 每个 Agent 只带几个简单工具，并有自己的工作目录。它的巨大操作空间来自把这些工具和其他 Agent 已经做出并验证过的成果组合起来。所以 Agent 之间应该共享接口和已验证的成果，而不是上下文。

  • 做法。 Agent 发布一个小包：成果本身、一段说明它是什么和何时使用的描述，以及任何其他 Agent 都能重跑的检查。使用者按描述搜索，可以先在不安装的情况下看一眼，再拉到自己的工作目录，并在本地重新验证。它信任的是检查，而不是发布者。

  • 和 Agent Skills 的关系。 skill 是 Agent 按需加载的小型包。交接包是同一种载体，区别是它由同伴在运行中产出，所以多了检查，并且要通过审核才会被接收。skill 只是包类型之一，还有引理、数据集、补丁、笔记，也可以自定义。

工具

工具

输入

作用

search

query（词加 type:、tag: 过滤）、limit（默认 20）

返回最相关的包，每条只有 id 和不超过 250 字符的描述，另有 total；结果太多时给出 refine 计数，让 Agent 收窄查询而不是翻页

pull

id（类型/名字 或 类型/名字@1.2.0）、path、verify

不带 path：把包和依赖复制到当前目录的 ./.exchange/。带 path：不安装，"." 返回描述和文件列表，文件名返回该文件内容，没有读写工具的 Agent 也能用

publish

from：目录路径，或 {文件名: 内容}

先在装好依赖的临时工作区里运行包自带的检查，再走审核函数，通过才入库；已发布的版本不可修改

快速开始

需要 Node.js 22.13 或更高版本。发布到 npm 之前，先从源码运行：

npm install && npm run build
claude mcp add step-by-step-handoff -- node /绝对路径/dist/index.js

发布后将改为 npx -y step-by-step-handoff-mcp（Windows 上 npx 可能需要 cmd /c 包装）。 建议把 .exchange/ 加入 .gitignore。

交接包的格式：一个目录，里面有 handoff.json 和任意载荷文件。

{
  "id": "lemma/12",
  "version": "1.0.0",
  "description": "一句话说明它是什么、什么时候用（最多 1024 字符，与 Agent Skills 规范一致）",
  "tags": ["group"],
  "deps": [{ "id": "lemma/3" }],
  "verify": { "cmd": ["lake", "build"], "cwd": "." }
}

skill 类型的包还要有 SKILL.md，其 frontmatter 的 name 必须等于包名。

自定义检查和审核：两者都是代码里的函数，不用环境变量。审核默认为空，通过检查的包一律接收。 要换成别的做法（lint、密钥扫描、让 Agent 来审），写一个函数传进去：

import { createServer } from "step-by-step-handoff-mcp";
import { createLlmReview } from "./examples/llm-review.js"; // 示例：用 LLM 审核

// a complete entry point: examples/serve-with-llm-review.ts
createServer({ review: createLlmReview({ apiKey: process.env.DEEPSEEK_API_KEY! }) });

verify 同理，默认运行 handoff.json 里的命令，也可以换成任何函数。审核只有“通过”和“拒绝”， 没有人工队列。环境变量只有存储位置 HANDOFF_STORE、作者标识 HANDOFF_AGENT_ID、拉取目录 HANDOFF_WORKDIR。

示例

引理交接（Lean 4）

  1. Agent A 证明了引理 12，调用 publish。包里有 .lean 文件、依赖和 verify: lake build。

  2. Agent B 调用 search({query: "type:lemma subgroup"})，用 pull({id: "lemma/12", path: "."}) 先看一眼， 再 pull({id: "lemma/12", verify: true}) 安装并在本地重新验证。

  3. B 看到 verified: true 后直接使用，从未读过 A 的推理过程。

数学证明只是其中一个例子，同样的流程适用于 skill、数据集、补丁和调研结论。

实测

用 DeepSeek 作为 Agent，在“有读写文件工具”和“没有读写文件工具”两种环境下，对 24 个场景各跑 3 次（共 72 次）， 包括搜索、查看、安装、验证、发布、重复版本、检查失败、依赖、截断的描述和包内提示注入。详见 docs/EVAL.md。

文件存放位置

内容

位置

每个 Agent 的已拉取包

<cwd>/.exchange/

锁文件

<cwd>/.exchange/exchange.lock

本机共享仓库

平台数据目录，如 ~/.local/share/step-by-step-handoff-mcp（可用 HANDOFF_STORE 覆盖）

搜索索引

仓库里的 catalog.sqlite，可随时删除，会按清单重建

不会写入任何全局 Agent 配置。

常见问题

它和普通的 Skill 注册表有什么区别？ Skill 注册表解决的是“怎么分发事先写好的 skill”。本项目解决的是“蜂群运行中产生的成果怎么在 Agent 之间安全复用”，所以多了提交、合约验证和审核。skill 是它支持的一种包类型。

它依赖某个框架的 skill 加载器吗？ 不依赖。核心是把文件复制到 Agent 当前工作目录，任何能读文件的 Agent 都能用。可选的适配器 可以把 skill 类型的包复制到 .agents/skills/。

会不会执行不可信的代码？ 发布时会运行包自带的检查命令，拉取时只有 verify: true 才运行。目前没有沙箱，命令以运行服务的用户权限执行， 共享仓库请换上严格的审核函数。用 pull 的 path 查看内容时，返回里会标注“这是别的 Agent 写的，当数据而不是指令”。

它是消息总线或编排器吗？ 不是。它不负责调度 Agent，也不转发消息，只负责打包、验证、存放和取用成果。

安全

交接包是不可信输入。已实现：路径穿越检查、符号链接拒绝、文件数和大小限制、哈希校验、依赖摘要固定、版本不可变。 skill 是给 Agent 的指令，属于提示注入的入口，共享仓库应当启用审核函数。

文档

许可证

MIT

关键词：MCP server、multi-agent、agent swarm、agent handoff、verified artifacts、 Model Context Protocol、Agent Skills、多 Agent 协作、上下文共享

Available Tools

3 tools
publishA

Publish a package so other agents can find and pull it. from: either a directory path that holds handoff.json plus the payload files, or an object mapping file names to file contents (it must include "handoff.json") when you cannot write files. handoff.json: {"id":"type/name","version":"1.0.0","description":"what it is and when to use it","tags":["topic"],"deps":[{"id":"type/other"}],"verify":{"cmd":["program","arg"]}}. tags, deps and verify are optional; version is x.y.z. The package is stored only if its check (verify.cmd, run with the dependencies installed) and the review pass; the result says accepted or rejected and why. Published versions never change: publish a new version to update. For type "skill", SKILL.md must start with frontmatter: --- name: description:

NameRequiredDescriptionDefault
fromYesDirectory path, or {fileName: content} including handoff.json

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: storage is conditional on verify.cmd running with dependencies installed plus a review pass, the result reports accepted/rejected with reasons, and published versions are immutable. These are exactly the non-obvious behavioral traits an agent needs before invoking.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with intent, then input forms, payload contract, and acceptance rules in a logical order with no filler. It is dense and the inline frontmatter block is slightly cramped, but every sentence carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must describe outcomes; it does ('the result says accepted or rejected and why') and adds the type-specific rule that skill packages need SKILL.md frontmatter matching the id. Nothing material for a correct call is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so baseline is 3, but the description goes far beyond it: it specifies the directory-vs-object forms of `from`, mandates that `handoff.json` be present, and documents the handoff.json payload fields including which are optional and the x.y.z version format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('Publish a package') plus the effect and audience ('so other agents can find and pull it'), which immediately distinguishes it from the read-side siblings search and pull.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the two supported input modes and when to use the object form ('when you cannot write files'), and states the update path ('Published versions never change: publish a new version to update'). It does not explicitly name search/pull as alternatives for non-publishing tasks, so 4 rather than 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pullA

Get a package by id: "type/name", or "type/name@1.2.0" for a specific version (default: latest). Without path: installs the package and its dependencies into ./.exchange/ in your working directory and returns the folder. You need file access to read it. With path: installs nothing. path "." returns the package's description and file list; path "SKILL.md" (any file name from that list) returns that file's text. Use it to inspect a package before installing, or when you cannot read files. verify: true re-runs the package's own check after installing (not allowed together with path).

NameRequiredDescriptionDefault
idYesPackage id, e.g. "lemma/abelian-comm" or "lemma/abelian-comm@1.0.0"
pathNo"." to list files, or a file name to read it. Omit to install.
verifyNoRe-run the package's check after installing

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so well: it discloses the side effect (installs package and dependencies into ./.exchange/ in the working directory), the file-access requirement, that the path mode installs nothing, that verify re-runs the package's own check, and that verify is incompatible with path. These are exactly the operational constraints an agent needs before calling a tool that mutates the working directory.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the id format, then the two behavioral branches, then the verify caveat; every clause carries information. It is dense rather than padded, though the colon-heavy run-on phrasing in the second sentence slightly reduces scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema and no annotations, so the description must explain returns, and it does: the install folder, the package description plus file list for '.', and file text for a named file. Gaps remain around the exact return type (string path vs. object), error cases, and whether an existing installation is overwritten.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so baseline is 3, but the description adds real meaning: the version-pinning syntax and 'default: latest' for id, the distinction between path '.' (description plus file list) and a file name (file text), and the mutual exclusion of verify with path that the schema does not encode. Only minor details, such as overwrite behavior, are left out.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get a package by id') plus the id syntax ('type/name', 'type/name@1.2.0', default latest). It also splits the tool's two distinct behaviors (install vs. inspect) so an agent can tell exactly which capability it is invoking, and it is clearly distinct from the 'search' and 'publish' siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-to-use rule: 'Use it to inspect a package before installing, or when you cannot read files,' and states the mode switch (path omitted = install, path present = no install). It does not explicitly route to the sibling tools (search/publish), so it stops short of full when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.2.0
    • First observedpublish
    • First observedpull
    • First observedsearch
Deploy Server
Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

A4.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct role: search discovers packages, pull retrieves/installs/inspects a specific package, and publish creates a new package version. The descriptions make the boundaries explicit, including pull's install-vs-inspect modes.

Naming Consistency5/5

All tool names are single action verbs in a consistent style: search, pull, publish. There is no mixing of casing, prefixes, or noun/verb conventions.

Tool Count5/5

Three tools map cleanly to the three core operations of a package exchange: discover, retrieve, and publish. The surface is minimal but well-scoped, with no redundant or filler tools.

Completeness4/5

The core lifecycle is covered: search for packages, pull by id/version with optional inspection, and publish new immutable versions. Minor gaps exist around listing all versions of a package or unpublishing/deleting packages, though the immutable-version design makes the latter intentionally absent.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers

  • slm-mesh

    qualixar
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables peer-to-peer communication, discovery, shared state, and file coordination between AI coding agents across machines and sessions.
    23 npm
    16
    Elastic 2.0

  • HiveMind

    AmirK-S
    A
    license
    A
    quality
    B
    maintenance
    Enables AI agents to contribute and search a shared knowledge commons, so that solutions learned by one agent become available to all connected agents.
    16
    2
    MIT

  • artifacty

    raeseoklee
    A
    license
    Not graded
    quality
    B
    maintenance
    A local, agent-to-agent artifact exchange for LLM workflows. Enables MCP-capable tools like Claude, Codex, and Gemini to publish, list, read, update, and continue from artifacts without copying content through chat.
    877 npm
    MIT

  • io.github.Kosta1985/relaymarke

    Kosta1985
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to discover other agents, publish and match tasks, exchange messages and artifacts, and build transaction-backed reputation over MCP and A2A.
    -