couchdb-mcp-server

与CouchDB交互的模型上下文协议服务器

这是一个基于TypeScript的MCP服务器，提供了管理CouchDB数据库和文档的工具。它使AI助手能够通过简单的接口与CouchDB进行交互。

功能

工具

基础工具（适用于所有CouchDB版本）

• createDatabase - 创建一个新的CouchDB数据库

  • 需要参数：dbName
  • 如果数据库不存在，则创建该数据库

• listDatabases - 列出所有CouchDB数据库

  • 返回一个包含数据库名称的数组

• deleteDatabase - 删除一个CouchDB数据库

  • 需要参数：dbName
  • 移除指定的数据库及其所有文档

• createDocument - 在数据库中创建一个新的文档或更新现有文档

  • 必需参数：
    • dbName: 数据库名称
    • docId: 文档ID
    • data: 文档数据（JSON对象）
      • 对于更新操作，需要包含当前文档修订的_rev字段
  • 返回值：
    • 对于新文档：文档ID和新的修订版本
    • 对于更新操作：文档ID和更新后的修订版本
  • 根据_rev字段的存在自动检测是创建还是更新操作

• getDocument - 从数据库中获取文档

  • 必需参数：
    • dbName: 数据库名称
    • docId: 文档ID
  • 返回文档内容

Mango查询工具（仅适用于CouchDB 3.x+）

• createMangoIndex - 创建一个新的Mango索引

  • 必需参数：
    • dbName: 数据库名称
    • indexName: 索引名称
    • fields: 要索引的字段名称数组
  • 创建一个新的索引以实现高效的查询

• deleteMangoIndex - 删除一个Mango索引

  • 必需参数：
    • dbName: 数据库名称
    • designDoc: 设计文档名称
    • indexName: 索引名称
  • 移除现有的Mango索引

• listMangoIndexes - 列出数据库中的所有Mango索引

  • 必需参数：
    • dbName: 数据库名称
  • 返回数据库中所有索引的信息

• findDocuments - 使用Mango查询查询文档

  • 必需参数：
    • dbName: 数据库名称
    • query: Mango查询对象
  • 使用CouchDB的Mango查询语法执行查询

版本支持

服务器会自动检测CouchDB版本并启用相应功能：

• 所有版本：基本的数据库和文档操作
• CouchDB 3.x+：Mango查询支持（索引和查询）

配置

服务器需要CouchDB连接URL和版本。这些可以通过环境变量提供：

COUCHDB_URL=http://username:password@localhost:5984
COUCHDB_VERSION=1.7.2

您可以在项目根目录创建一个`.env`文件来配置这些设置。如果没有提供，默认为`http://localhost:5984`。

## 开发

安装依赖项：
```bash
npm install

构建服务器：

npm run build

开发时自动重建：

npm run watch

安装

通过Smithery安装

要通过Smithery自动安装couchdb-mcp-server到Claude Desktop：

npx -y @smithery/cli install @robertoamoreno/couchdb-mcp-server --client claude

要在Claude Desktop中使用，请添加服务器配置：

在MacOS上：~/Library/Application Support/Claude/claude_desktop_config.json
在Windows上：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "couchdb-mcp-server": {
      "command": "/path/to/couchdb-mcp-server/build/index.js",
      "env": {
        "COUCHDB_URL": "http://username:password@localhost:5984"
      }
    }
  }
}

先决条件

• Node.js 14或更高版本
• 运行中的CouchDB实例
• 如果启用了身份验证，需要正确的CouchDB凭据

调试

由于MCP服务器通过标准I/O通信，调试可能会很困难。我们建议使用MCP Inspector，它作为包脚本提供：

npm run inspector

Inspector将提供一个URL，以便在浏览器中访问调试工具。

错误处理

服务器包括针对常见情况的强大错误处理机制：

• 无效的数据库名称或文档ID
• 数据库已存在/不存在
• 连接问题
• 认证失败
• 无效的文档数据

所有错误都经过适当的格式化并通过MCP协议返回，附带相应的错误代码和消息。