内容
# @vectros-ai/mcp-server
[](https://www.npmjs.com/package/@vectros-ai/mcp-server)
[](https://www.apache.org/licenses/LICENSE-2.0)
[](https://cursor.com/install-mcp?name=vectros&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB2ZWN0cm9zLWFpL21jcC1zZXJ2ZXIiXSwiZW52Ijp7IlZFQ1RST1NfQVBJX0tFWSI6IiJ9fQ%3D%3D)
[](https://insiders.vscode.dev/redirect/mcp/install?name=vectros&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40vectros-ai%2Fmcp-server%22%5D%2C%22env%22%3A%7B%22VECTROS_API_KEY%22%3A%22%22%7D%7D)
[](https://github.com/vectros-ai/vectros-mcp-server/releases/latest/download/vectros.mcpb)
> 一键安装徽章将为您在客户端安装 **服务器入口**。您仍然需要提供密钥 - 运行 `npx -y @vectros-ai/cli bootstrap`（推荐）或粘贴您的 `ssk_...`。请参阅 [从客户端连接](#connect-from-your-client) 和 [诚实的注意事项](#honest-caveats)。
一个适用于 **Vectros** 的 [Model Context Protocol](https://modelcontextprotocol.io) 服务器 - 一个类型化的、多租户的 **记录存储与混合搜索** 以及基于引用的 RAG 统一系统。确定性的查找和枚举 *以及* 在一个隔离的、每个客户的记录和文档索引上进行语义搜索 - 因此代理获得的内存是精确的，而不仅仅是模糊的回忆。通过 MCP（Claude Desktop，Cursor，Claude Code，Cline，Continue，VS Code，托管平台） - 以及相同的数据可以通过 Vectros 应用程序 + SDK 访问。
```bash
npx -y @vectros-ai/mcp-server
```
您的代理可以搜索索引的语料库，查询结构化记录，摄入文档，并提出基于文档的问题 - 仅访问您租户的数据，永远不会访问公共网络（没有网络工具）。
## 快速开始 - 一个命令
最快的设置方法是使用 [`@vectros-ai/cli`](https://www.npmjs.com/package/@vectros-ai/cli) 的 `bootstrap` 命令。它会生成一个 **最小权限作用域密钥** (`ssk_*`)，绑定到一个狭窄的 AccessProfile，可选地为用例数据模型提供支持，并将 `vectros` 服务器安全地合并到您的 MCP 客户端配置中 - 无需根密钥，也无需手动编辑 JSON：
```bash
npx -y @vectros-ai/cli bootstrap
```
您可以选择设置的内容（一个空白的只读凭证，或一个 **蓝图**，如任务跟踪），并使用来自开发者门户的令牌登录一次。然后，该命令：
- 为 **此机器** 生成一个作用域 `ssk_*`（独立可旋转）
- 创建匹配的 AccessProfile - **仅限数据层面**；命令拒绝提供控制层面范围（密钥/配置文件/计费/...）
- 备份并将条目合并到 `claude_desktop_config.json`（Claude Desktop，Cursor，Cline）。对于 **Claude Code**，添加 `--client code`：它会合并项目 `.mcp.json` 并打印等效的 `claude mcp add` 命令。
重启您的 MCP 客户端，然后您就完成了。它是幂等的（随时可以重新运行）；`--rotate` 替换此机器的密钥。
对于脚本化/代理使用，在环境中设置登录令牌并跳过提示：
```bash
VECTROS_BOOTSTRAP_TOKEN=… npx -y @vectros-ai/cli bootstrap \
--blueprint task-management --yes
```
更喜欢手动配置？请参见下面的 **手动配置**。
## 从您的客户端连接
| 客户端 | 一键安装 | 手动安装 |
|---|---|---|
| **Claude Desktop** | [桌面扩展（`.mcpb`）](https://github.com/vectros-ai/vectros-mcp-server/releases/latest/download/vectros.mcpb) - 双击，粘贴您的密钥 | [JSON 代码片段](#configure-manually-claude-desktop-or-any-mcp-client) |
| **Cursor** | [](https://cursor.com/install-mcp?name=vectros&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB2ZWN0cm9zLWFpL21jcC1zZXJ2ZXIiXSwiZW52Ijp7IlZFQ1RST1NfQVBJX0tFWSI6IiJ9fQ%3D%3D) | `.cursor/mcp.json`，与下面相同的格式 |
| **VS Code** | [](https://insiders.vscode.dev/redirect/mcp/install?name=vectros&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40vectros-ai%2Fmcp-server%22%5D%2C%22env%22%3A%7B%22VECTROS_API_KEY%22%3A%22%22%7D%7D) | `.vscode/mcp.json`，格式相同 |
| **Claude Code** | `claude mcp add`（下面） | [项目 `.mcp.json`](#configure-manually-claude-code) |
| **Cline / Continue** | - | 与 Claude Desktop 相同的 JSON 代码片段 |
| **Smithery** | `npx -y @smithery/cli install @vectros-ai/mcp-server` | - |
| **Codex** | - | TOML 代码片段（下面） |
每个客户端最快捷的方式是 `npx -y @vectros-ai/cli bootstrap` - 它为您生成一个作用域密钥并为您编写配置。单击按钮安装服务器条目；然后您提供密钥（引导或粘贴您的 `ssk_...`）。
**Codex** (`~/.codex/config.toml`):
```toml
[mcp_servers.vectros]
command = "npx"
args = ["-y", "@vectros-ai/mcp-server"]
env = { VECTROS_API_KEY = "ssk_live_..." }
```
## 诚实的注意事项
精度是我们的卖点 - 这个服务器故意 **不** 做以下事情：
- **有一个人为步骤**。Bootstrap 需要一个开发者门户登录/桥接令牌。一个命令，但一个人登录 - 没有完全无人值守的配置。
- **没有网络工具， purposefully**。代理界面没有网络搜索或网络获取工具。Vectros 是内存，而不是浏览器。
- **代理文档上传今天是文本内联**。代理内联摄入文档文本；在一个 stdio 传输上支持一个隔离的本地文件上传，但来自代理界面的批量文件上传不是今天的路径。
- **审计历史是防篡改**，而不是防篡改。一个状态连续性链使得 **篡改是可检测的**；它不是连续的自动验证。
## 手动配置（Claude Desktop 或任何 MCP 客户端）
```json
{
"mcpServers": {
"vectros": {
"command": "npx",
"args": ["-y", "@vectros-ai/mcp-server"],
"env": {
"VECTROS_API_KEY": "ssk_live_..."
}
}
}
}
```
重启 Claude Desktop。代理现在可以看到 Vectros 工具和两个可调用的资源。
## 手动配置（Claude Code）
Claude Code 读取一个项目范围的 `.mcp.json`，具有相同的格式 - 将其放在项目根目录（提交到存储库中与其他人共享服务器）：
```json
{
"mcpServers": {
"vectros": {
"command": "npx",
"args": ["-y", "@vectros-ai/mcp-server"],
"env": {
"VECTROS_API_KEY": "ssk_live_..."
}
}
}
}
```
或者让 Claude Code 的 CLI 为您编写：
```bash
claude mcp add vectros -e VECTROS_API_KEY=ssk_live_... -- npx -y @vectros-ai/mcp-server
```
添加 `-e VECTROS_API_BASE_URL=https://api.staging.vectros.ai` 以获取非生产环境。在 Claude Code 中重新打开项目，Vectros 工具即可使用。
## 工具（21 个工具）
**搜索与 RAG**
| 工具 | 它做什么 |
|---|---|
| `hybrid_search` | 跨租户索引内容的混合 BM25 + 稠密搜索（记录 + 文档）。按所有权、文件夹、类型、元数据过滤器、创建时间窗口和关键词精度（`textMode`）/相关性底线缩小范围。返回每个命中的索引投影。 |
| `rag_ask` | 提出一个基于索引语料库的问题。范围检索（所有权/文件夹/类型/元数据过滤器/日期窗口），并控制生成（`instructions` / `temperature`）。生成聚合；进度通知在生成窗口期间保持调用活跃。 |
| `document_ask` | 提出一个基于单个文档的问题。与 `rag_ask` 具有相同的聚合 + 进度通知形状。 |
**记录**（结构化、模式验证的数据）
| 工具 | 它做什么 |
|---|---|
| `list_schemas` | 列出凭证可见的记录模式目录（按 `surface` 过滤或按 `recordType` 解析）。使 `record_query` / `record_create` 可发现。 |
| `record_query` | 按查找字段（相等/范围/前缀，具有 `asc`/`desc` 排序）或列表模式（按所有权 + 类型过滤）查询记录。 |
| `record_get` | 按 ID 获取一条记录，包括其完整有效载荷（大有效载荷截断以保护代理上下文窗口）。 |
| `record_create` | 创建给定类型的记录；`externalId` 幂等；可选的每条记录 `indexMode`。 |
| `record_update` | 修补记录的有效载荷（深度合并；`null` 删除键）；通过 `expectedVersion` 进行乐观并发。 |
| `record_delete` | 永久删除一条记录（留下墓碑）。 |
**文档**（文本/文件内容，索引用于搜索 + 问答）
| 工具 | 它做什么 |
|---|---|
| `document_ingest` | 创建一个文档 - 内联文本正文或本地文件上传（文件模式仅限 stdio 传输）。`externalId` 幂等；可选 `schemaId` + `payload` 用于类型化、可查询文档。 |
| `document_query` | 按查找字段（相等/范围/前缀，具有 `asc`/`desc` 排序）或列表模式（按所有权 + 类型过滤）查询文档。 |
| `document_get` | 按 ID 获取文档（元数据；可选文本截断至 ~8K 令牌；文件支持文档的可预签名 `downloadUrl`）。 |
| `document_update` | 修补文档的元数据/类型化有效载荷（深度合并）；通过 `expectedVersion` 进行乐观并发。 |
| `document_delete` | 永久删除文档（删除其索引内容）。 |
**文件夹**（分组记录 + 文档）
| 工具 | 它做什么 |
|---|---|
| `folder_query` | 按 ID 获取文件夹，或列出文件夹（父文件夹的子文件夹用于树导航，或平坦的租户列表；通过 `nextCursor` 分页）。 |
| `folder_create` | 创建文件夹。 |
| `folder_update` | 更新文件夹的名称/描述/所有权（合并修补；通过 `expectedVersion` 进行乐观并发；文件夹不能重新父级）。 |
| `folder_delete` | 删除文件夹。 |
**身份与历史**
| 工具 | 它做什么 |
|---|---|
| `current_identity` | 描述凭证：tenantId、environment、principalType 和（在表面上）allowedActions + dataScope。 |
| `lookup_principal` | 按您自己的 `externalId`（→ 其 Vectros UUID，用于所有权过滤）或按模式查找字段解析用户/组织/客户端。只读。 |
| `version_history` | 读取审计/版本轨迹（CREATE/UPDATE/DELETE，具有操作者 + 差异）用于一个记录或文档。只读。 |
所有 21 个工具都封装了发布的 Vectros HTTP API 端点。JSON 响应是代理看到的工具输出。每次调用的成本都通过推理响应上的 `usage` 字段显示。
### 选择子集
传递 `VECTROS_MCP_TOOLS=hybrid_search,rag_ask` 以仅注册这两个 - 对于给凭证提供只读搜索访问而不暴露摄入或推理成本非常有用。未知工具名称在启动时快速失败。
## 资源
两个只读资源用于环境上下文（不需要工具调用）：
| URI | 它返回什么 |
|---|---|
| `vectros://schemas` | 与 `list_schemas` 相同。让代理将模式预加载到上下文中以进行环境发现。 |
| `vectros://identity` | 与 `current_identity` 相同。让代理在不调用工具的情况下自我描述。 |
## 推荐凭证
使用 **作用域永久 API 密钥** (`ssk_*`)，而不是根密钥 (`sk_*`)。
作用域密钥绑定到一个狭窄的 `AccessProfile` - 例如，一个组织的只读 `orgId`。如果您的 MCP 安装被泄露，风险范围仅限于配置文件允许的范围，而不是整个租户。服务器在启动时会在出现通配符 `sk_*` 的情况下发出警告日志，原因正是如此。
**获取其中一个的最简单方法是 `npx -y @vectros-ai/cli bootstrap`（上面）** - 它为您生成一个最小权限的 `ssk_*` 和一个 AccessProfile，无需根密钥。手动执行：从开发者门户的 **密钥 → 创建作用域密钥** 下生成一个作用域密钥，将其绑定到名为 `mcp-read-all` 或 `mcp-read-scoped` 的 AccessProfile，然后将生成的 `ssk_live_...` 放入上面的配置中。
参阅 Vectros 开发者文档，了解作用域令牌（“MCP 的推荐访问配置文件”），以获取最小权限凭证设置 - `vectros bootstrap` 流程通过一个命令配置作用域 `ssk_*` 密钥及其访问配置文件。
## 环境变量
| 变量 | 必需 | 默认值 | 用途 |
|---|---|---|---|
| `VECTROS_API_KEY` | **是** | - | Vectros API 密钥。接受 `sk_*` / `ssk_*` / `st_*`；推荐 `ssk_*`。 |
| `VECTROS_API_BASE_URL` | 否 | `https://api.vectros.ai` | 覆盖用于暂存或其他环境的 URL。验证：必须是 `https://`（或 `http://` 至 localhost）并且是官方的 `*.vectros.ai` 主机。 |
| `VECTROS_ALLOW_INSECURE_BASE_URL` | 否 | - | 设置为 `1` 以绕过基于 URL 的允许列表（例如，受信任的本地代理）。 **不推荐** - 将您的密钥发送到未经验证的主机；日志记录警告。 |
| `VECTROS_MCP_INGEST_ROOT` | 否 | 进程 cwd | `document_ingest` 的 `filePath` 模式被限制在此范围内。路径转义（遍历/绝对/符号链接）或与敏感模式匹配的路径将被拒绝。 |
| `VECTROS_MCP_TOOLS` | 否 | （所有工具） | 以逗号分隔的工具名称（例如 `hybrid_search,rag_ask`）。 |
| `VECTROS_MCP_DEBUG` | 否 | - | 设置为 `1` 以获取详细的 stderr 日志。 |
| `VECTROS_MCP_SKIP_PING_VALIDATION` | 否 | - | 设置为 `1` 以禁用启动 `/v1/ping` 检查。 |
| `VECTROS_MCP_HTTP_PORT` | 仅限 HTTP | `8765` | HTTP 传输端口。 |
| `VECTROS_MCP_HTTP_HOST` | 仅限 HTTP | `127.0.0.1` | 绑定地址。使用 `0.0.0.0` 表示所有接口（然后设置承载令牌）。 |
| `VECTROS_MCP_HTTP_BEARER_TOKEN` | 仅限 HTTP | - | 客户端→服务器承载令牌。 **强烈推荐** 超出 localhost；**必需** 用于非环回绑定。 |
| `VECTROS_MCP_HTTP_ALLOWED_HOSTS` | 仅限 HTTP | - | 以逗号分隔的额外允许 `Host` 值（DNS 重新绑定保护）。设置为反向代理后面的公共主机名（s）。 |
| `VECTROS_MCP_HTTP_ALLOWED_ORIGINS` | 仅限 HTTP | - | 以逗号分隔的额外允许 `Origin` 值。 |
| `VECTROS_MCP_HTTP_ALLOW_INSECURE` | 仅限 HTTP | - | 设置为 `1` 以允许非环回绑定而无需承载令牌。 **不推荐。** |
## 启动凭证验证
在第一次工具调用之前，服务器会运行一个 `GET /v1/ping` 检查您的凭证。错误的密钥会在启动时快速失败，并显示清晰的错误信息，而不是在对话中不明确地 401 错误。设置 `VECTROS_MCP_SKIP_PING_VALIDATION=1` 以禁用。
## HTTP 传输
对于托管的 MCP 场景 - 在网络边界上运行服务器，在多个代理实例上共享它，作为边车部署 - 包还附带了一个 HTTP 二进制文件：
```bash
VECTROS_API_KEY=ssk_live_... \
VECTROS_MCP_HTTP_PORT=8765 \
VECTROS_MCP_HTTP_BEARER_TOKEN=$(openssl rand -hex 32) \
npx -y -p @vectros-ai/mcp-server vectros-mcp-server-http
```
> HTTP 二进制文件 **不是** 默认 - 显式选择它与 `npx -p <pkg> vectros-mcp-server-http`。 裸 `npx -y @vectros-ai/mcp-server` 始终启动 stdio 服务器。
服务器默认监听 `http://127.0.0.1:8765/mcp`。 承载令牌是可选的，但 **强烈建议** 用于任何 **超出 localhost 的部署** - 没有它，任何可以访问该端口的人都可以调用 Vectros 以及您的凭证。
健康检查位于 `GET /healthz`（始终是未经身份验证的，适用于 k8s 就绪检查）。
当前限制：服务器在每个进程中使用一个上游凭证（环境变量 `VECTROS_API_KEY`）。按请求凭证覆盖通过传入的 Authorization 头是一个计划中的增强功能。现在，为您要部署的每个凭证边界部署一个服务器。
## 程序化使用（高级）
大多数消费者使用上述 CLI 形状。如果您需要将服务器嵌入到您自己的 Node 进程中：
```ts
import { VectrosMCPServer, createStdioTransport } from '@vectros-ai/mcp-server';
const server = new VectrosMCPServer({
apiKey: process.env.VECTROS_API_KEY!,
tools: ['hybrid_search', 'rag_ask'],
resources: ['schemas'], // 选择加入资源过滤器；默认 = 所有
validateOnStart: true, // 默认 - 设置 false 以跳过启动 ping
});
await server.connect(createStdioTransport());
```
## 这个服务器（暂时）不具备的功能
- **没有提示功能** - `/rag` 和 `/ingest_pdf` 斜杠命令模板将在未来的版本中提供。（配置 - `bootstrap` 命令 - 位于单独的 [`@vectros-ai/cli`](https://www.npmjs.com/package/@vectros-ai/cli) 包中。）
- **HTTP 传输对每个进程都是单一租户的** - 通过传入的 Authorization 头进行每请求凭证覆盖是一个 v1.0+ 增强功能。
- **没有 Python 实现** - TS 唯一。Python 用户可以从任何项目中使用 `npx` 启动此服务器。
- **`rag_ask` 和 `document_ask` 不是原生流式传输的** - 完整答案在工具返回之前聚合。进度通知涵盖延迟。原生 MCP 规范流式传输将在规范稳定后上线。
## 速率限制
工具调用会受到与任何 API 客户端相同的每帐户每分钟速率限制（写入、搜索和推理都计入此限制；读取不计入）。在出现 `429` 错误时，服务器会将错误及其 `Retry-After` 提示一起返回，以便代理可以调整和重试，而不是盲目重试。请参阅 [速率限制指南](https://docs.vectros.ai/guides/operations-trust/rate-limits)，了解每个计划的限制。
## 从源代码构建
```sh
git clone https://github.com/vectros-ai/vectros-mcp-server
cd mcp-server
npm install
npm run build
npm test
```
`npm install` 会从配置的 npm 注册表中拉取 `@vectros-ai/sdk`。
`npm run build` 运行 `tsup` 以在 `dist/` 中生成双 ESM/CJS 输出。SDK 被捆绑到构建中（参见 [`tsup.config.ts`](./tsup.config.ts)）- 发布后的 npm 包是自包含的，无需在消费者机器上进行 `.npmrc` 配置即可工作。
## 许可证
Apache-2.0。参见 LICENSE 文件。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器