couchbase-guru

Couchbase Guru MCP 服务

一个 MCP 服务，可让大模型通过你的 MCP 客户端搜索 Couchbase 文档。它提供一个工具 ask_couchbase_docs，将你的问题转发给托管的检索增强生成（RAG）文档 Agent，并返回附有来源链接的答案。

无需 Couchbase 集群或凭据。 此服务只与文档 Agent 后端通信，不会访问你的数据。

工具

工具名称	描述
ask_couchbase_docs	通过搜索官方文档，回答有关任何 Couchbase 产品、功能、SDK、服务、教程或示例的问题。返回自然语言答案，随后附上文档来源 URL。

请提出完整且自包含的问题——后端没有对话历史，因此请在相关时注明产品、版本和语言（例如 "How do I create a primary index with the Python SDK in Couchbase Server 7.6?"）。

前提条件

• Python 3.10 或更高版本。
• 已安装 uv，用于运行此服务。
• 一个 MCP 客户端，例如 Claude Desktop、Cursor 或 VS Code。

配置

此服务可以通过预构建的 PyPI 软件包运行，也可以使用 uv 从源代码运行。无需任何配置即可使用——默认使用公开的文档 Agent。

从 PyPI 运行

{
  "mcpServers": {
    "couchbase-guru": {
      "command": "uvx",
      "args": ["couchbase-guru"]
    }
  }
}

如果你已配置其他 MCP 服务，请将此条目添加到现有的 mcpServers 对象中。

从源代码运行

克隆仓库：

git clone https://github.com/Couchbase-Ecosystem/couchbase-guru.git

然后将 MCP 客户端指向它：

{
  "mcpServers": {
    "couchbase-guru": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/couchbase-guru/",
        "run",
        "src/mcp_server.py"
      ]
    }
  }
}

path/to/cloned/repo/couchbase-guru/ 应为你计算机上克隆的仓库路径。别忘了末尾的斜杠。

选项

所有选项均为可选，可通过 CLI 参数或环境变量设置：

CLI 参数	环境变量	描述	默认值
--transport	CB_MCP_TRANSPORT	传输模式：stdio 或 http	stdio
--host	CB_MCP_HOST	HTTP 传输模式的主机	127.0.0.1
--port	CB_MCP_PORT	HTTP 传输模式的端口	8000
--agent-base-url	CB_AGENT_BASE_URL	文档 Agent 后端的基本 URL。设置此项可连接到你自己的可自托管 Agent；若未设置，则使用公开 Agent。	公开 Agent
--agent-ip-salt	CB_AGENT_IP_SALT	用于对客户端 IP 进行假名化处理的密钥盐值（HTTP 传输）。设置共享值可确保多个实例之间的哈希一致；若未设置，则会生成本地盐值。	自动生成

使用以下命令检查已安装的版本：

uvx couchbase-guru --version

自托管文档 Agent

默认情况下，此服务使用共享的公开文档 Agent，因此大多数用户无需进行任何设置。如果你运行自己的 Agent 后端，请将此服务指向它：

uvx couchbase-guru --agent-base-url https://your-agent.example.com

速率限制与隐私

公开 Agent 会实施公平使用速率限制。为支持此功能，此服务会通过 User-Agent 标头向后端发送一个假名化设备标识符：

• stdio：随机生成一个 ID，并将其存储在你计算机上按用户区分的文件中。
• HTTP：对连接 IP 进行加盐单向哈希——绝不会发送原始地址。

MCP 服务本身不会持久化任何问题内容或个人数据。如果你不想共享速率限制信号，请自托管 Agent（见上文）。

特定客户端的配置

Claude Desktop

1. 编辑配置文件（参见 MCP 快速入门指南）：
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
2. 将配置添加到 mcpServers 部分。
3. 重启 Claude Desktop。

日志：~/Library/Logs/Claude（macOS）或 %APPDATA%\Claude\Logs（Windows）。

Cursor

1. 在 Cursor 中，前往 Cursor Settings > Tools & Integrations > MCP Tools。
2. 手动添加配置，或使用一键式在 Cursor 中安装链接。
3. 保存，然后刷新以确认服务已启用。

