embedbase

embedbase

embedbase を使うと、エージェントも、ターミナルを使うあなたも、ベクターコレクションを手軽に扱えます。コレクションを作成し、ドキュメントを追加して、最も近い一致を検索できます。Chroma 互換の HTTP サービスと v2 REST API 経由で通信するため、埋め込みストアは別プロセスとして動作し、このツールはテストしやすい薄いクライアントのままです。

CHROMA_URL または EMBEDBASE_URL を指定して、稼働中のサービスに接続します（どちらも指定しない場合は、http://localhost:8000 を使用します）。MCP と CLI の各レイヤーでは、コレクションを名前で指定します。クライアントは内部で各名前をサーバー ID に解決してから、REST API の仕様に従って ID スコープのドキュメントエンドポイントを呼び出します。

インストール

npx @reneturcios/embedbase list

または、コンテナイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/embedbase

コンテナはデフォルトで MCP サーバーとして起動します（下記を参照）。CLI として使うには、CLI 引数を渡してください。

CLI

# List collections (pagination is optional)
embedbase list --limit 20 --offset 0

# Inspect one collection, or count its records
embedbase info notes
embedbase count notes

# Create a collection
embedbase create notes

# Start the MCP server
embedbase mcp

embedbase --version

終了コード：成功時は 0、サービス呼び出しに失敗した場合（エラーには HTTP ステータスが含まれます）は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

1 つの実行ファイルで、どちらの用途にも対応します。mcp サブコマンドを実行すると、stdio MCP サーバーが起動します。

npx -y @reneturcios/embedbase mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "embedbase": {
      "command": "npx",
      "args": ["-y", "@reneturcios/embedbase", "mcp"],
      "env": { "CHROMA_URL": "http://localhost:8000" }
    }
  }
}

ツール

特に記載がない限り、すべてのツールで collection_name（文字列）が必要です。省略可能なパラメーターは、指定されない場合、リクエストから省略されます。

ツール	必須	省略可能	目的
chroma_list_collections	—	limit、offset（整数）	ページネーションを使ってコレクションを一覧表示します。
chroma_create_collection	collection_name	metadata（オブジェクト）、embedding_function_name（文字列）	コレクションを作成します。
chroma_peek_collection	collection_name	limit（整数）	コレクション内のドキュメントをプレビューします。
chroma_get_collection_info	collection_name	—	コレクションのメタデータと設定を取得します。
chroma_get_collection_count	collection_name	—	コレクション内のレコード数を取得します。
chroma_modify_collection	collection_name	new_name、new_metadata	コレクションの名前を変更するか、タグを付け直します。
chroma_delete_collection	collection_name	—	コレクションとそのレコードを削除します。
chroma_add_documents	collection_name、documents（文字列配列）	metadatas、ids	ドキュメントを追加します。省略された場合、ID は決定論的に生成されます。
chroma_query_documents	collection_name、query_texts（文字列配列）	n_results、where、where_document、include	最近傍検索を実行します。
chroma_get_documents	collection_name	ids、where、limit、offset、include	ID またはフィルターを使ってドキュメントを取得します。
chroma_update_documents	collection_name、ids	documents、metadatas、embeddings	既存のレコードを更新します。
chroma_delete_documents	collection_name	ids、where	ID またはフィルターを使ってレコードを削除します。

リクエストは v2 のテナント／データベースパス（/api/v2/tenants/default_tenant/databases/default_database/collections...）に送信されます。サービスエラーは HTTP ステータスを含むツールエラーとして返され、結果が作り出されることはありません。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake fetch only, no live service
npm run dev     # run the CLI from source via tsx

クライアントのコアは、差し替え可能な fetch 関数を介して実行されます。テストスイートではこの関数を使って、URL の構築、リクエスト本文、ID の解決、件数の取り出し、エラーの通知をテストします。これらのテストは、サーバーを起動せずに実行できます。

ライセンス

MIT — LICENSE を参照してください。