MCP Service Hub

MCP服务中心

全栈MCP Explorer+船舶排放计算器

一个用于管理和与多个模型上下文协议（MCP）服务器交互的综合平台，其特征是基于波塞冬原理的船舶排放计算。

🌟 特性

• MCP管理：用于管理多个MCP服务器的集中式集线器
• 船舶排放：使用波塞冬原理基线进行高级计算
• 实时监控：基于WebSocket的健康检查和状态更新
• 交互式仪表板：具有实时数据可视化功能的现代React前端
• API网关：用于MCP工具调用和管理的RESTful API
• 认证：基于JWT的用户身份验证，具有基于角色的访问控制

🏗️ 建筑

服务

• 后端（NestJS）：主API服务器、MCP管理、WebSocket网关
• 前端（Next.js）：用于MCP探索和交互的React仪表板
• MCP公式：船舶排放计算服务（波塞冬原则）
• MCP天气：气象数据服务
• PostgreSQL：主数据库
• 瑞迪斯：缓存和会话存储

MCP服务

1. 排放MCP (:3004)：符合波塞冬原则的船舶排放计算
2. 天气MCP (:3002)：天气数据和预报
3. 发送邮件MCP (:3005)：使用BullMQ队列发送电子邮件
4. 聊天MCP (:3003)：人工智能聊天界面（计划中）

🚀 快速开始

先决条件

• Docker和Docker Compose
• Node.js 22+（用于本地开发）
• PostgreSQL 16+（如果不使用Docker运行）

生产设置（推荐）

1. 克隆存储库

   git clone 
   cd mcp-service-hub

1. 配置环境

   cp .env.example .env
   # Edit .env with your configuration
   # IMPORTANT: Change default secrets and API keys!

1. 启动所有服务

   npm run dev
   # or
   docker-compose up -d

1. 运行数据库迁移

   npm run db:migrate
   # or
   docker-compose exec backend npx prisma migrate deploy

1. 访问应用程序

- 前端：http://localhost:3001 - 后端API：http://localhost:3000 - MCP公式：http://localhost:3004 - MCP天气：http://localhost:3002 - MCP发送邮件：http://localhost:3005

环境配置

应用程序使用来自 根 .env 文件所有服务（后端、前端、MCP服务）都使用此单一配置文件。

重要安全注意事项:

• 这 .env 文件是 从不 复制到Docker镜像中（受保护 .dockerignore)
• 环境变量在运行时通过以下方式传递给容器 env_file 在docker-compose.yml中
• 这确保了秘密不会被烘焙到图像中，并且可以在不重建的情况下进行更改

关键变量 .env:

# Database
POSTGRES_USER=mcp_service
POSTGRES_PASSWORD=mcp_service_password  # CHANGE THIS!
POSTGRES_DB=mcp_service
DATABASE_URL=postgresql://mcp_service:mcp_service_password@postgres:5432/mcp_service?schema=public

# JWT Security (CHANGE THESE!)
ACCESS_TOKEN_SECRET=change-this-to-a-secure-random-string-min-32-chars
REFRESH_TOKEN_SECRET=change-this-to-another-secure-random-string-min-32-chars

# MCP API Key (CHANGE THIS!)
MCP_HUB_API_KEY=change-this-to-a-secure-api-key

# Frontend URLs
NEXT_PUBLIC_API_URL=http://localhost:3000
NEXT_PUBLIC_WS_URL=ws://localhost:3000

📦 NPM脚本

该项目包括用于开发和部署的方便的npm脚本：

发展

# Start all services in development mode
npm run dev

# Start with fresh build
npm run dev:build

# View all logs
npm run dev:logs

# Stop all services
npm run dev:stop

# Restart all services
npm run dev:restart

# Check service status
npm run status

数据库

# Run migrations
npm run db:migrate

# Generate Prisma client
npm run db:generate

# Open Prisma Studio
npm run db:studio

# Reset database (WARNING: destroys data)
npm run db:reset

日志记录

# All service logs
npm run dev:logs

# Backend logs only
npm run backend:logs

# Frontend logs only
npm run frontend:logs

# MCP services logs
npm run mcp:logs

建筑

# Build all services
npm run build

# Build specific services
npm run build:backend
npm run build:frontend
npm run build:mcp

测试与质量

# Run all unit tests
npm run test

# Run tests with coverage report
npm run test:cov

# Run tests in watch mode (for development)
npm run test:watch

