VLLM MCP Server

# VLLM MCP Server - 项目总结 ## 🎯 项目概述 VLLM MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器，使纯文本模型能够调用多模态模型。该项目支持 OpenAI 和 Dashscope (阿里云) 的多模态模型，通过标准化的 MCP 工具让文本模型处理图像和其他媒体格式。 ## ✅ 已完成功能 ### 1. 核心架构 - ✅ **多提供商支持**: OpenAI GPT-4 Vision 和 Dashscope Qwen-VL 模型 - ✅ **模块化设计**: 分离的提供商和模型层 - ✅ **现代包管理**: 使用 uv 进行依赖管理 - ✅ **类型安全**: 完整的 Pydantic 数据模型 ### 2. MCP 服务器功能 - ✅ **多传输协议支持**: - STDIO (默认，适用于 MCP 客户端) - HTTP (适用于 Web 服务部署) - SSE (适用于流式响应) - ✅ **丰富的工具集**: - `generate_multimodal_response`: 生成包含文本、图像和文件的响应 - `list_available_providers`: 列出支持的提供商和模型 - `validate_multimodal_request`: 验证请求兼容性 ### 3. 部署选项 - ✅ **Docker**: 多阶段构建，安全最佳实践 - ✅ **Docker Compose**: 完整部署配置，可选 Nginx 反向代理 - ✅ **本地开发**: 热重载支持，开发环境优化 ### 4. 开发者体验 - ✅ **启动脚本**: 生产和环境启动器 - ✅ **环境配置**: `.env` 文件支持 - ✅ **示例客户端**: 完整的 Python 客户端示例 - ✅ **测试套件**: 设置验证和基础测试 ### 5. 隐私和安全 - ✅ **完善的 `.gitignore`**: 保护 API 密钥和敏感信息 - ✅ **环境变量配置**: 避免硬编码敏感信息 - ✅ **Docker 安全**: 非 root 用户运行，最小化镜像 ## 📁 项目结构 ``` vllm-mcp/ ├── src/vllm_mcp/ # 主包 │ ├── __init__.py # 包初始化 │ ├── server.py # MCP 服务器实现 │ ├── models.py # 数据模型 (Pydantic) │ └── providers/ # 模型提供商 │ ├── __init__.py │ ├── openai_provider.py # OpenAI 集成 │ └── dashscope_provider.py # Dashscope 集成 ├── scripts/ # 启动脚本 │ ├── start.sh # 生产环境启动 │ └── start-dev.sh # 开发环境启动 ├── examples/ # 客户端示例 │ ├── client_example.py # Python 客户端示例 │ └── mcp_client_config.json # MCP 客户端配置 ├── Dockerfile # 容器配置 ├── docker-compose.yml # 编排配置 ├── config.json # 服务器配置 ├── .env.example # 环境变量模板 ├── .gitignore # Git 忽略文件 (隐私保护) ├── pyproject.toml # 项目配置 ├── README.md # 完整文档 ├── test_setup.py # 设置验证测试 └── PROJECT_SUMMARY.md # 项目总结 ``` ## 🚀 快速开始 ### 1. 环境设置 ```bash # 克隆仓库 git clone <repository-url> cd vllm-mcp # 设置环境变量 cp .env.example .env # 编辑 .env 文件，填入你的 API 密钥 ``` ### 2. API 密钥配置 ⚠️ 在 `.env` 文件中设置至少一个 API 密钥： ```bash # OpenAI 配置 OPENAI_API_KEY=sk-your-openai-api-key # Dashscope 配置 (阿里云) DASHSCOPE_API_KEY=sk-your-dashscope-api-key ``` ### 3. 安装依赖 ```bash uv sync ``` ### 4. 启动服务器 ```bash # STDIO 传输 (默认) ./scripts/start.sh # HTTP 传输 ./scripts/start.sh --transport http --host 0.0.0.0 --port 8080 # 开发模式 (热重载) ./scripts/start-dev.sh ``` ### 5. 运行测试 ```bash # 验证设置 uv run python test_setup.py # 测试客户端 uv run python examples/client_example.py ``` ## 🔧 支持的模型 ### OpenAI - `gpt-4o` (推荐) - `gpt-4o-mini` - `gpt-4-turbo` - `gpt-4-vision-preview` ### Dashscope (阿里云) - `qwen-vl-plus` (推荐) - `qwen-vl-max` - `qwen-vl-chat` - `qwen2-vl-7b-instruct` - `qwen2-vl-72b-instruct` ## 🐳 Docker 部署 ### 使用 Docker Compose ```bash # 设置环境变量 cp .env.example .env # 启动服务 docker-compose up -d ``` ### 手动构建 ```bash # 构建镜像 docker build -t vllm-mcp . # 运行容器 docker run -p 8080:8080 --env-file .env vllm-mcp ``` ## 🛡️ 隐私保护 项目实施了严格的隐私保护措施： 1. **Git 忽略文件**: 自动忽略所有敏感配置文件 2. **环境变量**: 所有 API 密钥通过环境变量配置 3. **配置模板**: 提供安全的配置模板 4. **容器安全**: 非 root 用户，最小权限原则 ### 被忽略的敏感文件： - `.env` - 包含真实 API 密钥 - `config.local.json` - 本地配置 - `secrets.json` - 密钥文件 - `logs/` - 日志文件 - `*.log` - 日志文件 - `__pycache__/` - Python 缓存 - `.venv/` - 虚拟环境 ## 📋 下一步开发计划 1. **增强的提供商支持**: 添加更多多模态模型提供商 2. **流式响应**: 完善流式响应功能 3. **认证和安全**: 添加 OAuth 和 JWT 支持 4. **监控和指标**: 集成 Prometheus 和 Grafana 5. **缓存机制**: 实现响应缓存以提高性能 6. **批量处理**: 支持批量请求处理 ## 🤝 贡献指南 1. Fork 项目 2. 创建功能分支 (`git checkout -b feature/amazing-feature`) 3. 提交更改 (`git commit -m 'Add amazing feature'`) 4. 推送到分支 (`git push origin feature/amazing-feature`) 5. 打开 Pull Request ## 📄 许可证 MIT License ## 🙏 致谢 - [Model Context Protocol](https://modelcontextprotocol.io/) - 协议规范 - [OpenAI](https://openai.com/) - GPT-4 Vision API - [Dashscope](https://dashscope.aliyun.com/) - Qwen-VL API - [FastMCP](https://github.com/modelcontextprotocol/python-sdk) - MCP Python SDK --- ## 📊 项目状态 - ✅ **核心功能**: 100% 完成 - ✅ **部署配置**: 100% 完成 - ✅ **文档**: 100% 完成 - ✅ **测试**: 基础测试完成 - ✅ **隐私保护**: 100% 完成 **状态**: 🎉 **生产就绪** - 项目已准备好用于生产环境 --- **注意**: 在使用前请确保设置了正确的 API 密钥！项目已通过所有基础测试，可以安全部署。