Ainstruct MCP

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:

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`
1. 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 " \ -H "Content-Type: application/json" \ -d '{"label": "My Client", "collection_id": "", "permission": "read_write"}'

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

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

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

**REST API**:

curl -X POST http://localhost:8001/api/v1/auth/pat \ -H "Authorization: Bearer " \ -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//promote \ -H "X-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：

|API |目的|授权方法|
|-----|---------|-------------|
|REST API |交互式身份验证+操作| JWT（短期）|
|MCP API | AI代理操作| PAT或CAT（长期）|

### 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|PAT令牌|
|---------|-----|-----------|
|范围|单个集合|所有用户的集合|
|权限|读取或read_write |继承用户的作用域（读取、写入、管理）|
|用例|文档操作| API完全访问（文档+管理）|
|创建|需要JWT/PAT |需要JWT|
|集合绑定|是（一个集合）|否（所有用户集合）|
|用户绑定|否（绑定到集合）|是（绑定到用户）|
|前缀| `cat_live_` | `pat_live_`

## 基于集合的数据模型

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

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

## 环境变量

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

### 服务选择

|变量|必填|描述|
|----------|----------|-------------|
| `SERVICE` |是|运行哪个服务： `mcp-server` （默认端口8000）或 `rest-api` （默认端口8001）|

### 数据库

|变量|默认值|必填|说明|
|----------|---------|----------|-------------|
| `DATABASE_URL` |-|是| PostgreSQL连接字符串（例如。， `postgresql+asyncpg://user:pass@host:5432/db`) |
| `POSTGRES_PASSWORD` |-|是| PostgreSQL密码（用于docker compose）|

### 向量存储

|变量|默认值|必填|说明|
|----------|---------|----------|-------------|
| `QDRANT_URL` | `http://localhost:6333` |否|Qdrant服务器URL|
| `QDRANT_API_KEY` |-|否| Qdrant API密钥（可选）|
| `OPENROUTER_API_KEY` |-|是|用于嵌入的OpenRouter API密钥|
| `EMBEDDING_MODEL` | `Qwen/Qwen3-Embedding-8B` |否|嵌入模型|
| `EMBEDDING_DIMENSIONS` | `4096` |否|嵌入尺寸|
| `USE_MOCK_EMBEDDINGS` | `false` |否|使用基于哈希的确定性向量进行测试|

### 认证

|变量|默认值|必填|说明|
|----------|---------|----------|-------------|
| `ADMIN_API_KEY` |-|是|管理员身份验证密钥|
| `JWT_SECRET_KEY` | `change-this-secret-in-production` |是| JWT令牌签名的密钥|
| `JWT_ALGORITHM` | `HS256` |否|JWT签名算法|
| `JWT_ACCESS_TOKEN_EXPIRE_MINUTES` | `30` |否|访问令牌到期时间|
| `JWT_REFRESH_TOKEN_EXPIRE_DAYS` | `7` |否|刷新令牌到期时间|

### PAT令牌设置

|变量|默认值|必填|说明|
|----------|---------|----------|-------------|
| `PAT_DEFAULT_EXPIRY_DAYS` | `90` |否|新PAT令牌的默认到期日|
| `PAT_MAX_EXPIRY_DAYS` | `365` |否| PAT令牌允许的最大过期时间|

### 服务器配置

|变量|默认值|必填|说明|
|----------|---------|----------|-------------|
| `HOST` | `0.0.0.0` |否|服务器主机|
| `PORT` | `8000` （MCP）， `8001` （REST）|否|服务器端口。MCP默认为8000，REST API默认为8001|

### 文档处理

|变量|默认值|必填|说明|
|----------|---------|----------|-------------|
| `CHUNK_MAX_TOKENS` | `400` |否|每个文档块的最大令牌数|
| `CHUNK_OVERLAP_TOKENS` | `50` |否|块之间重叠|
| `SEARCH_MAX_RESULTS` | `5` |否|最大搜索结果|
| `SEARCH_MAX_TOKENS` | `2000` |否|搜索结果中的最大令牌数|

## MCP配置

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

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

Authorization: Bearer YOUR_PAT_OR_CAT_TOKEN

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

## REST API配置

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

### 认证

|方法|端点|描述|
|--------|----------|-------------|
|职位| `/auth/register` |注册新用户|
|职位| `/auth/login` |登录并获取JWT代币|
|职位| `/auth/refresh` |刷新JWT令牌|
|得到| `/auth/profile` |获取用户资料|

### PAT代币

|方法|端点|描述|
|--------|----------|-------------|
|职位| `/auth/pat` |创建PAT令牌|
|得到| `/auth/pat` |列出PAT令牌|
|删除| `/auth/pat/{pat_id}` |撤销PAT令牌|
|职位| `/auth/pat/{pat_id}/rotate` |旋转PAT令牌|

### CAT代币

|方法|端点|描述|
|--------|----------|-------------|
|职位| `/auth/cat` |创建CAT令牌|
|得到| `/auth/cat` |列出CAT令牌|
|删除| `/auth/cat/{cat_id}` |撤销CAT令牌|
|职位| `/auth/cat/{cat_id}/rotate` |旋转CAT令牌|

### 集合

|方法|端点|描述|
|--------|----------|-------------|
|职位| `/collections` |创建收藏|
|得到| `/collections` |列出收藏|
|得到| `/collections/{collection_id}` |获取收藏|
|补丁| `/collections/{collection_id}` |重命名集合|
|删除| `/collections/{collection_id}` |删除收藏|

### 文件

|方法|端点|描述|
|--------|----------|-------------|
|职位| `/documents` |存储文档|
|得到| `/documents` |列出文件|
|得到| `/documents/{document_id}` |获取文档|
|补丁| `/documents/{document_id}` |更新文档|
|删除| `/documents/{document_id}` |删除文档|
|职位| `/documents/search` |语义搜索|

### 管理员

|方法|端点|描述|
|--------|----------|-------------|
|得到| `/admin/users` |列出用户|
|得到| `/admin/users/search` |搜索用户|
|得到| `/admin/users/{user_id}` |获取用户详细信息|
|补丁| `/admin/users/{user_id}` |更新用户|
|删除| `/admin/users/{user_id}` |删除用户|
|职位| `/admin/users/{user_id}/promote` |晋升为管理员|

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

Authorization: Bearer YOUR_JWT_TOKEN

## 发展

### 测试

./scripts/test.sh

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

有关更多详细信息，请参阅 [测试指导](./docs/TESTING.md).

### 数据库迁移

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

有关更多详细信息，请参阅 [测试指导](./docs/TESTING.md).

## 许可证

麻省理工学院