MCP For Retriever Demo

MCP用于寻回犬

集成Web搜索、矢量数据库（Qdrant）、关系数据库（PostgreSQL）。\ 提供认证/授权（Authentication/Authorization）功能的模型上下文协议（MCP）服务器。

许可证

麻省理工学院 根据许可证分发。

🚀 快速入门

基本要求

• 码头工人：所有服务都以Docker（Compose）运行。
• Tavilly API密钥: https://tavily.com由发放（免费）

作为Docker运行

# 1. 환경 설정
cp .env.example .env
# .env 파일에서 TAVILY_API_KEY 설정 필수

# 2. 모든 서비스 시작
./scripts/start-docker.sh --build

# 3. 서비스 상태 확인
./scripts/test-services.sh

此项目配置为仅以Docker Compose运行。（仅支持MCP-Streamable HTTP）\ 因此，所有数据库和服务都由容器管理。

📋 主要功能

搜索功能

• Web搜索：通过Tavily API搜索Web内容
• 矢量搜索：通过Qdrant进行语义搜索
• 搜索数据库：PostgreSQL专业搜索
• 集成搜索：在所有源中同时搜索

管理面板

• JWT认证：基于角色的访问控制（RBAC）
• 管理用户/会话：令牌无效和权限管理
• 📊 分析仪表板：基于Chart.js的可视化度量NEW
• 📤 导出数据：CSV/JSON形态数据提取NEW
• 🌍 国际化：韩语/英语支持NEW
• 🔔 实时通知：基于SSE的系统事件通知NEW

性能和监控

• Redis缓存：缓存搜索结果
• 异步处理：基于python asyncio
• 观察性：OpenTelemetry+Sentry集成
• 健康检查：监控所有服务状态

🏗️ 体系结构

graph TB
    Client[MCP Client] -->|JWT Token| MCPServer[MCP Server :8001]
    Client -->|Login/Admin| AuthGateway[Auth Gateway :8000]
    
    AuthGateway --> SQLite[(SQLite DB)]
    AuthGateway --> Redis[(Redis)]
    
    MCPServer --> PostgreSQL[(PostgreSQL)]
    MCPServer --> Qdrant[(Qdrant)]
    MCPServer --> Redis
    MCPServer --> Tavily[Tavily API]

配置服务

服务端口数据库说明 |--------|------|-------------|------| | Auth Gateway | 8000 | SQLite |身份验证/授权，Admin UI | 提供MCP Server 8001 PostgreSQL MCP工具 PostgreSQL 5432-|保存搜索数据、内容| Qdrant 6333/6334-矢量搜索引擎 |Redis|6379\]-|缓存、会话、令牌存储库|

🔐 验证流

1.用户注册和登录

# 등록
curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "Password123!"}'

# 로그인 (JWT 토큰 획득)
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "Password123!"}'

2.MCP客户端设置

{
  "mcpServers": {
    "mcp-retriever": {
      "url": "http://localhost:8001/",
      "transport": "http",
      "auth": {
        "type": "bearer",
        "token": "YOUR_JWT_TOKEN_HERE"
      }
    }
  }
}

🛠️ 可用工具

• search_web：Tavily网页搜索
• search_vectors：Qdrant矢量搜索
• search_database：搜索PostgreSQL
• search_all：搜索所有源整合
• health_check：检查服务状态

👨‍💼 管理用户界面

📋 概述

基于FastHTML+HTMX的现代化管理界面

关键特性：

• 🎨 顺风CSS + HTMX 响应式设计
• 🔐 JWT认证 和 RBAC 权限管理
• 📊 实时分析 和 导出数据 ✨ 新
• 🌍 多语言支持 （韩语/英语）NEW
• 🔔 实时通知 （基于SSE）NEW
• 🧩 14个可重复使用的组件 库

🎯 管理员功能

1. 仪表板 (/admin)

• 系统统计卡（用户、会话、权限数）
• 快速动作按钮

2. 用户管理 (/admin/users)

• 管理用户列表和角色
• 查看权限和更改角色

3. 会话管理 (/admin/sessions)

• 活动JWT令牌列表
• 单个/批令牌无效

4. 权限管理 (/admin/permissions)

• 权限列表和实时筛选
• 创建/删除特定于资源的权限
• 支持通配符模式

5. 角色管理 (/admin/roles)

• 角色-权限表
• 编辑和管理角色

6. 分析仪表板 (/admin/analytics) ✨ 新

• Chart.js可视化：工具使用情况，响应时间分布
• 度量表：可排序的详细统计信息
• 自动刷新：基于HTMX的实时更新

7. 导出数据 ✨ 新

• 用户数据: /admin/export/users.csv
• 权限数据: /admin/export/permissions.csv
• 公制数据: /admin/export/metrics.json

8. 语言设置 ✨ 新

• 语言转换：顶部LanguageSelector下拉列表
• 保留会话：浏览器重新启动后仍保留语言设置
• 全部翻译：翻译200多个UI元素

9. 实时通知 ✨ 新

• SSE流: /admin/events 端点
• 系统事件：错误，用户动作实时通知
• HTMX集成：无JavaScript实时更新

🔐 权限管理系统（RBAC）

基于角色的访问控制

MCP Retriever是一个完整的 RBAC（基于角色的访问控制） 实施系统：

# 기본 역할 구조
admin:    # 모든 권한 (웹검색, 벡터DB, 데이터베이스 R/W)
├─ user:  # 제한된 권한 (웹검색 R, 벡터DB R/W, 데이터베이스 R/W)
└─ guest: # 읽기 전용 (웹검색 R만)

