Chromadb Remote MCP

🚀 ChromaDB Remote MCP Server

このプロジェクトは、AIアシスタント（Claudeなど）がChromaDBにリモートアクセスできるようにする「Streamable HTTP」MCP（Model Context Protocol）サーバーです。モバイルデバイスやリモートの場所からも、意味検索やベクターデータベース操作が可能です。

注意: このプロジェクトはMCP Streamable HTTP（2025-03-26仕様）を使用しています。SSEトランスポートは非推奨です。

한국어 문서

🚀 クイックスタート

ワンコマンドインストール

curl -fsSL https://raw.githubusercontent.com/meloncafe/chromadb-remote-mcp/release/scripts/install.sh | bash

このコマンドを実行すると、以下のことが行われます。

1. docker-compose.yml と .env.example がダウンロードされます。
2. Docker Composeコマンド (docker-compose または docker compose) が自動検出されます。
3. 安全な認証トークンが自動生成されます（オプション）。
4. ChromaDBのデータ保存場所が設定されます（Dockerボリューム、ローカルディレクトリ、またはカスタムパス）。
5. Dockerイメージがダウンロードされます。
6. 認証トークンと接続URLが表示されます。

手動インストール

オプション1: Docker（推奨 - 事前構築済みイメージ）

# 設定ファイルをダウンロード
mkdir chromadb-remote-mcp && cd chromadb-remote-mcp
curl -O https://raw.githubusercontent.com/meloncafe/chromadb-remote-mcp/release/docker-compose.yml
curl -O https://raw.githubusercontent.com/meloncafe/chromadb-remote-mcp/release/.env.example

# 環境を設定
cp .env.example .env
# .envを編集して以下を設定
#   - MCP_AUTH_TOKEN（以下のトークン生成方法を参照）
#   - PORT（デフォルト: 8080）
#   - CHROMA_DATA_PATH（デフォルト: chroma-data）

# サービスを起動
docker compose up -d
# または: docker-compose up -d（古いバージョンの場合）

# ヘルスチェック
curl http://localhost:8080/health

# ログを表示
docker compose logs -f

オプション2: ソースからビルド

# リポジトリをクローン
git clone https://github.com/meloncafe/chromadb-remote-mcp.git
cd chromadb-remote-mcp

# 環境を設定
cp .env.example .env
# .envを自分の設定で編集

# docker-composeで起動（ソースからイメージをビルド）
docker compose -f docker-compose.dev.yml up -d
# または: docker-compose -f docker-compose.dev.yml up -d（古いバージョンの場合）

オプション3: ローカル開発

# クローンしてインストール
git clone https://github.com/meloncafe/chromadb-remote-mcp.git
cd chromadb-remote-mcp
yarn install

# 環境を設定
cp .env.example .env
# .envファイルを編集

# ビルドして実行
yarn build
yarn start

安全なトークンの生成

本番環境では、.env の MCP_AUTH_TOKEN に安全なトークンを生成して設定してください。

# 方法1: Node.js（推奨）
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

# 方法2: OpenSSL
openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

生成されたトークンをコピーして、.env ファイルに貼り付けます。

MCP_AUTH_TOKEN=your-generated-token-here

サーバーエンドポイント

• MCP: http://localhost:8080/mcp（Caddyプロキシ経由）
• ヘルスチェック: http://localhost:8080/health
• ChromaDB API: http://localhost:8080/api/v2/*
• Swagger UI: http://localhost:8080/docs

✨ 主な機能

このリモートMCPサーバーにより、すべてのClaudeクライアント（デスクトップ、コード、モバイル）が同じセルフホスト型ChromaDBインスタンスにアクセスできます。

