内容
# Couchbase MCP 服务器（TypeScript/Bun 版本）
[](https://bun.sh)
[](https://www.typescriptlang.org/)
[](https://www.couchbase.com/)
[](https://deepwiki.com/zx8086/mcp-server-couchbase)
Couchbase 的 MCP 服务器实现，允许大型语言模型直接与 Couchbase 集群交互。
## 功能
### 工具
#### 数据库操作
- `get_scopes_and_collections`：列出指定存储桶中的所有作用域和集合
- `get_schema_for_collection`：获取特定集合的结构和模式
- `get_document_by_id`：从指定作用域和集合中检索 ID 对应的文档
- `upsert_document_by_id`：在指定作用域和集合中创建或更新 ID 对应的文档
- `delete_document_by_id`：从指定作用域和集合中删除 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](https://bun.sh/) 1.0 或更高版本
- 运行中的 Couchbase 集群。最简单的开始方法是使用 [Capella](https://docs.couchbase.com/cloud/get-started/create-account.html#getting-started) 免费层，它是 Couchbase 服务器的完全托管版本。您可以按照 [说明](https://docs.couchbase.com/cloud/clusters/data-service/import-data-documents.html#import-sample-data) 导入其中一个示例数据集或导入您自己的数据。
- 已安装的 [MCP 客户端](https://modelcontextprotocol.io/clients)，例如 [Claude Desktop](https://claude.ai/download)，以将服务器连接到 Claude。提供了 Claude Desktop 和 Cursor 的说明。也可以使用其他 MCP 客户端。
## 配置
将存储库克隆到本地机器。
```bash
git clone https://github.com/yourusername/mcp-server-couchbase-bun.git
cd mcp-server-couchbase-bun
```
安装依赖项：
```bash
bun install
```
构建 TypeScript 项目：
```bash
bun run build
```
根据示例创建 `.env` 文件：
```bash
cp .env.example .env
# 使用您的 Couchbase 凭据编辑 .env
```
### MCP 客户端的服务器配置
这是用于 MCP 客户端（如 Claude Desktop、Cursor、Windsurf Editor）的配置。
```json
{
"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 服务器的工作目录
### 运行服务器
可以直接运行服务器：
```bash
# 开发模式（直接使用 TypeScript）
bun run dev
# 生产模式（编译后的 JavaScript）
bun run start
```
对于 SSE 传输模式：
```bash
# 开发模式（直接使用 TypeScript）
bun run dev:sse
# 生产模式（编译后的 JavaScript）
bun run start:sse
```
### 客户端设置说明
Claude Desktop、Cursor 和 Windsurf Editor 的设置说明与原始 Python 版本相同，只需将 `uv` 替换为 `bun` 即可。
### SSE 服务器模式
有一个选项可以以 [Server-Sent Events (SSE)](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse) 传输模式运行 MCP 服务器。
#### 用法
默认情况下，MCP 服务器将在端口 8080 上运行，但可以使用 `FASTMCP_PORT` 环境变量进行配置。
```bash
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 客户端中使用。
### 与 LLMs 相关的风险
- 使用大型语言模型和类似技术涉及风险，包括潜在的不准确或有害输出。
- Couchbase 不会审查或评估此类输出的质量或准确性，此类输出可能不能反映 Couchbase 的观点。
- 您完全负责确定是否使用大型语言模型和相关技术，并遵守任何许可条款、使用条款和您的组织管理您使用这些技术的政策。
## TypeScript 实现说明
此实现比原始 Python 版本具有几个优势：
1. **类型安全**: 所有函数、参数和返回值都具有强类型
2. **开发体验**: 更好的 IDE 支持，带有自动补全和内联文档
3. **性能**: Bun 运行时为 JavaScript/TypeScript 应用程序提供了出色的性能
## 故障排除提示
- 确保您的 MCP 服务器存储库路径在配置中正确。
- 验证您的 Couchbase 连接字符串、数据库用户名、密码和存储桶名称是否正确。
- 如果使用 Couchbase Capella，请确保集群可以从运行 MCP 服务器的机器访问。
- 检查数据库用户是否具有访问指定存储桶的适当权限。
- 确认 Bun 已正确安装并可访问。
- 检查日志中是否有任何错误或警告，这些错误或警告可能指示 MCP 服务器存在问题。
---
## 支持政策
我们真正感谢您对该项目的兴趣！
该项目是 **社区维护的**，这意味着它 **不受官方支持**，不受支持团队的支持。
如果您需要帮助、发现了错误或希望贡献改进，最好的地方是这里 - 通过 [打开 GitHub 问题](https://github.com/yourusername/mcp-server-couchbase-bun/issues)。
我们的支持门户无法协助此项目的请求，因此我们请您将所有查询保留在 GitHub 上。
您的合作帮助我们共同进步 - 谢谢！
