Gitbook MCP Proxy

GitBook MCP代理

GitBook MCP的OAuth风格身份验证代理，具有自定义JWT身份验证和安全凭据存储。

 ](https://nodejs.org)

一个本地代理服务器，使AI助手（Cursor、Claude Desktop等）能够通过MCP（模型上下文协议）从后端使用自定义JWT身份验证访问您的GitBook文档。

特性

✨ 双重运输支持 -MCP的HTTP服务器模式或stdio传输 ✨ 自动端口选择 -如果使用默认端口，则自动查找可用端口 ✨ 符合MCP的凭证存储 -使用AES-256-GCM进行静态加密 ✨ 平台特定应用支持 -遵循MCP生态系统标准 ✨ OAuth风格身份验证 -基于浏览器的安全授权流 ✨ 令牌持久性 -使用加密存储重新启动后仍能生存 ✨ 自动打开浏览器 -自动打开授权URL ✨ 自动重定向跟踪 -处理HTTP 3xx重定向 ✨ 多方法身份验证 -将JWT作为查询参数和cookie发送 ✨ LaunchDarkly集成 -转发自适应内容的功能标志 ✨ 详细日志记录 -请求跟踪、身份验证上下文、安全信息

运作原理

┌─────────────────────────────────────────────────────────┐
│  1. Start proxy → generates session ID                  │
│  2. Browser opens → authenticate with your backend      │
│  3. Backend generates JWT → redirects to localhost      │
│  4. Proxy encrypts & stores credentials (MCP compliant) │
│  5. AI makes MCP request → proxy adds JWT + forwards    │
│  6. GitBook validates JWT → returns documentation       │
└─────────────────────────────────────────────────────────┘

先决条件

• Node.js 16+
• 可以生成GitBook JWT令牌的后端
• 启用自定义身份验证的GitBook空间

安装

npm install

配置

创建一个 .env 文件（或设置环境变量）：

# Required: Your authentication backend URL
BACKEND_AUTH_URL=https://your-backend.com

# Required: Your GitBook MCP endpoint
GITBOOK_MCP_URL=https://your-docs.gitbook.io/~gitbook/mcp

# Optional: Proxy port (default: 3333)
MCP_PROXY_PORT=3333

看 .env.example 对于模板。

后端要求

您的后端必须实现一个授权端点，该端点：

1. 对用户进行身份验证 （通过会话cookie或其他方式）
2. 生成GitBook JWT令牌 声明如下：

   {
     "iat": 1738478400,
     "exp": 1739083200,
     "user_context_id": "user-123",
     "organization_context_id": "org-456"
   }

1. 重定向到回调 带有令牌和可选的LaunchDarkly cookie：

   http://localhost:3333/callback?token=JWT&expires=UNIX_TIMESTAMP&ld_cookie={...}

从代理收到的查询参数：

• session -用于记录的唯一会话ID
• callback -本地主机回调URL（必须验证这是本地主机！）

授权端点示例：

public function gitbookMcpAuthorize() {
    // 1. Check authentication
    if (!authenticated()) {
        redirectToLogin();
    }

    // 2. Validate callback is localhost
    $callback = $_GET['callback'];
    if (!isLocalhost($callback)) {
        halt(400, "Callback must be localhost");
    }

    // 3. Generate JWT
    $jwt = generateGitbookJWT($user, $org);
    $expires = time() + 604800; // 1 week

    // 4. Get LaunchDarkly flags (optional)
    $ldFlags = getLaunchDarklyFlags($user);

    // 5. Redirect to callback
    redirect($callback . "?token=$jwt&expires=$expires&ld_cookie=" . urlencode($ldFlags));
}

运输方式

代理支持两种传输模式。GitBook的MCP服务器使用HTTP和服务器发送事件（SSE）传输，这两种模式现在都支持。

HTTP传输（默认）

HTTP传输运行MCP客户端可以连接到的本地HTTP服务器。

npm start
# or
node index.js

代理将自动找到一个从3333开始的可用端口。如果端口3333正在使用中，它将尝试3334、3335等。

HTTP模式的配置：

{
  "mcpServers": {
    "your-gitbook": {
      "url": "http://localhost:3333"
    }
  }
}

标准运输

Stdio传输使用stdin/stdout进行JSON-RPC通信。这是本机MCP协议。

node index.js --stdio

标准配置选项

有两种方法可以为stdio模式配置环境变量：

选项1：在配置中使用env字段（推荐）

直接在MCP配置中传递环境变量：

{
  "mcpServers": {
    "your-gitbook": {
      "command": "node",
      "args": ["/path/to/gitbook-mcp-proxy/index.js", "--stdio"],
      "env": {
        "BACKEND_AUTH_URL": "https://your-backend.com",
        "GITBOOK_MCP_URL": "https://your-docs.gitbook.io/~gitbook/mcp",
        "MCP_PROXY_PORT": "3333"
      }
    }
  }
}

选项2：使用shell包装脚本

包装脚本 start-proxy.sh 包括：

#!/bin/bash
export BACKEND_AUTH_URL="${BACKEND_AUTH_URL:-https://your-backend.com}"
export GITBOOK_MCP_URL="${GITBOOK_MCP_URL:-https://your-docs.gitbook.io/~gitbook/mcp}"
export MCP_PROXY_PORT="${MCP_PROXY_PORT:-3333}"
exec node "$SCRIPT_DIR/index.js" --stdio

使用您的值编辑脚本，然后配置：

{
  "mcpServers": {
    "your-gitbook": {
      "command": "/path/to/gitbook-mcp-proxy/start-proxy.sh"
    }
  }
}

标准模式行为

在stdio模式下，代理充当JSON-RPC到HTTP/SSE的网桥：

1. 接收JSON-RPC 来自stdin（MCP协议）
2. 转发到GitBook 通过HTTP POST和JWT身份验证
3. 解析SSE响应 从GitBook（从中提取JSON data: 线路）
4. 返回JSON-RPC 到stdout

技术细节：

• JSON-RPC消息从stdin读取（每行一条）
• JSON-RPC响应被写入stdout（每行一个）
• 自动解析GitBook中的服务器发送事件（SSE）格式
• 所有日志和诊断都会进入stderr（保持stdout干净）
• 临时HTTP服务器仅针对OAuth回调启动
• 没有端口冲突，因为没有永久HTTP服务器
• 与HTTP模式相同的身份验证和凭据存储

注： Stdio模式适用于大多数MCP操作，但在流操作中可能存在局限性，因为它将持久的SSE连接转换为离散的请求/响应周期。

用法

1.启动代理

npm start

您将看到带有授权URL的输出：

========================================
GitBook MCP Proxy
========================================

✓ Proxy server running
  • Local endpoint: http://localhost:3333
  • Target: https://your-docs.gitbook.io/~gitbook/mcp

🔐 AUTHORIZATION REQUIRED:
   https://your-backend.com/api/gitbook/mcp-authorize?session=abc123...

Opening browser automatically...

2.在浏览器中授权

• 浏览器自动打开（或复制URL）
• 如有需要，请登录您的后端
• 后端生成JWT并重定向回
• 代理加密并保存凭据
• 您将看到“授权成功”

3.配置您的AI助手

光标

打开光标设置： ⌘ + Shift + P → “MCP：配置”

{
  "mcpServers": {
    "your-gitbook": {
      "url": "http://localhost:3333"
    }
  }
}

克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "your-gitbook": {
      "url": "http://localhost:3333"
    }
  }
}

