couchdb-mcp-server

couchdb-mcp-server

CouchDB とやり取りするための Model Context Protocol サーバーです。

CouchDB のデータベースとドキュメントを管理するツールを提供する、TypeScript ベースの MCP サーバーです。シンプルなインターフェースを通じて、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 プロトコルを通じて返されます。