花生十三-mcp

注意：本项目不是独立自动答题器。MCP 负责题型路由、方法卡检索、解题脚手架、答题提示词约束和安全门控；最终读图、读表、计算、推理和选答案仍由接入的大模型完成。因此，实际答题正确率会受到接入模型能力影响。建议使用中文理解、多模态视觉、表格阅读和推理能力较强的大模型。

基于花生十三行测方法论的 MCP 解题辅助工具。为 Claude Code、Codex 等支持 MCP 协议的 LLM Agent 提供结构化的行测题型路由、方法检索和答题引导。

Important: what this MCP does and does not guarantee

本 MCP 不是独立自动答题器。

它提供题型路由、方法卡检索、解题脚手架、答题提示词约束和安全门控，服务于接入的 LLM Agent（如 Claude Code、Codex 等）。接入的大模型负责读图、读表、理解题意、计算、逐步推理和选择最终答案。

因此，最终答题正确率取决于：

1. MCP 的路由 / 脚手架 / 安全门控约束，以及

2. 接入大模型的能力和指令遵循程度。

为获得较好实际效果，客户端应在已知考试模块时传入 module_hint 或 section_context，例如：

• 言语理解

• 数量关系

• 图形推理

• 定义判断

• 类比推理

• 逻辑判断

• 资料分析

图形推理题需要原始图片或可靠的文字描述。资料分析题需要完整的表格、图表或材料上下文。

Related MCP server: Sequential Thinking Multi-Agent System

功能概述

• 题型路由：自动识别题目所属模块（资料分析、逻辑判断、图形推理、定义判断、类比推理、数量关系、言语理解），返回置信度和推荐分析路径

• 方法检索：从 292 张结构化方法卡片中检索匹配的解题方法

• 结构化求解：资料分析和逻辑判断模块提供完整的解题草案

• Scaffold 引导：6 个模块的方法论脚手架，指导逐步分析

• 保守答题：多层安全门控制，信息不足时自动降级为分析模式，不强行作答

架构

用户题目 → MCP Server（路由 + prompt 组合） → LLM 客户端执行 → 结构化答案
                ↓
        知识库（292张方法卡片 + 路由规则）

MCP Server 本身不调用外部 LLM，只生成严格约束的 prompt，由接入的 LLM Agent（如 Claude Code、Codex 等）执行解题。

安装

需要 Python 3.10+。

pip install -e .

验证安装：

python -c "import xingce_solver.mcp_server; print('ok')"
python smoke_test_core.py

CLI 使用

# 搜索方法卡
huasheng-mcp search --query "比重 增长率"

# 查看方法卡详情
huasheng-mcp card --id da_share_change_004

# 资料分析求解
huasheng-mcp solve-data --text

# 逻辑判断求解
huasheng-mcp solve-logic --text

MCP Server

huasheng-mcp-server
# 或
python -m xingce_solver.mcp_server

提供 15 个 MCP tool：

接入 LLM Agent

以 Claude Code 为例：

claude mcp add-json huasheng-mcp '{"type":"stdio","command":"python","args":["-m","xingce_solver.mcp_server"]}' --scope user

重启 Claude Code 后运行 /mcp 验证 tool 列表。

其他支持 MCP 协议的 Agent（如 Codex、Cline、opencode 等）可参照各自的 MCP 配置方式接入，server 启动命令相同。

与 LLM 的协作模式

1. LLM 调用 route_xingce_question 获取模块路由

2. LLM 调用 compose_xingce_answer_prompt 获取严格约束的答题 prompt

3. LLM 调用对应模块的 scaffold tool 获取方法论指导

4. LLM 基于 prompt + scaffold + 自身能力输出结构化答案

关键约束：MCP tool 永远不直接输出答案，只生成 prompt。答案由 LLM 严格遵循约束后输出。

安全机制

• Answer Gate：缺图片/缺材料/路由不确定/低置信度时阻止回答，自动降级为 analysis_only

• 13 条核心约束：不猜测、不默认选 A、不编造视觉内容、不确定时不作答

• Safety Contract：tool 返回中不包含 answer/selected_option/prediction 字段

• module_hint 安全优先：强材料信号始终覆盖 module_hint，防止误路由导致错误作答

Hard gates vs prompt constraints

本 MCP 使用两类约束：代码层面的硬门控（hard gates）和提示词层面的约束（prompt-level constraints）。

代码层面的硬门控

