couchdb-mcp-server

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 协议返回，同时包含相应的错误代码和消息。