内容
# Bittlebits MCP 服务器
一个 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，将您的 Bittlebits GEO 分数和重写建议直接带入 AI 代理 — Claude Code、Cursor、VS Code、Codex 或任何兼容 MCP 的客户端。
不再需要在多个窗口之间复制内容，您的代理可以直接拉取 Bittlebits 的建议，并直接在您的代码库中应用这些更改。
---
## 快速开始
```bash
npx @bittlebits.ai/mcp setup
```
这将引导您完成整个过程：
1. **选择您的客户端** — Claude Code、Cursor、VS Code、Codex（任意组合）。
2. **登录** — 一个浏览器窗口将打开；登录 Bittlebits 后，您将完成登录。您的 API 密钥将被获取并缓存在本地 `~/.bittlebits/config.json`。
3. **已连接** — 服务器将被写入每个客户端的配置文件中。重启客户端并开始提问。
无需复制粘贴密钥，也无需手动编辑 JSON。
> 如果您已经拥有 API 密钥，可以跳过浏览器登录：
> `npx @bittlebits.ai/mcp setup --api-key bb_your_key`
---
## 您可以使用 Bittlebits MCP 服务器的功能
连接后，您可以向您的代理提问，例如：
- *"显示 Bittlebits 建议在此页面上更改的内容以及原因。*"
- *"应用 Bittlebits 的建议，重写我的首页副本。*"
- *"哪些指标最弱，我应该先修复哪些？*"
- *"获取我的登陆页面的分数，然后在我的代码库中找到并更新文件。*"
---
## 可用工具
| 工具 | 功能 |
|------|-------------|
| `get_score` | 返回 GEO 指标分数（0-10，每个维度） |
| `get_rewrite` | 返回原始和重写的页面内容，并应用 Bittlebits 建议 |
| `get_url_content` | 返回 Bittlebits 获取的页面的原始 HTML 和 Markdown |
所有工具都接受 `url`（完整页面 URL）或 `url_id`（如果已知 Bittlebits 内部 ID）。结果可能需要几分钟才能生成，初次运行需要 Bittlebits 处理页面。
---
## `setup` 命令
```
npx @bittlebits.ai/mcp setup [选项]
--claude --cursor --vscode --codex 配置特定客户端（跳过菜单）
-p, --project 编写项目范围的配置文件（当前目录）
--global 编写用户全局配置文件
--api-key <key> 使用此密钥代替登录
-y, --yes 非交互式（使用标志/默认值）
```
每个客户端的配置文件写入位置：
| 客户端 | 项目范围 | 全局范围 |
|--------|---------------|--------------|
| Claude Code | `.mcp.json` | `~/.claude.json` |
| Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
| VS Code | `.vscode/mcp.json` | 用户 `mcp.json` |
| Codex | `.codex/config.toml` | `~/.codex/config.toml` |
重新运行 `setup` 是安全的：它会合并到现有的文件中，保留其他 MCP 服务器，并仅更新 Bittlebits 条目。
---
## `launch` 命令
已经运行了 `setup`？使用 `launch` 立即打开一个 AI 会话，并预加载 Bittlebits — 无需手动配置。
```bash
npx @bittlebits.ai/mcp launch
```
该命令会检测您的机器上安装了哪些 AI 客户端（Claude Code、Codex），并打开一个会话。如果找到两个客户端，您将被要求选择一个。
```
npx @bittlebits.ai/mcp launch [选项]
-c, --client <name> 强制使用特定客户端：claude，codex
-p, --prompt <text> 发送初始提示（非交互式/脚本使用）
```
**示例：**
```bash
# 交互式会话，自动检测客户端
npx @bittlebits.ai/mcp launch
# 强制使用 Claude Code
npx @bittlebits.ai/mcp launch --client claude
# 在终端中进行一次性评分
npx @bittlebits.ai/mcp launch --client claude --prompt "获取 nike.com 的 GEO 分数"
```
---
## 手动配置
如果您更喜欢自己动手配置？任何支持 stdio 传输的客户端都可以使用。将 `BITTLEBITS_API_KEY` 设置在环境中，然后运行 `npx bittlebits-mcp` — 在 [bittlebits.ai](https://bittlebits.ai) 的 **设置 → API 密钥** 下找到您的密钥。
**Claude Code（CLI）：**
```bash
claude mcp add --transport stdio bittlebits -e BITTLEBITS_API_KEY=your_key -- npx -y @bittlebits.ai/mcp
```
**Cursor / Claude Code（`.cursor/mcp.json` 或 `.mcp.json`）：**
```json
{
"mcpServers": {
"bittlebits": {
"command": "npx",
"args": ["-y", "@bittlebits.ai/mcp"],
"env": { "BITTLEBITS_API_KEY": "your_key_here" }
}
}
}
```
**VS Code（`.vscode/mcp.json`）：**
```json
{
"servers": {
"bittlebits": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@bittlebits.ai/mcp"],
"env": { "BITTLEBITS_API_KEY": "your_key_here" }
}
}
}
```
**Codex（`~/.codex/config.toml`）：**
```toml
[mcp_servers.bittlebits]
command = "npx"
args = ["-y", "@bittlebits.ai/mcp"]
[mcp_servers.bittlebits.env]
BITTLEBITS_API_KEY = "your_key_here"
```
---
## 先决条件
- Node.js 18+
- 一个 [Bittlebits](https://bittlebits.ai) 账户
---
## 开发
```bash
git clone https://github.com/bittlebitsai/bittlebits-mcp
cd bittlebits-mcp # 本地开发仍然使用文件夹名称
npm install
npm run dev # 使用 tsx 运行服务器（无构建步骤）
npm run build # 编译到 dist/
# 尝试设置流程
node dist/index.js setup
```
环境变量：
- `BITTLEBITS_API_KEY` — 服务器模式的 API 密钥（跳过浏览器登录）。
---
## 提示
- **具体说明要保留的内容**。如果品牌声音很重要，请告诉您的代理：*"应用建议，但保留随意的对话语气。"*
- **按部分处理较长的页面** — 更容易审查。
- **在编辑后重新评分**。在更新页面后，触发一个新的 Bittlebits 分数，看看指标是否有所改善。