以下检查由 MCP tool 返回值强制执行。触发时，compose_xingce_answer_prompt 返回 answer_allowed = false 及对应的 answer_block_reason。

当前硬门控包括：

• 图形推理缺少图片或视觉描述：

  • answer_block_reason = missing_visual_content

• 资料分析缺少表格/材料上下文：

  • answer_block_reason = missing_table_or_material

• 路由不确定且无语义覆盖：

  • answer_block_reason = route_uncertain_without_semantic_override

• 显式禁用答题模式：

  • answer_block_reason = answer_mode_disabled

• 强材料信号（如 表中、根据表格、图中数据、统计图表、上述资料、材料显示）在未提供材料/表格时仍触发材料门控。

合规的客户端在 answer_allowed = false 时不应要求 LLM 输出最终答案。

提示词层面的约束

部分约束表达在生成的答题 prompt 中，由接入的 LLM 客户端遵循。

例如：

• 按模块对应的解题脚手架进行分析；

• 逐项核验选项；

• 证据不足时不猜测；

• 无法唯一确定答案时返回 analysis_only；

• 题目内容与 module_hint / section_context 冲突时说明原因；

• 在需要时使用提供的图片、表格或材料。

这些提示词约束引导 LLM 的推理行为，但最终遵循程度取决于接入模型和客户端实现。

测试

# 冒烟测试
PYTHONPATH=src python smoke_test_core.py

# 完整测试（需安装 pytest）
python -m pytest

项目结构

src/xingce_solver/
├── mcp_server.py          # MCP Server 核心（路由 + prompt 组合 + tool 注册）
├── router.py              # 基于 YAML 规则的题型路由
├── kb.py                  # 知识库加载与检索
├── cli.py                 # CLI 接口
├── solvers/
│   ├── data_analysis.py   # 资料分析求解器
│   ├── logic_reasoning.py # 逻辑判断求解器
│   ├── truth_reasoning.py # 真假推理
│   └── logic_analysis_reasoning.py  # 分析推理
└── scaffolds/             # 6 个模块的方法论脚手架
    ├── graphic_reasoning_scaffold.py
    ├── definition_judgement_scaffold.py
    ├── analogy_reasoning_scaffold.py
    ├── logic_analysis_scaffold.py
    ├── quantity_relation_scaffold.py
    └── verbal_reasoning_scaffold.py

knowledge_base/
├── all_cards.jsonl        # 292 张方法卡片
├── global_router_rules.yaml  # 路由规则
├── module_map.yaml        # 模块映射
└── synonyms.yaml          # 同义词表

版本历史

• v0.5.1：module_hint 边界case修复，三年真题330/330路由验证通过

• v0.5.0：新增 module_hint/section_context 参数，支持中文模块名

• v0.4.3：文本排列题和定义判断路由覆盖增强

• v0.4.2：资料分析材料信号独立检测

• v0.4.1：保守答题门控强化

• v0.4.0：保守型答题 prompt 组合器

视觉能力说明

本 MCP Server 本身不具备视觉能力，不能直接识别图片。行测中的图形推理、资料分析（含图表）等需要看图的题型，依赖 LLM 客户端的多模态能力：

1. 客户端负责看图：支持视觉的 LLM Agent 先识别图片内容，将图形特征、图表数据转写为文字描述

2. MCP 负责结构化分析：将转写后的文字描述传入 MCP tool，由路由和 scaffold 引导分析流程

推荐使用支持视觉的模型（如 Claude Sonnet/Opus、GPT-4o 等）作为客户端，以完整覆盖图形推理和资料分析等含图表的题型。纯文本模型只能处理文字类题型。

答题正确率说明

本仓库中的验证结果（三年真题 330/330 路由验证）衡量的是 MCP 路由/门控/脚手架的行为，而非独立的最终答案正确率。

最终答案质量取决于接入模型的能力，包括但不限于：

• 中文阅读理解能力

• 多模态视觉识别能力（图形推理、图表题）

• 表格/材料数据提取能力

• 计算准确性

• 多步推理稳定性

获得较好实际效果的建议：

• 已知考试模块时，始终传入 module_hint 或 section_context

• 图形推理题提供原始图片

• 资料分析题提供完整的表格/材料

• 涉及图形、图表、表格的题目，使用多模态大模型

限制

• 不做 OCR 或图片识别，视觉内容由 LLM 客户端转写

• 不调用外部 LLM/API

• 不重新解析 PDF 或重新生成知识卡片

• 知识库基于花生十三方法论，不含其他来源的方法

License

MIT