iRAG MCP Server

# 百度iRAG MCP服务器 - 项目总结 ## 项目概述 本项目成功创建了一个基于百度iRAG图片生成API的MCP（Model Context Protocol）服务器，允许MCP客户端（如Claude Desktop）通过标准化接口调用百度的图片生成服务。 ## 已完成的功能 ### ✅ 核心功能 - [x] 百度iRAG API客户端封装 - [x] MCP协议完整实现 - [x] 图片生成工具（generate_image） - [x] 支持多种模型（irag-1.0, flux.1-schnell） - [x] 灵活的参数配置 - [x] 完善的错误处理 - [x] 图片本地保存功能 - [x] 多种资源模式（URL/本地文件） - [x] 可配置的默认模型 ### ✅ 技术特性 - [x] TypeScript开发，类型安全 - [x] 完整的参数验证（使用Zod） - [x] 自动重试机制 - [x] 结构化日志记录 - [x] 环境变量配置管理 - [x] 单元测试覆盖 ### ✅ 开发工具 - [x] ESLint代码检查 - [x] Jest测试框架 - [x] TypeScript编译 - [x] 开发热重载 - [x] 构建脚本 ## 项目结构 ``` irag-mcp-server/ ├── src/ │ ├── client/ # 百度iRAG API客户端 │ │ └── irag-client.ts │ ├── config/ # 配置管理 │ │ └── index.ts │ ├── server/ # MCP服务器实现 │ │ └── mcp-server.ts │ ├── types/ # TypeScript类型定义 │ │ └── index.ts │ ├── utils/ # 工具函数 │ │ ├── logger.ts │ │ └── image-saver.ts # 图片保存工具 │ ├── __tests__/ # 测试文件 │ │ └── basic.test.ts │ └── index.ts # 主入口文件 ├── dist/ # 编译输出目录 ├── docs/ # 文档文件 │ ├── README.md │ ├── QUICKSTART.md │ ├── EXAMPLES.md │ └── PROJECT_SUMMARY.md ├── package.json # 项目配置 ├── tsconfig.json # TypeScript配置 ├── jest.config.js # Jest测试配置 ├── .eslintrc.json # ESLint配置 ├── .env.example # 环境变量模板 └── test-server.js # 服务器测试脚本 ``` ## 支持的API参数 ### generate_image工具参数 | 参数 | 类型 | 必需 | 默认值 | 描述 | |------|------|------|--------|------| | prompt | string | ✅ | - | 图片生成提示词 | | model | string | ❌ | irag-1.0 | 模型选择 | | refer_image | string | ❌ | - | 参考图片URL | | n | integer | ❌ | 1 | 生成数量(1-4) | | size | string | ❌ | 1024x1024 | 图片尺寸 | | steps | integer | ❌ | - | 采样步数(flux.1-schnell) | | seed | integer | ❌ | - | 随机种子(flux.1-schnell) | | guidance | number | ❌ | 3.5 | 指导密度(flux.1-schnell) | ### 图片保存配置 | 配置项 | 类型 | 默认值 | 描述 | |--------|------|--------|------| | RESOURCE_MODE | string | local | url: 仅返回URL和base64 \| local: 同时保存到本地 | | BASE_PATH | string | 桌面/irag-images | 自定义图片保存路径 | | MODEL | string | irag-1.0 | 默认模型: irag-1.0 \| flux.1-schnell | ## 使用方法 ### 1. 快速开始 ```bash # 安装和构建 npm run setup # 验证功能 npm run validate ``` ### 2. 配置Claude Desktop ```json { "mcpServers": { "irag-image-generator": { "command": "node", "args": ["/path/to/irag-mcp-server/dist/index.js"], "env": { "BAIDU_API_KEY": "your-api-key" } } } } ``` ### 3. 使用示例 在Claude Desktop中： ``` 请生成一张现代简约风格的客厅设计图 ``` ## 技术亮点 ### 1. 类型安全 - 完整的TypeScript类型定义 - 运行时参数验证 - 编译时类型检查 ### 2. 错误处理 - 详细的错误信息 - 自动重试机制 - 优雅的降级处理 ### 3. 可观测性 - 结构化日志记录 - 请求/响应追踪 - 性能监控 ### 4. 可维护性 - 模块化架构 - 清晰的代码组织 - 完整的文档 ## 测试覆盖 ### 基础测试（无需真实API Key） - ✅ 基本功能测试 - ✅ 参数验证测试 - ✅ API Key格式验证 - ✅ 服务器启动测试 - ✅ 模型和尺寸支持测试 ### 真实API测试（需要真实API Key） - ✅ 直接API调用测试 (`npm run test:api`) - ✅ 图片生成和下载测试 - ✅ Base64转换验证 - ✅ 端到端MCP工具调用测试 (`npm run test:e2e`) - ✅ 完整流程验证 ### 测试脚本 - `npm test` - 基础单元测试 - `npm run test:server` - 服务器启动测试 - `npm run test:api` - 真实API调用测试 - `npm run test:e2e` - 端到端测试 - `npm run test:images` - 图片保存功能测试 - `npm run test:config` - 配置参数测试 - `npm run validate` - 基础验证 - `npm run validate:full` - 完整验证（包括API） ## 部署建议 ### 开发环境 ```bash npm run dev ``` ### 生产环境 ```bash npm run build npm start ``` ### Docker部署（可选） ```dockerfile FROM node:18-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY dist ./dist CMD ["npm", "start"] ``` ## 性能特性 - 🚀 快速启动（< 2秒） - 🔄 自动重试机制 - ⚡ 异步处理 - 📊 内存优化 - 🛡️ 错误隔离 ## 安全考虑 - 🔐 API Key环境变量存储 - 🛡️ 输入参数验证 - 🚫 敏感信息过滤 - 📝 安全日志记录 ## 扩展性 项目设计支持以下扩展： 1. **新模型支持** - 在types中添加新模型类型 2. **新参数支持** - 扩展接口定义和验证schema 3. **新功能** - 添加新的MCP工具 4. **监控集成** - 添加APM和指标收集 ## 已知限制 1. 仅支持百度iRAG API 2. 图片输出为URL链接（24小时有效期） 3. 依赖网络连接稳定性 4. API调用有配额限制 ## 后续改进建议 1. 添加图片缓存机制 2. 支持更多图片格式 3. 添加批量处理优化 4. 集成更多AI图片生成服务 5. 添加图片质量评估 ## 总结 本项目成功实现了一个功能完整、类型安全、易于使用的百度iRAG MCP服务器。通过标准化的MCP协议，用户可以在Claude Desktop等客户端中无缝使用百度的图片生成能力。项目具有良好的可维护性和扩展性，为后续功能增强奠定了坚实基础。