gd-tiku-mcp-server

面向 book-structuring（智能题库）的 MCP Server（stdio）：用成员 API Key 调用只读接口，向 Agent / IDE 暴露个人信息、字典、试题文件夹、自定义标签。

• npm 包名：gd-tiku-mcp-server
• MCP 服务器名（客户端配置里的 key）：建议 tiku-info-context
• 要求：Node.js ≥ 20
• 传输：stdio（npx / 本地 node / 题库 Agent 桌面内嵌均可）

本地缓存目录：~/.tikuagent/mcp-cache/book-member/（按 API Key 分桶，结合 revision 做短 TTL 缓存）。

快速开始

1. 准备环境变量

| 变量 | 必填 | 说明 | |------|------|------| | BOOK_API_BASE | 是 | API 根，如 https://tiku.yiguodu.cn/api 或 https://tiku.yiguodu.cn（无 /api 后缀时会自动补上） | | BOOK_API_KEY | 是 | WebExt / 智能题库 个人中心 生成的成员 Key，形如 bk_live_… |

Key 鉴权走 HTTP 头 Token: <BOOK_API_KEY>。

也可在智能题库 个人中心 › Agent / MCP API Key 生成 Key 后点「复制 MCP 配置」，会带上当前环境的 BOOK_API_BASE 与 Key。

2. 用 npx 拉起（推荐第三方）

第三方客户端请使用 @latest，显式解析 npm latest dist-tag，避免本机 npx 缓存继续跑旧版：

BOOK_API_BASE=https://tiku.yiguodu.cn/api BOOK_API_KEY=bk_live_xxx \
  npx -y gd-tiku-mcp-server@latest

探测进程是否可启动（不连 API、不占 stdio JSON-RPC）：

npx -y gd-tiku-mcp-server@latest --ping
# stderr: gd-tiku-mcp-server:pong

3. 写入客户端 MCP 配置

Cursor（~/.cursor/mcp.json 或项目 .cursor/mcp.json）：

{
  "mcpServers": {
    "tiku-info-context": {
      "command": "npx",
      "args": ["-y", "gd-tiku-mcp-server@latest"],
      "env": {
        "BOOK_API_BASE": "https://tiku.yiguodu.cn/api",
        "BOOK_API_KEY": "bk_live_…"
      }
    }
  }
}

Claude Desktop（claude_desktop_config.json）同结构，键名一般为 mcpServers。

题库 Agent 桌面：在 设置 › 账号 填写 BASE + API Key 后点「启用 MCP」即可，无需本机 Node / npx（见下文「桌面安装包」）。

Tools

所有 tool 成功时返回 JSON 文本；失败时 isError: true，正文为 { "error": "…" }。

| Tool | 说明 | 入参 | |------|------|------| | get_member_profile | 当前成员画像（不含手机号）+ 课程偏好 | 无 | | get_sync_status | 字典 / 试题夹 / 自定义标签的 revision 水位 | forceRefresh?: boolean | | get_dictionary | 按 kind 拉字典列表（带磁盘 revision 缓存） | 见下表 | | list_question_folders | 智能录题试题夹列表，带完整 path | forceRefresh?: boolean | | get_custom_tag_catalog | 个人试题标签目录（type=question），tags 带 path | courseId?: number；forceRefresh?: boolean |

get_dictionary 的 kind

| kind | 额外参数 | 用途 | |------|----------|------| | stage | — | 学段 | | course | — | 课程 | | questionDifficulty | — | 试题难度 | | questionType | courseId | 系统题型 | | knowledgePoint | courseId | 知识点树 | | textbook | courseId | 教材 | | textbookVersion | courseId | 教材版本 | | catalog | textbookId | 教材目录 |

可选公共入参：forceRefresh?: boolean（绕过短 TTL / 磁盘缓存强制刷新）。

推荐调用顺序（抽题 / 绑 ID）

1. get_member_profile → 默认课、courseId 线索
2. get_dictionary({ kind: "course" }) → 对齐课程
3. 按目标课拉 questionType / questionDifficulty / knowledgePoint
4. list_question_folders → recommendedFolderId + path
5. get_custom_tag_catalog({ courseId }) → customTags[]
6. 仅在怀疑缓存陈旧时用 get_sync_status，或对各 tool 传 forceRefresh: true（勿默认每次强制刷新）

禁止在 Agent 侧根据记忆编造 folderId / customTagId / questionTypeId；MCP 不可用时应跳过 ID 绑定并说明原因。

缓存行为

• 根目录：~/.tikuagent/mcp-cache/book-member/<apiKey-hash>/
• 字典 / 文件夹 / 标签按服务端 revision 落盘；revision 探测本身有约 60s 内存 TTL
• forceRefresh: true 可跳过 TTL 并重新拉数

本地开发

本包位于 monorepo：packages/book-member-mcp（npm 名 gd-tiku-mcp-server）。

pnpm install
pnpm --filter gd-tiku-mcp-server build
pnpm --filter gd-tiku-mcp-server test
pnpm --filter gd-tiku-mcp-server typecheck

BOOK_API_BASE=http://localhost:4000/api BOOK_API_KEY=bk_live_xxx \
  node packages/book-member-mcp/dist/index.mjs

构建产物：单文件 dist/index.mjs（esbuild 内联 @modelcontextprotocol/server / zod，带 shebang，可直接作 npm bin）。

依赖 MCP TypeScript SDK v2（@modelcontextprotocol/server）。

打包发版（npm）

在仓库根目录（与桌面 pnpm release 一样走 bumpp）：

# 预检：不升版、不真正 publish
pnpm release:mcp -- --dry-run

# 交互选择升版类型后发布（需已 npm login）
pnpm release:mcp

# 指定升版类型
pnpm release:mcp -- patch
pnpm release:mcp -- minor --yes

# 不升版、用当前 version 重发
pnpm release:mcp -- --no-bump

# 2FA
pnpm release:mcp -- patch --otp=xxxxxx

流程：

1. bumpp 只改本包 package.json（commit 信息 / tag：[email protected]，先不 push）
2. typecheck → test → build → pnpm pack 核对
3. pnpm publish
4. git push --follow-tags

更多参数：pnpm release:mcp -- --help。

发版后第三方应继续用 gd-tiku-mcp-server@latest（或钉死具体版本如 @0.1.1）；桌面内嵌入口不走 npx，发版后随桌面安装包更新。

桌面安装包

题库 Agent 桌面安装包不依赖本机 Node：Settings 写入的 entry 使用

• command = Electron 可执行文件
• env.ELECTRON_RUN_AS_NODE=1
• 脚本 = Resources/book-member-mcp/index.mjs

启动时会刷新绝对路径；「测试连接」会带 --ping 探测进程。

安全说明

• API Key 仅用于本机 MCP 进程访问成员只读接口，不要提交到 git / 公开配置仓库
• get_member_profile 已做字段白名单，不回传手机号等敏感字段
• 第三方客户端配置里的 env.BOOK_API_KEY 等同于密钥，按各产品的密钥管理方式保管