couchdb-mcp-server

🚀 CouchDB-MCP-Server

CouchDB-MCP-Server是一个用于与CouchDB交互的模型上下文协议（MCP）服务器。它基于TypeScript构建，为管理CouchDB数据库和文档提供了一系列实用工具，能让AI助手通过简单接口与CouchDB进行交互。

🚀 快速开始

服务器需要CouchDB连接URL和版本信息，可通过环境变量提供：

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

你可以在项目根目录创建一个.env文件，将上述配置信息写入其中。若未提供相关信息，默认的连接地址为 http://localhost:5984。

✨ 主要特性

工具

基础工具（所有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：要索引的字段数组
  • 功能：创建新的Mango索引，以实现高效的查询操作。
• deleteMangoIndex - 删除Mango索引
  • 必需参数：
    • dbName：数据库名称
    • designDoc：设计文档名称
    • indexName：索引名称
  • 功能：移除现有的Mango索引。
• listMangoIndexes - 列出数据库中的所有Mango索引
  • 必需参数：dbName（数据库名称）
  • 返回值：有关所有索引的信息。
• findDocuments - 使用Mango查询文档
  • 必需参数：
    • dbName：数据库名称
    • query：Mango查询对象
  • 功能：执行CouchDB的Mango查询语法进行文档查询。

版本支持

服务器会自动检测CouchDB版本，并根据版本情况启用相应功能：

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

📦 安装指南

通过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

配置内容如下：

{
  "servers": {
    "couchdb-mcp-server": {
      "url": "http://localhost:4000",
      "username": "admin",
      "password": "password"
    }
  }
}

💻 使用示例

开发

安装依赖

npm install

构建服务器

npm run build

带有自动重建的开发

npm run watch

🔧 技术细节

服务器具备强大的错误处理功能，可针对以下常见情况进行处理：

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

所有错误都会通过MCP协议以适当的状态码和消息格式返回。