快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

详细介绍

矢量知识库MCP服务器

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

______________________________________________________________________

📖 目录

矢量知识库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知识库的身份验证令牌。

- 👉 如何生成 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

示例：通过管理端点创建新的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=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可以是：

直接在浏览器中打开
嵌入于 `` 元素
用于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

目录标签

知识管理搜索FastAPI向量数据库Python本地部署语义搜索文档存储

接入字段

传输方式（transport，传输协议）

未说明

鉴权方式（authType，认证方式）

none

工具数量（toolCount，工具数）

0

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

未说明none部署方式未说明

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

仍需确认：installCommand

来源信息

MCP World

mcpworld.com

/detail/1cb9c24edf7c22ef5ff1503ea2074632

基于FastAPI和FastMCP的高性能向量知识库服务器，提供文档存储、相似性搜索和智能检索功能。

继续浏览同类 MCP

更多文档知识 MCP（3,282）返回 MCP 目录

上一个 MCP

Vectorize MCP Server

Vectorize MCP服务器实现，用于高级向量检索和文本提取，适用于文档处理和数据分析场景。

下一个 MCP

Vega-Lite MCP Server

Provides AI assistants with access to Vega-Lite documentation, visualization examples, and specification validation tools. Enables searching docs, retrieving examples by category, validating JSON specs, and accessing schema information for creating data visualizations.

Vector Knowledge Base MCP Server

快速接入

详细介绍

矢量知识库MCP服务器

📖 目录

🚀 特性

🏗️ 建筑

🛠️ 技术栈

📋 先决条件

🚀 快速开始

环境变量

开发设置

生产设置

服务端口（dev）

🔑 身份验证和API密钥

使用管理员API密钥

使用API密钥

汇总表

📦 MinIO文档存储和公共访问

运作原理

配置

文档URL

安全考虑

📖 API文档

📁 项目结构

🚨 故障排除

健康检查

🤝 贡献

开发指南

📄 许可证

🆘 支持

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP