Luogu MCP Server

洛谷 MCP 服务 | 洛谷 MCP Server

中文文档

一个轻量的 MCP 服务，可用于搜索洛谷题目、阅读题面和训练集，以及查找相关练习。可通过 npm 在本地运行，也可作为托管的 Streamable HTTP 服务运行。

快速开始

无需安装任何内容，即可使用托管的只读服务：

{
  "mcpServers": {
    "luogu": {
      "url": "https://luogu-mcp.ksrnyx.top/mcp"
    }
  }
}

如需在自己的机器上运行服务，请使用已发布的 luogu-mcp-server 软件包：

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

然后询问：

Search Luogu for five beginner binary-tree problems.
Fetch Luogu P1305 with its statement and samples.
Find related practice for traversal-order confusion.

工具

工具	用途
luogu_search_problems	按关键词、主题、标题片段、题目 ID 和可选的洛谷标签 ID 搜索洛谷题目。
luogu_fetch_problem	按 pid 获取一道洛谷题目的题面、格式、样例、标签、难度和 URL。
luogu_resolve_problem	解析洛谷 URL、题目 ID 或标题片段，然后获取题目。
luogu_find_related_problems	结合主题／薄弱点推荐和实时关键词搜索，查找相关练习。
luogu_list_algorithm_topics	列出规范的算法主题、别名和已知标签 ID。
luogu_find_topic_problems	使用别名、标签 ID、去重和匹配原因查找主题练习题。
luogu_search_problem_sets	按关键词搜索洛谷训练／题目集。支持 `type: "all"
luogu_fetch_problem_set	按 ID 获取一个洛谷训练／题目集及题目摘要。
luogu_recommend_problems	根据主题或学生薄弱点提供初步推荐。
luogu_get_user_profile	按 uid 获取公开的洛谷用户资料。
luogu_get_capabilities	报告 LeetCode 风格路由功能哪些可用、需要身份验证或仍在计划中。

所有工具均为只读。

可用性

• 托管的 MCP 服务：https://luogu-mcp.ksrnyx.top/mcp
• 健康检查：https://luogu-mcp.ksrnyx.top/health
• 官方 MCP Registry：io.github.Kaiserunix/luogu-mcp-server，由 server.json 描述

其他运行方式

从源码运行：

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

从源码检出目录直接使用 node：

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

调用示例

搜索题目：

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

使用洛谷标签筛选搜索题目：

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

获取一道题目：

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

根据薄弱点进行推荐：

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

解析粘贴的 URL：

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

查找相关练习：

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

通过扩展别名查找主题练习：

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

获取公开用户资料：

{
  "uid": 1
}

搜索训练／题目集：

{
  "keyword": "网络流",
  "type": "select",
  "limit": 5
}

type: "all" 是默认值。它会合并按标题筛选的官方题集和精选用户分享题集的搜索结果。使用 type: "official" 搜索公开的官方索引，或使用 type: "select" 搜索精选用户分享题集。

洛谷路由功能对等性

本项目在尊重洛谷公开数据范围的同时，借鉴了功能更丰富的 LeetCode MCP 服务的实用结构：

• 当前可用：题目搜索、题目获取、URL／ID／标题解析、相关题目发现、训练集搜索／获取、公开用户资料获取。
• 实际探测时需要身份验证：最近提交、公开题解页面和讨论页面。
• 计划中但有意未启用：题解提交／运行代码工具。这些功能需要处理经过身份验证的会话，并设置明确的写入工具安全限制。

开发

cmd /c npm test
cmd /c npm run build

Cloudflare Worker 部署

此软件包还包含一个无状态的 Streamable HTTP MCP 入口点，可用于 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

Worker 在 /mcp 提供相同的只读工具，并在 / 或 /health 提供健康检查端点。

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

验证已部署的 Worker：

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

对于私有部署，请使用 wrangler secret put 设置 LUOGU_MCP_TOKEN，并将 MCP 客户端配置为在支持的情况下发送 Authorization: Bearer <token> 标头。默认情况下会拒绝浏览器 Origin 请求；如果需要浏览器访问，请将 LUOGU_MCP_ALLOWED_ORIGINS 设置为以逗号分隔的来源列表。

完整的发布检查清单请参阅 docs/cloudflare-deployment.md。

针对 Luogu 当前网站响应运行全面的实时检查：

cmd /c npm run smoke:live

实时冒烟测试会通过真实的 stdio 客户端启动 MCP 服务，然后将问题获取、问题搜索、训练集搜索、训练集获取、URL/ID 解析、相关推荐、公开用户资料和路由功能与 Luogu 仅包含内容的页面响应进行比较。此测试与单元测试分开，因为它依赖 Luogu 网络可用性和当前的网站行为。

运行涵盖 100 个主题的算法冒烟测试：

cmd /c npm run smoke:topics

主题冒烟测试会启动真实的 MCP 服务，并针对 100 个算法类别进行高级主题搜索和训练集搜索。如果返回 Luogu 结果的主题搜索少于 98 项，测试就会失败。

将目录中每个主题的一个代表性问题下载到本地忽略文件夹：

cmd /c npm run download:topics

测试 MiMo Agent 循环：由模型选择 MCP 工具，再通过本地 stdio MCP 服务执行这些调用：

cmd /c npm run smoke:mimo

smoke:mimo 会从环境变量读取 MIMO_API_KEY，或从本机的 C:\Users\qwerf\.continue\.env 读取。

说明

• 此处使用的 Luogu 端点是仅提供内容的 Web 端点，并非正式的稳定性承诺。
• 服务会保持输出简洁且结构化，以便控制模型上下文。
• 浏览器自动化并非默认方案。对于无法通过轻量级 HTTP 读取的页面，之后可以添加 Playwright 回退方案。
• 要广泛发现主题，Luogu 训练集搜索通常比原始问题标题搜索更清晰；原始关键词搜索遵循 Luogu 网站的排序方式，可能会包含标题层面的噪声。