Document MCP

文件mcp（基础）

基于Gin+Ent+JWT（access/refresh）+PostgreSQL（pgvector）的 文档索引/搜索（包括2-depth、year-document、alias） 和 基于组的文档ACL（Read/RW/Deny） 是底妆。

配置

• HTTP： cmd/api/main.go
• 应用程序引导带（加载设置/DB连接/pgvector+ent自动迁移）： internal/app/app.go
• Ent模式（文档/alias/embedding/ACL/用户/组/刷新令牌）： ent/schema
• 嵌入提供者（OpenAI text-embedding-3-small，1536昏暗）： internal/embedding/openai.go
• 认证/认可（JWT+refresh rotation，文档ACL判定）： internal/service/auth/service.go
• 搜索（向量相似度+year/depth/alias过滤器+ACL过滤）： internal/service/search/service.go
• 路由： internal/httpapi/router.go

准备运行

1） PostgreSQL+pgvector

用于本地测试 提供。

docker compose up -d

数据库必须预先创建（应用程序 CREATE DATABASE不至于）。

示例）

CREATE DATABASE document_mcp;

启动应用程序时 internal/db/migrate.go在中：

• CREATE EXTENSION IF NOT EXISTS vector;
• 自动创建ent模式
• document_embeddings.embedding 在中创建ivfflat索引

2）环境变量

.env创建 .env.example请参考填写。

必需：

• DATABASE_URL
• JWT_ACCESS_SECRET, JWT_REFRESH_SECRET
• OPENAI_API_KEY

执行

go run ./cmd/api --serve

默认地址为 HTTP_ADDR（默认 :8080）。

健康检查：

curl localhost:8080/health

Swagger用户界面：

• http://localhost:8080/swagger/
• OpenAPI JSON： http://localhost:8080/openapi.json

初始帐户设置（命令）

无需运行服务器 创建/更新最初用户可以（衣领）。

go run ./cmd/api --init-user \
  --email a@example.com \
  --password 'password123!' \
  --name Alice \
  --group team-security

初始化后一起运行到服务器的步骤 --serve一起指定。

go run ./cmd/api --init-user --email a@example.com --password 'password123!' --name Alice --serve

注意： --init-user虽然没有OpenAI键也可以工作， --serve用于在生成/检索文档时调用嵌入 OPENAI_API_KEY需要。

API摘要

认证

• POST /auth/register
• POST /auth/login → {access_token, refresh_token}
• POST /auth/refresh （刷新旋转）
• POST /auth/logout

群组

• POST /groups （创建组）
• POST /groups/:id/members （将用户添加到组中）
• GET /me/groups （我的组列表）

文件

• POST /documents （创建文档+嵌入创建+保存alias）
• GET /documents/:id （通过ACL时查询）
• POST /documents/:id/acl （文档ACL设置/更新）

搜索

• POST /search

- 矢量搜索+过滤器： year, depth1, depth2, alias - 应用ACL规则： deny如果有，则排除， read/read_write如果有或拥有，则包括

cURL示例

1）注册/登录会员

curl -s -X POST localhost:8080/auth/register \
  -H 'content-type: application/json' \
  -d '{"email":"a@example.com","password":"password123!","name":"Alice"}'

TOKENS=$(curl -s -X POST localhost:8080/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"a@example.com","password":"password123!"}')

ACCESS=$(echo $TOKENS | jq -r .access_token)
REFRESH=$(echo $TOKENS | jq -r .refresh_token)

2）创建组并添加成员

G=$(curl -s -X POST localhost:8080/groups \
  -H "authorization: Bearer $ACCESS" \
  -H 'content-type: application/json' \
  -d '{"name":"team-security"}')
GID=$(echo $G | jq -r .id)

# 내 user_id는 register 응답에서 얻거나 DB에서 확인(추후 /me 엔드포인트 추가 가능)
curl -s -X POST localhost:8080/groups/$GID/members \
  -H "authorization: Bearer $ACCESS" \
  -H 'content-type: application/json' \
  -d '{"user_id":""}'

3）生成文档

DOC=$(curl -s -X POST localhost:8080/documents \
  -H "authorization: Bearer $ACCESS" \
  -H 'content-type: application/json' \
  -d '{
    "year": 2024,
    "depth1": "policy",
    "depth2": "security",
    "title": "ISMS 가이드",
    "content": "...",
    "aliases": ["ISMS","정보보호"]
  }')
DOCID=$(echo $DOC | jq -r .id)

4）文档ACL设置

curl -s -X POST localhost:8080/documents/$DOCID/acl \
  -H "authorization: Bearer $ACCESS" \
  -H 'content-type: application/json' \
  -d '{"group_id":"'$GID'","effect":"read"}'

5）搜索

curl -s -X POST localhost:8080/search \
  -H "authorization: Bearer $ACCESS" \
  -H 'content-type: application/json' \
  -d '{"query":"ISMS 심사 대응","year":2024,"alias":"ISMS","limit":10}'

注意/扩展点

• 现在贝斯 Ent自动迁移启动应用程序时执行。操作建议使用单独的migrate管线（DDL分离）。
• pgvector索引（ivfflat）参数（lists）请根据数据规模进行调整。 internal/db/migrate.go
• 组/成员/ACL管理的管理员权限模型（RBAC）仍然是最低实施（建议必要时扩展Role/Permission）。