星战科技xingzhan.cloud
返回市场
mcp服务器- Couchbase

mcp服务器- Couchbase

作者：zx80860 星标更新：2025-05-21
安装使用来源：spider==github.com

项目介绍

Couchbase MCP Server (TypeScript/Bun 版本)

由 Bun 提供支持 TypeScript Couchbase 咨询 DeepWiki

这是一个基于 Couchbase 的 MCP（模型上下文协议）服务器实现，允许大型语言模型（LLMs）直接与 Couchbase 集群交互。

功能

工具

数据库操作

  • get_scopes_and_collections: 列出指定存储桶中的所有范围和集合
  • get_schema_for_collection: 获取特定集合的结构和模式
  • get_document_by_id: 根据ID从指定的范围和集合中检索文档
  • upsert_document_by_id: 在指定的范围和集合中创建或更新文档
  • delete_document_by_id: 从指定的范围和集合中删除文档
  • run_sql_plus_plus_query: 在指定的范围内执行 SQL++ 查询

查询分析

  • get_detailed_indexes: 获取关于数据库索引的详细信息
  • get_detailed_prepared_statements: 查看关于预编译语句的详细信息
  • get_system_vitals: 监控系统健康指标
  • get_system_nodes: 查看集群节点的信息
  • get_most_expensive_queries: 识别资源消耗最高的查询
  • suggest_query_optimizations: 获取查询性能改进的建议
  • analyze_document_structure: 分析并理解文档结构模式
  • get_document_type_examples: 查看不同类型的示例文档
  • get_prepared_statements: 列出所有预编译语句
  • get_indexes_to_drop: 识别未使用的或冗余的索引
  • get_completed_requests: 查看已完成的查询请求
  • get_system_indexes: 列出所有系统索引
  • get_primary_index_queries: 识别使用主索引的查询
  • get_largest_result_count_queries: 找到返回结果最多的查询
  • get_largest_result_size_queries: 识别结果大小最大的查询
  • get_most_frequent_queries: 查看最常执行的查询
  • get_longest_running_queries: 识别执行时间最长的查询
  • get_fatal_requests: 查看失败的查询请求

文档管理

  • list_documentation: 列出可用的 MCP 服务器工具和功能文档
  • read_documentation: 阅读特定的文档条目
  • create_documentation: 创建新的工具和功能文档条目
  • delete_documentation: 删除文档条目
  • sync_documentation: 同步和更新现有文档

操作手册管理

  • list_playbooks: 列出可用于数据库操作的操作手册

资源

  • 数据库结构资源：访问和管理数据库结构信息
  • 模式资源：处理集合模式和验证
  • 文档资源：管理文档操作和 CRUD 功能
  • 查询资源：处理 SQL++ 查询操作和结果
  • 查询分析资源：监控和优化查询性能
  • 文档资源：管理工具和功能文档
  • 操作手册资源：管理和执行数据库操作手册

安全特性

  • READ_ONLY_QUERY_MODE: 默认启用设置，防止 SQL++ 查询修改数据
  • 通过基于ID的访问进行安全的文档操作
  • 基于环境配置敏感凭证

先决条件

  • Bun 1.0 或更高版本
  • 运行中的 Couchbase 集群。最简单的方法是使用 Capella 免费层，这是 Couchbase 服务器的完全托管版本。您可以按照 说明 导入一个示例数据集或导入您自己的数据集。
  • 安装了 MCP 客户端，如 Claude Desktop，以连接到 Claude。提供了针对 Claude Desktop 和 Cursor 的说明。也可以使用其他 MCP 客户端。

配置

将仓库克隆到本地机器。

git clone https://github.com/yourusername/mcp-server-couchbase-bun.git
cd mcp-server-couchbase-bun

安装依赖项：

bun install

构建 TypeScript 项目：

bun run build

根据示例创建 .env 文件：

cp .env.example .env
# 使用您的 Couchbase 凭证编辑 .env

MCP 客户端的服务器配置

这是针对 Claude Desktop、Cursor 和 Windsurf Editor 等 MCP 客户端的配置。

{
  "mcpServers": {
    "couchbase-capella-mcp": {
      "command": "bun",
      "args": [
        "/path/to/your/mcp-server-couchbase/dist/index.js",
        "--transport",
        "stdio"
      ],
      "env": {
        "COUCHBASE_URL": "couchbases://your-cluster-url",
        "COUCHBASE_USERNAME": "your-username",
        "COUCHBASE_PASSWORD": "your-password",
        "COUCHBASE_BUCKET": "your-bucket",
        "COUCHBASE_SCOPE": "your-scope",
        "COUCHBASE_COLLECTION": "your-collection",
        "LOG_LEVEL": "debug",
        "DOCS_ENABLED": "true",
        "DOCS_BASE_DIR": "/path/to/your/mcp-server-couchbase/docs",
        "DOCS_FILE_EXT": ".md",
        "PWD": "/path/to/your/mcp-server-couchbase",
        "PATH": "/Users/your-username/.bun/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
      },
      "cwd": "/path/to/your/mcp-server-couchbase"
    }
  }
}

