{
  "markdown": "# Luogu MCP Server | 洛谷 MCP Server\n\n[中文文档](README.zh-CN.md)\n\nA small MCP server for searching Luogu problems, reading statements and training sets, and finding related practice. It can run locally through npm or as a hosted Streamable HTTP server.\n\n## Quick Start\n\nUse the hosted read-only server without installing anything:\n\n```json\n{\n  \"mcpServers\": {\n    \"luogu\": {\n      \"url\": \"https://luogu-mcp.ksrnyx.top/mcp\"\n    }\n  }\n}\n```\n\nTo keep the server on your machine, use the published [`luogu-mcp-server`](https://www.npmjs.com/package/luogu-mcp-server) package:\n\n```json\n{\n  \"mcpServers\": {\n    \"luogu\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"luogu-mcp-server\"]\n    }\n  }\n}\n```\n\nThen ask:\n\n```text\nSearch Luogu for five beginner binary-tree problems.\nFetch Luogu P1305 with its statement and samples.\nFind related practice for traversal-order confusion.\n```\n\n## Tools\n\n| Tool | Purpose |\n| --- | --- |\n| `luogu_search_problems` | Search Luogu problems by keyword, topic, title fragment, problem id, and optional Luogu tag ids. |\n| `luogu_fetch_problem` | Fetch one Luogu problem statement, formats, samples, tags, difficulty, and URL by `pid`. |\n| `luogu_resolve_problem` | Resolve a Luogu URL, problem id, or title fragment, then fetch the problem. |\n| `luogu_find_related_problems` | Mix topic/pain-point recommendations with live keyword search to find related practice. |\n| `luogu_list_algorithm_topics` | List canonical algorithm topics, aliases, and known tag ids. |\n| `luogu_find_topic_problems` | Find topic practice problems using aliases, tag ids, deduplication, and match reasons. |\n| `luogu_search_problem_sets` | Search Luogu training/problem sets by keyword. Supports `type: \"all\" | \"official\" | \"select\"` because Luogu's current official-list endpoint only exposes the public official index, while selected user-shared sets support keyword search. |\n| `luogu_fetch_problem_set` | Fetch one Luogu training/problem set and problem summaries by id. |\n| `luogu_recommend_problems` | Return seed recommendations from a topic or student pain point. |\n| `luogu_get_user_profile` | Fetch public Luogu user profile data by uid. |\n| `luogu_get_capabilities` | Report which LeetCode-style route features are available, auth-required, or planned. |\n\nAll tools are read-only.\n\n## Availability\n\n- Hosted MCP: `https://luogu-mcp.ksrnyx.top/mcp`\n- Health: `https://luogu-mcp.ksrnyx.top/health`\n- Official MCP Registry: `io.github.Kaiserunix/luogu-mcp-server`, described by [`server.json`](server.json)\n\n## Other Ways To Run\n\nFrom source:\n\n```powershell\ngit clone https://github.com/kaiserunix/luogu-mcp-server.git\ncd luogu-mcp-server\ncmd /c npm install\ncmd /c npm run build\n```\n\nUse `node` directly from a source checkout:\n\n```json\n{\n  \"mcpServers\": {\n    \"luogu\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"C:\\\\path\\\\to\\\\luogu-mcp-server\\\\dist\\\\index.js\"\n      ],\n      \"cwd\": \"C:\\\\path\\\\to\\\\luogu-mcp-server\"\n    }\n  }\n}\n```\n\n## Example Calls\n\nSearch problems:\n\n```json\n{\n  \"keyword\": \"二叉树\",\n  \"page\": 1,\n  \"limit\": 5\n}\n```\n\nSearch problems with a Luogu tag filter:\n\n```json\n{\n  \"keyword\": \"二叉树\",\n  \"tagIds\": [11],\n  \"limit\": 5\n}\n```\n\nFetch a problem:\n\n```json\n{\n  \"pid\": \"P1305\",\n  \"maxStatementChars\": 5000\n}\n```\n\nRecommend from a pain point:\n\n```json\n{\n  \"topic\": \"binary_tree\",\n  \"painPoint\": \"traversal_order_confusion\",\n  \"limit\": 3\n}\n```\n\nResolve a pasted URL:\n\n```json\n{\n  \"query\": \"https://www.luogu.com.cn/problem/P1305\",\n  \"maxStatementChars\": 5000\n}\n```\n\nFind related practice:\n\n```json\n{\n  \"topic\": \"binary_tree\",\n  \"painPoint\": \"traversal_order_confusion\",\n  \"query\": \"二叉树 遍历\",\n  \"limit\": 5\n}\n```\n\nFind topic practice with alias expansion:\n\n```json\n{\n  \"topic\": \"Treap\",\n  \"limit\": 5,\n  \"excludeProblemIds\": [\"P3369\"]\n}\n```\n\nFetch a public user profile:\n\n```json\n{\n  \"uid\": 1\n}\n```\n\nSearch training/problem sets:\n\n```json\n{\n  \"keyword\": \"网络流\",\n  \"type\": \"select\",\n  \"limit\": 5\n}\n```\n\n`type: \"all\"` is the default. It combines title-filtered official sets with selected user-shared set search. Use `type: \"official\"` for the public official index, or `type: \"select\"` for selected user-shared sets.\n\n## Luogu Route Parity\n\nThis project mirrors the useful shape of richer LeetCode MCP servers while respecting what Luogu exposes publicly:\n\n- Available now: problem search, problem fetch, URL/id/title resolution, related problem discovery, training set search/fetch, public user profile fetch.\n- Auth-required in live probes: recent submissions, public solution pages, and discussion pages.\n- Planned but intentionally not enabled: solution submission/run-code tools. Those require authenticated session handling and explicit write-tool safety gates.\n\n## Development\n\n```powershell\ncmd /c npm test\ncmd /c npm run build\n```\n\n## Cloudflare Worker Deployment\n\nThis package also includes a stateless Streamable HTTP MCP entrypoint for Cloudflare Workers.\n\n```powershell\ncmd /c npm test\ncmd /c npm run smoke:cf\ncmd /c npx wrangler login\ncmd /c npm run deploy:cf:dry\ncmd /c npm run deploy:cf\n```\n\nThe Worker exposes the same read-only tools at `/mcp`, with a health endpoint at `/` or `/health`.\n\n```json\n{\n  \"mcpServers\": {\n    \"luogu\": {\n      \"url\": \"https://<your-worker-name>.<your-workers-subdomain>.workers.dev/mcp\"\n    }\n  }\n}\n```\n\nVerify a deployed Worker:\n\n```powershell\ncmd /c npm run smoke:cf -- https://<your-worker-name>.<your-workers-subdomain>.workers.dev\n```\n\nFor private deployments, set `LUOGU_MCP_TOKEN` with `wrangler secret put` and configure your MCP client to send an `Authorization: Bearer <token>` header where supported. Browser `Origin` requests are rejected by default; set `LUOGU_MCP_ALLOWED_ORIGINS` to a comma-separated origin list if browser access is needed.\n\nSee `docs/cloudflare-deployment.md` for the full release checklist.\n\nRun broad live checks against Luogu's current website responses:\n\n```powershell\ncmd /c npm run smoke:live\n```\n\nThe live smoke starts the MCP server through a real stdio client, then compares problem fetches, problem searches, training searches, training fetches, URL/id resolution, related recommendations, public user profiles, and route capabilities against Luogu content-only page responses. It is intentionally separate from unit tests because it depends on Luogu network availability and current site behavior.\n\nRun the 100-topic algorithm coverage smoke:\n\n```powershell\ncmd /c npm run smoke:topics\n```\n\nThe topic smoke starts the real MCP server and probes 100 algorithm categories across high-level topic search and training-set search. It fails if fewer than 98 topic searches return Luogu results.\n\nDownload one representative problem per catalog topic into a local ignored folder:\n\n```powershell\ncmd /c npm run download:topics\n```\n\nTest a MiMo agent loop that asks the model to choose MCP tools, then executes those calls through the local stdio MCP server:\n\n```powershell\ncmd /c npm run smoke:mimo\n```\n\n`smoke:mimo` reads `MIMO_API_KEY` from the environment, or from `C:\\Users\\qwerf\\.continue\\.env` on this machine.\n\n## Notes\n\n- Luogu endpoints used here are content-only web endpoints, not a formal stability contract.\n- The server keeps outputs compact and structured for model context control.\n- Browser automation is intentionally not the default path. A Playwright fallback can be added later for pages that cannot be read through lightweight HTTP.\n- For broad topic discovery, Luogu training-set search is often cleaner than raw problem title search; raw keyword search follows Luogu's website ordering and can include title-level noise.\n",
  "bytes": 7548,
  "sha": "74e98d5b72b76586203082d63fa513a1a5b439df51c16b85207572b3552da8d6",
  "repo_slug": "kaiserunix/luogu-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kaiserunix_luogu_mcp_server_0208458f/readme"
}