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

You can create a `.env` file in the project root with this configuration. If not provided, it defaults to `http://localhost:5984`.

## Development

Install dependencies:
```bash
npm install

构建服务器:

npm run build

开发时使用自动重建:

npm run watch

安装

通过Smithery安装

要通过Smithery自动为Claude Desktop安装couchdb-mcp-server:

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 服务器通过 stdio 进行通信，调试可能会很困难。我们建议使用 MCP Inspector，它作为一个包脚本提供：

npm run inspector

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

错误处理

服务器为常见情况提供了强大的错误处理：

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

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