注意：将所有 /path/to/your/mcp-server-couchbase 替换为实际克隆的仓库路径。同时，更新环境变量以包含您具体的 Couchbase 集群详情。

服务器可以通过环境变量进行配置。支持以下变量：

Couchbase 连接设置

  • COUCHBASE_URL: 连接到 Couchbase 集群的连接字符串
  • COUCHBASE_USERNAME: 用于连接的存储桶的用户名
  • COUCHBASE_PASSWORD: 用户名的密码
  • COUCHBASE_BUCKET: 服务器将访问的存储桶名称
  • COUCHBASE_SCOPE: 存储桶内的范围
  • COUCHBASE_COLLECTION: 范围内的集合
  • CN_ROOT: Couchbase 配置的根目录（默认：'/usr/src'）

MCP 服务器设置

  • MCP_SERVER_NAME: MCP 服务器实例的名称
  • MCP_TRANSPORT: 使用的传输模式（stdio 或 sse）
  • FASTMCP_PORT: SSE 传输模式的端口号（默认：8080）
  • READ_ONLY_QUERY_MODE: 设置是否允许 SQL++ 查询修改数据（默认：true）
  • LOG_LEVEL: 日志级别（例如："debug"，"info"，"warn"，"error"）

文档设置

  • DOCS_ENABLED: 启用/禁用文档功能
  • DOCS_BASE_DIR: 文档文件的基本目录
  • DOCS_FILE_EXT: 文档文件的扩展名

操作手册设置

  • PLAYBOOKS_ENABLED: 启用/禁用操作手册功能
  • PLAYBOOKS_BASE_DIR: 操作手册文件的基本目录
  • PLAYBOOKS_FILE_EXT: 操作手册文件的扩展名

系统设置

  • PWD: MCP 服务器的工作目录

运行服务器

可以直接运行服务器：

# 开发模式（直接 TypeScript）
bun run dev

# 生产模式（编译后的 JavaScript）
bun run start

对于 SSE 传输模式：

# 开发模式（直接 TypeScript）
bun run dev:sse

# 生产模式（编译后的 JavaScript）
bun run start:sse

客户端设置说明

针对 Claude Desktop、Cursor 和 Windsurf Editor 的设置说明与原始 Python 版本相同，只需将命令更改为使用 bun 而不是 uv。

SSE 服务器模式

可以选择在 服务器发送事件（SSE） 传输模式下运行 MCP 服务器。

使用方法

默认情况下，MCP 服务器将在端口 8080 上运行，但可以使用 FASTMCP_PORT 环境变量进行配置。

bun run dist/mcp_server.js --connection-string='<couchbase_connection_string>' --username='<database_username>' --password='<database_password>' --bucket-name='<couchbase_bucket_to_use>' --read-only-query-mode=true --transport=sse

服务器将在 http://localhost:8080/sse 上可用。这可以在支持 SSE 传输模式的 MCP 客户端中使用。

大型语言模型相关的风险

  • 使用大型语言模型及相关技术涉及风险，包括可能产生不准确或有害的结果。
  • Couchbase 不审查或评估此类输出的质量或准确性，这些输出可能不代表 Couchbase 的观点。
  • 您独自负责确定是否使用大型语言模型及相关技术，并遵守任何许可条款、使用条款以及您组织关于使用这些技术的政策。

TypeScript 实现说明

此实现相比原始 Python 版本具有以下优势：

  1. 类型安全性：所有函数、参数和返回值都有强类型
  2. 开发者体验：更好的 IDE 支持，包括自动完成和内联文档
  3. 性能：Bun 运行时为 JavaScript/TypeScript 应用程序提供出色的性能

故障排除提示

  • 确保配置中的 MCP 服务器仓库路径正确。
  • 验证 Couchbase 连接字符串、数据库用户名、密码和存储桶名称是否正确。
  • 如果使用 Couchbase Capella，请确保集群对运行 MCP 服务器的机器是 可访问的。
  • 确认数据库用户具有访问指定存储桶的适当权限。
  • 确认 Bun 正确安装且可访问。
  • 检查日志是否有任何错误或警告，这些可能指示 MCP 服务器的问题。

支持策略

我们非常感谢您对这个项目的兴趣！ 此项目是由社区维护的，这意味着它没有官方的支持团队。

如果您需要帮助、发现了一个错误或希望贡献改进，最好的方式是在这里——通过 打开一个 GitHub 问题 来进行。 我们的支持门户无法协助与此项目相关的要求，因此我们恳请您所有的询问都留在 GitHub 内。

您的合作有助于我们共同前进——谢谢！