luogu-mcp-server

中文文档

A small stdio MCP server for Luogu problem discovery. It exposes a LeetCode-MCP-style Luogu route for problem search, problem fetch, URL/id resolution, related practice discovery, training set search, training set fetch, public user profiles, and explicit capability reporting.

Why

This server is designed for AI tutoring and practice agents. The model can find a problem by topic, fetch the exact statement and samples, or ask for a bounded recommendation from a known topic or student pain point.

Tools

All tools are read-only.

Install From Source

git clone https://github.com/kaiserunix/luogu-mcp-server.git
cd luogu-mcp-server
cmd /c npm install
cmd /c npm run build

Use From npm

The package is published on npm as luogu-mcp-server.

npx -y luogu-mcp-server

For stdio MCP clients, use:

{
  "mcpServers": {
    "luogu": {
      "command": "npx",
      "args": ["-y", "luogu-mcp-server"]
    }
  }
}

MCP Client Config From Source

Use node directly as the stdio command:

{
  "mcpServers": {
    "luogu": {
      "command": "node",
      "args": [
        "C:\\Users\\qwerf\\Desktop\\luogu-mcp-server\\dist\\index.js"
      ],
      "cwd": "C:\\Users\\qwerf\\Desktop\\luogu-mcp-server"
    }
  }
}

Hosted Cloudflare Worker

A public read-only Streamable HTTP deployment is available at:

• Health: https://luogu-mcp-server.lantangtang54.workers.dev/health

• MCP endpoint: https://luogu-mcp-server.lantangtang54.workers.dev/mcp

For Streamable HTTP MCP clients, use:

{
  "mcpServers": {
    "luogu": {
      "url": "https://luogu-mcp-server.lantangtang54.workers.dev/mcp"
    }
  }
}

Example Calls

Search problems:

{
  "keyword": "二叉树",
  "page": 1,
  "limit": 5
}

Search problems with a Luogu tag filter:

{
  "keyword": "二叉树",
  "tagIds": [11],
  "limit": 5
}

Fetch a problem:

{
  "pid": "P1305",
  "maxStatementChars": 5000
}

Recommend from a pain point:

{
  "topic": "binary_tree",
  "painPoint": "traversal_order_confusion",
  "limit": 3
}

Resolve a pasted URL:

{
  "query": "https://www.luogu.com.cn/problem/P1305",
  "maxStatementChars": 5000
}

Find related practice:

{
  "topic": "binary_tree",
  "painPoint": "traversal_order_confusion",
  "query": "二叉树 遍历",
  "limit": 5
}

Find topic practice with alias expansion:

{
  "topic": "Treap",
  "limit": 5,
  "excludeProblemIds": ["P3369"]
}

Fetch a public user profile:

{
  "uid": 1
}

Luogu Route Parity

This project mirrors the useful shape of richer LeetCode MCP servers while respecting what Luogu exposes publicly:

• Available now: problem search, problem fetch, URL/id/title resolution, related problem discovery, training set search/fetch, public user profile fetch.

• Auth-required in live probes: recent submissions, public solution pages, and discussion pages.

• Planned but intentionally not enabled: solution submission/run-code tools. Those require authenticated session handling and explicit write-tool safety gates.

Development

cmd /c npm test
cmd /c npm run build

Cloudflare Worker Deployment

This package also includes a stateless Streamable HTTP MCP entrypoint for Cloudflare Workers.

cmd /c npm test
cmd /c npm run smoke:cf
cmd /c npx wrangler login
cmd /c npm run deploy:cf:dry
cmd /c npm run deploy:cf

The Worker exposes the same read-only tools at /mcp, with a health endpoint at / or /health.

{
  "mcpServers": {
    "luogu": {
      "url": "https://<your-worker-name>.<your-workers-subdomain>.workers.dev/mcp"
    }
  }
}

Verify a deployed Worker:

cmd /c npm run smoke:cf -- https://<your-worker-name>.<your-workers-subdomain>.workers.dev

For 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.

See docs/cloudflare-deployment.md for the full release checklist.

Run broad live checks against Luogu's current website responses:

cmd /c npm run smoke:live

The 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.

Run the 100-topic algorithm coverage smoke:

cmd /c npm run smoke:topics

The 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.

Download one representative problem per catalog topic into a local ignored folder:

cmd /c npm run download:topics

Test a MiMo agent loop that asks the model to choose MCP tools, then executes those calls through the local stdio MCP server:

cmd /c npm run smoke:mimo

smoke:mimo reads MIMO_API_KEY from the environment, or from C:\Users\qwerf\.continue\.env on this machine.

Notes

• Luogu endpoints used here are content-only web endpoints, not a formal stability contract.

• The server keeps outputs compact and structured for model context control.

• Browser automation is intentionally not the default path. A Playwright fallback can be added later for pages that cannot be read through lightweight HTTP.

• 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.