# 별칭 역할
viewer → guest   # 읽기 전용 사용자
analyst → user   # 분석가 (user와 동일한 권한)

资源类型和权限

工具特定的权限表

🚀 默认管理员帐户

Docker启动时自动创建的默认帐户：

📱 连接和使用

1.管理员登录

# 1. Auth Gateway 로그인 페이지 접속
open http://localhost:8000/auth/login-page

# 2. 기본 관리자 계정으로 로그인
이메일: admin@example.com
비밀번호: Admin123!

# 3. Admin UI 접속
open http://localhost:8000/admin

2.通过API访问

# JWT 토큰 획득
TOKEN=$(curl -s -X POST "http://localhost:8000/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "Admin123!"}' | \
  jq -r '.access_token')

# Admin API 호출
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/admin/users"

🛠️ 管理员帐户自定义

可以将初始管理员帐户设置为环境变量：

# .env 파일에서 설정
AUTO_CREATE_ADMIN=true                    # 자동 생성 여부
ADMIN_EMAIL=admin@yourdomain.com          # 관리자 이메일
ADMIN_PASSWORD=YourSecurePassword123!     # 관리자 비밀번호  
ADMIN_USERNAME=Your Admin Name            # 관리자 이름

🔗 主要API端点

认证和管理

# 인증
POST /auth/login
POST /auth/register

# 세션 관리
GET /api/v1/admin/sessions/active
POST /api/v1/admin/users/{user_id}/revoke-tokens

# 데이터 내보내기 ✨ NEW
GET /admin/export/users.csv
GET /admin/export/permissions.csv
GET /admin/export/metrics.json

# 분석 및 알림 ✨ NEW
GET /admin/analytics
GET /admin/events (SSE)

# 언어 설정 ✨ NEW
POST /admin/change-language

🧪 测试

完备的测试系统

• 总测试：扩展250多个
• E2E测试：基于Playwright的Admin UI自动化
• 测试单位：77个组件测试（现有38个+新增39个）NEW
• 集成测试：基于Docker环境的完整系统验证

🎭 E2E测试扩展NEW

新增4个测试文件（43个测试）：

• test_analytics_dashboard.py -测试分析仪表板的可视化
• test_data_export.py -验证CSV/JSON导出
• test_internationalization.py -测试多语言转换
• test_real_time_notifications.py -SSE实时通知测试

🧩 元件单位测试扩展NEW

新添加的5个组件测试（39个测试）：

• TestAnalyticsChart -验证Chart.js渲染
• TestExportButton -测试数据导出按钮
• TestMetricsTable -验证度量表功能
• TestNotificationBanner -测试实时通知显示
• TestLanguageSelector -测试语言选择下拉列表

运行测试

# 전체 테스트 실행
./scripts/run-integration-tests.sh

# E2E 테스트 실행
./scripts/run-e2e-tests.sh

# 새로운 기능 테스트만 실행
docker exec -it mcp-server pytest tests/e2e/test_analytics_dashboard.py -v
docker exec -it mcp-server pytest tests/unit/test_auth/test_components.py::TestAnalyticsChart -v

📝 首选参数

初始设置指南

1. 创建环境变量文件

   cp .env.example .env

1. 设置必需的API密钥

- TAVILY_API_KEY: 塔维利在中发放免费API密钥 - 自动生成其余密钥（无需修改）

1. Docker Compose环境变量 （自动设置）

   # 서비스 URL - Docker 네트워크에서 자동 설정
   AUTH_GATEWAY_URL=http://auth-gateway:8000
   MCP_SERVER_URL=http://mcp-server:8001

   # 데이터베이스 호스트 - 컨테이너 이름으로 자동 설정
   POSTGRES_HOST=postgres
   QDRANT_HOST=qdrant
   REDIS_HOST=redis

服务器配置文件

在Docker环境中自动 COMPLETE 应用配置文件以启用所有功能：

• JWT认证和权限管理
• 上下文跟踪
• Redis缓存
• 速度限制
• 性能度量

🚀 部署

Docker操作命令

# 서비스 시작/중지
./scripts/start-docker.sh
./scripts/stop-docker.sh

# 로그 확인
./scripts/logs-docker.sh -f
./scripts/logs-docker.sh mcp-server -f

# 컨테이너 접속
docker exec -it mcp-postgres psql -U mcp_user -d mcp_retriever
docker exec -it mcp-redis redis-cli

📈 项目现状

🔍 搜索和数据处理

• 集成搜索（Web/矢量/数据库）
• Redis缓存和异步处理

🔐 安全和认证

• JWT+RBAC权限管理
• 会话跟踪和令牌无效

🖥️ 管理用户界面（FastHTML+HTMX）

• 14个可重复使用的组件 （现有9个+扩展5个）扩展
• 分析仪表板 （Chart.js可视化）NEW
• 导出数据 （CSV/JSON）✨ 新
• 多语言支持 （韩语/英语）NEW
• 实时通知 （基于SSE）NEW

🧪 测试和质量保证

• 超过250个测试 （现有220个→扩展）扩展
• 77个元件单位测试 （38个→77个）扩展
• 添加43个E2E测试 （新功能自动化）NEW
• 完善的Docker集成测试

🚀 基础架构和部署

• Docker Compose完全容器化
• 统一服务器配置文件和健康检查
• 自动化脚本（部署/测试/日志）