Technical Answer Validator

技术答案验证器

一款小巧、确定性的 AI Agent 答案审查工具，可通过 MCP stdio 和 REST API 使用。每次评估时，调用方都会提供概念、可接受的同义词、数值要求和答案文本。它不包含题库或答案语料库。

这是一款辅助练习工具，并非官方认证考试评分器。关键词匹配可能会漏掉语义正确的改述，也可能接受具有误导性的表面匹配。用户应审查所提供的评分标准和每项结果。

在本地运行

Python 3.10+；REST 服务使用标准库。MCP 适配器使用官方 Python SDK 2.2.0。

$env:TAV_API_KEY = "replace-with-a-long-random-secret-at-least-24-characters"
python -m tav_api

服务默认监听 127.0.0.1:8080。如需更改，请设置 TAV_HOST 和 TAV_PORT。本地单密钥模式要求 TAV_API_KEY 至少包含 24 个字符，否则拒绝启动。部署时，请使用 python scripts/create_api_key.py CLIENT_ID 为每个调用方创建独立密钥，并将 TAV_API_KEYS 配置为一个 JSON 对象，将每个客户端 ID 映射到生成的 SHA-256 摘要。将一次性原始密钥交给对应客户端保管；不要将其存储在此仓库中或提交到仓库。当设置了 TAV_API_KEYS 时，它优先于 TAV_API_KEY。

面向 AI Agent 的 MCP

在虚拟环境中，使用已提交的锁定文件安装固定版本的 MCP SDK 2.2.0：

uv sync --locked
.\.venv\Scripts\Activate.ps1

stdio MCP 服务提供一个工具：evaluate_answer(rubric, answer)。配置 MCP 主机时，填写环境中 Python 和 mcp_server.py 的绝对路径。Claude Desktop 配置示例（请替换路径）：

{
  "mcpServers": {
    "technical-answer-validator": {
      "command": "C:\\path\\to\\technical-answer-validator\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\technical-answer-validator\\mcp_server.py"]
    }
  }
}

发布到 PyPI 后，使用 uvx --from technical-answer-validator tav-mcp 运行。本地开发时，请使用 .venv 中的 Python 和 mcp_server.py。对于 Codex CLI 或其他 MCP 主机，请使用其 stdio 服务配置，并填写该命令和脚本路径。重启主机，然后让它列出工具并调用 evaluate_answer。stdio 传输在用户的 Agent 主机本地运行，无需互联网端点或 API 密钥。

Codex TOML 模板为 codex-mcp-config.example.toml；Claude Desktop JSON 模板为 claude-mcp-config.example.json。请将这两个模板中的占位路径替换为绝对路径。将代码块合并到主机配置中；不要覆盖其他 MCP 服务或全局设置。

本地 MCP 使用次数统计

MCP 服务会在本地按日汇总工具调用、成功评估、无效请求和内部错误的次数。它绝不存储评分标准或答案文本，也不会向网络发送任何内容。统计数据会在 ~/.technical-answer-validator/usage.sqlite3 中保留 90 天（Windows：用户的主目录）。运行 tav-mcp-stats 可输出 JSON 报告。在 MCP 服务环境中设置 TAV_ANALYTICS=off 可禁用计数；设置 TAV_ANALYTICS_DB 可选择其他本地数据库路径。除非用户自愿分享报告，否则这些统计数据只会保留在用户的计算机上。

如要自愿向维护者分享匿名使用次数统计，请先阅读此声明，然后仅在 MCP 服务环境中启用远程遥测：

TAV_TELEMETRY=on
TAV_TELEMETRY_URL=https://technical-answer-validator-telemetry.chl1591204.workers.dev/v1/event

远程遥测默认关闭。启用后，每次工具调用只会向配置的 Cloudflare Worker 发送随机且持久的安装 ID、软件包版本和结果（success、invalid_request 或 error）。该 ID 是随机生成的，不源自用户、设备或账户标识符；它让我们可以估算不同安装实例的数量，而非不同人员的数量。事件负载不包含答案、评分标准、工具输出、IP 地址、主机名或请求内容。为传递请求，Cloudflare 必然会接收发送方 IP 等网络连接元数据；我们的 Worker 不会记录或存储这些信息。Analytics Engine 会将事件数据保留三个月。设置 TAV_TELEMETRY=off 即可禁用遥测；也可以删除 ~/.technical-answer-validator/telemetry-id 来重置随机 ID。遥测故障绝不会中断评估。

