使用说明

矢量知识库MCP服务器

基于FastAPI/FastMCP的高性能模型上下文协议（MCP）服务器，提供基于矢量的知识管理，具有文档存储、相似性搜索和智能检索功能。

📖 目录

矢量知识库MCP服务器

🚀 特性

FastAPI后端：高性能异步API服务器
矢量数据库：用于语义搜索的ChromaDB集成
文档存储：用于文件管理的MinIO对象存储
PostgreSQL数据库：结构化数据存储和元数据
MCP协议：使用FastMCP实现模型上下文协议服务器
管理界面：PgAdmin用于数据库管理（仅限开发）
开发就绪：包括热重载和开发工具

🏗️ 建筑

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   FastAPI App   │────│   ChromaDB      │────│   PostgreSQL    │
│   (Port 8100)   │    │   (Port 8101)   │    │   (Port 5432)   │
│─────────────────│    └─────────────────┘    └─────────────────┘
│   FastMCP App   │
│ (Port 8100/mcp) │
└─────────────────┘
         │
         │
┌─────────────────┐    ┌─────────────────┐
│     MinIO       │    │    PgAdmin      │
│ (Ports 9100/01) │    │   (Port 5550)   │
└─────────────────┘    └─────────────────┘

上述模式中描述的所有端口均用于开发

🛠️ 技术栈

后端：Python 3.11的FastAPI+
矢量数据库：用于嵌入和相似性搜索的ChromaDB
数据库：PostgreSQL 12与Alpine Linux
对象存储：MinIO用于文件存储
容器化：Docker和Docker Compose
MCP协议：用于模型上下文协议实现的FastMCP

📋 先决条件

Docker和Docker Compose
Python 3.11+（用于本地开发）
Git

🚀 快速开始

环境变量

在运行应用程序之前，创建一个 .env 文件基于 .env.example:

cp .env.example .env

根据您的环境填写变量：

APP_ENV=dev
APP_PORT=8100

# Nginx
NGINX_PORT=8080

DATABASE_URL=postgresql://akvo:password@db:5432/kb_mcp

# MinIO settings
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET_NAME=documents
# Should be same as NGINX_PORT
MINIO_SERVER_URL=http://localhost:8080/minio

# Chroma DB settings
CHROMA_DB_HOST=chromadb
CHROMA_DB_PORT=8000
VECTOR_STORE_BATCH_SIZE=100

# OpenAI settings
OPENAI_API_KEY=your-openai-api-key-here
OPENAI_API_BASE=https://api.openai.com/v1
OPENAI_MODEL=gpt-4
OPENAI_EMBEDDINGS_MODEL=text-embedding-ada-002

# Admin Auth
ADMIN_API_KEY=your-admin-api-key-here

备注

APP_ENV 接受两个值： prod 或 dev.
此变量控制中的启动命令 entrypoint.sh，确定应用程序是否在重新加载模式下运行(dev)或处于生产模式(prod).
VECTOR_STORE_BATCH_SIZE 控制在添加到向量存储时，一批处理多少个文档。在性能和达到一次可以存储的块数限制之间存在权衡——默认值为100，但您可以在此处调整此设置。
ADMIN_API_KEY 当前用于访问CRUD API密钥端点的身份验证。这样，脚本就可以创建一个API密钥，该密钥将用作访问CRUD知识库的身份验证令牌。
- 👉 如何生成 ADMIN_API_KEY
MINIO_ENDPOINT 是FastAPI应用程序用于与MinIO通信的内部Docker网络地址。
MINIO_SERVER_URL 是浏览器用于通过Nginx代理访问文档的外部URL。它应该与你的相匹配 NGINX_PORT.

开发设置

克隆存储库

git clone git@github.com:akvo/vector-knowledge-base-mcp-server.git
cd vector-knowledge-base-mcp-server

设置环境变量

cp .env.example .env
# Edit .env with your configurations

启动开发环境
```
./dev.sh up -d
```
验证服务是否正在运行
```
docker compose ps
```

