Rotifer Protocol MCP Server

---

快速开始

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "rotifer": {
      "command": "npx",
      "args": ["@rotifer/mcp-server"]
    }
  }
}

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "rotifer": {
      "command": "npx",
      "args": ["@rotifer/mcp-server"]
    }
  }
}

Windsurf / 其他 MCP 客户端

使用相同的 npx 命令即可——任何支持 MCP stdio 传输的客户端都可以使用。

它能做什么？

在一次对话中创建并运行 Agent

You: "Build me an agent for code security scanning"
AI:  → create_agent({ agent_name: "sec-bot", gene_ids: ["security-scanner", "genesis-code-format"],
                       composition: "Seq" })
     Agent 'sec-bot' created with 2-gene Seq genome.

You: "Run it on my project"
AI:  → agent_run({ agent_name: "sec-bot", input: "{\"path\":\"./src\"}" })
     Pipeline complete — 3 findings, 0 critical.

搜索、比较并组合基因

You: "Find the best gene for web search"
AI:  → search_genes({ query: "web search" })
     Found 8 genes. Top match: genesis-web-search (F(g) = 0.87, Native)

You: "Compare it against the lite version"
AI:  → compare_genes({ gene_ids: ["...", "..."] })
     Side-by-side: success rate, latency, fitness breakdown

在 IDE 中完成基因的完整生命周期管理

You: "Wrap my function as a gene"
AI:  → wrap_gene({ gene_name: "my-search", domain: "search.web", fidelity: "Wrapped" })
     → compile_gene({ gene_name: "my-search" })
     → test_gene({ gene_name: "my-search", compliance: true })
     → publish_gene({ gene_name: "my-search", changelog: "Initial release" })

工具（31）

发现与分析

工具	描述	关键参数
search_genes	按名称、领域或描述搜索 Gene 生态系统	query、domain、fidelity、sort（relevance/newest/popular/fitness）、page、per_page
get_gene_detail	获取 Gene 的详细信息（表型、适应度、元数据）	gene_id、content_hash（任一均可标识该基因）
get_arena_rankings	获取领域的 Arena 排名，按 F(g) 适应度排序	domain、page、per_page
compare_genes	并排比较 2–5 个 Gene 的适应度	gene_ids（数组）
get_gene_stats	下载统计数据（总计、7 天、30 天、90 天）	gene_id
get_leaderboard	创建者信誉排行榜	limit
get_developer_profile	创建者的公开个人资料和信誉	username
get_gene_reputation	信誉详细分析（Arena、使用情况、稳定性）	gene_id
list_gene_versions	版本历史链及变更日志	owner、gene_name
suggest_domain	根据注册表推荐匹配的领域	description

本地工作区

工具	描述	关键参数
list_local_genes	扫描本地工作区，查找已安装的 Gene	project_root、domain、fidelity
list_local_agents	列出本地工作区中的 Agent	project_root、state

Gene 生命周期

工具	描述	关键参数
init_gene	使用初始文件初始化一个新的 Gene 项目	gene_name、fidelity、domain、no_genesis
scan_genes	扫描候选函数或 SKILL.md 文件	path、skills、skills_path
wrap_gene	将函数/技能封装为 Gene	gene_name、domain、fidelity、from_skill、from_clawhub
test_gene	测试 Gene（模式验证 + 沙箱）	gene_name、verbose、compliance
compile_gene	将 Gene 编译为 WASM IR	gene_name、check、wasm_path、lang
doctor	检查本地 TypeScript→WASM 工具链（esbuild / javy）并报告缺失项——只读；在 compile_gene 失败时使用	project_root
run_gene	执行本地 Gene	gene_name、input、verbose、no_sandbox、trust_unsigned
publish_gene	发布到 Rotifer Cloud	gene_name、all、description、changelog、skip_arena、skip_security
install_gene	从 Cloud Registry 安装 Gene。force 会为被替换的副本创建快照	gene_id、project_root、force
rollback_gene	撤销本地 Gene 的上一次覆盖；不指定名称调用时，会列出可撤销的内容	gene_name、project_root
vg_scan	V(g) 安全扫描——对 Gene/Skill 代码进行静态安全分析	path、gene_id、all、project_root
arena_submit	在沙箱中测量本地 Gene，并将测量结果提交到 Arena。分数由运行 Gene 得出，绝不由调用方提供	gene_name、project_root

