xiaoya-teacher-mcp-server

# Tool List     Designed for teachers, Xiaoya's intelligent teaching platform education management MCP server. Through MCP integration with AI assistants, it provides course resource management, Markdown rich text question creation, test configuration, class query, attendance statistics, task quizzes, and student answer review. Default installation includes common document conversion dependencies, suitable for local editable, `uv tool`, and standard release packages. ## ✨ Core Features ### 🎯 AI Assistant Integration - **MCP Protocol Support** - Perfectly integrated into MCP-supported AI assistants (such as Claude Desktop, Cursor, etc.) - **Multiple Transmission Methods** - Supports stdio, SSE, Streamable HTTP transmission protocols - **Summary Priority Query** - Questions, resources, and tasks default to return summaries, reducing AI token consumption - **Unified Response Format** - Standardized API responses for easy parsing and display by AI assistants ### 📚 Intelligent Question Bank System - **7 Types of Questions** - Supports single-choice, multiple-choice, fill-in-the-blank, true/false, short-answer, attachment, and programming questions - **Rich Text Editing** - Supports rich text format for question descriptions (bold, italic, underline, code blocks, etc.) - **Intelligent Scoring** - Fill-in-the-blank questions support multiple automatic scoring strategies (exact match, partial match, ordered/unordered) - **Batch Operations** - Supports batch creation of questions, official import of questions, and question sorting adjustments ### 📁 Resource Management System - **Multi-Type Resources** - Folders, notes, mind maps, files, assignments, teaching designs - **Complete Lifecycle** - Creation, deletion, renaming, moving, sorting, permission management - **File Processing** - File download, markdown format conversion - **Tree Structure** - Clear resource hierarchy display ### 👥 Class and Attendance - **Class Management** - Class information query, student statistics - **Attendance System** - Attendance record query, student attendance details, multiple attendance statuses - **Data Statistics** - Attendance rate analysis, attendance trends ### 📋 Task and Quiz - **Task Query** - Query course group published task lists, task details - **Score Management** - Student answer situation statistics, score analysis - **Answer Analysis** - Student answer details preview, question analysis - **AI Review** - Batch student answer sheets and attachments, local caching of images/PDF/files, supports multi-question scoring and comments in one go and submission; submitted reviews can be reopened and modified ## 🆕 Attachment Download Behavior Change (v1.5.2) - `get_answer_file` has switched from `file_access` preview endpoint to `file_down/v2` real download link, avoiding treating web preview as attachment content. - Added HTML load recognition: when the response is an HTML preview page, the interface will return a structured error and will not write pseudo-files to the attachment cache. - Local attachment cache adds HTML pseudo-cache skip logic: if historical cache hits HTML content, it will automatically ignore and re-download the real file. ## 🚀 Quick Start ### Release Installation ```bash # Run directly using uvx uvx xiaoya-teacher-mcp-server ``` ### Local Development Installation ```bash git clone https://github.com/Sav1ouR520/xiaoya-teacher-mcp-server.git cd xiaoya-teacher-mcp-server # Install development dependencies uv sync --dev # Run server uv run xiaoya-teacher-mcp-server ``` ### Local Tool Installation ```bash # Install current repository as local executable MCP command uv tool install -e --reinstall . ``` ## ⚙️ Configuration Instructions ### Authentication Configuration The server supports two authentication methods, local (stdio) and remote (SSE/HTTP). Both account password mode and token mode are supported. Account password mode supports automatic login and token caching; Bearer Token mode only uses the token provided by the caller. #### Method 1: Account Password Automatic Login (Recommended, supports multi-account remote caching) Local (stdio) and remote (SSE/HTTP) can both use account password automatic login. The token will be automatically cached, and remote multi-account will also be automatically saved. If authentication expiration is detected during the request process, the server will automatically re-login and retry the current request. ```json { "mcpServers": { "xiaoya-teacher-mcp-server": { "command": "uvx", "args": ["xiaoya-teacher-mcp-server"], "env": { "XIAOYA_ACCOUNT": "your_account", "XIAOYA_PASSWORD": "your_password" } } } } ``` Remote requests also support passing account password through headers, automatic login and caching on the first access: ```http POST /mcp/xxx X-XIAOYA-ACCOUNT: your_account X-XIAOYA-PASSWORD: your_password ``` #### Method 2: Token Direct Authentication Local and remote can both directly pass Bearer Token without account password. This mode will not automatically re-login. If the token expires, the caller needs to update and retry. ```json { "mcpServers": { "xiaoya-teacher-mcp-server": { "command": "uvx", "args": ["xiaoya-teacher-mcp-server"], "env": { "XIAOYA_AUTH_TOKEN": "your_bearer_token" } } } } ``` Remote requests also support passing Authorization through headers: ```http Authorization: Bearer your_bearer_token ``` ### Transmission Protocol Configuration #### Standard Input and Output (Default) ```json { "mcpServers": { "xiaoya-teacher-mcp-server": { "command": "uvx", "args": ["xiaoya-teacher-mcp-server"], "env": { "MCP_TRANSPORT": "stdio" } } } } ``` #### Server-Sent Events ```json { "mcpServers": { "xiaoya-teacher-mcp-server": { "command": "uvx", "args": ["xiaoya-teacher-mcp-server"], "env": { "MCP_TRANSPORT": "sse", "MCP_MOUNT_PATH": "/mcp" } } } } ``` #### Streamable HTTP ```json { "mcpServers": { "xiaoya-teacher-mcp-server": { "command": "uvx", "args": ["xiaoya-teacher-mcp-server"], "env": { "MCP_TRANSPORT": "streamable-http", "MCP_MOUNT_PATH": "/mcp" } } } } ``` ### Advanced Configuration: Multiple Transmissions Enabled Simultaneously When multiple clients need to open MCP services simultaneously, multiple transmission protocols can be enabled at once by separating them with commas. Example: ```json { "mcpServers": { "xiaoya-teacher-mcp-server": { "command": "uvx", "args": ["xiaoya-teacher-mcp-server"], "env": { "MCP_TRANSPORT": "sse,streamable-http", "MCP_MOUNT_PATH": "/mcp", "MCP_HOST": "0.0.0.0", "MCP_PORT": "8000" } } } } ``` Then, remote clients only need to configure as follows to access (no local environment variables, supports automatic login and multi-account caching): ```json { "mcpServers": { "xiaoya-teacher-mcp-sse-server": { "url": "http://ip:port/mcp/sse", "headers": { "x-xiaoya-account": "your_account", "x-xiaoya-password": "your_password" } } } } ``` Also supports streamable-http protocol, just change the url to `/mcp` path. - MCP_PORT and MCP_HOST are optional, used to specify the listening address and port (only effective for HTTP-based transmissions) - When SSE and Streamable HTTP are enabled simultaneously, they will reuse the same Uvicorn/Starlette service, and clients can use two protocols concurrently - All HTTP-based transmissions are mounted to the same path, default is http://host:port/mcp/*, can be adjusted using MCP_MOUNT_PATH - stdio transmission does not use MCP_HOST/MCP_PORT ## 📖 Usage Guide 1. **Choose Authentication Method** - Choose account password or token authentication according to your needs 2. **Configure Environment Variables** - Set corresponding environment variables in the MCP client configuration file 3. **Integrate into AI Assistants** - Use in MCP-supported AI assistants such as Claude Desktop, Cursor 4. **Start Teaching Management** - Directly interact with AI, complete tasks such as question bank management, resource organization, class management ### Common Processes and Capability Boundaries #### Questioning/ Test Paper Generation - Test papers usually correspond to `ASSIGNMENT` job resources in course resources. When creating a new test paper, first use `query_course_resources_summary` to locate the target folder, then create a resource using `create_course_resource(type=ASSIGNMENT)` and get `paper_id`. - When modifying an existing test paper, prioritize finding the job resource with `paper_id` from `query_course_resources_summary` or `query_course_resources`, then use `query_paper_summary` to view the number of questions, question types, and total score. - `query_group_tasks` is for published tasks, mainly providing `paper_id` and `publish_id` for review/answer statistics, not responsible for screening unpublished test papers. - Currently, there is no separate "automatic generation of test paper title" tool. If a personalized title is needed, suggest letting AI provide candidate titles, and then use it as the resource name for `create_course_resource`. - Question stems, options, and short answer reference answers support Markdown input fields (such as `title_md`, `text_md`, `answer_md`), and tools will automatically convert to Xiaoya rich text; if precise Draft.js control is needed, use `*_raw`. - Markdown images and attachments use `asset://id` placeholders, and pass local files through adjacent assets fields. Example: `title_md="\n\n[Experiment Attachment](asset://file_1)"`, `title_assets=[{"id":"img_1","type":"image","name":"Node Graph.png","file_path":"/abs/node.png"},{"id":"file_1","type":"attachment","name":"Experiment Attachment.zip","file_path":"/abs/lab.zip"}]`. Tools will upload and write into rich text according to Xiaoya web process. - When reading test papers or answer sheets, set `parse_mode="markdown"` to return rich text fields and resource lists in standard Markdown format, such as `title_md` + `title_assets`, `value_md` + `value_assets`, `answer_md` + `answer_assets`. #### Review/Scores - First, use `query_group_tasks` to select published tasks, then call `query_test_result` to get the number of submissions, number of non-submissions, average score, and student answer records. - AI reviewing a single student uses `get_student_grading_bundle` first, can pass `save_dir` to specify the attachment save directory; if not passed, use the current system temporary directory. - `get_student_grading_bundle` only returns `grading_context` and subjective questions/attachment questions that need human review; automatic scoring questions, empty fields, `quote_id`, file size, and cache hit information will not return. - After AI determines the score, use `grade_student_paper(grading_context=..., grades=[...])` to pass multiple subjective questions/attachment questions' scores and comments at once, default to submit the entire paper review. - The core format of the review package is `{"grading_context": {...}, "questions": [{"question_id": "...", "answer_id": "...", "max_score": 10, "title": "...", "student_answer": "...", "attachments": [{"name": "...", "mimetype": "image/png", "file_path": "/tmp/..."}]}]}`; scoring only needs to pass `grades=[{"question_id": "...", "answer_id": "...", "score": 10, "comment": "..."}]`. - For low-level single question modification, still use `query_preview_student_paper(detail_level=full)`, `get_answer_file`, `grade_student_question`, and `submit_student_mark` to execute step by step. - If submitted review needs to be modified, first use `withdraw_student_mark` to reopen, or after clear confirmation, use `revise_student_mark(..., allow_reopen=true, submit_after=true)` to reopen, modify single questions and resubmit. - Attachment answers can be obtained using `get_answer_file`; image/PDF review recommends falling to disk reading or walking `get_student_grading_bundle`, avoid base64 bursting context. #### Programming Questions - `create_code_question` `program_setting.in_cases` only needs to provide input, format is `[{"in": "input content"}]`. - The platform will generate expected output based on reference answer code operation, no need to write `out` field in `in_cases`. - `description` is used for parsing or supplementing explanation, reference answer code should be placed in `program_setting.code_answer`. #### Batch Operations - Batch creation, batch deletion, and resource batch update only succeed when all succeed, top-level `success=true`; partial failure `success=false`, but `data.failed_items` will list uncreated/undeleted/unupdated entries and reasons, `data.success_ids` will retain successful IDs. ## 🏗️ Project Architecture ```text xiaoya-teacher-mcp-server/ ├── pyproject.toml # packaging configuration ├── README.md # project documentation ├── hatch_build.py # Hatchling packaging hook ├── xiaoya-teacher-skill/ # AI assistant skill, encapsulates Xiaoya platform operation process │ ├── SKILL.md │ ├── agents/openai.yaml │ └── references/ # installation configuration, operation link and rich text reference ├── src/ │ └── xiaoya_teacher_mcp_server/ │ ├── config.py # configuration file and authentication module │ ├── field_descriptions.py # MCP field description constants │ ├── main.py # server entry and transmission protocol processing │ ├── tools/ # core tool module │ │ ├── questions/ # question management tool │ │ ├── resources/ # resource management tool │ │ ├── group/ # class and attendance query │ │ └── task/ # task and quiz management │ ├── types/ # type definition │ │ ├── enums.py # common enumeration │ │ ├── question_models.py # question-related models │ │ ├── resource_models.py # resource-related models │ │ └── task_models.py # class and course-related models │ └── utils/ # common tool functions │ ├── client.py # unified HTTP client and automatic re-login │ ├── logging.py # unified log │ ├── response.py # unified response processing │ ├── rich_text.py # pure text, Markdown, raw rich text conversion │ └── upload.py # Xiaoya web-end same rich text resource upload └── tests/ # regression test ``` ### Core Module Description #### 🎯 Question Management Module - **create.py** - complete support for 7 types of question creation, including complex programming question settings - **update.py** - question content update, answer modification, option management - **query.py** - default return test paper summary, need to return complete details on demand - **delete.py** - question and answer item deletion operation #### 📁 Resource Management Module - **create.py** - multi-type resource creation (folders, notes, mind maps, etc.) - **update.py** - resource renaming, moving, sorting, permission settings - **query.py** - default return resource summary, support folder local snapshot, file download, markdown format conversion - **delete.py** - resource file deletion operation #### 👥 Class Management Module - **query.py** - class list, attendance records, course group overview query #### 📋 Task Management Module - **query.py** - default return task and answer summary, need to return complete answer sheet details on demand - **grade.py** - student whole paper review package, batch scoring submission, question-by-question scoring, submission review, reopen submitted review - **attachments.py** - answer sheet attachment collection, parallel download and local caching ## 🔧 Technology Stack - **Python 3.11+** - main development language - **FastMCP** - MCP protocol implementation framework - **Pydantic** - data validation and type definition - **Requests** - HTTP client - **MarkItDown** - document format conversion ## 📄 License This project uses MIT license - see [LICENSE](LICENSE) file for details. ## 👨‍💻 Author **Sav1ouR520** - Email: 3300233150@qq.com - GitHub: https://github.com/Sav1ouR520