内容
# ctxpack-mcp
[](https://github.com/nandemo-ya/ctxpack-mcp/actions/workflows/ci.yml)
[](https://github.com/nandemo-ya/ctxpack-mcp/releases/latest)
[](go.mod)
[](LICENSE)
**适用于 [ctxpack](https://github.com/atani/ctxpack) 的 MCP 服务器，实现面向 AI 代理的 token 感知上下文提取。**
代理在导航、脚本、cookie 横幅和页脚时消耗上下文。ctxpack 去除了这些，并返回带有测量令牌节省的紧凑 Markdown。此服务器将其置于任何 MCP 客户端之前，以便代理可以在读取页面之前打包页面，而不是将原始 HTML 拉入其窗口。
```
MCP 客户端（Claude Code、Codex、Gemini CLI、Cursor 等）
→ ctxpack-mcp （此服务器）
→ ctxpack （CLI，需单独安装）
```
它是一个薄包装。ctxpack 负责提取；此服务器负责进程执行、输入映射和将 ctxpack 的退出代码转换为代理可以采取的错误。
## 要求
- **ctxpack 0.4.0 或更高版本。** 单独安装（参见下文）。0.4.0 是开始报告 JavaScript 渲染页面而不是返回空内容的版本，此服务器依赖于此版本。
- 运行时无需其他内容。服务器是一个单独的静态二进制文件。
## 安装
### Homebrew
```bash
brew install --cask nandemo-ya/tap/ctxpack-mcp
```
该 cask 声明 `depends_on formula: "atani/tap/ctxpack"`，因此这会同时安装两个二进制文件。
### Go
```bash
go install github.com/nandemo-ya/ctxpack-mcp/cmd/ctxpack-mcp@latest
brew install atani/tap/ctxpack # 或参见 ctxpack README 以获取其他选项
```
### 预构建二进制文件
从 [Releases](https://github.com/nandemo-ya/ctxpack-mcp/releases) 下载适用于您平台的存档，并将 `ctxpack-mcp` 放在您的 `PATH` 中。发布了 macOS、Linux（arm64 和 x86_64）和 Windows x64。
## 配置您的 MCP 客户端
每个客户端都运行相同的二进制文件通过 stdio；只有配置文件不同。
### Claude Code
```bash
claude mcp add ctxpack -- ctxpack-mcp # 此项目仅限
claude mcp add -s user ctxpack -- ctxpack-mcp # 每个项目
```
或安装插件，该插件带有相同的配置：
```bash
/plugin marketplace add nandemo-ya/ctxpack-mcp
/plugin install ctxpack@nandemo-ya
/reload-plugins
```
该插件仅包含配置 - 首先安装二进制文件，如上所述。`/reload-plugins` 在不重启会话的情况下注册服务器。确认 `claude mcp list`；该条目显示为 `plugin:ctxpack:ctxpack`。
选择其中一个，而不是两者：插件安装和手动 `claude mcp add ctxpack` 注册相同的服务器两次，代理看到每个工具的两个副本。还要注意，插件以 `mcp__plugin_ctxpack_ctxpack__pack` 而不是 `mcp__ctxpack__pack` 公开工具，如果您根据工具名称编写权限规则，这很重要。
或将其添加到项目中的 `.mcp.json` 中，以便与仓库共享：
```json
{
"mcpServers": {
"ctxpack": {
"command": "ctxpack-mcp"
}
}
}
```
### Codex CLI
在 `~/.codex/config.toml` 中：
```toml
[mcp_servers.ctxpack]
command = "ctxpack-mcp"
```
### Gemini CLI
在 `~/.gemini/settings.json` 中：
```json
{
"mcpServers": {
"ctxpack": {
"command": "ctxpack-mcp"
}
}
}
```
### Cursor
在 `~/.cursor/mcp.json` 或 `.cursor/mcp.json` 中，用于一个项目：
```json
{
"mcpServers": {
"ctxpack": {
"command": "ctxpack-mcp"
}
}
}
```
## 工具
| 工具 | 功能 |
|------|--------------|
| `pack` | 从 URL 或本地 HTML/Markdown 文件中提取紧凑上下文 |
| `pack_content` | 清理您已经拥有的 HTML 或 Markdown，而无需获取 |
| `stats` | 报告累计代币节省记录 |
| `reset_stats` | 清除节省记录 |
`pack` 和 `pack_content` 都接受 `query`（将与任务相关的部分移动到顶部，丢弃其他部分）和 `no_record`（跳过此运行的节省记录）。
结果是 ctxpack 的 JSON，传递时未修改：
```json
{
"ok": true,
"source": { "url": "https://example.com/docs", "fetched_at": "..." },
"title": "示例文档",
"content": { "format": "markdown", "text": "..." },
"stats": {
"raw_html_tokens": 42100,
"final_tokens": 7800,
"saved_tokens": 34300,
"reduction_percent": 81.5
}
}
```
## 错误
失败以工具错误的形式返回，带有代码，以便代理可以对其进行分支：
| 代码 | 含义 | 可重试 |
|------|---------|-----------|
| `runtime_error` | ctxpack 内部的网络或运行时失败 | 是 |
| `usage_error` | 源路径或 URL 错误 | 否 |
| `js_rendering_required` | 页面在具有可读内容之前需要 JavaScript | 否 |
| `timeout` | ctxpack 未在时间内完成 | 是 |
| `unexpected_output` | ctxpack 返回此服务器无法解析的内容，通常是版本不匹配 | 否 |
| `ctxpack_not_installed` | 未找到 ctxpack 二进制文件 | 否 |
| `ctxpack_version_unsupported` | 已安装的 ctxpack 版本低于 0.4.0 | 否 |
`js_rendering_required` 是代理可以自行恢复的错误：使用具有 JavaScript 功能的工具获取页面，然后将渲染的 HTML 传递给 `pack_content`。错误消息说明了这一点。
## 故障排除
**即使已安装“ctxpack 未找到”**。从 GUI 启动的 MCP 客户端（桌面应用程序和 IDE 扩展）使用最小的 `PATH` 启动子进程，通常省略 `/opt/homebrew/bin`。服务器探测通常的安装目录，但可靠的修复方法是直接命名二进制文件：
```json
{
"mcpServers": {
"ctxpack": {
"command": "ctxpack-mcp",
"env": { "CTXPACK_BIN": "/opt/homebrew/bin/ctxpack" }
}
}
}
```
`CTXPACK_BIN` 优先于 `PATH`。如果它指向不可执行的内容，服务器会说明这一点，而不是静默搜索其他位置。
插件的捆绑配置中没有 `env` 块，因此无需编辑。或者，在客户端启动的环境中导出 `CTXPACK_BIN`，或者删除插件并使用上述配置手动注册服务器。
**服务器启动但每次调用都失败**。这是故意的。缺少 ctxpack 不会阻止服务器启动，因此您的客户端可以显示安装说明而不是失败连接。
## 开发
```bash
go build ./...
go test ./... # 不需要 ctxpack；执行层针对固定数据运行
gofmt -l . && go vet ./...
```
集成测试针对真正的 ctxpack 运行，并位于构建标签后面：
```bash
go test -tags integration ./...
```
Claude Code 插件清单有自己的检查：
```bash
claude plugin validate . --strict # 市场
claude plugin validate plugin --strict # 插件
```
它们还会在 CI 中每周针对最小支持的 ctxpack 和最新的上游版本运行。此服务器的合约完全是上游的 JSON 形状和退出代码，因此上游更改可能会破坏它，而此处无需更改。
设计说明在 [`docs/design.md`](docs/design.md) 中。
## 致谢
所有难点都属于 [**ctxpack**](https://github.com/atani/ctxpack) 作者 [@atani](https://github.com/atani)：可读性提取、chrome 过滤、基于查询的章节重新排序、代币估计和累计节省历史记录。此仓库仅添加协议适配器。除非 ctxpack 对您有用，否则请给该项目加星而不是这个。
ctxpack 的路线图提到了原生 MCP 模式。如果上游发布了一个原生 MCP 模式，此项目将贡献到那里或退出 - 保持薄主要是为了让该选项便宜。
有关提取质量的问题 - 错误删除的内容、章节排序异常、代币计数不准确 - 属于上游。有关工具形状、错误代码、客户端配置或二进制发现的问题属于此处。
## License
MIT，匹配 ctxpack。