运行pytest

运行FastAPI端点测试

./dev.sh exec main ./test.sh api

运行e2e测试

./dev.sh exec main ./test.sh e2e

运行FastMCP测试

./dev.sh exec main ./test.sh mcp

运行所有测试

./dev.sh exec main ./test.sh all

生产设置

构建并启动生产服务

docker compose -f docker-compose.yml up -d

服务端口（dev）

服务	开发	生产	描述
FastAPI	8100	8000	主要应用程序API
ChromaDB	8101	8001	矢量数据库
PostgreSQL	5432	5432	主数据库
MinIO API	9100	9000	对象存储API
MinIO控制台	9101	9001	MinIO web界面
PgAdmin	5550	-	数据库管理员（仅限开发人员）
Nginx	8080	80	反向代理

🔑 身份验证和API密钥

此项目使用 API密钥 用于访问知识库和管理API的身份验证。有两种类型的密钥：

管理员API密钥 (ADMIN_API_KEY)–用于管理操作，例如创建或撤销其他API密钥。
API密钥 –通过管理员API生成以访问知识库端点。

使用管理员API密钥

你的 ADMIN_API_KEY 定义在您的 .env 文件。
要执行管理任务，请将其包含在 Authorization 头球

Authorization: Admin-API-Key <your_admin_api_key>

示例：通过管理端点创建新的API密钥

curl -X POST http://localhost:8100/api/v1/api-key \
  -H "Authorization: Admin-Key sk_xxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "app-name", "is_active": true}'

使用API密钥

生成的API密钥用于访问受保护的知识库终结点。
将其纳入 Authorization 头球

Authorization: API-Key <your_api_key>

示例：查询知识库

curl -X GET http://localhost:8100/api/v1/knowledge-base \
  -H "Authorization: API-Key sk_xxxxxxx"

👉 有关详细信息 API-Key 用法，请阅读：SECURITY.md

汇总表

密钥类型	标题名称	目的
管理员API密钥	`Authorization: Admin-Key <key>`	管理API密钥和管理任务
用户/API密钥	`Authorization: API-Key <key>`	访问知识库并执行CRUD操作

📦 MinIO文档存储和公共访问

此应用程序使用MinIO进行对象存储，并通过Nginx反向代理提供对上传文档的公共访问。这允许在web浏览器中直接查看或下载文档，而不需要AWS基于签名的身份验证。

运作原理

文档访问流旨在与Docker网络无缝协作：

Browser Request
    ↓
http://localhost:8080/minio/documents/kb_1/file.pdf
    ↓
Nginx (port 8080) - Reverse Proxy
    ↓
MinIO Container (minio:9000) - Internal Docker Network
    ↓
Document Served

关键部件：

内部沟通(MINIO_ENDPOINT):
- FastAPI应用程序用于上传、删除和管理操作
- 格式： minio:9000
- 仅在Docker网络中可访问
外部访问(MINIO_SERVER_URL):
- 浏览器用于访问文档
- 格式： http://localhost:8080/minio
- 通过Nginx反向代理路由
公共存储桶策略:
- MinIO存储桶配置了公共读取策略
- 允许在没有AWS签名的情况下直接访问文档
- 策略版本 2012-10-17 是AWS S3标准（静态，永不更改）

配置

环境变量：

# Internal endpoint - used by FastAPI for operations
MINIO_ENDPOINT=minio:9000

# External endpoint - used by browsers to access files
MINIO_SERVER_URL=http://localhost:8080/minio

# MinIO credentials
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET_NAME=documents

Nginx配置：

