embedbase

embedbase

embedbase gives an agent — or you, at a terminal — a tidy way to work with vector collections: create them, fill them with documents, and query them for the closest matches. It speaks to a Chroma-compatible HTTP service over its v2 REST API, so the embedding store stays a separate process and this tool stays a thin, testable client.

Point it at a running service with CHROMA_URL or EMBEDBASE_URL (without either, it assumes http://localhost:8000). Collections are addressed by name at the MCP and CLI layers; internally the client resolves each name to its server id before calling the id-scoped document endpoints, exactly as the REST API requires.

Install

npx @reneturcios/embedbase list

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/embedbase

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

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

Exit codes: 0 on success, 1 when the service call fails (the error includes the HTTP status), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/embedbase mcp

MCP client configuration:

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

Tools

All tools take collection_name (string) unless noted. Optional parameters are omitted from the request when not supplied.

Tool	Required	Optional	Purpose
chroma_list_collections	—	limit, offset (integers)	List collections with pagination.
chroma_create_collection	collection_name	metadata (object), embedding_function_name (string)	Create a collection.
chroma_peek_collection	collection_name	limit (integer)	Preview documents in a collection.
chroma_get_collection_info	collection_name	—	Collection metadata and configuration.
chroma_get_collection_count	collection_name	—	Number of records in a collection.
chroma_modify_collection	collection_name	new_name, new_metadata	Rename or re-tag a collection.
chroma_delete_collection	collection_name	—	Delete a collection and its records.
chroma_add_documents	collection_name, documents (string array)	metadatas, ids	Add documents; ids are generated deterministically when omitted.
chroma_query_documents	collection_name, query_texts (string array)	n_results, where, where_document, include	Nearest-neighbour query.
chroma_get_documents	collection_name	ids, where, limit, offset, include	Fetch documents by id or filter.
chroma_update_documents	collection_name, ids	documents, metadatas, embeddings	Update existing records.
chroma_delete_documents	collection_name	ids, where	Delete records by id or filter.

Requests go to the v2 tenant/database paths (/api/v2/tenants/default_tenant/databases/default_database/collections...). Service errors come back as tool errors carrying the HTTP status — results are never invented.

Development

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

The client core sits behind an injectable fetch function, which is what the test suite drives: URL construction, request bodies, id resolution, count unwrapping, and error surfacing are all covered without a running server.

License

MIT — see LICENSE.