• デバイス間での共有メモリ - すべてのClaudeクライアントが同じChromaDBインスタンスを使用します。
• セルフホスト型でプライベート - データはあなたのインフラストラクチャに留まります。
• リモートアクセス - Tailscaleまたは公開インターネットを介してどこからでも接続できます。
• 完全なChromaDBサポート - MCPツールを介してすべてのCRUD操作が可能です。
• REST APIプロキシ - Python/JavaScriptから直接ChromaDBにアクセスできます。
• 統一認証 - 単一のトークンでMCPとREST APIエンドポイントの両方を保護します。
• 簡単なデプロイ - Dockerを使用したワンコマンドインストールです。

📦 インストール

環境変数（.envファイル）

すべての設定は .env ファイルを通じて行われます。.env.example を .env にコピーしてカスタマイズしてください。

cp .env.example .env

認証

重要: 公開インターネットアクセス（Tailscale Funnel、Cloudflare Tunnelなど）の場合は、.env ファイルに MCP_AUTH_TOKEN を設定する必要があります。

安全なトークンを生成します。

# 方法1: Node.js（推奨 - .env.exampleから）
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

# 方法2: OpenSSL
openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

.env ファイルを編集します。

MCP_AUTH_TOKEN=your-generated-token-here

その後、サービスを再起動します。

docker compose restart
# または: docker-compose restart

サポートされる認証方法:

1. Authorizationヘッダー（最も安全）: Authorization: Bearer TOKEN
   • APIクライアントや自動化ツールに推奨
   • MCP仕様に準拠
   • 例: curl -H "Authorization: Bearer YOUR_TOKEN"
2. X-Chroma-Tokenヘッダー: X-Chroma-Token: TOKEN
   • ChromaDBのPython/JavaScriptライブラリ用
   • ChromaDBクライアントSDKと互換性がある
   • 例: client = chromadb.HttpClient(headers={"X-Chroma-Token": "TOKEN"})
3. クエリパラメータ（デフォルトで有効）: ?apiKey=TOKEN
   • Claude Desktop Custom Connectorに必要
   • ブラウザベースの統合を可能にする
   • デフォルトで有効 (ALLOW_QUERY_AUTH=true)
   • 必要ない場合は ALLOW_QUERY_AUTH=false を設定して無効にできます

オリジンヘッダーの検証（DNSリバインディング保護）

サーバーは、ブラウザからのリクエストの Origin ヘッダーを検証し、DNSリバインディング攻撃を防止します。このセキュリティ機能はデフォルトで有効で、ローカルのMCPサーバーを悪意のあるウェブサイトから保護します。

デフォルトで許可されるオリジン（常に許可）:

• ローカルホストのバリエーション: localhost, 127.0.0.1, [::1]
• Claude.aiドメイン: https://claude.ai, https://api.anthropic.com

追加の許可オリジンを設定する: 追加のウェブアプリケーションやカスタムドメインを許可する必要がある場合は、.env ファイルの ALLOWED_ORIGINS に追加してください。

# 追加のカスタムドメインを追加（Claude.aiはデフォルトで許可されています）
ALLOWED_ORIGINS=https://myapp.com,https://yourdomain.com

ALLOWED_ORIGINSを設定するタイミング:

• ✅ Claude Desktop Custom Connectorを使用する → 設定不要（デフォルトで許可されています）
• ✅ カスタムウェブアプリケーションからアクセスする → アプリケーションのドメインを追加
• ✅ リモートでSwagger UIを使用する → サーバーのドメインを追加
• ❌ Claude Code CLIを使用する → 不要（Originヘッダーがない）
• ❌ Python/JavaScriptクライアントを使用する → 不要（Originヘッダーがない）
• ❌ ローカル開発のみ → 不要（ローカルホストはデフォルトで許可されています）

設定例:

# カスタムウェブアプリケーション用
ALLOWED_ORIGINS=https://myapp.com,https://app.mycompany.com

# 複数のカスタムドメイン（カンマ区切り、スペースはトリムされます）
ALLOWED_ORIGINS=https://myapp.com, https://api.example.com, https://dashboard.mycompany.com