日志：在底部面板中，点击 Output，然后从下拉菜单中选择 Cursor MCP。

Windsurf Editor

1. 打开 Command Palette > Windsurf MCP Configuration Panel（或 Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers）。
2. 点击 Add Server > Add custom server，然后添加配置。
3. 保存，然后刷新以确认服务已启用。

详情请参阅 Windsurf MCP 文档。

VS Code

1. 在工作区中创建 .vscode/mcp.json（或运行 MCP: Open User Configuration 进行全局配置）。

2. VS Code 使用 servers 作为顶层键（而非 mcpServers）：

   {
     "servers": {
       "couchbase-guru": {
         "command": "uvx",
         "args": ["couchbase-guru"]
       }
     }
   }
   

3. 保存后，使用内联操作列表来启动/停止/管理服务。

详情请参阅 VS Code MCP 文档。

JetBrains IDEs

1. 安装 AI Assistant 或 Junie 插件。
2. 前往 Settings > Tools > AI Assistant or Junie > MCP Server。
3. 点击“+”，添加配置，然后点击 Save，再点击 Apply。

日志：Help > Show Log in Finder (Explorer) > mcp > couchbase-guru。

Streamable HTTP 传输模式

服务可以在 Streamable HTTP 模式下运行，以便多个客户端连接到同一个实例。请先确认你的 MCP 客户端支持此传输方式。

uvx couchbase-guru --transport=http --port=8000

服务将在 http://localhost:8000/mcp 上提供：

{
  "mcpServers": {
    "couchbase-guru-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

此模式不支持授权。

Docker

构建镜像：

docker build -t couchbase-guru .

运行它（默认使用 stdio；无需凭据）：

{
  "mcpServers": {
    "couchbase-guru-docker": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "couchbase-guru"]
    }
  }
}

对于 HTTP 传输，发布端口并设置传输方式：

docker run --rm -i \
  -e CB_MCP_TRANSPORT=http \
  -e CB_MCP_HOST=0.0.0.0 \
  -e CB_MCP_PORT=8000 \
  -p 8000:8000 \
  couchbase-guru

与大模型相关的风险

• 使用大模型及类似技术存在风险，包括可能产生不准确或有害的输出。
• Couchbase 不会审查或评估此类输出的质量或准确性，且此类输出不一定反映 Couchbase 的观点。
• 你应自行决定是否使用大模型及相关技术，并负责遵守任何适用的许可条款、使用条款以及所在组织的政策。

故障排除

• 确认已安装 uv/uvx，并且它们位于 PATH 中。你可能需要在 command 字段中提供 uv/uvx 的绝对路径。
• 如果搜索超时，文档后端可能正忙——请稍后重试。
• 若要排除公共后端的影响，请使用 --agent-base-url 指定自己的 Agent。
• 如果更新仓库后从源代码运行，请运行 uv sync 以刷新依赖项。
• 检查 MCP 客户端的日志（位置见上文），查看是否有错误。

测试

单元测试离线运行（后端使用模拟对象）：

uv sync --extra dev
uv run pytest tests/

集成测试会针对在线 Agent 后端对工具进行端到端测试，需选择启用：

CB_MCP_RUN_INTEGRATION=1 uv run pytest tests/test_docs_tools.py

默认情况下，测试使用公共 Agent；设置 CB_AGENT_BASE_URL 可指定其他后端。

---

👩‍💻 贡献

欢迎贡献！如需报告错误、请求功能或贡献改进，请提交 GitHub issue。

有关开发者环境设置（使用 uv 配置环境、使用 Ruff 进行 lint 和格式化、配置 pre-commit 钩子以及了解项目结构），请参阅 CONTRIBUTING.md。

# Clone and set up
git clone https://github.com/Couchbase-Ecosystem/couchbase-guru.git
cd couchbase-guru

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

---

📢 支持政策

感谢你对本项目的关注！本项目由 Couchbase 社区维护，这意味着我们的支持团队不提供官方支持。我们的工程师会监控并维护此仓库，并尽力解决问题。请通过 GitHub 提交所有咨询。