MoeReview

# MoeReview <p align="center"> <strong>A local-first learning workspace for MCP Agent.</strong><br /> Let Agent think, and browser stabilize the learning process. </p> <p align="center"> <a href="./README.en.md">English</a> · <a href="./README.md">Simplified Chinese</a> </p> <p align="center"> <img alt="Node.js >= 18" src="https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white" /> <img alt="React" src="https://img.shields.io/badge/react-19-61DAFB?logo=react&logoColor=111" /> <img alt="Vite" src="https://img.shields.io/badge/vite-8-646CFF?logo=vite&logoColor=white" /> <img alt="MCP" src="https://img.shields.io/badge/MCP-agent%20tools-8A2BE2" /> <img alt="Local first" src="https://img.shields.io/badge/storage-local--first-blue" /> <img alt="License: GPL v3" src="https://img.shields.io/badge/license-GPLv3-blue" /> </p> > This is not just another "chat window wrapper". MoeReview is more like the cockpit of a learning mech: Agent handles reasoning and teaching, Hub stabilizes connections, and Web UI precipitates, exercises, reviews, and interacts. ## Table of Contents - [What problems does it solve](#what-problems-does-it-solve) - [Key Features](#key-features) - [Architecture](#architecture) - [Directory Structure](#directory-structure) - [Environment Requirements](#environment-requirements) - [Quick Start](#quick-start) - [Installation and Build](#installation-and-build) - [Start Hub](#start-hub) - [Configure MCP Adapter](#configure-mcp-adapter) - [Optional Agent Skill](#optional-agent-skill) - [Core Interaction Model](#core-interaction-model) - [Common Commands](#common-commands) - [Local Data](#local-data) - [Frequently Asked Questions](#frequently-asked-questions) - [Pre-open Source Status](#pre-open-source-status) ## What problems does it solve Many AI learning tools put everything into chat records: explanations, questions, answers, status, and reminders are all mixed together. MoeReview's approach is to break down the learning process into a more stable interface layer: - Long-term valuable content enters the learning page. - Temporary explanations and next-step suggestions enter the right guidance panel. - Agent can wait for user input in the web page or send messages. - Agent offline, the web page can still open and review history. In other words, don't let Agent's lifecycle tie up the stability of the learning interface. ## Key Features - Resident `MoeReview Hub`, Web page does not depend on Agent startup. - Temporary `MCP Agent Adapter`, only responsible for forwarding MCP tool calls to Hub. - Session-level history: learning pages, favorites, wrong answers, Q&A history, activity logs. - Quiz page, answer collection, result page, and wrong answer precipitation. - Right `Guidance Panel` displays temporary status, short suggestions, and next steps. - Without Agent, you can still enter the welcome page and review history. - Default local storage, no need for accounts or cloud services. ## Architecture ```text Browser UI <-- HTTP / WebSocket --> MoeReview Hub <-- HTTP --> MCP Agent Adapter <-- stdio --> Agent ``` MoeReview backend is split into two roles: - `MoeReview Hub`: resident HTTP/WebSocket service, responsible for web pages, sessions, history, connection status, and event routing. - `MCP Agent Adapter`: temporary MCP stdio service, responsible for registering Agent and forwarding tool calls to Hub. The direct benefit of this is: restarting Agent, switching Agent, or ending Agent conversation will not cause the website to become inaccessible. ## Directory Structure ```text . +-- mcp-server/ # MoeReview Hub and MCP Agent Adapter | +-- src/hub.ts # Hub entry | +-- src/index.ts # MCP Adapter entry | +-- src/ws/server.ts # HTTP / WebSocket / API / routing | +-- src/tools/ # MCP tool implementation +-- web/ # React + Vite frontend +-- skills/ | +-- moereview-agent/ # Optional Codex skill: constrain Agent to use MoeReview correctly +-- docs/ # design documents +-- scripts/ # local quick start and check scripts +-- start.cmd # Windows double-click startup entry +-- README.md # Chinese documentation +-- README.en.md # English documentation ``` ## Environment Requirements - Node.js 18+ - npm - An MCP-supported Agent/client The current project prioritizes local single-user scenarios. Account systems, cloud synchronization, and permission models have not been introduced yet. ## Quick Start For Windows users, you can double-click: ```text start.cmd ``` Or run in the repository root directory: ```powershell npm run start ``` This will automatically: 1. Check Node.js and npm. 2. Install missing `web`/`mcp-server` dependencies. 3. Build frontend and backend. 4. Check port `3456`. 5. Open browser. 6. Start MoeReview Hub. If you only want to check the environment: ```powershell npm run check ``` If you don't want to automatically open the browser: ```powershell npm run start:no-open ``` Quick start script will not automatically kill port occupiers. If `3456` is occupied, please manually stop the old process or use: ```powershell .\scripts\start.ps1 -Port 4567 ``` ## Installation and Build Install dependencies: ```powershell cd mcp-server npm install cd ../web npm install ``` Build frontend: ```powershell cd web npm run build ``` Build Hub/MCP Adapter: ```powershell cd ../mcp-server npm run build ``` If you start from the repository root directory, you can execute in this order: ```powershell cd web npm run build cd ../mcp-server npm run build ``` ## Start Hub Hub listens on port `3456` by default and hosts the built `web/dist`. ```powershell cd mcp-server npm run hub ``` Then open: ```text http://localhost:3456 ``` Without Agent connection, MoeReview can still open normally, enter the welcome page, or review historical sessions. If you want to change the port: ```powershell $env:MOEREVIEW_HUB_PORT="4567" npm run hub ``` ## Configure MCP Adapter After building `mcp-server`, configure in your MCP client: ```text node <repo>/mcp-server/dist/index.js ``` Example: ```json { "mcpServers": { "moereview": { "command": "node", "args": ["<absolute-path-to-repo>/mcp-server/dist/index.js"] } } } ``` Replace `<absolute-path-to-repo>` with your local clone repository path. Recommended startup order: 1. Build `web` and `mcp-server`. 2. Run `npm run hub` to start Hub. 3. Start MCP-supported Agent/client. 4. Open `http://localhost:3456`. ## Optional Agent Skill The repository provides an optional Codex skill: ```text skills/moereview-agent/ ``` It does not regulate teaching methods or interfere with explanation styles. It only constrains Agent to use MoeReview correctly: - Explicitly bind sessions. - Read pending messages at the beginning of each round. - Distinguish `idle`/`waiting`/`working`/`disconnected` states. - Only create pages for content with long-term review value. - Put temporary status and next-step suggestions in the sidebar guidance. If your Agent supports explicit skill calls, you can use: ```text Use $moereview-agent ``` Or directly point to: ```text skills/moereview-agent/SKILL.md ``` ## Core Interaction Model ### Pages: Long-term Learning Records Content suitable for pages: - Knowledge point explanations - Structured summaries - Quiz questions - Quiz results - Wrong answer reviews - Learning plans - Important revisions Content not suitable for pages: - "Good" - "I'm processing" - Temporary suggestions - Tool status - One-sentence reminders ### Guidance Panel: Right Temporary Guidance Content suitable for the sidebar: - Current status - Next-step suggestions - Operation prompts - Waiting for user input instructions - Lightweight warnings The goal is to let users know what to do without opening the Agent chat window. ### Agent Waiting and Wake-up MCP cannot wake up an Agent that has ended a turn. MoeReview therefore explicitly distinguishes states: | State | Meaning | |---|---| | `offline` | No Agent in the current session | | `idle` | Adapter online, but Agent not actively waiting | | `waiting` | Agent is `wait_for_response`/`ask_choice`/`enter_standby` | | `working` | Agent is processing or calling tools | | `disconnected` | Agent heartbeat expired or connection broken | Only `waiting` can be immediately woken up by Web input. In `idle` and `working` states, Web messages will enter the queue, waiting for Agent to call `get_pending_messages` in the next round. ## Common Commands Frontend: ```powershell cd web npm run dev npm run build npm run lint ``` Backend: ```powershell cd mcp-server npm run build npm run hub npm run dev:hub npm run start ``` Note: `npm run start` starts MCP Adapter, not Hub. ## Local Data MoeReview defaults to placing runtime data in the user directory: ```text ~/.examforge/ ``` Session data includes: - `meta.json` - `pages.json` - `favorites.json` - `wrong_answers.json` - `qa_memory.json` - `activity_log.json` - `message_queue.json` - `guidance.json` These data should not be submitted to Git. ## Frequently Asked Questions ### Port 3456 occupied Hub will not automatically kill port occupiers. Please manually stop the old process or set `MOEREVIEW_HUB_PORT`. ### Hub opened, but not complete Web UI Usually, the frontend has not been built: ```powershell cd web npm run build ``` Then restart Hub. ### MCP tool prompts Hub not started Start Hub before starting MCP Adapter: ```powershell cd mcp-server npm run hub ``` ### Frontend sends message, Agent no response Check session status: - `waiting`: should wake up immediately. - `idle`: message queued, Agent reads in the next round. - `working`: message queued, waiting for Agent to finish. - `disconnected`: need to restart MCP Adapter. ## Pre-open Source Status MoeReview is still rapidly iterating, and API and directory structure may continue to change. The current most important design principle is: > Web workspace must run stably independently of Agent lifecycle. Subsequent supplements are suitable: - One-click startup script - Connection diagnosis panel - pending message quantity prompt - standby cancel/extension mechanism - Automatic generation of MCP tool documentation ## License This project uses [GNU General Public License v3.0](./LICENSE).