Skip to content

CyanBukkit/PicoXR-Doc-MCP

BranchesTags

Repository files navigation

Pico XR 开发文档 MCP 知识库服务器

先看这里：普通用户怎么启动

如果你只是想把这个 MCP 加到 Claude Code / Claude Desktop / 其他支持 MCP 的工具里，只需要用一个文件：

dist\pico-xr-docs-mcp.exe

不要双击它来判断是否成功。这个程序默认是 stdio MCP，就是给 Claude 这类客户端自动拉起用的；你手动双击看到黑窗口、一闪而过、或者像卡住一样，通常不是坏了。

用法 1：Claude Code 添加 stdio MCP（推荐）

在 Claude Code 里运行：

claude mcp add pico-xr-docs -- "G:\\Ai_Agent\\pico-mcp-server\\dist\\pico-xr-docs-mcp.exe"

如果你把项目放到了别的位置，只改 exe 路径即可。

添加后重启 Claude Code，或在 Claude Code 里运行：

claude mcp list

看到 pico-xr-docs 就说明配置已写入。

Claude Desktop 或其他 MCP 客户端可使用同样的 stdio 配置：

{
  "mcpServers": {
    "pico-xr-docs": {
      "command": "G:\\Ai_Agent\\pico-mcp-server\\dist\\pico-xr-docs-mcp.exe",
      "args": []
    }
  }
}

如果你把项目放到了别的位置，只改 command 这一行路径即可。

用法 2：Claude Code 添加 HTTP MCP

如果你的客户端要填 HTTP 地址，双击根目录的：

start.bat

它会启动本地 HTTP 服务，然后在 Claude Code 里运行：

claude mcp add --transport http pico-xr-docs http://127.0.0.1:8000/mcp

如果你的客户端是界面配置，就填这个地址：

http://127.0.0.1:8000/mcp

这个窗口要保持开着；关掉窗口，HTTP MCP 就停了。

哪些文件不用管

文件 普通用户要不要点
dist\pico-xr-docs-mcp.exe stdio 配置用它，不需要双击
start.bat 只在你要 HTTP 模式时双击
setup.bat 不用管，源码开发/重新爬文档才需要
start_mcp_windows.bat 不用管，源码运行才需要
build_exe_windows.bat 不用管，维护者重新打包才需要
crawl_docs*.py 不用管，维护者更新知识库才需要

将 PICO XR 官方开发文档整合成 FastMCP 知识库，供 AI 助手（WorkBuddy / Claude Desktop / Claude Code）查询使用

维护者说明

下面内容给需要重新爬取、源码运行或重新打包的人看；普通用户只看上面的“先看这里”即可。

当前项目状态

  • 已完成从 https://developer-cn.picoxr.com/document/ 递归发现与全量重爬，当前知识库包含 264 篇文档。
  • data/pico_docs_full.json 已保存完整 Markdown 正文，data/pico_docs_index.json 已保存搜索索引摘要。
  • 已清理 Pico 页面导航栏、页脚等站点壳内容，搜索结果返回的是文档正文摘要。
  • 已完成 PyInstaller 单文件打包，dist/pico-xr-docs-mcp.exe 内置当前 data/ 知识库。
  • 已验证 exe 的 Streamable HTTP MCP 模式可正常调用 get_stats 和 search_docs。
  • 普通用户只需要配置并运行 dist/pico-xr-docs-mcp.exe，不需要安装 Python、Playwright 或重新爬取文档。

项目结构

pico-mcp-server/
├── server.py            # FastMCP 服务器主程序（MCP 工具定义）
├── crawl_docs_v3.py     # 文档全量爬虫（覆盖双域名，增量爬取）
├── build_exe.py         # PyInstaller 打包脚本
├── build_exe_windows.bat # Windows 一键打包脚本（使用 conda mcpmaker 环境）
├── dist/
│   └── pico-xr-docs-mcp.exe # Windows 单文件 MCP 服务器
├── data/
│   ├── pico_docs_full.json   # 完整文档数据（含 markdown 正文）
│   └── pico_docs_index.json  # 文档索引（含摘要，不含全文）
├── mcp_config.json      # Python 版 MCP 配置示例
├── mcp_config_exe.json  # 独立 exe 版 MCP 配置示例
├── requirements.txt     # Python 依赖
├── setup.bat            # 一键安装依赖脚本
└── start_mcp_windows.bat # Windows 一键启动脚本

知识库统计

指标 数值
文档总数 264 篇
总内容量 1,050,237 字符
分类数 7 个
数据来源 developer-cn.picoxr.com + developer-cn.pico-interactive.com

