内容
# @voxell/forge-mcp
**Forge** 的 MCP 服务器 - Voxell 的托管文本嵌入 API。它将 Forge 公开给任何 MCP 客户端（Claude、Cursor、Cline、Windsurf、VS Code 等）作为两个工具：
- **`embed`** — 将文本转换为向量
- **`list_models`** — 列出可用的模型及其维度
您需要提供 Forge API 密钥。服务器是无状态的，**Voxell 不会存储您发送的文本或返回的向量** — 仅记录使用元数据（令牌计数）用于计费。它仅执行嵌入操作 — 没有存储、搜索或 RAG。这些是不同的产品。
## 快速安装
在您的编辑器中一键安装（然后将 `your-key-here` 替换为来自 [dash.voxell.ai](https://dash.voxell.ai) 的真实密钥）：
[](cursor://anysphere.cursor-deeplink/mcp/install?name=forge&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB2b3hlbGwvZm9yZ2UtbWNwIl0sImVudiI6eyJGT1JHRV9BUElfS0VZIjoieW91ci1rZXktaGVyZSJ9fQ==)
[](vscode:mcp/install?%7B%22name%22%3A%22forge%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40voxell%2Fforge-mcp%22%5D%2C%22env%22%3A%7B%22FORGE_API_KEY%22%3A%22your-key-here%22%7D%7D)
**Claude Code** — 一个命令：
```bash
claude mcp add forge -e FORGE_API_KEY=your-key-here -- npx -y @voxell/forge-mcp
```
任何其他客户端（Claude Desktop、Cline、Windsurf、Zed 等）都使用标准的 `mcpServers` 块 — 请参见下面的 [使用它](#使用它)。
## 为什么选择 Forge
- **您可以控制的质量**。Forge 运行 Qwen3-Embedding 系列；`ultra` 是 8B — 在 MTEB 上平均任务得分为 75+，目前在 MTEB（英文）上排名第 4， 而且是 *可用的* 模型（排名前 3 的模型仅用于研究）。`turbo`（0.6B）是快速/廉价的默认模型。选择您的质量/成本点。
- **Matryoshka（MRL）**。设置 `dim` 以截断（重新归一化）为约 4 倍更小、更便宜的向量。
- **低延迟**（Go + CUDA 引擎），**零信任**（每密钥身份验证；mTLS 可用），以及 **免费开始**（1000 万令牌，无信用卡 — [dash.voxell.ai](https://dash.voxell.ai)；更多信息请访问 [voxell.ai/forge](https://voxell.ai/forge)）。
## 您可以用它做什么
- **添加语义搜索** — 使用 `input_type: "document"` 嵌入您的文档，并使用 `input_type: "query"` 嵌入每个查询，然后按余弦相似度排序。
- **构建 RAG** — 嵌入知识库，存储向量，并检索最接近的块以支持 LLM。
- **查找相似或重复文本** — 嵌入两个文本并比较它们的向量。
- **聚类或分类** — 嵌入一批数据，然后在向量上聚类或训练分类器。
- **缩小向量存储** — 设置 `dim` 以截断（Matryoshka）并以较小的精度换取较小、较便宜的向量。
- **直接从编辑器** — 请求您的 AI 代理（Cursor、Claude 等）通过 `embed` 工具嵌入代码段、批次或文件 — 无需单独的脚本。
## 要求
- Node.js ≥ 18（已在 20 上测试）
- Forge API 密钥 — 在 https://dash.voxell.ai 上创建一个。新账户开始时有 1000 万免费令牌，无需信用卡。
## 使用它
大多数 MCP 客户端都使用 `npx` 按需运行它。将以下内容添加到客户端的 MCP 配置中：
```json
{
"mcpServers": {
"forge": {
"command": "npx",
"args": ["-y", "@voxell/forge-mcp"],
"env": { "FORGE_API_KEY": "your-key-here" }
}
}
}
```
（Cursor、Claude Desktop、Cline、Windsurf 和 VS Code 都使用此 `mcpServers` 形状。）
## 工具
### `embed`
| 参数 | 类型 | 默认值 | 备注 |
| --- | --- | --- | --- |
| `input` | 字符串或字符串数组 | — | 要嵌入的文本（必填） |
| `model` | 字符串 | `turbo` | `turbo`（1024-d），`pro`（2560-d），`ultra`（4096-d） |
| `dim` | 数字 | 模型默认值 | 截断为 N 维度（Matryoshka）— 适用于每个模型 |
| `input_type` | `"query"` \| `"document"` | `document` | 对搜索查询使用 `query` |
返回向量以及模型、维度和令牌计数。
默认值为 `turbo` — 您可能想要的那个。`pro`/`ultra` 以更大的尺寸换取大小和速度。
### `list_models`
列出可用的模型及其维度。
## 配置
| 环境变量 | 是否必填 | 默认值 |
| --- | --- | --- |
| `FORGE_API_KEY` | 是 | — |
| `FORGE_BASE_URL` | 否 | `https://api.voxell.ai` |
## 超越 MCP：OpenAI 兼容 API
Forge 支持 **OpenAI 嵌入 API**。将任何 OpenAI 客户端指向 Forge — **无需代码更改**，并且现有的向量维度得以保留：
```python
from openai import OpenAI
client = OpenAI(base_url="https://api.voxell.ai/v1", api_key="your-forge-key")
# 您已经在使用的确切调用 — 现在在更高级别的引擎上：
client.embeddings.create(model="text-embedding-3-large", input=["hello world"]) # -> 3072-d
```
您的 OpenAI 模型名称映射到 **匹配维度** 的 Forge 级别（`text-embedding-3-small` / `ada-002` → 1536-d，`text-embedding-3-large` → 3072-d），因此现有的向量存储保持不变。或者，直接访问 Forge 级别 — `turbo` | `pro` | `ultra`。还支持 `dimensions`（Matryoshka，重新归一化）和 `encoding_format: "base64"`。
**在每条路径上都是升级**。Forge 的 *最小* 级别（`turbo`，Qwen3-Embedding-0.6B）在 MTEB 上优于 OpenAI 的 *最大* 嵌入模型（`text-embedding-3-large`）— 因此没有降级插入。`ultra`（Qwen3-Embedding-8B，约 75+ 平均任务得分，MTEB 英文排名第 4）是一个不同的层次。
**为什么重新嵌入到 Forge 是值得的**。嵌入是一扇单向门：无论编码器在写入时丢弃什么，都无法通过重新排名、更长的提示或下游更大的 LLM 重建。您嵌入的模型为上方的一切设定了上限。重新嵌入一次到更高级别的引擎，并且上限上升 — 永久。
## 许可证
MIT © Voxell, Inc.
