语义文档存储搜索服务

AI文档存储MCP服务器

远程MCP服务器，用于存储和搜索带有语义嵌入的markdown文档。具有使用JWT令牌的用户身份验证、具有权限的CAT（收集访问令牌）管理和基于收集的数据组织功能。

建筑

该系统由两个服务组成：

两者共享相同的数据库（PostgreSQL）和向量存储（Qdrant）。

更改端口

要更改默认端口，请设置 PORT 环境变量：

MCP服务器：

docker run -e SERVICE=mcp-server -e PORT=9000 ...

REST API：

docker run -e SERVICE=rest-api -e PORT=9001 ...

或者在docker compose中，修改 ports 映射：

mcp_server:
  ports:
    - "9000:9000"  # host:container

rest_api:
  environment:
    - PORT=9001
  ports:
    - "9001:9001"

## Quick Start

1. Copy environment file:
```bash
cp .env.example .env

2. 编辑 .env 使用您的凭据：

• POSTGRES_PASSWORD -PostgreSQL需要
• OPENROUTER_API_KEY -从https://openrouter.ai
• ADMIN_API_KEY -管理员身份验证密钥

3. 启动服务器：

docker-compose up -d

4. MCP服务器可在 http://localhost:8000/mcp
5. REST API可在 http://localhost:8001/api/v1

新用户入职培训

用户管理（注册、登录、令牌管理）仅通过REST API提供。

第一步：注册账号

REST API:

curl -X POST http://localhost:8001/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "username": "alice", "password": "secure123"}'

为新用户自动创建“默认”集合。

第二步：登录

REST API:

curl -X POST http://localhost:8001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "secure123"}'

保存返回的 access_token 和 refresh_token.

步骤3：创建身份验证凭据

您有两个身份验证选项：

选项A:CAT（收集访问令牌）

REST API:

curl -X POST http://localhost:8001/api/v1/auth/cat \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"label": "My Client", "collection_id": "<uuid>", "permission": "read_write"}'

提供标签、收藏ID（来源 /collections)、权限和可选到期。保存返回的令牌。

如果使用此：您只需要访问单个集合即可进行文档操作。

选项B:PAT令牌（用户级别）

REST API:

curl -X POST http://localhost:8001/api/v1/auth/pat \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"label": "My Client"}'

提供标签和可选的有效期。保存返回的令牌。

如果使用此：您需要访问所有集合或希望执行管理操作（创建集合、管理CAT等）。

步骤4：配置客户端

更新您的MCP客户端配置：

{
  "mcp": {
    "ainstruct": {
      "type": "remote",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_OR_PAT_TOKEN_HERE"
      },
      "enabled": true
    }
  }
}

管理用户

管理员用户(is_superuser=True)拥有对所有管理REST API端点的完全访问权限。

晋升为管理员

curl -X POST http://localhost:8001/api/v1/admin/users/<user_id>/promote \
  -H "X-Admin-API-Key: <your-admin-api-key>"

• 需要有效 X-Admin-API-Key 头球
• 无论现有管理员用户如何，都能正常工作

主要特点

• 文档管理：使用自动分块存储、检索、更新和删除markdown文档
• 语义搜索：使用嵌入（OpenRouter模型）搜索文档
• 集合：将文档组织到具有精细权限的用户拥有的集合中
• CAT（集合访问令牌）：创建、撤销和轮换具有读/写权限的令牌
• 用户认证：使用刷新令牌的基于JWT的登录
• 管理工具：管理用户并查看所有收藏（仅限管理员）
• REST API：端口8001上的独立REST API服务

MCP工具

文档工具

• store_document_tool -使用嵌入功能存储文档
• search_documents_tool -语义搜索
• get_document_tool -按ID检索
• list_documents_tool -列出文件
• update_document_tool -更新文档
• delete_document_tool -删除文档
• move_document_tool -在集合之间移动文档

收集访问令牌（CAT）工具

• create_collection_access_token_tool -创建CAT（特定于集合的令牌）
• list_collection_access_tokens_tool -列出CAT
• revoke_collection_access_token_tool -撤销CAT
• rotate_collection_access_token_tool -旋转CAT

收藏工具

• create_collection_tool -创建收藏
• list_collections_tool -列出收藏
• get_collection_tool -获取收藏详细信息
• delete_collection_tool -删除收藏
• rename_collection_tool -重命名集合

认证

系统使用两个具有不同身份验证方法的API：

JWT代币

• 通过REST API获取 /api/v1/auth/login
• 用于REST API操作和令牌管理
• 30分钟后过期（可通过刷新 /api/v1/auth/refresh)
• 不建议用于MCP -改用PAT或CAT

集合访问令牌（CAT）

• 通过REST API创建 /api/v1/auth/cat
• 特定收藏：分配给单个集合
• 权限： read （搜索/获取）或 read_write （完全访问）
• 可选到期日期
• 用例：文档操作（存储、搜索、更新、删除）
• 前缀: cat_live_

个人访问令牌（PAT）

• 通过REST API创建 /api/v1/auth/pat
• 用户级别：绑定到用户帐户，而不是特定集合
• 继承用户作用域：用户的读取、写入和管理权限
• 可选到期日期（最大可配置日期： PAT_MAX_EXPIRY_DAYS)
• 用例：API完全访问-文档操作（所有集合）、用户/集合管理、CAT管理
• 前缀: pat_live_

比较：CAT与PAT令牌

基于集合的数据模型

文档被组织成用户拥有的集合：

• 每个用户在注册时都会获得一个“默认”收藏
• 集合可以有多个具有不同权限的CAT
• 数据按收集进行隔离
• 丢失的令牌可以在不丢失数据的情况下进行替换

环境变量

除非另有说明，否则所有环境变量都由MCP服务器和REST API使用。这 SERVICE 变量决定运行哪个服务。

服务选择

数据库

向量存储

认证

PAT令牌设置

服务器配置

文档处理

MCP配置

对于任何兼容MCP的客户端，请使用以下配置：

1. MCP服务器URL: http://localhost:8000/mcp （或更改自定义端口）
2. 身份验证：通过 Authorization 头球
   复制

   Authorization: Bearer YOUR_PAT_OR_CAT_TOKEN
   

有关具体的配置文件格式和位置，请参阅MCP客户的文档。

REST API配置

REST API可在 http://localhost:8001/api/v1 具有以下端点：

认证

PAT代币

CAT代币

集合

文件

管理员

身份验证使用JWT承载令牌：

Authorization: Bearer YOUR_JWT_TOKEN

发展

测试

./scripts/test.sh

使用紫外线进行掉毛、类型检查和测试。

有关更多详细信息，请参阅 测试指导.

数据库迁移

alembic revision --autogenerate -m "description"
alembic upgrade head

有关更多详细信息，请参阅 测试指导.

许可证

麻省理工学院