Smartfridge MCP Server Fixed

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

核心组件

1. MCP 服务器实现了用于AI助手集成的模型上下文协议
2. HTTP桥接器提供RESTful API访问MCP功能
3. 数据层基于JSON的持久化存储，支持原子操作
4. 安全层输入验证、错误处理和安全头部信息
5. 监测健康检查、日志记录和指标收集

🔧 配置

环境变量

创建一个 .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, debug

Nginx 代理

对于生产环境部署，请使用提供的 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 工具

1. 添加食物项在冰箱里添加一种新的食物
2. 移除食物项通过ID移除一个食物项
3. 列出食品项目列出并筛选食品项目

HTTP 端点

• POST /api/tools/{toolName}通过HTTP执行MCP工具
• GET /api/tools列出可用工具
• GET /api/resources列出可用资源
• GET /api/resources/{uri}读取资源内容

请参阅测试文件以获取全面的API使用示例。

🤝 贡献（或：参与贡献）

1. 克隆该仓库
2. 创建一个特性分支： git checkout -b feature/amazing-feature
3. 进行你的更改并添加测试
4. 运行测试套件： npm run validate
5. 提交您的更改： git commit -m 'Add amazing feature'
6. 推送到分支： git push origin feature/amazing-feature
7. 创建拉取请求

开发环境设置

# 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 自动化

______________________________________________________________________

满怀信心地准备投入生产部署！ 🚀✨（火箭+星星，常用于表达兴奋或庆祝的语气，无直接对应中文翻译，可保留原样或根据语境译为“🚀✨（激动/庆祝的语气）”）