4.使用它！

问你的AI助手一些问题，比如：

• “文档对功能标志有什么说明？”
• “在文档中搜索身份验证示例”
• “显示API参考资料”

凭证存储（MCP规范）

遵循安全凭证存储的模型上下文协议规范：

存储位置（特定于平台）

• macOS: ~/Library/Application Support/gitbook-mcp-proxy/credentials.json
• Linux: ~/.config/gitbook-mcp-proxy/credentials.json
• 视窗: %APPDATA%/gitbook-mcp-proxy/credentials.json

加密

• 算法：AES-256-GCM（经过身份验证的加密）
• 密钥存储：特定于机器的键入 .key 文件
• 权限：0600（仅限所有者读/写）
• 篡改检测：GCM认证标签确保完整性

安全属性

• ✅ 静态加密凭据
• ✅ 特定于机器的加密密钥
• ✅ 自动清理过期令牌
• ✅ 特定于平台的应用程序支持目录
• ✅ 限制文件权限

安全

✅ 符合MCP的凭证存储 -遵循模型上下文协议安全规范 ✅ 静态加密 -AES-256-GCM认证加密 ✅ env变量中没有凭据 -OAuth风格的浏览器授权 ✅ 仅限本地主机回调 -后端必须验证回调URL ✅ 令牌过期 -令牌自动过期 ✅ 仅限HTTPS -所有通过HTTPS进行的GitBook通信 ✅ JWT签名验证 -GitBook通过加密方式验证令牌 ✅ 限制文件权限 -0600在所有凭据文件上

API终点

健康检查

curl http://localhost:3333/health

答复：

{
  "status": "ok",
  "authenticated": true,
  "expires": "2026-02-10T12:00:00.000Z"
}

故障排除

“未设置BACKEND_AUTH_URL”

设置 BACKEND_AUTH_URL 将环境变量发送到您的身份验证后端。

授权超时

代理等待30秒进行授权。在该时间内完成浏览器流，否则MCP请求将超时。

令牌已过期

令牌根据后端的配置过期（通常为1周）。过期时：

1. 浏览器将自动打开以重新授权
2. 或者手动打开控制台中显示的授权URL

端口已在使用中

代理会自动找到一个从3333开始的可用端口。如果端口3333正在使用中，它将尝试3334、3335等。

您还可以：

# Set a specific preferred port
export MCP_PROXY_PORT=3334
npm start

# Or use stdio mode (no permanent HTTP server)
node index.js --stdio

凭据损坏

如果凭据损坏，代理将自动删除它们并提示重新授权。

环境变量

发展

# Install dependencies
npm install

# Run in development
npm start

# Run health check
npm run health

建筑

代理充当AI助手和GitBook之间的桥梁：

1. 认证层：后端的OAuth风格浏览器流
2. 凭据存储：符合MCP的加密存储
3. 请求转发：将JWT身份验证添加到GitBook请求中
4. Cookie管理：转发JWT+LaunchDarkly功能标志
5. 重定向处理：自动遵循HTTP 3xx重定向

相关资源

• 模型上下文协议规范
• GitBook MCP文档
• GitBook自定义身份验证

许可证

MIT许可证-请参阅 许可证 详细信息文件

贡献

欢迎投稿！请打开问题或PR。

作者

Forrest Middleton创作

支持

如果您遇到问题：

1. 检查 故障排除 部分
2. 查看控制台中的日志
3. 在GitHub上打开一个问题