# Claude.aiとローカルホストのみ必要な場合は空にする
ALLOWED_ORIGINS=

注意: Claude.aiドメイン (https://claude.ai, https://api.anthropic.com) とローカルホストは、ALLOWED_ORIGINS が空でも常に許可されます。サーバー間のリクエスト（Originヘッダーがない）は常に許可されます。

データ保存設定

ChromaDBのデータは3つの方法で保存できます。

1. Dockerボリューム（デフォルト）: CHROMA_DATA_PATH=chroma-data
   • Dockerによって管理されます。
   • コンテナの再起動後もデータが保持されます。
   • docker volume ls と docker volume inspect chroma-data で場所を確認できます。
2. ローカルディレクトリ: CHROMA_DATA_PATH=./data
   • バックアップやアクセスが容易です。
   • インストールディレクトリに保存されます。
3. カスタムパス: CHROMA_DATA_PATH=/path/to/data
   • 絶対パスである必要があります。
   • 外部ストレージをマウントするのに便利です。

CHROMA_DATA_PATH を変更した後は、サービスを再起動します。

docker compose restart

💻 使用例

基本的な使用法

import chromadb

# HTTPS（Tailscale Funnel、公開デプロイメント）
client = chromadb.HttpClient(
    host="your-server.com",
    port=443,
    ssl=True,
    headers={
        "X-Chroma-Token": "YOUR_TOKEN"
    }
)

# ローカル開発（HTTP）
client = chromadb.HttpClient(
    host="localhost",
    port=8080,
    ssl=False,
    headers={
        "X-Chroma-Token": "YOUR_TOKEN"
    }
)

# 使用例
collection = client.create_collection("my_collection")
collection.add(
    documents=["Document 1", "Document 2"],
    ids=["id1", "id2"]
)
results = collection.query(query_texts=["query"], n_results=2)

高度な使用法

from chromadb.config import Settings

client = chromadb.HttpClient(
    host="your-server.com",
    port=443,
    ssl=True,
    settings=Settings(
        chroma_client_auth_provider="chromadb.auth.token_authn.TokenAuthClientProvider",
        chroma_client_auth_credentials="YOUR_TOKEN"
    )
)

APIドキュメント

すべてのChromaDB REST APIエンドポイントのSwagger UIドキュメントは、https://your-server.com/docs を訪問して確認できます。

📚 ドキュメント

クロスプラットフォームAIメモリサーバー

すべての主要なAIプラットフォームと互換性があります:

• Claude（デスクトップ、モバイル、コード）
• Gemini（CLI、コードアシスト）
• Cursor、Cline、Windsurf、VS Code Copilot
• その他のMCP互換クライアントでもRemote MCPを使用できます

アーキテクチャ

概要

┌──────────────────────────────┐      ┌──────────────┐
│   Claude Desktop + Mobile    │      │  Claude Code │
│  (Custom Connector - synced) │      │  (CLI setup) │
└──────────────┬───────────────┘      └──────┬───────┘
               │                             │
               │     MCP Remote Connector    │
               └─────────────┬───────────────┘
                             │ HTTPS
                   ┌─────────▼──────────┐
                   │   Remote MCP       │
                   │   Server (Node.js) │
                   │                    │
                   │ • Auth Gateway     │
                   │ • MCP Protocol     │
                   │ • REST API Proxy   │
                   └─────────┬──────────┘
                             │
                   ┌─────────▼──────────┐
                   │     ChromaDB       │
                   │ (Vector Database)  │
                   │                    │
                   │ • Embeddings       │
                   │ • Collections      │
                   │ • Semantic Search  │
                   └────────────────────┘

クライアントの接続方法:

• Claude Desktop + Mobile: Claude Desktopのカスタムコネクタを一度設定すると、自動的にモバイルアプリに同期されます。両方が自動的に同じ接続を共有します。
• Claude Code: claude mcp add CLIコマンドを使用して個別に設定する必要があります。

すべてのクライアントは、このリモートMCPサーバーを通じて同じセルフホスト型ChromaDBにアクセスします。ベクター埋め込みと意味検索結果はすべてのプラットフォームで永続化されます。

APIエンドポイント

動作原理

1. Claude Desktop/Mobile: カスタムコネクタを使用してMCPサーバーを追加します（デバイス間で自動的に同期されます）
2. Claude Code: claude mcp add CLIコマンドを使用してMCPサーバーを追加します
3. Remote MCP Server がリクエストを認証し、MCPプロトコルをChromaDB操作に変換します
4. ChromaDB がベクター埋め込みを保存し、意味検索のために取得します
5. Python は、プロキシされたREST APIを介して直接ChromaDBにアクセスすることもできます

利点:

• すべてのクライアントで同じベクターデータベースを使用できます
• デスクトップとモバイルが自動的に接続を共有します
• セルフホスト型でプライベートです
• アプリの再起動後もメモリが保持されます
• 埋め込みの単一の信頼できる情報源です

Claudeの接続方法

Claude Desktop + Mobile

方法1: カスタムコネクタ（推奨 - Pro/Team/Enterprise）

1. Claude Desktopを開き、設定 → 統合 → カスタムコネクタを選択します。
2. 「カスタムサーバーを追加」をクリックします。
3. 以下を入力します。
   • 名前: ChromaDB
   • URL: https://your-server.com/mcp?apiKey=YOUR_TOKEN

注意: カスタムコネクタは自動的にモバイルアプリに同期されます。リモートアクセスには認証が必須です。

方法2: mcp-remoteラッパー（Free/Proユーザー） カスタムコネクタにアクセスできない場合は、mcp-remote パッケージをワークアラウンドとして使用できます。

設定ファイルの場所:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

設定ファイルに追加:

{
  "mcpServers": {
    "chromadb": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-server.com/mcp?apiKey=YOUR_TOKEN"]
    }
  }
}

