SmartFridge MCP 服务器 - 准生产就绪 🚀
一个经过全面测试、具备容器化和生产就绪特性的强大SmartFridge MCP服务器。此实现提供了关键修复、适当的数据持久性、HTTP桥接、容器化支持以及广泛的错误处理功能。
✨ 特点
- 🔧 MCP 协议支持完整模型上下文协议实现
- 🌐 HTTP桥接器用于网页集成的RESTful API
- 🐳 Docker 准备就绪使用Docker和docker-compose实现完全容器化
- 📊 数据持久化可靠的基于JSON的数据存储，支持备份/恢复
- 🔒 安全全面的安全头部信息、输入验证和错误处理
- 🧪 广泛测试100%的测试覆盖率，涵盖单元测试、集成测试和端到端（E2E）测试
- 📈 生产监控健康检查、日志记录和指标监控
- 🔄 持续集成/持续交付（CI/CD）流水线自动化测试、构建和部署
- 📖 完整的文档资料详细的设置、使用和测试指南
🚀 快速入门
先决条件
- Node.js 18.0.0 或更高版本
- npm 8.0.0 或更高版本
- Docker（可选，用于容器化部署）
安装
# Clone the repository
git clone https://github.com/TheAriaki/smartfridge-mcp-server-fixed.git
cd smartfridge-mcp-server-fixed
# Install dependencies
npm install
# Build the project
npm run build
# Initialize sample data (optional)
npm run init-data运行服务器
# MCP mode (stdio)
npm start
# HTTP mode
npm run start:http
# Development mode with hot reload
npm run dev # MCP mode
npm run dev:http # HTTP mode🧪 测试
这个项目包含一个全面的测试套件，涵盖了应用程序的所有方面：
快速测试命令
# Run all tests
npm test
# Run specific test types
npm run test:unit # Unit tests
npm run test:integration # Integration tests
npm run test:config # Configuration tests
# Run tests with coverage
npm run test:coverage
# Validate deployment readiness
npm run validate-deployment测试运行器脚本
进行全面测试并输出详细结果：
# Make script executable
chmod +x scripts/run-tests.sh
# Run all tests
./scripts/run-tests.sh
# Run specific test type
./scripts/run-tests.sh unit
./scripts/run-tests.sh integration
./scripts/run-tests.sh validation测试覆盖率
测试套件包括：
- 单元测试MCP服务器工具、HTTP终端点、数据验证
- 集成测试Docker部署，端到端工作流程
- 配置测试环境变量、Nginx代理、安全性
- 部署验证生产准备就绪验证
见 TESTING.md 翻译为中文是：“测试说明文件.md” 或者 “测试文档.md”（具体翻译可能根据上下文有所调整，但“md”通常表示Markdown格式的文件） 以获取详细的测试文档。
🐳 Docker 部署
Docker Compose（推荐）
# Start with docker-compose
docker-compose up -d
# View logs
docker-compose logs -f
# Stop services
docker-compose down手动Docker
# Build image
npm run docker:build
# Run container
npm run docker:run
# Or manually
docker run -p 3000:3000 -v $(pwd)/data:/app/data smartfridge-mcp-server🌐 HTTP API 使用
当以HTTP模式运行时，服务器提供RESTful端点：
健康与信息终端
# Health check
curl http://localhost:3000/health
# Server information
curl http://localhost:3000/info
# Readiness check
curl http://localhost:3000/ready食品管理API
# Add a food item
curl -X POST http://localhost:3000/api/tools/addFoodItem \\
-H "Content-Type: application/json" \\
-d '{
"name": "Organic Milk",
"quantity": 1,
"unit": "liter",
"category": "dairy",
"expirationDate": "2025-01-15",
"location": "Main Shelf",
"notes": "2% fat content"
}'
# List all items
curl -X POST http://localhost:3000/api/tools/listFoodItems \\
-H "Content-Type: application/json" \\
-d '{}'
# Filter by category
curl -X POST http://localhost:3000/api/tools/listFoodItems \\
-H "Content-Type: application/json" \\
-d '{"category": "dairy"}'
# Remove an item (replace ITEM_ID with actual ID)
curl -X POST http://localhost:3000/api/tools/removeFoodItem \\
-H "Content-Type: application/json" \\
-d '{"id": "ITEM_ID"}'🏗️ 建筑学
项目结构
smartfridge-mcp-server-fixed/
├── src/ # Source code
│ ├── index.ts # Application entry point
│ ├── mcp-server.ts # MCP protocol implementation
│ ├── http-server.ts # HTTP bridge server
│ ├── services/ # Business logic services
│ ├── types/ # TypeScript type definitions
│ └── utils/ # Utility functions
├── tests/ # Comprehensive test suite
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ ├── config/ # Configuration tests
│ ├── fixtures/ # Test data
│ └── setup.ts # Test configuration
├── scripts/ # Utility scripts
│ ├── validate-deployment.js # Deployment validation
│ ├── run-tests.sh # Test runner
│ └── init-data.js # Sample data initialization
├── nginx/ # Nginx configuration
├── data/ # Data storage directory
├── logs/ # Application logs
└── .github/workflows/ # CI/CD pipelines核心组件
- MCP 服务器实现了用于AI助手集成的模型上下文协议
- HTTP桥接器提供RESTful API访问MCP功能
- 数据层基于JSON的持久化存储，支持原子操作
- 安全层输入验证、错误处理和安全头部信息
- 监测健康检查、日志记录和指标收集
🔧 配置
环境变量
创建一个 .env 基于文件的 .env.example:
# Server configuration
SERVER_MODE=http # 'mcp' or 'http'
PORT=3000 # HTTP server port
NODE_ENV=production # Environment
# Data configuration
DATA_FILE=data/fridge-data.json # Data storage file
# Logging
LOG_LEVEL=info # Log level: error, warn, info, debugNginx 代理
对于生产环境部署，请使用提供的 Nginx 配置：
# Copy configuration
sudo cp nginx/smartfridge.conf /etc/nginx/sites-available/
sudo ln -s /etc/nginx/sites-available/smartfridge.conf /etc/nginx/sites-enabled/
# Test configuration
sudo nginx -t
# Reload Nginx
sudo systemctl reload nginx📊 监控与健康检查
健康终点指标
GET /health基本健康检查GET /ready就绪性探针（包括数据文件状态）GET /info服务器信息和功能
记录日志
服务器使用结构化日志记录，并支持可配置的日志级别：
- 错误严重错误和异常
- 警告警告条件和可恢复错误
- 信息一般操作信息
- 调试详细的调试信息
日志同时写入控制台和文件（logs/smartfridge.log）。
🚀 持续集成/持续交付 (CI/CD) 流水线
该项目包含一个全面的GitHub Actions工作流：
- 多版本测试Node.js 18、20 和 22
- 测试覆盖率单元测试、集成测试和端到端（E2E）测试
- 安全扫描使用Trivy进行漏洞评估
- Docker 测试容器构建和部署验证
- 性能测试使用Artillery进行负载测试
- 自动化部署Docker镜像发布
🔒 安全功能
- 输入验证对所有输入进行Zod模式验证
- 安全头部（或安全标头）XSS防护、CSRF防护、内容嗅探防护
- 错误处理全面的错误捕获和安全的错误提示
- 速率限制基于Nginx的请求速率限制
- 集装箱安全非root用户，最小化基础镜像
📚 API 文档
MCP 工具
- 添加食物项在冰箱里添加一种新的食物
- 移除食物项通过ID移除一个食物项
- 列出食品项目列出并筛选食品项目
HTTP 端点
POST /api/tools/{toolName}通过HTTP执行MCP工具GET /api/tools列出可用工具GET /api/resources列出可用资源GET /api/resources/{uri}读取资源内容
请参阅测试文件以获取全面的API使用示例。
🤝 贡献（或：参与贡献）
- 克隆该仓库
- 创建一个特性分支：
git checkout -b feature/amazing-feature - 进行你的更改并添加测试
- 运行测试套件：
npm run validate - 提交您的更改：
git commit -m 'Add amazing feature' - 推送到分支：
git push origin feature/amazing-feature - 创建拉取请求
开发环境设置
# Install dependencies
npm install
# Run in development mode
npm run dev:http
# Run tests in watch mode
npm run test:watch
# Lint and format code
npm run lint:fix
npm run format📋 生产检查清单
在部署到生产环境之前：
- \[ \] 运行完整测试套件：
npm run validate - \[ \] 运行部署验证：
npm run validate-deployment - \[ \] 配置环境变量
- \[ \] 设置数据目录并分配适当权限
- \[ \] 配置 Nginx 代理（如使用）
- \[ \] 建立监控和日志记录
- \[ \] 为数据目录配置备份
- \[ \] 测试健康检查端点
- \[ \] 验证安全头部
📖 文档
- TESTING.md（文件名，可译为“测试说明.md”或保持原样，具体根据上下文决定是否翻译文件名）全面测试指南
- .env.example（通常用于说明环境配置文件的示例）环境配置参考
- nginx/smartfridge.conf（可译为“Nginx/智能冰箱配置文件”）Nginx 配置
- Docker 部署配置
📄 许可证
这个项目遵循MIT许可证授权——详见 许可证 文件中有详细信息。
🙏 致谢
- 模型上下文协议（MCP）规范和软件开发工具包（SDK）
- Express.js 用于实现HTTP服务器功能
- 卓越测试工具的社区与测试环境
- Docker和容器化生态系统
- GitHub Actions 用于 CI/CD 自动化
______________________________________________________________________
满怀信心地准备投入生产部署！ 🚀✨（火箭+星星，常用于表达兴奋或庆祝的语气，无直接对应中文翻译，可保留原样或根据语境译为“🚀✨（激动/庆祝的语气）”）