Skip to content

feat(mcp): add wiki MCP index server - #126

Open
liyc-sys wants to merge 1 commit into
LLMQuant:masterfrom
liyc-sys:feat/wiki-mcp-index
Open

feat(mcp): add wiki MCP index server#126
liyc-sys wants to merge 1 commit into
LLMQuant:masterfrom
liyc-sys:feat/wiki-mcp-index

Conversation

@liyc-sys

Copy link
Copy Markdown

概述

实现 #88:给 wiki 添加 MCP 目录索引。不上传任何页面内容到外部——MCP server 只把 mkdocs.yml 里那棵导航树(与 quant-wiki.com 渲染所用的同一棵)暴露成目录,Agent 先看目录、再按需读取单页。

内容

新增 mcp/server.py(单文件 MCP server,stdio 传输)+ mcp/README.md(接入说明),主 README 增加一节指引。三个工具:

  • wiki_catalog():顶层分区总览(11 个分区、423 页,含每区页数);wiki_catalog(section="基本概念") 列出该分区全部页面(导航标题路径 + docs 路径);
  • wiki_search(query):大小写不敏感的标题/路径搜索,中英文都可命中(词条文件名同时带中英文,如 债券_Bond.md),最多返回 50 条;
  • wiki_page(path):按 docs 路径读取单页 markdown,输出头部带该页在 quant-wiki.com 的引用 URL;路径不在目录里时返回引导提示而不是报错。

实现细节:

  • 依赖只有官方 mcp SDK 和 PyYAML,以 PEP 723 内联声明,uv run mcp/server.py 即可运行,无需改动仓库现有 requirements.txt;兼容 mcp 1.x(FastMCP)和 2.x(MCPServer)两代 API;
  • 解析 mkdocs.yml 用容忍 !!python/name: 扩展标签的 SafeLoader,不引入 mkdocs 依赖;
  • 在本地 checkout 内运行时直接读本地文件;否则自动从 raw.githubusercontent.com 拉取(中文路径已做 URL 编码),因此单独下载 server.py 一个文件也能用,不必 clone 整个仓库;
  • 自带 --check 冒烟模式(打印目录统计、抽样页面、搜索结果),不需要 MCP 客户端即可验证。

验证

  • uv run mcp/server.py --check:目录 423 页 / 11 分区解析正确,抽样页面读取与站点 URL 生成正确,搜索命中正常;
  • 远程模式(无本地 checkout)实测:目录与页面均从 GitHub raw 正常拉取;
  • MCP 协议层实测:用官方 SDK 的 stdio 客户端连接,initialize / list_tools(3 个工具)/ 逐个 call_tool(含不存在路径的兜底提示)全部通过。

Closes #88

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[RFC] add wiki MCP index

1 participant