huasheng-mcp

# Tool List > Note: This project is not an independent automatic answer generator. MCP is responsible for question type routing, method card retrieval, problem-solving scaffolding, answer prompt constraints, and safety gate control; the final image reading, table reading, calculation, reasoning, and answer selection are still completed by the connected large model. Therefore, the actual answer accuracy will be affected by the capabilities of the connected model. It is recommended to use large models with strong Chinese understanding, multimodal vision, table reading, and reasoning capabilities. Based on the Huasheng Thirteen-line test method theory of MCP problem-solving auxiliary tools. For Claude Code, Codex and other support MCP protocol LLM Agent provides structured line test questions routing, method retrieval, and answer guidance. ## Important: what this MCP does and does not guarantee This MCP is **not** an independent automatic answer generator. It provides question type routing, method card retrieval, problem-solving scaffolding, answer prompt constraints, and safety gate control, serving the connected LLM Agent (such as Claude Code, Codex, etc.). The connected large model is responsible for image reading, table reading, understanding the question meaning, calculation, step-by-step reasoning, and selecting the final answer. Therefore, the final answer accuracy depends on: 1. MCP routing / scaffolding / safety gate constraints, and 2. The capabilities and instruction compliance of the connected large model. For better actual results, the client should pass in `module_hint` or `section_context` when the exam module is known, such as: - `Verbal Comprehension` - `Quantitative Relations` - `Graphic Reasoning` - `Definition Judgment` - `Analogy Reasoning` - `Logical Judgment` - `Data Analysis` Graphic reasoning questions require the original image or a reliable text description. Data analysis questions require complete tables, charts, or material context. ## Function Overview - **Question Type Routing**: Automatically identify the module that the question belongs to (Data Analysis, Logical Judgment, Graphic Reasoning, Definition Judgment, Analogy Reasoning, Quantitative Relations, Verbal Comprehension), return confidence and recommended analysis path - **Method Retrieval**: Retrieve matching problem-solving methods from 292 structured method cards - **Structured Solving**: Provide complete problem-solving drafts for Data Analysis and Logical Judgment modules - **Scaffold Guidance**: 6 module methodology scaffolding, guiding step-by-step analysis - **Conservative Answering**: Multi-layer safety gate control, automatically degrade to analysis mode when information is insufficient, do not force answers ## Architecture ``` User Question → MCP Server (routing + prompt combination) → LLM Client Execution → Structured Answer ↓ Knowledge Base (292 method cards + routing rules) ``` MCP Server itself does not call external LLM, only generates strictly constrained prompts, which are executed by connected LLM Agent (such as Claude Code, Codex, etc.). ## Installation Requires Python 3.10+. ```bash pip install -e . ``` Verification installation: ```bash python -c "import xingce_solver.mcp_server; print('ok')" python smoke_test_core.py ``` ## CLI Usage ```bash # Search method cards huasheng-mcp search --query "proportion growth rate" # View method card details huasheng-mcp card --id da_share_change_004 # Data analysis solving huasheng-mcp solve-data --text # Logical judgment solving huasheng-mcp solve-logic --text ``` ## MCP Server ```bash huasheng-mcp-server # or python -m xingce_solver.mcp_server ``` Provides 15 MCP tools: | Category | Tool | Description | |------|------|------| | Routing | `route_xingce_question` | Question type routing, supports module_hint/section_context | | Routing | `compose_xingce_analysis_prompt` | Composition analysis prompt | | Routing | `compose_xingce_answer_prompt` | Conservative answer prompt | | Knowledge | `get_method_card` | Get method card | | Knowledge | `search_methods` | Search method cards | | Knowledge | `classify_question` | Lightweight keyword routing | | Knowledge | `get_source_reference` | Source tracing | | Solving | `solve_data_analysis` | Data analysis structured solving | | Solving | `solve_logic_reasoning` | Logical judgment structured solving | | Guidance | `get_graphic_reasoning_scaffold` | Graphic reasoning methodology | | Guidance | `get_definition_judgement_scaffold` | Definition judgment methodology | | Guidance | `get_analogy_reasoning_scaffold` | Analogy reasoning methodology | | Guidance | `get_logic_analysis_scaffold` | Analysis reasoning methodology | | Guidance | `get_quantity_relation_scaffold` | Quantitative relation methodology | | Guidance | `get_verbal_reasoning_scaffold` | Verbal comprehension methodology | ### Accessing LLM Agent Take Claude Code as an example: ```bash claude mcp add-json huasheng-mcp '{"type":"stdio","command":"python","args":["-m","xingce_solver.mcp_server"]}' --scope user ``` Restart Claude Code and run `/mcp` to verify the tool list. Other MCP protocol-supported agents (such as Codex, Cline, opencode, etc.) can be accessed by referring to their respective MCP configuration methods, and the server startup command is the same. ## Collaboration Mode with LLM 1. LLM calls `route_xingce_question` to get module routing 2. LLM calls `compose_xingce_answer_prompt` to get strictly constrained answer prompts 3. LLM calls the corresponding module's scaffold tool to get methodology guidance 4. LLM outputs structured answers based on prompt + scaffold + its own capabilities Key constraints: MCP tools never directly output answers, only generate prompts. Answers are output by LLM strictly following constraints. ## Safety Mechanism - **Answer Gate**: Prevents answering when images/materials are missing, routing is uncertain, or confidence is low, automatically degrades to analysis_only - **13 Core Constraints**: No guessing, no defaulting to A, no fabricating visual content, no answering when uncertain - **Safety Contract**: Tool returns do not contain answer/selected_option/prediction fields - **Module_hint Safety Priority**: Strong material signals always override module_hint to prevent mis-routing and incorrect answers ## Hard Gates vs Prompt Constraints This MCP uses two types of constraints: code-level hard gates and prompt-level constraints. ### Code-Level Hard Gates The following checks are enforced by MCP tool return values. When triggered, `compose_xingce_answer_prompt` returns `answer_allowed = false` and the corresponding `answer_block_reason`. Current hard gates include: - Graphic reasoning missing images or visual descriptions: - `answer_block_reason = missing_visual_content` - Data analysis missing tables/material context: - `answer_block_reason = missing_table_or_material` - Routing uncertain and no semantic coverage: - `answer_block_reason = route_uncertain_without_semantic_override` - Explicitly disabled answer mode: - `answer_block_reason = answer_mode_disabled` - Strong material signals (e.g., `in the table`, `according to the table`, `data in the figure`, `statistical chart`, `above data`, `material display`) still trigger material gates when materials/tables are not provided. Compliant clients should not require LLM to output final answers when `answer_allowed = false`. ### Prompt-Level Constraints Some constraints are expressed in generated answer prompts, which are followed by connected LLM clients. For example: - Analyze according to module-specific problem-solving scaffolding; - Verify options item by item; - Do not guess when evidence is insufficient; - Return `analysis_only` when unable to uniquely determine the answer; - Explain reasons when question content conflicts with `module_hint` / `section_context`; - Use provided images, tables, or materials when necessary. These prompt constraints guide LLM's reasoning behavior, but the degree of compliance depends on the connected model and client implementation. ## Testing ```bash # Smoke test PYTHONPATH=src python smoke_test_core.py # Full test (requires pytest installation) python -m pytest ``` ## Project Structure ``` src/xingce_solver/ ├── mcp_server.py # MCP Server core (routing + prompt combination + tool registration) ├── router.py # YAML-based question type routing ├── kb.py # Knowledge base loading and retrieval ├── cli.py # CLI interface ├── solvers/ │ ├── data_analysis.py # Data analysis solver │ ├── logic_reasoning.py # Logical judgment solver │ ├── truth_reasoning.py # Truth reasoning │ └── logic_analysis_reasoning.py # Analysis reasoning └── scaffolds/ # 6 module methodology scaffolding ├── 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 method cards ├── global_router_rules.yaml # Routing rules ├── module_map.yaml # Module mapping └── synonyms.yaml # Synonym table ``` ## Version History - **v0.5.1**: Module_hint boundary case fix, 330/330 routing verification passed for three years of real questions - **v0.5.0**: Added module_hint/section_context parameters, supports Chinese module names - **v0.4.3**: Text arrangement questions and definition judgment routing coverage enhancement - **v0.4.2**: Data analysis material signal independent detection - **v0.4.1**: Conservative answer gate reinforcement - **v0.4.0**: Conservative answer prompt composer ## Visual Capability Description This MCP Server itself does not have visual capabilities and cannot directly recognize images. Graphic reasoning, data analysis (including charts), and other question types that require image viewing rely on LLM client's multimodal capabilities: 1. **Client responsible for image viewing**: Vision-supported LLM Agent recognizes image content and transcribes graphic features and chart data into text descriptions 2. **MCP responsible for structured analysis**: Transcribed text descriptions are passed to MCP tools, guided by routing and scaffolding analysis processes It is recommended to use vision-supported models (such as Claude Sonnet/Opus, GPT-4o, etc.) as clients to fully cover graphic reasoning and data analysis questions with charts. Pure text models can only handle text-based question types. ## Answer Accuracy Description The verification results in this repository (three years of real questions, 330/330 routing verification) measure MCP routing/gate/scaffolding behavior, not independent final answer accuracy. Final answer quality depends on the capabilities of the connected model, including but not limited to: - Chinese reading comprehension ability - Multimodal visual recognition ability (graphic reasoning, chart questions) - Table/material data extraction ability - Calculation accuracy - Multi-step reasoning stability Suggestions for better actual results: - Pass in `module_hint` or `section_context` when the exam module is known - Provide original images for graphic reasoning questions - Provide complete tables/materials for data analysis questions - Use multimodal large models for questions involving graphics, charts, and tables ## Limitations - No OCR or image recognition, visual content transcribed by LLM client - No external LLM/API calls - No PDF re-parsing or knowledge card regeneration - Knowledge base based on Huasheng Thirteen method theory, not containing methods from other sources ## License MIT