Agent 组合

工具	描述	关键参数
create_agent	创建由多个 Gene 组合而成的 Agent	agent_name、gene_ids、composition（Seq/Par/Cond/Try/TryPool）、domain、top、strategy、par_merge
agent_run	按名称运行本地 Agent	agent_name、input、verbose、no_sandbox

身份验证与分析

工具	描述	关键参数
auth_status	检查登录状态	—
login	OAuth 登录（GitHub/GitLab）	provider、endpoint
logout	清除凭据	—
get_mcp_stats	MCP 调用分析	days
get_my_reputation	当前用户的声誉	—

资源（7 个）

MCP 资源允许 AI 客户端将 Rotifer 数据作为上下文引用：

URI 模板	描述
rotifer://genes/{gene_id}/stats	Gene 下载统计数据
rotifer://genes/{gene_id}	Gene 详情 + 表型
rotifer://developers/{username}	创建者资料 + 声誉
rotifer://leaderboard	按声誉分数排名的顶尖创建者
rotifer://local/genes	本地 Gene 清单
rotifer://local/agents	本地 Agent 注册表
rotifer://version	MCP 服务版本及更新可用情况

每项资源返回的内容与对应同类工作的工具相同，因此声明的工具 集合同时涵盖两者：使用 --tools=evolve 时，rotifer://genes/{gene_id}/stats、 rotifer://developers/{username} 和 rotifer://leaderboard 会从列表中消失， 直接读取时也会被拒绝，因为调用方未请求 get_gene_stats、 get_developer_profile 和 get_leaderboard。 rotifer://version 始终会响应——它描述的是服务自身，而非一项 能力。在 0.16.0 之前，无论工具集如何设置，都可以访问这些资源。

提示词（4）

MCP 提示词为 AI 客户端提供常见任务的引导式工作流：

提示词	描述	关键参数
rotifer-hello	交互式创建 Agent——选择模板并立即运行	template、input
rotifer-guide	了解 Rotifer Protocol——基因、Agent、Arena、保真度模型	—
rotifer-architect	设计 Agent——根据任务搜索基因并规划组合	task
rotifer-challenge	Arena 评估——提交基因并与竞争者比较	gene

试着向 AI 提问：“使用 rotifer-hello 提示词帮我构建一个 Agent”，或 “使用 rotifer-architect 设计一个用于文档问答的 Agent”。

---

架构

┌─────────────────────────────────────────────────┐
│  AI IDE (Cursor / Claude / Windsurf)            │
│                                                 │
│  "Find genes for code formatting"               │
│       │                                         │
│       ▼                                         │
│  ┌─────────────────────┐                        │
│  │  MCP Client         │                        │
│  │  (stdio transport)  │                        │
│  └────────┬────────────┘                        │
└───────────┼─────────────────────────────────────┘
            │ MCP Protocol
            ▼
┌─────────────────────────────────────────────────┐
│  @rotifer/mcp-server                            │
│                                                 │
│  31 Tools  7 Resources  4 Prompts  Local Scanner│
│  ┌──────────┐  ┌───────────┐   ┌────────────┐  │
│  │ discover │  │rotifer:// │   │ ./genes/    │  │
│  │ lifecycle│  │genes/stats│   │ phenotype   │  │
│  │ agents   │  │developers │   │ agents      │  │
│  │ auth     │  │leaderboard│   └────────────┘  │
│  └────┬─────┘  └─────┬─────┘         │         │
└───────┼──────────────┼────────────────┼─────────┘
        │              │                │
        ▼              ▼                ▼
┌─────────────────────────────────────────────────┐
│  Rotifer Cloud API          Local File System   │
│  (Supabase)                 (genes/, .rotifer/) │
└─────────────────────────────────────────────────┘

