vibocode-mcp

vibocode-mcp

两个工具，而非 API 目录。 一个 MCP 服务，能让 Agent 保持小巧的上下文，同时拥有广泛的触达能力。

search  — finds the right endpoints and memory facts, returns compact signatures
run     — executes model-written Python in a sandbox: api.get(path) + vi.add/find/stats

整个工具集只有 217 个 token（o200k_base 分词器）。同一份 GitHub REST 目录包含 1,272 个端点，若将其作为普通 MCP 工具，则需要 79,525 个 token：相差 366 倍。Slack 的 174 个端点则相差 42 倍。测量结果和复现命令见基准测试。

安装

npx vibocode-mcp

需要 Node 18+ 和 Python 3.10+（服务端使用 Python）。

MCP 客户端配置：

{
  "mcpServers": {
    "vibocode": {
      "command": "npx",
      "args": ["-y", "vibocode-mcp"],
      "env": {
        "VIBOCODE_CATALOG": "/path/to/catalog.json",
        "VIBO_MEM_FILE": "/path/to/memory.web"
      }
    }
  }
}

操作目录

catalog.json 描述一项服务：基础 URL、允许的域名以及操作列表。

{
  "service": "example",
  "base_url": "http://127.0.0.1:4174",
  "allow_domains": ["127.0.0.1"],
  "actions": [
    {"name": "health", "method": "GET", "path": "/api/health", "auth": false,
     "desc": "Service health: storage, notification channels, server time"}
  ]
}

目录不是手工编写的：对于 OpenAPI，可以自动生成。

python3 tools/openapi_to_catalog.py openapi.json -o catalog.json \
  --base-url https://api.example.com --allow api.example.com --service example

使用示例

h = api.get("/api/health")
print(h["status"], h["data"]["storage"])
vi.add("Service health", "health ok, storage local-json")
print(vi.stats())

一次 run 调用：发送 API 请求、写入记忆并读取统计信息。如果没有记忆，它就只是一个沙箱；其价值在于，下一次会话不必重新发现已有的信息。

内部构成

bin/vibocode-mcp.js        — npm entry point (starts the Python server)
vibocode/server.py         — MCP server (JSON-RPC over stdio)
vibocode/catalog.py        — catalog search, compact signatures
vibocode/aliases.json      — query alias data (natural language -> catalog terms)
vibocode/bridge.py         — bridge: ViBo memory + allowlisted HTTP
vibocode/sandbox.py        — AST validation + isolated process with limits
vibocode/runner.py         — model code executor
tools/openapi_to_catalog.py — catalog generator from OpenAPI
tests/test_mcp.py          — 19 checks
skill/                     — packaging as an agent skill (SKILL.md + CLI)

安全性

• 导入：json, math, re, datetime, statistics, itertools
• 禁止使用：open, eval, exec, compile, __import__, getattr, setattr、双下划线属性、global/nonlocal、无限循环
• 网络：仅允许调用 api.get(path)，且只能访问 allow_domains 中的主机
• 限制：墙钟时间 40 s、内存 1.5 GB、CPU 时间 20 s、输出上限为 4,000 个字符
• 同一事实重复写入记忆时会跳过

这是 Python 层级的沙箱（AST + rlimits + 独立进程），并非 V8 隔离环境：它能防范意外和不谨慎的代码，但无法抵御蓄意的操作系统级攻击。

测试

python3 tests/test_mcp.py     # protocol, search, memory, API, limits, blocks

基准测试

分词器：o200k_base（tiktoken）。目录由官方 OpenAPI 规范生成。 “完整目录”指每个端点对应一个工具，包含名称、描述和空输入架构——这是对替代方案更为宽松的下限估算。

目录	操作数	完整目录	vibocode	比率
GitHub REST	1,272	79,525 个 token	217	366 倍
Stripe	612	38,020 个 token	217	175 倍
Slack Web API	174	9,129 个 token	217	42 倍

对于 GitHub，在用户还没说一个字之前，就会占用 200,000-token 上下文窗口的 40%。

端到端测试：一次 run 调用使用 196 个 token 的代码，向 api.github.com 发送了三个请求，将一条事实写入记忆，并读取了统计信息。整个五步交互共计 2,202 个 token。

搜索质量

搜索采用词法匹配并支持别名。aliases.json 将用户输入的词映射到目录术语，因此查询可以使用自然的表达方式，而不必使用端点术语。

随附配置（英文别名）：

目录	查询数	Top-1	Top-4
Stripe	12	83%	92%
GitHub REST	5	40%	80%

使用通过 VIBOCODE_ALIASES 加载的语言包时（共 28 个混合查询，其中一半为非英语）：Stripe 为 80% / 95%，GitHub 为 38% / 75%。

两种情况下已知的弱点相同：描述完整场景而非具体对象的查询。 下一步：混合使用 BM25 + 嵌入。

限制

• 传输协议采用按行分隔的 JSON-RPC（非 Content-Length）；足以满足 stdio 客户端的需求
• 基于会话的端点需要 cookie 或服务令牌
• 目录是静态的：新增端点需添加到 catalog.json（或从 OpenAPI 生成）
• 搜索采用词法匹配，不使用向量索引

许可证

MIT。ViBo memory 是独立产品，拥有自己的许可证。