内容
<h1 align="center">
<code>vectorless-mcp</code>
</h1>
<p align="center">
<strong>适用于 Vectorless 的 MCP 服务器 — 为 AI 代理提供保留文档结构的检索服务。</strong>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/vectorless-mcp"><img src="https://img.shields.io/npm/v/vectorless-mcp?style=flat-square&logo=npm&logoColor=white&color=CB3837" alt="npm" /></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-4A90D9?style=flat-square" alt="MCP" /></a>
<img src="https://img.shields.io/badge/OAuth_2.1-PKCE-green?style=flat-square" alt="OAuth" />
<img src="https://img.shields.io/badge/transport-Streamable_HTTP-blue?style=flat-square" alt="Streamable HTTP" />
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License" /></a>
</p>
---
## 工作原理
Vectorless 提供了一个 **远程 MCP 服务器**，地址为 `https://api.vectorless.store/mcp`。您的 AI 助手可以直接通过互联网连接到它 — 无需本地进程，也无需管理 API 密钥。
身份验证使用 **OAuth 2.1 with PKCE**：在首次连接时，您的 AI 客户端会打开 Vectorless 仪表盘，您在那里登录并批准访问。之后，它就可以直接工作。
```
┌──────────────────────────────────────────────────────────────┐
│ Claude Desktop / Cursor / Windsurf / Claude Code │
│ │
│ 1. 添加远程 MCP URL │
│ 2. OAuth 重定向 → Vectorless 仪表盘（登录 + 同意） │
│ 3. 发出令牌 → MCP 会话激活 │
│ 4. AI 通过 Streamable HTTP + SSE 调用工具 │
└───────────────────────────┬──────────────────────────────────┘
│
│ Streamable HTTP + SSE
▼
┌──────────────────────────────────────────────────────────────┐
│ api.vectorless.store/mcp │
│ │
│ OAuth 2.1 (PKCE) 7 工具 │
│ ┌──────────────────┐ ┌──────────────────────────┐ │
│ │ /.well-known/ │ │ vectorless_list_documents │ │
│ │ oauth-* │ │ vectorless_ingest_document│ │
│ │ /oauth/authorize │ │ vectorless_get_document │ │
│ │ /oauth/token │ │ vectorless_get_tree │ │
│ │ /oauth/register │ │ vectorless_get_section │ │
│ └──────────────────┘ │ vectorless_query │ │
│ │ vectorless_delete_document│ │
│ 作用域： └──────────────────────────┘ │
│ • documents:read │
│ • documents:write Vectorless 引擎 │
│ • query （检索 + 摄入） │
└──────────────────────────────────────────────────────────────┘
```
## 设置（远程 — 推荐）
将远程 URL 添加到您的 AI 客户端配置中。**无需安装。**
### Claude Desktop
`设置 → 开发者 → 编辑配置`：
```json
{
"mcpServers": {
"vectorless": {
"url": "https://api.vectorless.store/mcp"
}
}
}
```
### Cursor
`.cursor/mcp.json`：
```json
{
"mcpServers": {
"vectorless": {
"url": "https://api.vectorless.store/mcp"
}
}
}
```
### Windsurf
`~/.codeium/windsurf/mcp_config.json`：
```json
{
"mcpServers": {
"vectorless": {
"url": "https://api.vectorless.store/mcp"
}
}
}
```
### Claude Code
`.claude/settings.json`：
```json
{
"mcpServers": {
"vectorless": {
"url": "https://api.vectorless.store/mcp"
}
}
}
```
就这样。在第一次使用时，您的 AI 客户端会在您的浏览器中打开 Vectorless 仪表盘。登录（Google、GitHub 或电子邮件），批准权限，然后您就连接成功了。
## OAuth 作用域
当您授权时，同意屏幕会显示这些权限：
| 作用域 | 授予访问权限 |
|-------|-----------------|
| **`documents:read`** | 列出文档、获取元数据、浏览树、获取章节 |
| **`documents:write`** | 上传新文档、删除现有文档 |
| **`query`** | 对文档运行自然语言查询 |
您可以选择授予哪些作用域。AI 代理只能使用与您批准的作用域相匹配的工具。
## 可用工具
### `vectorless_list_documents`
列出所有文档，包含状态、元数据和分页。
### `vectorless_ingest_document`
从 URL 或 base64 内容上传文档。支持 PDF、DOCX、Markdown、HTML、纯文本。文档被解析为具有 AI 生成摘要的层次章节树。
### `vectorless_get_document`
获取文档的元数据和处理状态（待处理 → 解析 → 总结 → 已准备）。
### `vectorless_get_tree`
查看层次大纲 — 包含标题、摘要、深度和令牌计数的章节。使用此功能来了解查询前文档的内容。
### `vectorless_get_section`
通过 ID 获取特定章节的完整内容。
### `vectorless_query`
提出自然语言问题。LLM 导航文档树以查找并返回最相关的章节，包含完整内容、策略、时间和成本。
### `vectorless_delete_document`
永久删除文档和所有章节。
## 示例对话
```
您： 上传这篇论文：https://arxiv.org/pdf/2301.00001
Claude： [调用 vectorless_ingest_document]
完成 — doc_abc123 已准备（14 章节，48,200 个令牌）。
您： 结构是什么？
Claude： [调用 vectorless_get_tree]
引言（1,200 个令牌）
背景（800 个令牌）
相关工作（2,400 个令牌）
方法论（3,600 个令牌）
数据收集（1,100 个令牌）
模型架构（2,500 个令牌）
结果（4,200 个令牌）
结论（900 个令牌）
您： 他们使用了什么模型架构？
Claude： [调用 vectorless_query]
找到 2 个相关章节（分段树，340ms）：
## 模型架构
我们采用具有 12 个注意力头的基于变换器的编码器...
## 结果
模型在基准测试中达到了 94.2% 的准确率...
```
## 备用方案：本地 Stdio 服务器
如果您的 MCP 客户端不支持远程服务器，请在本地运行 stdio 桥接：
```bash
npx vectorless-mcp
```
```json
{
"mcpServers": {
"vectorless": {
"command": "npx",
"args": ["-y", "vectorless-mcp"],
"env": {
"VECTORLESS_API_KEY": "vl_..."
}
}
}
}
```
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `VECTORLESS_API_KEY` | — | API 密钥（远程必填，自托管可选） |
| `VECTORLESS_BASE_URL` | `https://api.vectorless.store` | 服务器 URL |
| `VECTORLESS_TRANSPORT` | `http` | 线路协议（`http` 或 `connect`） |
## 自托管
将 MCP 指向您自己的 Vectorless 实例：
```json
{
"mcpServers": {
"vectorless": {
"url": "https://your-server.com/mcp"
}
}
}
```
或通过 stdio：
```json
{
"mcpServers": {
"vectorless": {
"command": "npx",
"args": ["-y", "vectorless-mcp"],
"env": {
"VECTORLESS_BASE_URL": "https://your-server.com",
"VECTORLESS_API_KEY": "your-key"
}
}
}
}
```
## 许可证
MIT