配置

默认无需配置——连接到公共 Rotifer Cloud API。

若要使用自定义端点，请创建 ~/.rotifer/cloud.json：

{
  "endpoint": "https://your-supabase-instance.supabase.co",
  "anonKey": "your-anon-key"
}

或者设置环境变量：

ROTIFER_CLOUD_ENDPOINT=https://your-instance.supabase.co
ROTIFER_CLOUD_ANON_KEY=your-anon-key

选择要公开的工具

默认情况下，所有三十一个工具均可用。ROTIFER_MCP_TOOLS 可将范围缩小到特定集成实际需要的工具——当服务连接到不应代表你发布内容或登录的助手时，这很有用：

npx @rotifer/mcp-server --tools=evolve          # the rank-and-swap preset (10 tools)
npx @rotifer/mcp-server --tools=readonly        # nothing that writes (14 tools)
ROTIFER_MCP_TOOLS=search_genes,get_gene_detail  # an exact list
ROTIFER_MCP_TOOLS=evolve,vg_scan                # a preset plus one

既不是预设名称、也不是此处所列工具名称的名称会被忽略，并在 stderr 中显示提示。如果没有任何名称匹配，服务将不会启动：它会列出预设项并以代码 2 退出，而不是在没有任何工具的情况下运行。

标志和变量的作用相同；如果两者都已设置，则以标志为准。两者并存是因为调用方能够访问的设置方式不同：Shell 用户可以设置变量，而通过清单启动此服务的程序只能控制命令行。

声明的集合涵盖整个功能范围，而不仅仅是 tools/list。集合之外的工具在按名称调用时会被拒绝；与被排除工具重复的资源会从列表中移除，读取时也会被拒绝；除非另行声明，下面的沙箱逃逸选项也会保持关闭。若某项限制仍有未列出的绕过方式，那就不是真正的限制。

集合之外的工具不会出现在 listTools 中，即使被调用也会遭到拒绝。拒绝信息会说明如何重新添加该工具，并在适用时提供执行相同操作的 rotifer CLI 命令——因此，缩小后的集合是一道可见且可有意跨越的边界，而不是死胡同。

不设置此项则一切保持不变。

关闭沙箱

agent_run 和 run_gene 接受 no_sandbox，而 run_gene 还接受 trust_unsigned——这些选项会让 Gene 代码以纯 Node.js 方式运行，而非在 WASM 沙箱内运行。如果缩小工具集后，其中的工具仍可执行此操作，那么限制工具集就意义不大；因此，除非在启动时声明，否则这些选项都会被拒绝：

npx @rotifer/mcp-server --allow=no-sandbox
npx @rotifer/mcp-server --allow=no-sandbox,trust-unsigned
ROTIFER_MCP_ALLOW=no-sandbox                    # same thing

不会移除任何内容。变化只是从“任何调用方都可以设置”变成“必须有人在启动时声明”，你始终可以自行执行：

rotifer agent run <name> --no-sandbox
rotifer run <gene> --trust-unsigned

变化在于，助手不能再自行决定关闭沙箱。传入 no_sandbox: false 表示请求安全行为，绝不会遭到拒绝。

撤销安装

过去，install_gene 搭配 force 会覆盖 Gene，且无法恢复。现在，它会先将旧副本移至 <genes>/.snapshots/，然后由 rollback_gene 将其还原：

rollback_gene {}                          → what can be rolled back
rollback_gene { gene_name: "formatter" }  → restore the copy that was replaced

每个 Gene 只保留一个快照：下次覆盖该 Gene 时会取代现有快照，而回滚操作会消耗该快照。这会撤销最近一次升级，而非保留历史记录——list_gene_versions 已可查询上游存在哪些版本。

保持服务为最新版本

服务一直会在落后于最新版本时提醒你——启动时在 stderr 中显示一行提示，每天一次。self-update 则是另一半：

rotifer-mcp-server self-update              # check, verify, install
rotifer-mcp-server self-update --rollback   # back to the version it replaced