Nginx代理配置为转发 /minio/* 对MinIO服务的请求：

location /minio/ {
    proxy_pass http://minio/;
    proxy_set_header Host $host;
    # ... additional proxy settings
}

文档URL

当文档被上传和处理时，API以以下格式返回URL：

{
  "document_id": 1,
  "file_name": "example.pdf",
  "file_path": "http://localhost:8080/minio/documents/kb_1/example.pdf",
  "file_type": "application/pdf",
  "is_viewable_in_browser": true
}

这些URL可以是：

直接在浏览器中打开
嵌入于 <iframe> 元素
用于PDF查看器
通过直接链接下载

安全考虑

当前设置：

知识库中的文档是公开可读的
文档访问不需要身份验证
适用于内部网络或非敏感数据

对于使用敏感数据的生产：

如果需要限制文档访问，请考虑：

基于API的访问：通过已验证的API终结点删除公共存储桶策略和流式文档
Nginx身份验证：在Nginx级别添加身份验证
网络隔离：将MinIO和Nginx保持在专用网络上
VPN/防火墙：仅限制访问授权网络

禁用公共访问，删除或修改中的bucket策略 minio_service.py:

# Comment out or remove this in init_minio()
# set_bucket_public_read_policy(bucket_name)

然后根据您的安全需求在API或Nginx级别实现身份验证。

📖 API文档

应用程序运行后 (uvicorn app.main:app --reload 或通过Docker），API文档可通过 FastAPI文档:

Swagger用户界面→ http://localhost:8000/api/docs或http://localhost:8100/api/docs
ReDoc→ http://localhost:8000/redoc或http://localhost:8100/redoc

通过这些界面，您可以：

直接试用端点
查看请求和响应模式
交互式测试API

📁 项目结构

vector-knowledge-base-mcp-server/
├── main/                          # FastAPI application
│   ├── app/
│   │   ├── api/                   # API routes (endpoint FastAPI)
│   │   ├── core/                  # Core configuration (settings, logging, security)
│   │   ├── mcp/                   # MCP related files (FastMCP server, tools)
│   │   ├── models/                # Pydantic models / ORM models
│   │   ├── schemas/               # API schemas (Pydantic / base)
│   │   ├── services/              # Business logic / service layer
│   │   ├── utils/                 # Helpers / utilities
│   ├── tests/                     # Unit / integration tests
│   ├── Dockerfile
│   └── requirements.txt
├── script/                        # Data pipeline and init scripts
├── nginx/                         # Nginx reverse proxy
│   ├── conf.d/
│   │   └── default.conf          # Nginx configuration
│   └── Dockerfile
├── db/
│   ├── docker-entrypoint-initdb.d/ # Init SQL scripts
│   └── script/                    # Migration / seed
├── pgadmin4/
│   └── servers.json               # GUI config
├── docker-compose.yml             # Compose prod
├── docker-compose.override.yml    # Override dev
├── .env.example                   # Env vars
└── README.md

🚨 故障排除

健康检查

# Check all services
curl http://localhost:8100/health

# Check individual components
curl http://localhost:8101/api/v2/heartbeat  # ChromaDB
curl http://localhost:9100/minio/health/live # MinIO
curl http://localhost:8080/health            # Nginx

常见问题：

无法访问文档（404错误）
- 验证Nginx是否正在运行： docker compose ps nginx
- 检查Nginx日志： docker compose logs nginx
- 确保 MINIO_SERVER_URL 匹配您的 NGINX_PORT
MinIO连接被拒绝
- 验证MinIO是否正在运行： docker compose ps minio
- 检查MinIO日志： docker compose logs minio
- 确保正确设置bucket策略（启动时检查应用程序日志）
浏览器中未加载文档
- 检查URL格式是否正确： http://localhost:8080/minio/documents/...
- 验证bucket策略：访问MinIO控制台 http://localhost:9101 并检查bucket权限
- 在中查看Nginx代理配置 nginx/conf.d/default.conf

🤝 贡献

分叉存储库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

开发指南

遵循PEP 8风格指南
为新功能添加测试
更新API变更文档
对提交消息使用常规提交

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🆘 支持

问题：在GitHub上打开一个问题
文档：检查 /docs 服务器运行时的终结点
社区：在GitHub讨论中加入我们的讨论

建于❤️ 使用FastAPI和FastMCP