embedbase

embedbase

embedbase 为 Agent（或在终端前的你）提供了一种简洁的方式来使用向量集合：创建集合、填入文档，并查询最匹配的结果。它通过 v2 REST API 与兼容 Chroma 的 HTTP 服务通信，因此嵌入存储作为独立进程运行，而此工具则保持为一个精简且易于测试的客户端。

通过 CHROMA_URL 或 EMBEDBASE_URL 指定正在运行的服务（如果两者都未设置，则默认使用 http://localhost:8000）。在 MCP 和 CLI 层，集合通过名称标识；在内部，客户端会先将每个名称解析为服务端 ID，再调用按 ID 定位的文档端点，完全遵循 REST API 的要求。

安装

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，服务调用失败时为 1（错误中包含 HTTP 状态码），用法错误时为 2。

MCP 服务

一个二进制文件同时支持两种用法。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。