Vocabit

vocabit-mcp

适用于 Vocabit（一款抽认卡应用）的 MCP 服务。 它可以让 AI 助手将一组学习卡片写入手机上的真实应用，然后读取学习者的实际学习情况。

大多数 MCP 服务从 API 读取数据，而这个服务能闭合反馈循环：

flowchart LR
    A["Assistant<br/>teaches a topic"] --> B["create_study_set"]
    B --> C["Set appears in the<br/>Vocabit app"]
    C --> D["Learner works<br/>through it"]
    D --> E["get_set_results"]
    E -->|weak cards| A

有意思的工具不是 create_study_set——生成抽认卡谁都能做到。 真正有意思的是 get_set_results：学习者将哪些卡片标记为难、哪些卡片从未学过，以及每张卡片复习了多少次。下一组学习卡片会据此生成，而不是凭猜测。

30 秒快速体验

无需后端、账号或 API 密钥：

npx -y vocabit-mcp --demo

演示模式会使用带有两组预置学习卡片的内存版 Vocabit，运行同一个服务。 创建一组学习卡片并请求查看结果后，一个确定性的模拟学习者会完成学习；响应中会标明结果是模拟的，因此绝不会被误认为是真实数据。

使用 UI 试用：

npx @modelcontextprotocol/inspector npx -y vocabit-mcp --demo

安装

已列入 MCP Registry，名称为 io.github.JohnBilousov/vocabit-mcp，因此能够读取该注册表的客户端可以自行找到它。

claude mcp add vocabit -- npx -y vocabit-mcp

{
  "mcpServers": {
    "vocabit": {
      "command": "npx",
      "args": ["-y", "vocabit-mcp"],
      "env": {
        "VOCABIT_BASE_URL": "https://your-vocabit-backend.example.com",
        "VOCABIT_AGENT_KEY": "your-agent-key"
      }
    }
  }
}

工具

此外还提供 vocabit://set/{setId} 资源（以 JSON 格式表示一组学习卡片，可供列出），以及引导完成整个循环的 study-session 提示词。

卡片状态

进度由应用的间隔重复引擎生成，而非由助手生成：

当不再有状态为 new 的卡片时，学习卡片组会报告 completed: true。

实时模式

将服务指向已启用 Agent API 的 Vocabit 后端：

export VOCABIT_BASE_URL=https://your-vocabit-backend.example.com
export VOCABIT_AGENT_KEY=...   # must match one of AGENT_API_KEYS on the backend
npx -y vocabit-mcp

不设置 URL 和密钥时，服务会以演示模式启动。只设置其中一个时，服务会拒绝启动——配置不完整是错误，而不是提示。

设计说明

演示模式是一等客户端，而不是占位实现。 HttpVocabitClient 和 DemoVocabitClient 实现相同的 VocabitClient 接口，因此没有任何工具需要判断“我们是不是在模拟？”。审查者可以在尚未获得凭据时运行服务，而测试套件会通过真实的 MCP 传输测试实际工具，而不是模拟 SDK。

错误可恢复，而非致命。 调用失败时会返回 isError，其中包含后端自己的消息以及面向模型的提示——404 会提示“调用 list_study_sets 查看有哪些学习集”，401 会提示“或者使用 VOCABIT_DEMO=1 运行”。 对于互斥参数，系统会说明原因并拒绝调用，而不是自行猜测。

输出架构在边缘处保持宽松。 标识字段为必填；其他字段均为可选，因此后端新增字段不会导致原本可用的工具出现验证错误。

注释如实反映行为。 delete_study_set 标记为 destructiveHint，读取工具标记为 readOnlyHint。notify_learner 会向真人发送消息，其说明也提示应谨慎使用。

开发

git clone https://github.com/JohnBilousov/vocabit-mcp && cd vocabit-mcp
npm install
npm run build
npm test          # tool surface + full loop, plus the HTTP client against a mocked fetch
npm run lint      # eslint
npm run format    # prettier --write
npm run inspect   # demo mode in the MCP Inspector

CI 会在每次推送和拉取请求时运行 typecheck、lint、format:check、test 和 build。

src/
  index.ts        CLI entry, stdio transport
  config.ts       env → Config, demo-mode resolution
  server.ts       tool / resource / prompt registration
  schemas.ts      zod input and output shapes
  format.ts       human-readable summaries next to structuredContent
  client/
    types.ts      wire types + VocabitClient contract
    http.ts       live backend
    mock.ts       in-memory backend for demo mode
test/
  server.test.ts       tool surface + full loop — over an in-memory MCP transport
  client/
    http.test.ts       query encoding, error-body parsing, timeouts — against a mocked fetch

发布

发布使用 npm 的可信发布（OIDC）—— 无需 NPM_TOKEN 密钥，也没有可能泄露或过期的内容。只需在 npmjs.com 上进行一次性设置：在软件包的设置 → 可信发布 → GitHub Actions下，填写组织 JohnBilousov、此仓库以及工作流文件名 publish.yml。

要发布新版本：同时更新 package.json、server.json 和 src/server.ts 中的 VERSION（测试会确保它们保持一致），然后提交、推送，再发布带有对应 vX.Y.Z 标签的 GitHub Release。这会触发 .github/workflows/publish.yml，运行测试套件并将软件包发布到 npm，同时附带来源证明—— 软件包页面会显示一个经过验证的链接，指向此确切提交和工作流运行记录，而不只是注册表中的名称。

路线图

• 除 stdio 外，支持 Streamable HTTP 传输
• 支持多位学习者，无需后端默认 UID
• 音频发音卡片

许可证

MIT © Ivan Bilousov