# Run end-to-end tests
npm run test:e2e

# Run linting
npm run lint

# View coverage report (after running test:cov)
open backend/coverage/lcov-report/index.html

测试覆盖范围：

• ✅ 服务单元测试（MCP、认证、密码）
• ✅ 控制器单元测试
• ✅ E2E认证流测试
• ✅ MCP API的E2E测试

看 后端/测试.md 获取详细的测试指南。

维护

# Stop and remove containers/volumes
npm run clean

# Full system cleanup (WARNING: removes everything)
npm run clean:all

快速设置

# Complete setup (copies env, starts services, runs migrations)
npm run setup

替代方案：使用Make

如果您更喜欢使用Make命令：

# Show all available commands
make help

# Start development environment
make dev

# View logs
make dev-logs

# Database operations
make db-migrate
make db-studio

# Stop services
make dev-stop

开发环境设置

备注：对于基于Docker的设置，所有服务都使用根 .env 文件。对于没有Docker的本地开发，您需要单独配置每个服务。

后端开发（本地）

cd backend
cp ../env.example .env
# Edit .env file and adjust DATABASE_URL and REDIS_URL to use localhost
npm install
npx prisma generate
npx prisma migrate dev
npm run start:dev

前端开发

cd frontend
npm install
npm run dev

MCP服务开发

# MCP Formula
cd mcp-hub/mcp-formula
npm install
npm run dev

# MCP Weather
cd mcp-hub/mcp-weather
npm install
npm start

📋 完整的环境变量参考

所有环境变量都在根中定义 .env 文件。看 .env.example 获取包含所有可用选项和描述的完整模板。

Docker（生产/开发）

将服务名称用作主机：

• DATABASE_URL=postgresql://user:password@postgres:5432/mcp_service
• REDIS_HOST=redis

本地开发（无Docker）

使用localhost作为主机：

• DATABASE_URL=postgresql://user:password@localhost:5432/mcp_service
• REDIS_HOST=localhost

🐳 Docker命令

生产

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Rebuild specific service
docker-compose up -d --build backend

开发（仅后端）

cd backend
docker-compose up -d

仅限前端

cd frontend
docker-compose up -d

📚 API文档

认证

• POST /auth/register -用户注册
• POST /auth/login -用户登录
• GET /auth/me -获取当前用户

MCP管理

• GET /mcps -列出所有MCP配置
• POST /mcps/config -创建MCP配置
• GET /mcps/:mcpId/tools -获取MCP工具
• POST /mcps/:mcpId/tools/:toolId/invoke -调用MCP工具

健康监测

• POST /mcps/health/check/:mcpId -检查MCP健康状况
• GET /mcps/health/history/:mcpId -获取健康史

🔧 发展

数据库管理

# Generate Prisma client
npx prisma generate

# Create migration
npx prisma migrate dev --name "migration-name"

# Reset database
npx prisma migrate reset

# Open Prisma Studio
npx prisma studio

测试

# Backend tests
cd backend
npm run test
npm run test:e2e

# Frontend tests (if available)
cd frontend
npm run test

📊 MCP服务

排放MCP

提供基于波塞冬原理的船舶排放计算：

• 基线计算：最小目标、奋斗目标和射程目标
• 船舶数据：综合船舶信息数据库
• 排放追踪：历史排放数据分析
• 合规性分析：波塞冬原则合规性检查

天气MCP

天气数据和预报服务：

• 当前天气：实时天气状况
• 预测：多日天气预报
• 位置支持：全球天气数据访问

发送邮件MCP

带队列管理的电子邮件发送服务：

• BullMQ队列：可靠的异步电子邮件处理
• Redis存储：队列持久性和作业管理
• 工作排程：自动队列维护和清理
• MCP集成：标准MCP Hub身份验证和健康检查
• 可扩展：已准备好使用自定义电子邮件提供商（SMTP、SendGrid等）

🔒 安全

• 基于JWT的刷新令牌身份验证
• 基于角色的访问控制（USER/ADMIN）
• MCP服务的API密钥认证
• 跨源请求的CORS配置
• 仅用于刷新令牌的HTTP Cookie

📈 监控

• 健康检查：自动MCP服务监控
• WebSocket更新：实时状态通知
• 呼叫记录：全面的API呼叫跟踪
• 指标：响应时间和错误率

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

📄 许可证

本项目根据未经许可的许可证获得许可。

📞 支持

如有疑问或需要支持，请在存储库中创建问题。