它会拒绝安装任何没有 provenance attestation 的 npm 版本——此软件包通过 CI 使用 --provenance 发布，因此没有认证的构建并非本项目发布的版本。

有两点值得注意：

• 正在运行的服务会继续提供旧代码。 安装会替换磁盘上的文件，但不会替换编辑器当前正在与之通信的进程。之后请重启 MCP 主机。
• 如果你通过 npx 启动，就无需更新。 未指定版本的 npx @rotifer/mcp-server 每次运行时都会重新解析最新发布的版本，因此 self-update 会说明这一点并停止，而不会安装一个会造成遮蔽的全局副本。

这是一条由你运行的命令，不是模型可以调用的工具。更新意味着全局安装，而工具甚至无法如实报告结果——模型会说“已更新”，但实际提供服务的仍是旧进程。

通过 HTTP 提供服务

通常，服务通过 stdio 与启动它的 MCP 主机通信。若要改为通过 Streamable HTTP 对外提供服务：

rotifer-mcp-server serve                      # http://127.0.0.1:3000/mcp
rotifer-mcp-server serve --port 8080
rotifer-mcp-server serve --host 0.0.0.0       # reachable from other machines

• 除非传入 --host，否则它会监听 127.0.0.1。 HTTP 端点没有身份验证，其工具会以你已登录的 Rotifer 账户执行操作，因此默认无法从其他机器访问。如果传入非环回地址作为 --host，服务启动时会在 stderr 中说明。早期版本会监听所有网络接口。
• 请求正文上限为 256 KiB。 更大的请求会在解析前返回带有 JSON-RPC 错误的 413。MCP 消息远小于此限制；设置上限是因为 SDK 的默认值（4 MiB）正是 GHSA-46jr-4wx8-v453 所述漏洞的限制，在该漏洞中，单个请求就能耗尽服务的内存。
• GET /health 会返回 {"status":"ok","transport":"streamable-http"}，用于存活检查。

使用情况报告

已登录时，每次工具调用都会向 Rotifer Cloud 报告一条使用记录：工具名称、其操作的 Gene id、是否成功、耗时以及你的用户 id。get_mcp_stats 读取的就是这些记录。运行 Gene 也会记录该次调用，协议的防操纵指标依赖这一记录。

不会发送你传入的参数、任何文件的内容、你的环境变量或本地配置。

未登录时，不会发送使用记录。 无论是否登录，都会发送一项请求：安装 Gene 时会递增该 Gene 的公开安装计数器。请求只包含 Gene id，不包含其他内容——没有用户 id、会话或参数——Arena 正是通过它统计安装次数的。直到 0.15.1 版本，这项请求都无法关闭；而本节曾写着“未登录时不会报告任何信息”，对于安装操作来说并不属实。

现在，ROTIFER_TELEMETRY=0 可以停止这三项：

ROTIFER_TELEMETRY=0    # also accepts false / off

这三项是 src/cloud.ts 中的 logMcpCall、logGeneInvocation，以及 installGene 内的 track_download 调用——代码很短，可以从头到尾读完。除此之外，这里没有任何内容会自行报告信息：此服务中的其他出站调用都是你调用的工具在执行任务——查询、发布、登录——此外还有 WASM 构件下载，以及每天一次的 npm 版本检查。

要求

• Node.js >= 20

与 CLI 配合使用

此 MCP 服务与 Rotifer CLI 配合使用效果最佳。CLI 提供本地运行时（WASM 沙箱、Arena 引擎、IR 编译器），而 MCP 服务则将这些功能提供给你的 AI 助手：

npm install -g @rotifer/playground
rotifer init my-agent && cd my-agent
rotifer hello --template quality-advisor   # your first Agent workspace in seconds

链接

• Rotifer Protocol — 官网
• MCP 设置指南 — 分步设置
• Gene Marketplace — 浏览和发现 Genes
• CLI Playground — 在本地构建和测试 Genes
• 协议规范 — 正式规范

许可证

Apache-2.0