ファイルを編集した後、Claude Desktopを再起動します。

重要: streamableHttp トランスポートを使用して claude_desktop_config.json で直接リモートMCPサーバーを設定することはできません。カスタムコネクタまたは mcp-remote ラッパーパッケージを使用する必要があります。

Claude Code

CLIコマンド:

# 認証なし
claude mcp add --transport http chromadb https://your-server.com/mcp

# 認証あり（クエリパラメータ - 推奨）
claude mcp add --transport http chromadb https://your-server.com/mcp?apiKey=YOUR_TOKEN

# 認証あり（ヘッダー）
claude mcp add --transport http chromadb https://your-server.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# 確認
claude mcp list

利用可能なツール

MCPサーバーは、Claude用の以下のツールを提供します。

コレクション管理

• chroma_list_collections - すべてのコレクションをリストする
• chroma_create_collection - 新しいコレクションを作成する
• chroma_delete_collection - コレクションを削除する
• chroma_get_collection_info - コレクションのメタデータを取得する
• chroma_get_collection_count - ドキュメント数を取得する
• chroma_peek_collection - コレクションの内容をプレビューする

ドキュメント操作

• chroma_add_documents - 埋め込み付きのドキュメントを追加する
• chroma_query_documents - 意味検索（ベクター類似度）
• chroma_get_documents - IDまたはフィルターでドキュメントを取得する
• chroma_update_documents - 既存のドキュメントを更新する
• chroma_delete_documents - ドキュメントを削除する

デプロイメント

オプション1: Tailscale VPN（推奨）

Tailscaleネットワーク内での安全なアクセス:

# サービスを起動
docker compose up -d

# Tailscale Serveを有効にする（自動証明書付きのHTTPS）
tailscale serve https / http://127.0.0.1:8080

# ステータスを確認
tailscale serve status