收集器已部署在上方的 URL，并且只在 /v1/event 接受事件。要读取汇总使用情况，请创建一个仅限拥有该 Worker 的账户使用 Account Analytics Read 权限的 Cloudflare API 令牌，然后在此代码库中运行 python scripts/query_telemetry.py。该脚本会提示输入令牌，且不会回显或保存令牌。报告按 UTC 日期、软件包版本和结果汇总调用总数，并估算不同安装实例的数量；它不会识别人员。请勿将令牌放入源代码管理、MCP 配置或命令行中。

PyPI 0.1.1 不包含此可选启用的遥测代码。软件包用户可在 0.1.2 中使用该功能；只有安装该版本且用户明确启用上述两个环境变量后，才会开始收集数据。本地专用的 tav-mcp-stats 命令仍可独立使用。

请求

POST /v1/evaluate

{
  "rubric": {
    "required_concepts": ["isolation", "lockout tag"],
    "accepted_synonyms": {"isolation": ["energy isolation"]},
    "numeric_requirements": [],
    "required_count": 2
  },
  "answer": "Apply energy isolation and attach a lockout tag."
}

accepted_synonyms 的键必须与某个概念完全匹配。numeric_requirements 是可选数组，例如 [{"value":"10","unit":"kN","tolerance":"0"}]。只有在提供明确要求时，才会检查答案中的数字。概念得分为匹配的概念数 / 必需概念数（默认为概念数量），最高为 1.0；数值检查失败时，得分会降低 50%。判定阈值为：correct >= 0.8、partial >= 0.4，否则为 wrong。

响应和错误

成功请求会返回 api_version、status、score、verdict、匹配/缺失概念、数值检查详情以及 review_required: true。

错误采用 JSON 格式 { "error": { "code": "...", "message": "..." } }。状态码包括 400（请求无效）、401（缺少密钥/密钥无效）、404、405、413（请求正文超过 64 KiB）和 429（每个客户端 ID 每分钟超过 60 个请求）。速率限制为每个经过身份验证的客户端 ID 每分钟 60 个请求，计数保存在内存中，并在进程重启时重置。每日请求数/成功数/客户端错误数/速率限制数会持久化到 SQLite，不含答案文本，并在 90 天后过期。GET /v1/usage 仅返回调用方当前 UTC 日期的计数。可按需保留和备份使用量数据库；其中仅包含客户端 ID 和汇总数据。

隐私与部署限制

stdio MCP 选项在本地运行，除非用户明确启用上文所述的远程遥测，否则不会向中央服务发送任何使用信息。本地汇总调用次数可以单独禁用。REST API 会按 API 客户端分别统计服务端汇总数据。

服务端不会记录请求正文或答案。为限制 REST 请求速率，服务端会在进程内存中按客户端 ID 存储每日请求次数和请求时间戳。stdio MCP 选项在 Agent 宿主内本地运行，不会向此 HTTP 服务发送请求。REST API 采用容器化部署，并将使用计数器保存在持久卷中。面向公众提供服务前，应在反向代理处终止 TLS、设置代理级别的速率／并发限制、通过密钥管理器进行部署、监控主机，并发布数据保留／联系政策。应用级别的客户端速率限制会在重启后重置，不能替代边缘控制措施。

验证

python -m unittest discover -s tests -v

OpenAPI 契约位于 openapi.yaml；官方 MCP Registry 描述文件草案为 server.json，发布步骤见 PUBLISHING.md。将 .env.example 复制为 .env 并添加私钥后，即可使用 Docker Compose 在本地运行；Compose 仅在环回地址上发布服务，因此需另行配置 HTTPS 反向代理。compose.yaml 会将汇总使用数据持久化到具名卷，并启用只读根文件系统、移除 Linux 功能权限以及资源限制。

这些测试用于检查 API 和评分行为；它们不能证明专业考试的准确性。