矢量知识库MCP服务器
基于FastAPI/FastMCP的高性能模型上下文协议（MCP）服务器，提供基于矢量的知识管理，具有文档存储、相似性搜索和智能检索功能。
______________________________________________________________________
📖 目录
- 📖 目录 - 🚀 特性 - 🏗️ 建筑 - 🛠️ 技术栈 - 📋 先决条件 - 🚀 快速开始 - 环境变量 - 开发设置 - 生产设置 - 服务端口（dev） - 🔑 身份验证和API密钥 - 使用管理员API密钥 - 使用API密钥 - 汇总表 - 📦 MinIO文档存储和公共访问 - 运作原理 - 配置 - 文档URL - 安全考虑 - 📖 API文档 - 📁 项目结构 - 🚨 故障排除 - 健康检查 - 🤝 贡献 - 开发指南 - 📄 许可证 - 🆘 支持
______________________________________________________________________
🚀 特性
- 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知识库的身份验证令牌。
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 示例：通过管理端点创建新的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 示例：查询知识库
curl -X GET http://localhost:8100/api/v1/knowledge-base \
-H "Authorization: API-Key sk_xxxxxxx"👉 有关详细信息 API-Key 用法，请阅读：SECURITY.md
汇总表
| 密钥类型 | 标题名称 | 目的 |
|---|---|---|
| 管理员API密钥 | Authorization: Admin-Key | 管理API密钥和管理任务 |
| 用户/API密钥 | Authorization: API-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=documentsNginx配置：
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可以是：
- 直接在浏览器中打开
- 嵌入于 `` 元素
- 用于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