内容
# Pinax
<p align="center">
<img src="assets/banner.svg" alt="Pinax — 任意文档站点转为本地 MCP 服务器" width="520">
</p>
[](https://github.com/desmondsanctity/pinax/actions/workflows/ci.yml)
[](https://pkg.go.dev/github.com/desmondsanctity/pinax)
[](https://goreportcard.com/report/github.com/desmondsanctity/pinax)
[](LICENSE)
[](https://github.com/desmondsanctity/pinax/releases)
> 将任意文档站点转为本地 MCP 服务器，操作时间不到一分钟。
**在线站点：** [pinax.dev](https://pinax.dev)
<p align="center">
<img src="assets/demo.gif" alt="Pinax demo — banner, list indexed docs, serve MCP over HTTP" width="800">
</p>
Pinax 是一个小型 Go CLI 工具，它可以爬取公共文档站点，索引其结构，并将其暴露给任何 [Model Context Protocol](https://modelcontextprotocol.io) 客户端（Claude Desktop、Cursor、Windsurf、Copilot、自定义代理），作为四个专注的工具。页面按需实时获取，因此代理看到的内容始终是文档站点今天提供的内容 — 没有过时的嵌入式内容，不需要重新索引管道。
## 为什么
编码代理会产生已废弃的 API，因为它们的训练数据有截止日期。Pinax 为代理提供了一个实时的窗口，可以看到开发人员今天实际针对的文档。
- 零基础设施 — 单个静态二进制文件，无守护进程，无云账户
- 实时获取，内容协商 `Accept: text/markdown` 和内存会话缓存以及持久化 SQLite 页面缓存
- 通过 `llms.txt` 发现页面，然后是站点地图，然后是有界限的 BFS 爬取
- 四工具代理接口（`list_sections`、`search_pages`、`get_section_pages`、`get_page`）— 无作业管理噪音
- 内置暗色主题日志 UI，在 HTTP 根目录中，您可以看到代理正在调用哪些工具
## 安装
### Homebrew（macOS / Linux）
```sh
brew install desmondsanctity/tap/pinax
```
### 预编译二进制文件
从 [发布页面](https://github.com/desmondsanctity/pinax/releases) 下载适用于您平台的最新版本，并将其放在 `$PATH` 中。
### `go install`
```sh
go install github.com/desmondsanctity/pinax/cmd/pinax@latest
```
### 从源代码编译
需要 Go 1.25 或更高版本。
```sh
git clone https://github.com/desmondsanctity/pinax.git
cd pinax
make build
# 二进制文件位于 ./bin/pinax — 将其放在 $PATH 中
```
## 快速开始
```sh
# 1. 从精选目录中索引文档站点…
pinax add stripe
# …或任意 URL
pinax add https://docs.convex.dev
# 2. 列出已索引的内容
pinax list
# 3. 通过 stdio 提供所有已索引的站点（MCP 客户端启动时）
pinax serve
# …或固定一个站点：pinax serve stripe
# 或通过 HTTP 提供服务，带有日志查看器
pinax serve --http --port 8423
# → http://localhost:8423/ （日志 UI，具有每个文档的筛选）
# → http://localhost:8423/mcp （可流式传输的 HTTP MCP 端点）
# → http://localhost:8423/sse （旧版 SSE）
# 4. 检查清单的健康状况（页面计数漂移、平均文本等）
pinax doctor stripe
```
在统一模式下，每个工具都接受一个可选的 `docs` 参数，以限定为单个站点；省略它以跨每个已索引的清单进行搜索。调用 `list_docs` 以查看已加载的内容。
### 目录
`pinax add <name>` 通过一个小型内置目录解析（Stripe、React、Next.js、Convex、Anthropic、OpenAI、Supabase、Tailwind、FastAPI、Django、Go 标准库、Kubernetes、Vercel、Modal、MCP）。任何包含 `://`、`.` 或 `/` 的内容仍被视为 URL，因此现有脚本保持正常工作。
```sh
pinax catalog list # 显示每个目录条目及其标签 + URL
pinax catalog refresh # 从 GitHub 获取最新的目录（缓存在 ~/.pinax/ 下）
```
将 `PINAX_CATALOG_URL` 设置为指向私有/分叉目录的 `refresh`。
### 连接到 MCP 客户端
相同的 stdio 命令适用于每个 MCP 兼容客户端。将服务器名称替换为您在 `pinax add` 中使用的名称。
<details>
<summary><b>Claude Desktop</b> — <code>~/Library/Application Support/Claude/claude_desktop_config.json</code></summary>
```jsonc
{
"mcpServers": {
"convex-docs": {
"command": "pinax",
"args": ["serve", "convex-docs"],
},
},
}
```
或让 Pinax 为您打印代码片段：`pinax config claude --project`。
</details>
<details>
<summary><b>Claude Code</b> — 从 CLI 注册</summary>
```sh
claude mcp add convex-docs -- pinax serve convex-docs
```
</details>
<details>
<summary><b>Cursor</b> — <code>~/.cursor/mcp.json</code>（或项目中的 <code>.cursor/mcp.json</code>）</summary>
```jsonc
{
"mcpServers": {
"convex-docs": {
"command": "pinax",
"args": ["serve", "convex-docs"],
},
},
}
```
</details>
<details>
<summary><b>Windsurf</b> — <code>~/.codeium/windsurf/mcp_config.json</code></summary>
```jsonc
{
"mcpServers": {
"convex-docs": {
"command": "pinax",
"args": ["serve", "convex-docs"],
},
},
}
```
</details>
<details>
<summary><b>Cline（VS Code）</b> — <code>cline_mcp_settings.json</code></summary>
```jsonc
{
"mcpServers": {
"convex-docs": {
"command": "pinax",
"args": ["serve", "convex-docs"],
},
},
}
```
</details>
## 命令
```
pinax add <url|目录名称> [--name 名称] [--exclude 模式 ...] [--max-pages N] [--no-preflight]
pinax list
pinax remove <名称>
pinax refresh <名称> [--rebuild-index]
pinax search <名称> <查询>
pinax doctor [<名称>...] [--json]
pinax serve [<名称>] [--http] [--port N]
pinax cache clear [--older-than 时长]
pinax catalog list|refresh
pinax config claude [--project] [--split] [--force]
```
## MCP 工具
每个工具都接受一个可选的 `docs` 参数，该参数限定调用为单个清单，当统一服务器托管多个清单时。
| 工具 | 描述 | 参数 |
| ------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `list_docs` | 已加载清单的名称、基本 URL 和页面计数 | 无 |
| `list_sections` | 按顶级部分分组的 URL 路径，附带页面计数 | `docs?: 字符串` |
| `search_pages` | URL 路径、标题和部分名称的 BM25 排名搜索，附带子字符串和模糊备用 | `查询: 字符串`，`限制?: 数字`，`docs?: 字符串` |
| `get_section_pages` | 部分前缀下的所有页面 | `部分: 字符串`，`docs?: 字符串` |
| `get_page` | 实时获取页面；返回干净的提取 Markdown | `网址: 字符串` |
## 项目布局
```
cmd/pinax/ CLI 入口点和参数解析器
internal/buildinfo/ 版本/用户代理，共享于 CLI 和 MCP 服务器
internal/crawler/ 发现：llms.txt 探测，站点地图解析器，BFS，平台检测
internal/extractor/ HTML/Markdown → 干净的 Markdown
internal/manifest/ 原子 JSON 清单 + ~/.pinax/servers/ 中的 BM25 索引
internal/cache/ SQLite 页面缓存（WAL，读取时应用 TTL）
internal/logger/ SQLite 工具调用日志存储和 HTML 日志查看器
internal/mcp/ 统一 MCP 服务器，传输（stdio + 可流式传输的 HTTP + SSE），工具，中间件
internal/preflight/ 内容密度检查，控制 `pinax add`
internal/doctor/ `pinax doctor` 使用的健康诊断
```
## 开发
```sh
make build # 构建 ./bin/pinax
make test # go test -race ./...
make lint # golangci-lint（需要 Go 1.25+）
make vulncheck # govulncheck
make vet # go vet ./...
make fmt # gofmt -s -w .
make test-integration # 构建标签的网络测试
```
## 限制
- JS 渲染的站点（Mintlify，readme.io）仅在它们公开可用的 `llms.txt` 或站点地图时受支持。没有服务器渲染内容的纯 SPA 外壳将产生薄页面。
- `search_pages` 是带有模糊备用的 token-AND 子字符串匹配。
- 没有预定的重新爬取 — 使用 `pinax refresh <名称>`，和 `pinax doctor` 来检测漂移。
- 私有文档没有身份验证。
## 贡献
欢迎拉取请求。参见 [`CONTRIBUTING.md`](CONTRIBUTING.md) 以了解设置、编码约定和 PR 检查清单。参与即表示您同意 [行为准则](CODE_OF_CONDUCT.md)。
## 安全
请通过 [GitHub 安全公告](https://github.com/desmondsanctity/pinax/security/advisories/new) 报告漏洞，而不是公开的问题。有关完整政策，请参见 [SECURITY.md](SECURITY.md)。
## 许可证
[MIT](LICENSE) © Pinax 贡献者
