ESQ BUILDER MCP

题库包自由 · 双轨校验 · auto_fix 修复留痕 · uvx 一行接入

esq-builder-mcp 把 ESQ 1.0 题库包工具链固化为 5 个 MCP 工具：构建（自动修复机械性坑）→ 校验（内置 vendored + 官方 CLI 双轨）→ 上传发布（503 重试），外加 kajweb 词表解析与真题热点词统计。已上架 MCP Registry。

⭐ 如果 esq-builder-mcp 对你有帮助，点个 Star 就是最大的支持

为什么

技能（SKILL.md）传的是流程知识，LLM 每次执行都可能踩坑（ASCII key、双花括号、上传路径 405……）。本 server 把这些坑固化进工具代码——调用方不会再遇到它们。

auto_fix：机械性坑自动修复

esq_build_package(auto_fix=true) 在校验前自动修复「纯机械」的坑，修复明细记录在返回值 fixes 数组（审计）：

• 含中文/非法字符的 packageId/paperKey/unitKey/questionKey → cn.xxx.y2021.u1 风格重建，answers 两级键自动同步改名

• 单花括号 {blank:N} → 双花括号 {{blank:N}}

• 缺失的 unit.sequence 补 index+1；不达标 blockKey（如 2 位的 p1）归一为 block-{index}

判断性问题（空位数≠题数、答案不在选项中）不会被静默修复，仍走「拒绝 + 可行动错误」。默认 false 保持严格行为。

双轨校验

esq_validate_package 有两条通道，返回值 validator 字段标明所用通道：

• 默认：内置校验器（esq_validator.py，vendor 自 backend/app/services/esq.py 校验子集，import 调用）——零外部依赖，PyPI/uvx/PyInstaller 分发可用；

• 对账：官方 CLI——显式传 validator_path 或设 ESQ_VALIDATOR_PATH 时走 subprocess 调官方校验器。

两条通道的一致性由 tests/test_validator_conformance.py 守护（本机有刷题机仓库时自动执行；后端校验逻辑变更后先跑它再同步 vendored 副本）。

Related MCP server: seohead

🚀 快速开始

# PyPI（任意 MCP 客户端，无需 clone）
uvx esq-builder-mcp              # stdio 模式

# Windows 单文件 exe：到 Releases 下载 esq-builder-mcp.exe，客户端 command 直指该 exe

ZCode（~/.zcode/cli/config.json → mcpServers）或其他客户端：

{
  "mcpServers": {
    "esq-builder": {
      "command": "uvx",
      "args": ["esq-builder-mcp"]
    }
  }
}

Windows 下 MCP 命令参数一律用正斜杠路径（Codex config.toml 转义坑的同款规避）。

📐 工具参数参考

以下参数表与 src/esq_builder_mcp/server.py 的实际签名逐一对应。

esq_build_package

返回 {ok, zip_path, totals, errors, fixes, warnings}。

esq_validate_package

返回 {valid, errors|totals, validator}；valid=true 且 0 errors 才可上传。

esq_upload_and_publish

返回 {ok, job_id, uploaded, published}。

esq_parse_wordlist

返回 {ok, count, bad_lines, words:[{rank, word, phonetic, translations, synonyms}]}。

esq_hot_words

返回 {ok, texts_scanned, unique_words, hot_words:[{term, count}]}。

🧪 测试

uv run pytest -v          # 111 项；含 vendored vs 官方 CLI 一致性对账（无刷题机环境自动 skip）
uv run ruff check src tests && uv run bandit -r src -q --skip B101   # lint 与安全静态扫描（CI 同款）

🌍 环境变量

🔁 与技能的关系

• 上游技能：~/.agents/skills/esq-question-bank-import/SKILL.md（流程与数据源）

• 本 server 是其「确定性环节」的工具化；AI 标注答案等 LLM 判断环节仍在技能侧。

📄 许可证、安全与隐私 (License, Security & Privacy)

• 许可证：MIT License

• 安全政策：SECURITY.md

• 隐私保护：PRIVACY.md（零遥测、100% 本地运算）

📌 更多：作者仓库矩阵（墨题刷题机 / 第二大脑 / 安全三部曲 / 孵化线）