これで、サーバーは https://your-machine.tailXXXXX.ts.net からTailnet内のすべてのデバイスにアクセス可能になります。

利点:

• 自動的なHTTPS証明書
• 公開インターネットに公開されない
• 暗号化されたVPNトンネル
• 認証はオプション（VPNがセキュリティ層を提供します）

オプション2: Tailscale Funnel（公開インターネット）

Claude Desktop UIのカスタムコネクタを使用する場合、または公開する場合は、以下のコマンドを実行します。

# Funnelを有効にする（公開インターネットアクセスを許可）
tailscale funnel 8080 on
tailscale serve https / http://127.0.0.1:8080

# Funnelがアクティブであることを確認
tailscale serve status  # "Funnel on" と表示されるはず

警告: これによりサーバーが公開インターネットに公開されます。認証は必須です！ .env で MCP_AUTH_TOKEN を設定してください。

Funnelを無効にする:

tailscale funnel 8080 off

オプション3: Cloudflare Tunnel

# cloudflaredをインストール
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared

# 認証
./cloudflared tunnel login

# トンネルを作成
./cloudflared tunnel create chroma-mcp

# トンネルを実行
./cloudflared tunnel --url http://localhost:3000

オプション4: Nginxリバースプロキシ

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

テスト

ローカルテスト

# ヘルスチェック
curl http://localhost:3000/health

# MCPツールリスト
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# ChromaDBのハートビート
curl http://localhost:3000/api/v2/heartbeat

リモートテスト（認証付き）

# MCPエンドポイント（Bearerトークン）
curl -X POST https://your-server.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# MCPエンドポイント（クエリパラメータ）
curl -X POST "https://your-server.com/mcp?apiKey=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# ChromaDB REST API
curl https://your-server.com/api/v2/heartbeat \
  -H "X-Chroma-Token: YOUR_TOKEN"

# Swagger UI（ブラウザ）
https://your-server.com/docs?apiKey=YOUR_TOKEN

トラブルシューティング

ChromaDBの接続が失敗した場合

# ChromaDBが実行中か確認
curl http://localhost:8000/api/v2/heartbeat

# DockerでChromaDBを起動
docker run -d -p 8000:8000 chromadb/chroma:latest

# MCPサーバーのログを確認
docker compose logs mcp-server

MCPサーバーが応答しない場合

# ログを確認
docker compose logs mcp-server

# ポートの競合を確認
lsof -i :3000

# サービスを再起動
docker compose restart

Claude Desktopの接続に問題がある場合

1. Claude Desktopを再起動します。
2. URLに /mcp パスが含まれていることを確認します。
3. トランスポートタイプが streamableHttp であることを確認します（sse ではない）。
4. 認証トークンが有効であることを確認します。
5. カスタムコネクタの場合: Tailscale Funnelがアクティブであることを確認します。

ローカルネットワークでTLSハンドシェイクがタイムアウトする場合

サーバーと同じローカルネットワークから接続し、Tailscale FunnelのHTTPSを使用している場合、https://your-server.ts.net へのアクセス時にTLSハンドシェイクがタイムアウトすることがあります。

問題: 同じLAN内のクライアントが公開Funnelドメインを介して接続しようとすると、Tailscale FunnelのTLS終端に問題が発生します。

解決策: TailscaleのHTTPSではなく、直接のローカルネットワーク接続を使用します。

# 既存の設定を削除
claude mcp remove chromadb

# ローカルIPアドレスで追加
claude mcp add chromadb --transport http \
  http://192.168.x.x:8080/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# または、DNSが解決する場合はホスト名を使用
claude mcp add chromadb --transport http \
  http://server-hostname:8080/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

確認:

# ローカルネットワーク接続をテスト
curl http://192.168.x.x:8080/health

# 以下のような応答が返されるはず
# {"status":"ok","service":"chroma-remote-mcp",...}