分类分布：

  • Unity SDK: 173 篇
  • Unreal SDK: 52 篇
  • 分发上架: 31 篇
  • 设备介绍: 3 篇
  • 安全信息: 2 篇
  • 其他: 2 篇
  • Native SDK: 1 篇

快速开始

第 1 步：安装依赖（首次，仅 Python 源码运行/爬虫需要）

setup.bat

或手动安装到 mcpmaker conda 环境：

conda create -y -n mcpmaker python=3.11
/c/ProgramData/miniconda3/envs/mcpmaker/python.exe -m pip install -r requirements.txt
/c/ProgramData/miniconda3/envs/mcpmaker/python.exe -m playwright install chromium

第 2 步：爬取文档（维护者更新数据时使用）

set CRAWL4_AI_BASE_DIRECTORY=.
/c/ProgramData/miniconda3/envs/mcpmaker/python.exe crawl_docs_v3.py

注意：需要设置 CRAWL4_AI_BASE_DIRECTORY 环境变量指向项目目录，以避免 Crawl4AI 写入用户主目录时权限问题。脚本内部已自动处理此设置。

爬取完成后，data/ 目录下会生成：

  • pico_docs_full.json — 完整文档内容
  • pico_docs_index.json — 文档索引（快速搜索用）

第 3 步：配置到 WorkBuddy / Claude Desktop

推荐使用独立 exe（目标机器不需要安装 Python），将 mcp_config_exe.json 中的配置添加到你的 MCP 配置文件：

{
  "mcpServers": {
    "pico-xr-docs": {
      "command": "G:\\Ai_Agent\\pico-mcp-server\\dist\\pico-xr-docs-mcp.exe",
      "args": [],
      "description": "Windows standalone Pico XR docs MCP server. Target machine does not need Python installed."
    }
  }
}

如果使用 Python 源码运行，可参考 mcp_config.json，并把路径改成当前项目路径。

第 4 步：启动服务器

stdio 模式（用于 Claude Desktop / WorkBuddy，直接通过配置自动启动）：

./dist/pico-xr-docs-mcp.exe

Streamable HTTP 模式（用于远程访问或测试）：

./dist/pico-xr-docs-mcp.exe --port 8000 --host 127.0.0.1

源码模式：

/c/ProgramData/miniconda3/envs/mcpmaker/python.exe server.py
/c/ProgramData/miniconda3/envs/mcpmaker/python.exe server.py --port 8000 --host 127.0.0.1

MCP 工具列表

工具名 功能
search_docs 全文搜索文档（支持中英文关键词、分类过滤、CJK 双字分词）
get_doc 通过文档 ID 获取完整内容
get_doc_by_url 通过 Pico 文档 URL 获取内容
list_categories 列出所有文档分类及数量
list_docs_by_category 按分类列出文档（支持分页）
get_stats 获取知识库统计信息

使用示例

在 AI 助手中：

搜索手柄输入相关文档
→ search_docs(query="手柄 输入")

获取 Unity 渲染优化文档
→ search_docs(query="渲染优化", category="Unity SDK")

列出所有 OpenXR 文档
→ list_docs_by_category(category="OpenXR")

通过 URL 获取文档
→ get_doc_by_url(url="https://developer-cn.picoxr.com/document/unity/input-mapping")

查看知识库总览
→ get_stats()

搜索技巧：中文关键词建议用空格分隔，如 "手势 追踪" 比 "手势追踪" 效果更好。搜索函数会自动将连续中文词拆分为双字组合进行匹配。

文档覆盖范围

分类 内容
Unity SDK 输入追踪、渲染、混合现实、空间音频、平台服务、手势追踪、眼动追踪、全身动捕、空间锚点、空间网格、Building Blocks
Unreal SDK 虚幻引擎 Pico 开发文档、渲染、输入、MR、平台服务
Native SDK 原生 Android/C++ SDK
OpenXR OpenXR 标准接口文档
设备介绍 PICO 4、Neo3、体感追踪器规格
设计指南 VR 交互设计、视觉设计规范、游戏类型设计、移动设计
分发上架 应用审核、发布流程、内容准则、结算打款
安全信息 安全响应与合规

更新文档

重新运行爬虫即可增量更新（已爬取的 URL 会自动跳过）：

/c/ProgramData/miniconda3/envs/mcpmaker/python.exe crawl_docs_v3.py

打包独立 exe

build_exe_windows.bat

或直接使用 mcpmaker 环境：

/c/ProgramData/miniconda3/envs/mcpmaker/python.exe build_exe.py

打包产物：dist/pico-xr-docs-mcp.exe。

已知问题

  • pico-interactive.com 域名的 rtc 页面偶尔超时
  • Crawl4AI 的 js: wait_for 语法在 0.8.6 版本有 bug，当前使用 css:body 替代

About

专用于PicoVR 官网文档的MCP库

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages