|
| 1 | +# ModelScope MCP Server |
| 2 | + |
| 3 | +[](https://pypi.org/project/modelscope-mcp-server) |
| 4 | +[](https://github.com/modelscope/modelscope-mcp-server/blob/main/Dockerfile) |
| 5 | +[](https://github.com/modelscope/modelscope-mcp-server/pkgs/container/modelscope-mcp-server) |
| 6 | +[](https://github.com/modelscope/modelscope-mcp-server/blob/main/LICENSE) |
| 7 | + |
| 8 | +[English](README.md) | 中文 |
| 9 | + |
| 10 | +一个集成 [ModelScope](https://modelscope.cn)(魔搭社区)生态的模型上下文协议(MCP)服务器,通过流行的 MCP 客户端无缝访问 AI 模型、数据集、应用、论文和内容生成能力。 |
| 11 | + |
| 12 | +## ✨ 功能特性 |
| 13 | + |
| 14 | +- 🎨 **AI 图像生成** - 使用 AIGC 模型从文本提示生成图像或转换现有图像(支持文生图和图生图) |
| 15 | +- 🔍 **资源发现** - 搜索和发现 ModelScope 资源,包括机器学习模型、研究论文和 MCP 服务器,支持高级过滤选项 |
| 16 | +- 📋 **资源详情** _(即将推出)_ - 获取特定资源的全面详情,包括模型规格、论文摘要和 MCP 服务器配置 |
| 17 | +- 📖 **文档搜索** _(即将推出)_ - 对 ModelScope 文档和文章进行语义搜索 |
| 18 | +- 🚀 **Gradio API 集成** _(即将推出)_ - 调用任何预配置的 ModelScope Studio(AI 应用)暴露的 Gradio API |
| 19 | +- 🔐 **上下文信息** - 访问当前操作上下文,包括认证用户信息和环境详情 |
| 20 | + |
| 21 | +## 🚀 快速开始 |
| 22 | + |
| 23 | +### 1. 获取您的 API Token |
| 24 | + |
| 25 | +1. 访问 [ModelScope](https://modelscope.cn/home) 站点并登录您的账户 |
| 26 | +2. 导航至 **[首页] → [访问令牌]** 获取或创建您的 API Token |
| 27 | + |
| 28 | +> 📖 详细说明请参考 [ModelScope 访问令牌](https://modelscope.cn/docs/accounts/token) |
| 29 | +
|
| 30 | +### 2. 与 MCP 客户端集成 |
| 31 | + |
| 32 | +将以下 JSON 配置添加到您的 MCP 客户端配置文件中: |
| 33 | + |
| 34 | +```json |
| 35 | +{ |
| 36 | + "mcpServers": { |
| 37 | + "modelscope-mcp-server": { |
| 38 | + "command": "uvx", |
| 39 | + "args": ["modelscope-mcp-server"], |
| 40 | + "env": { |
| 41 | + "MODELSCOPE_API_TOKEN": "your-api-token" |
| 42 | + } |
| 43 | + } |
| 44 | + } |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +或者,您可以使用预构建的 Docker 镜像: |
| 49 | + |
| 50 | +```json |
| 51 | +{ |
| 52 | + "mcpServers": { |
| 53 | + "modelscope-mcp-server": { |
| 54 | + "command": "docker", |
| 55 | + "args": [ |
| 56 | + "run", "--rm", "-i", |
| 57 | + "-e", "MODELSCOPE_API_TOKEN", |
| 58 | + "ghcr.io/modelscope/modelscope-mcp-server" |
| 59 | + ], |
| 60 | + "env": { |
| 61 | + "MODELSCOPE_API_TOKEN": "your-api-token" |
| 62 | + } |
| 63 | + } |
| 64 | + } |
| 65 | +} |
| 66 | +``` |
| 67 | + |
| 68 | +更多详情请参考 [MCP JSON 配置标准](https://gofastmcp.com/integrations/mcp-json-configuration#mcp-json-configuration-standard)。 |
| 69 | + |
| 70 | +此格式在 MCP 生态系统中被广泛采用: |
| 71 | + |
| 72 | +- **Cherry Studio**: 参见 [Cherry Studio MCP 配置](https://docs.cherry-ai.com/advanced-basic/mcp/config) |
| 73 | +- **Claude Desktop**: 使用 `~/.claude/claude_desktop_config.json` |
| 74 | +- **Cursor**: 使用 `~/.cursor/mcp.json` |
| 75 | +- **VS Code**: 使用工作区 `.vscode/mcp.json` |
| 76 | +- **其他客户端**: 许多 MCP 兼容的应用程序都遵循此标准 |
| 77 | + |
| 78 | +## 🛠️ 开发 |
| 79 | + |
| 80 | +### 环境设置 |
| 81 | + |
| 82 | +1. **克隆和设置**: |
| 83 | + |
| 84 | + ```bash |
| 85 | + git clone https://github.com/modelscope/modelscope-mcp-server.git |
| 86 | + cd modelscope-mcp-server |
| 87 | + uv sync |
| 88 | + ``` |
| 89 | + |
| 90 | +2. **激活环境**(或使用您的 IDE): |
| 91 | + |
| 92 | + ```bash |
| 93 | + source .venv/bin/activate # Linux/macOS |
| 94 | + ``` |
| 95 | + |
| 96 | +3. **设置您的 API Token**(Token 设置请参见快速开始部分): |
| 97 | + |
| 98 | + ```bash |
| 99 | + export MODELSCOPE_API_TOKEN="your-api-token" |
| 100 | + # 或创建 .env 文件: echo 'MODELSCOPE_API_TOKEN="your-api-token"' > .env |
| 101 | + ``` |
| 102 | + |
| 103 | +### 运行演示脚本 |
| 104 | + |
| 105 | +运行快速演示以探索服务器的功能: |
| 106 | + |
| 107 | +```bash |
| 108 | +uv run python demo.py |
| 109 | +``` |
| 110 | + |
| 111 | +使用 `--full` 标志进行全面功能演示: |
| 112 | + |
| 113 | +```bash |
| 114 | +uv run python demo.py --full |
| 115 | +``` |
| 116 | + |
| 117 | +### 本地运行服务器 |
| 118 | + |
| 119 | +```bash |
| 120 | +# 标准 stdio 传输(默认) |
| 121 | +uv run modelscope-mcp-server |
| 122 | + |
| 123 | +# 用于 Web 集成的可流式 HTTP 传输 |
| 124 | +uv run modelscope-mcp-server --transport http |
| 125 | + |
| 126 | +# 自定义端口的 HTTP/SSE 传输(默认:8000) |
| 127 | +uv run modelscope-mcp-server --transport [http/sse] --port 8080 |
| 128 | +``` |
| 129 | + |
| 130 | +对于 HTTP/SSE 模式,在您的 MCP 客户端配置中使用本地 URL 连接: |
| 131 | + |
| 132 | +```json |
| 133 | +{ |
| 134 | + "mcpServers": { |
| 135 | + "modelscope-mcp-server": { |
| 136 | + "url": "http://127.0.0.1:8000/mcp/" |
| 137 | + } |
| 138 | + } |
| 139 | +} |
| 140 | +``` |
| 141 | + |
| 142 | +您也可以使用 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 工具调试服务器: |
| 143 | + |
| 144 | +```bash |
| 145 | +npx @modelcontextprotocol/inspector uv run modelscope-mcp-server |
| 146 | +``` |
| 147 | + |
| 148 | +默认使用 stdio 传输;根据需要在 Web UI 中切换到 HTTP/SSE。 |
| 149 | + |
| 150 | +### 测试 |
| 151 | + |
| 152 | +```bash |
| 153 | +# 运行所有测试 |
| 154 | +uv run pytest |
| 155 | + |
| 156 | +# 运行特定测试文件 |
| 157 | +uv run pytest tests/test_search_papers.py |
| 158 | + |
| 159 | +# 带覆盖率报告 |
| 160 | +uv run pytest --cov=src --cov-report=html |
| 161 | +``` |
| 162 | + |
| 163 | +## 🔄 持续集成 |
| 164 | + |
| 165 | +本项目使用 GitHub Actions 进行自动化 CI/CD 工作流,在每次推送和拉取请求时运行: |
| 166 | + |
| 167 | +### 自动化检查 |
| 168 | + |
| 169 | +- **✨ [Lint](https://github.com/modelscope/modelscope-mcp-server/actions/workflows/lint.yml)** - 使用 pre-commit hooks 进行代码格式化、代码检查和风格检查 |
| 170 | +- **🧪 [Test](https://github.com/modelscope/modelscope-mcp-server/actions/workflows/test.yml)** - 跨所有支持的 Python 版本进行全面测试 |
| 171 | +- **🔍 [CodeQL](https://github.com/modelscope/modelscope-mcp-server/actions/workflows/codeql.yml)** - 安全漏洞扫描和代码质量分析 |
| 172 | +- **🔒 [Gitleaks](https://github.com/modelscope/modelscope-mcp-server/actions/workflows/gitleaks.yml)** - 检测密码、API 密钥和令牌等敏感信息 |
| 173 | + |
| 174 | +### 本地开发检查 |
| 175 | + |
| 176 | +在提交 PR 之前在本地运行相同的检查: |
| 177 | + |
| 178 | +```bash |
| 179 | +# 安装并运行 pre-commit hooks |
| 180 | +uv run pre-commit install |
| 181 | +uv run pre-commit run --all-files |
| 182 | + |
| 183 | +# 运行测试 |
| 184 | +uv run pytest |
| 185 | +``` |
| 186 | + |
| 187 | +在 [Actions 标签页](https://github.com/modelscope/modelscope-mcp-server/actions) 中监控 CI 状态。 |
| 188 | + |
| 189 | +## 📦 发布管理 |
| 190 | + |
| 191 | +本项目使用 GitHub Actions 进行自动化发布管理。创建新版本的步骤: |
| 192 | + |
| 193 | +1. **更新版本**,使用版本更新脚本: |
| 194 | + |
| 195 | + ```bash |
| 196 | + uv run python scripts/bump_version.py [patch|minor|major] |
| 197 | + # 或设置特定版本: uv run python scripts/bump_version.py set 1.2.3.dev1 |
| 198 | + ``` |
| 199 | + |
| 200 | +2. **提交并打标签**(按照脚本输出的说明): |
| 201 | + |
| 202 | + ```bash |
| 203 | + git add src/modelscope_mcp_server/_version.py |
| 204 | + git commit -m "chore: bump version to v{version}" |
| 205 | + git tag v{version} && git push origin v{version} |
| 206 | + ``` |
| 207 | + |
| 208 | +3. **自动发布** - GitHub Actions 将自动: |
| 209 | + - 创建新的 [GitHub Release](https://github.com/modelscope/modelscope-mcp-server/releases) |
| 210 | + - 发布包到 [PyPI 仓库](https://pypi.org/project/modelscope-mcp-server/) |
| 211 | + - 构建并推送 Docker 镜像到 [GitHub Container Registry](https://github.com/modelscope/modelscope-mcp-server/pkgs/container/modelscope-mcp-server) |
| 212 | + |
| 213 | +## 🤝 贡献 |
| 214 | + |
| 215 | +我们欢迎贡献!请确保您的 PR: |
| 216 | + |
| 217 | +- 包含相关测试并通过所有 CI 检查 |
| 218 | +- 为新功能更新文档 |
| 219 | +- 遵循常规提交格式 |
| 220 | + |
| 221 | +## 📚 参考资料 |
| 222 | + |
| 223 | +- **[Model Context Protocol](https://modelcontextprotocol.io/)** - 官方 MCP 文档 |
| 224 | +- **[FastMCP v2](https://github.com/jlowin/fastmcp)** - 高性能 MCP 框架 |
| 225 | +- **[MCP Example Servers](https://github.com/modelcontextprotocol/servers)** - 社区服务器示例 |
| 226 | + |
| 227 | +## 📜 许可证 |
| 228 | + |
| 229 | +本项目采用 [Apache 许可证(版本 2.0)](LICENSE)。 |
0 commit comments