注意: 外部のクライアントは引き続きTailscale FunnelのHTTPSを使用する必要があります。この問題はサーバーと同じLAN内のクライアントにのみ影響します。

認証エラー（401）

# MCP_AUTH_TOKENが設定されていることを確認
docker compose exec mcp-server env | grep MCP_AUTH_TOKEN

# トークンなしでテスト（401で失敗するはず）
curl -X POST https://your-server.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# 正しいトークンでテスト（成功するはず）
curl -X POST https://your-server.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

開発

ソースからビルド

# リポジトリをクローン
git clone https://github.com/meloncafe/chromadb-remote-mcp.git
cd chromadb-remote-mcp

# 依存関係をインストール
yarn install

# 開発モード（自動リロード）
yarn dev

# TypeScriptをビルド
yarn build

# 型チェック
yarn type-check

テスト

このプロジェクトには、DockerベースのE2E検証を含む統合テストが含まれています。

# すべてのテストを実行（サービスを起動、テストを実行、クリーンアップ）
yarn test

# テストを実行し、コンテナをデバッグのために実行し続ける
yarn test:keep

# オプション付きの手動テストスクリプト
./scripts/test.sh --help

統合テストのカバレッジ:

• ✅ ヘルスチェックエンドポイント
• ✅ 認証（Bearerトークン、X-Chroma-Token、クエリパラメータ）
• ✅ MCPプロトコル（tools/list、tools/call）
• ✅ ChromaDB REST APIプロキシ
• ✅ コレクションのCRUD操作
• ✅ レート制限
• ✅ 許可されていないアクセスの処理

単体テスト:

# 単体テストを実行
yarn test:unit

# ウォッチモードで実行
yarn test:unit:watch

# カバレッジを含めて実行
yarn test:unit:coverage

# すべてのテストを実行（単体 + 統合）
yarn test:all

単体テストのカバレッジ:

• ✅ 認証ユーティリティ（タイミングセーフな比較、バッファ操作）
• ✅ 入力検証（コレクション名、ドキュメントID、メタデータ）
• ✅ データ処理（レスポンスのフォーマット、JSONシリアライズ）
• ✅ エラーメッセージのフォーマット

詳細なテスト戦略については、__tests__/README.md を参照してください。

コード品質とカバレッジ

このプロジェクトは、コードカバレッジの追跡とテスト分析に Codecov を使用しています。

Docker開発

ローカルビルドとテスト

# ローカルテスト用にビルド（単一プラットフォーム、Dockerにロード）
yarn docker:build:local

# または、スクリプトを直接使用
./scripts/build.sh --platform linux/amd64 --load

# ビルドしたイメージをテスト
docker run -p 3000:3000 \
  -e MCP_AUTH_TOKEN=test123 \
  devsaurus/chromadb-remote-mcp:latest

マルチプラットフォームビルド

# すべてのプラットフォーム（amd64、arm64）用にビルド
yarn docker:build

# カスタムバージョンでビルド
./scripts/build.sh --version 1.2.3

# カスタムリポジトリでビルド
./scripts/build.sh --repo myuser/my-mcp --version dev

Docker Hubにプッシュ

# 最新タグをプッシュ
yarn docker:push

# 特定のバージョンをプッシュ
VERSION=1.2.3 yarn docker:push

# または、スクリプトを直接使用
./scripts/build.sh --version 1.2.3 --push

# カスタムリポジトリを使用
DOCKER_REPO=myuser/my-mcp ./scripts/build.sh --version 1.2.3 --push

Dockerスクリプト用の環境変数:

export DOCKER_REPO=myuser/my-mcp       # Dockerリポジトリ
export VERSION=1.2.3                    # イメージのバージョンタグ
export DOCKER_USERNAME=myuser           # プッシュ認証用
export DOCKER_PASSWORD=mytoken          # Docker Hubトークン

開発スクリプト

すべての開発スクリプトは scripts/ にあります。

