内容
# fumasignal-mcp
> 🚀 一个MCP服务器，允许AI助手搜索和阅读 **任何 [Fumadocs](https://fumadocs.dev)** 文档站点。
[](https://www.npmjs.com/package/fumasignal-mcp)
[](https://github.com/Manaiakalani/fumasignal-mcp/actions/workflows/ci.yml)
[](LICENSE)
指向一个部署的Fumadocs网址（或本地Fumadocs仓库），您的AI助手将获得七种工具来搜索、列表和阅读文档 — 通过 [模型上下文协议](https://modelcontextprotocol.io)。
名称是对Fumadocs作者 **fuma-nama** （*fuma* = 煙 = "smoke"）的致敬，以及MCP服务器存在于向AI客户端和外部工具发送信号的事实。烟雾信号在远处传递消息 — 正是这个服务器为您提供的文档。
> ⚠️ 这是一个非官方的第三方项目。与Fumadocs项目无关。
---
## 功能
- 🔌 **零设置远程模式** — 给它任意部署的Fumadocs网址即可。
- 💾 **本地模式** — 指向磁盘上的Fumadocs仓库，用于离线/预部署使用。
- 🔎 **7种工具**：`search_docs`、`list_pages`、`get_page`、`get_section`、`get_toc`、`get_meta`、`get_llms_txt`。
- 📦 **单个二进制文件**：`npx -y fumasignal-mcp --url https://your-docs.com`。
- 🔒 **只读** — 永远不会改变您的文档。
- 🧪 **经过充分测试** — 28+个单元测试，搜索/站点地图/HTML路径的固定测试。
---
## 快速开始
### Claude Desktop / Claude 代码
将以下内容添加到您的 `claude_desktop_config.json` 文件中（macOS上的 `~/Library/Application Support/Claude/claude_desktop_config.json`，Windows上的 `%APPDATA%/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"fumadocs": {
"command": "npx",
"args": ["-y", "fumasignal-mcp", "--url", "https://fumadocs.dev"]
}
}
}
```
重启Claude Desktop。您将看到七种可用的 `fumadocs__*` 工具。
### Cursor
在 `~/.cursor/mcp.json` 中（或通过IDE设置）：
```json
{
"mcpServers": {
"fumadocs": {
"command": "npx",
"args": ["-y", "fumasignal-mcp", "--url", "https://fumadocs.dev"]
}
}
}
```
### VS Code（带有GitHub Copilot Chat / Continue）
将以下内容添加到 `.vscode/mcp.json`：
```json
{
"servers": {
"fumadocs": {
"type": "stdio",
"command": "npx",
"args": ["-y", "fumasignal-mcp", "--url", "https://fumadocs.dev"]
}
}
}
```
### Continue.dev
在 `~/.continue/config.json` 中：
```json
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "npx",
"args": ["-y", "fumasignal-mcp", "--url", "https://fumadocs.dev"]
}
}
]
}
}
```
> 将 `https://fumadocs.dev` 替换为您自己的Fumadocs站点网址。多个站点？在不同的键下运行多个实例（`fumadocs`、`myproduct-docs`等）。
---
## 工具
| 工具 | 功能 | 必需输入 |
|---|---|---|
| `search_docs` | 通过站点的Orama API进行全文搜索 | `query` |
| `list_pages` | 列出所有已知的文档页面，可选按URL前缀过滤 | _(无)_ |
| `get_page` | 获取页面的完整Markdown内容 | `ref` |
| `get_section` | 按标题锚点获取页面的一个部分 | `ref`、`anchor` |
| `get_toc` | 列出页面的标题（带锚点） | `ref` |
| `get_meta` | 以JSON格式返回前言/页面元数据 | `ref` |
| `get_llms_txt` | 获取 `llms.txt`（或 `llms-full.txt` 如果 `full: true`） | _(无)_ |
`ref` 接受URL路径（`/docs/getting-started`）、绝对同主机URL或文档前缀下的slug。
---
## CLI标志
```text
-u, --url <url> 部署的Fumadocs站点的基本网址
-l, --local <path> 本地Fumadocs项目根路径
--search-path <path> 搜索API路径（默认：/api/search）
--docs-prefix <path> 文档页面的URL前缀（默认：/docs）
--content-dir <path> 本地内容/文档目录（默认：content/docs）
--auth-header <val> 授权头（例如 "Bearer xxx"）
--cache-ttl <ms> 远程响应的缓存TTL（默认：300000）
-v, --version 打印版本
-h, --help 显示帮助
```
每个标志也从相应的 `FUMASIGNAL_*` 环境变量中读取（`FUMASIGNAL_URL`、`FUMASIGNAL_LOCAL`、`FUMASIGNAL_AUTH_HEADER`、`FUMASIGNAL_CONTENT_DIR`）。
### 示例
```bash
# 远程模式（默认）
npx -y fumasignal-mcp --url https://fumadocs.dev
# 本地模式（在文档项目内部或旁边运行）
npx -y fumasignal-mcp --local ./my-docs-site
# 自定义前缀（适用于站点将文档放在 /handbook 而不是 /docs）
npx -y fumasignal-mcp --url https://acme.com --docs-prefix /handbook
# 经过身份验证的文档站点
npx -y fumasignal-mcp --url https://internal.docs.acme.com \
--auth-header "Bearer $DOCS_TOKEN"
```
---
## 工作原理
### 远程模式
1. **搜索** → 调用站点的Orama搜索API（默认为 `/api/search`）。处理数组和 `{hits:[{document}]}` 响应格式。
2. **列出页面** → 获取 `/sitemap.xml` 并按 `--docs-prefix` 过滤。
3. **获取页面** → 首先尝试 `<url>.md`、`<url>.mdx` 和 `<url>/raw`。如果不存在，则回退到抓取渲染的HTML并通过 [Turndown](https://github.com/mixmark-io/turndown) 将 `<article>` / `<main>` 内容转换为Markdown。
4. **llms.txt** → 获取 `/llms.txt` 或 `/llms-full.txt`。
响应在内存中缓存，默认TTL为5分钟。
### 本地模式
遍历 `<root>/content/docs/**/*.{md,mdx}` 并通过 [gray-matter](https://github.com/jonschlinkert/gray-matter) 解析前言。`index.{md,mdx}` 映射到文档根目录。搜索使用基于标题权重的令牌评分。
---
## 兼容性
- **Node.js:** 20+
- **Fumadocs:** 已针对默认的Orama搜索API和标准站点地图布局进行测试。多文档站点通过 `search_docs` 上的 `tag` 参数支持 `tag` 过滤。
- **MCP客户端:** 任何支持STDIO MCP的客户端 — Claude Desktop、Claude Code、Cursor、VS Code（Copilot Chat / Continue）、Zed、Cline等。
---
## 故障排除
**"Failed to fetch sitemap.xml"**
站点可能不公开 `/sitemap.xml`。您仍然可以使用 `search_docs` 和 `get_page`；只有 `list_pages` 需要站点地图。
**"Search request failed: 404"**
如果站点使用非默认路径，请传递 `--search-path`（例如 `--search-path /api/v2/search`）。
**HTML抓取返回垃圾**
一些Fumadocs站点已经通过 `<url>.md` 暴露了markdown — 这是首选路径。如果您的站点没有这样做，HTML抓取会剥去 `nav`/`aside`/`header`/`footer` 并转换最大的 `<article>` 元素。欢迎为特定站点的适配器提交PR。
**工具在我的客户端中不显示**
运行 `npm run inspector`（或 `npx -y @modelcontextprotocol/inspector node ./dist/index.js --url https://fumadocs.dev`）以交互式验证服务器。
---
## 开发
```bash
git clone https://github.com/Manaiakalani/fumasignal-mcp
cd fumasignal-mcp
npm install
npm test # vitest
npm run build # tsup → dist/
npm run inspector # MCP Inspector against dist/
```
欢迎贡献 — 请为非琐碎的更改开启一个问题。
---
## 许可证
[MIT](LICENSE) © Manaiakalani