迅速な開発ワークフロー:

# 1. コードを変更
vim src/index.ts

# 2. ローカルでテスト
yarn dev

# 3. 統合テストを実行
yarn test

# 4. Dockerイメージをビルド
yarn docker:build:local

# 5. Dockerイメージをテスト
docker-compose up

# 6. すべて正常なら、マルチプラットフォームをビルドしてプッシュ
./scripts/build.sh --version 1.2.3 --push

プロジェクト構造

chromadb-remote-mcp/
├── .github/
│   ├── ISSUE_TEMPLATE/       # GitHubのイシューテンプレート
│   └── workflows/            # GitHub Actions（publish-release、security-scan、chromadb-version-check）
├── scripts/
│   ├── build.sh             # Dockerのビルドとプッシュスクリプト（マルチプラットフォーム）
│   ├── test.sh              # 統合テストランナー
│   └── install.sh           # ワンコマンドインストール
├── src/
│   ├── index.ts             # メインサーバーのエントリポイント
│   ├── chroma-tools.ts      # MCPツールの定義とハンドラー
│   └── types.ts             # TypeScriptの型定義
├── docker-compose.yml       # 本番用（事前構築済みイメージ）
├── docker-compose.dev.yml   # 開発用（ソースからビルド）
├── Dockerfile               # MCPサーバーのDockerイメージ
├── .env.example             # 環境変数のテンプレート
├── package.json             # Node.jsの依存関係
├── tsconfig.json            # TypeScriptの設定
├── SECURITY.md              # セキュリティポリシー
├── CONTRIBUTING.md          # コントリビューションガイドライン
├── CODE_OF_CONDUCT.md       # 行動規範
├── CHANGELOG.md             # バージョン履歴
└── LICENSE                  # MITライセンス

🔧 技術詳細

コード品質とセキュリティ分析

このプロジェクトは厳格なセキュリティ慣行に従っており、静的分析で特定されたすべてのセキュリティ問題を解決しています。

• ✅ アクティブな問題がゼロ: すべてのOWASPとCWEのセキュリティ調査結果が解決されています。
• 🔒 静的分析: DeepSource で継続的に監視されています。
• 🛡️ セキュリティ標準: OWASP Top 10とNode.jsのセキュリティベストプラクティスに準拠しています。
• 📊 自動スキャン: Dependabot、CodeQL、およびコンテナの脆弱性スキャン。

詳細なセキュリティ情報については、Security Policy を参照してください。

セキュリティ推奨事項

1. 公開アクセスのための認証を有効にする
   • Tailscale Funnelまたは公開インターネットを使用する場合は、MCP_AUTH_TOKEN を設定します。
   • 強力なトークンを生成します: openssl rand -base64 32 | tr '+/' '-_' | tr -d '='
   • 定期的にトークンをローテーションします。
2. HTTPSを使用する
   • Tailscaleは自動的なHTTPS証明書を提供します。
   • 他のデプロイメントでは、Let's Encryptを使用したリバースプロキシ（Nginx/Caddy）を使用します。
3. 公開インターネットよりもVPNを優先する
   • Tailscale Serve（VPNのみ）はFunnel（公開）よりも安全です。
   • VPN内では認証はオプションですが、公開アクセスには必須です。
4. アクセスを監視する

   # 許可されていないアクセス試行を確認
   docker compose logs mcp-server | grep "Unauthorized"
   

5. ネットワークの分離
   • ChromaDBをプライベートネットワークに配置します。
   • MCPサーバーのみを公開インターネットに公開します。

📄 ライセンス

このプロジェクトは MIT License の下でライセンスされています。

リソース

• MCP仕様
• MCP TypeScript SDK
• ChromaDBドキュメント
• Tailscale Serve
• Tailscale Funnel
• Cloudflare Tunnel

サポート

問題が発生した場合や質問がある場合は、イシューを開いて ください。