Europe PMC Literature Search MCP Server

# 魔搭MCP广场部署总结

## 🎯 部署要求分析

根据[魔搭官方文档](https://modelscope.cn/headlines/article/1439)，自动化部署检测的**核心约束**：

> **当前只有command字段键值为npx和uvx的服务配置能够成功通过此步检测**

这意味着我们之前使用 `uv run` 的配置**无法通过检测**！

## ✅ 解决方案概览

我们准备了**两套完整的发布方案**来满足魔搭平台要求：

### 🥇 方案1：PyPI + uvx (推荐)
- **发布平台**：PyPI (Python Package Index)
- **包名**：`article-mcp`
- **运行命令**：`uvx article-mcp@latest server`
- **优势**：原生Python包，性能最佳

### 🥈 方案2：NPM + npx (备选)
- **发布平台**：NPM (Node Package Manager)  
- **包名**：`@gqy20/article-mcp-wrapper`
- **运行命令**：`npx @gqy20/article-mcp-wrapper@latest server`
- **优势**：兼容性强，NPM生态成熟

## 📋 配置文件清单

### 1. uvx 配置 (推荐使用)

**文件**: `modelscope_plaza_pypi.json`

```json
{
  "mcpServers": {
    "article-mcp": {
      "command": "uvx",
      "args": [
        "article-mcp@latest",
        "server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

### 2. npx 配置 (备选方案)

**文件**: `modelscope_plaza_npm.json`

```json
{
  "mcpServers": {
    "article-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@gqy20/article-mcp-wrapper@latest",
        "server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

## 🚀 部署步骤

### 第一步：发布包

1. **发布到 PyPI**：
   ```bash
   uv build
   uv publish
   ```

2. **发布到 NPM**：
   ```bash
   npm publish --access public
   ```

### 第二步：魔搭平台配置

1. 访问 [魔搭MCP广场](https://modelscope.cn/mcp)
2. 选择"添加MCP服务"
3. 粘贴上述配置之一
4. 点击"添加"提交

### 第三步：自动化检测

魔搭平台将自动进行：
- ✅ **服务配置解析**：检测配置字段完整性
- ✅ **配置可用性校验**：验证 `uvx`/`npx` 命令
- ✅ **部署连接测试**：调用 `list_tools` 方法

## 📊 配置对比分析

| 特性 | uvx (PyPI) | npx (NPM) | uv run (GitHub) |
|------|------------|-----------|-----------------|
| **通过魔搭检测** | ✅ 是 | ✅ 是 | ❌ 否 |
| **启动速度** | 🟢 快 | 🟡 中等 | 🟢 快 |
| **资源占用** | 🟢 低 | 🟡 中等 | 🟢 低 |
| **依赖管理** | 🟢 原生Python | 🟡 需Node.js | 🟢 原生Python |
| **维护复杂度** | 🟢 简单 | 🟡 中等 | 🟢 简单 |

## 🔧 项目文件结构

为支持多平台发布，项目新增了以下文件：

```
article-mcp/
├── pyproject.toml          # ✅ PyPI包配置（已优化）
├── package.json            # ✅ NPM包配置（新增）
├── bin/
│   └── article-mcp.js     # ✅ NPM包执行脚本（新增）
├── LICENSE                # ✅ MIT许可证（新增）
├── modelscope_plaza_pypi.json   # ✅ uvx配置（新增）
├── modelscope_plaza_npm.json    # ✅ npx配置（新增）
└── docs/
    └── 发布部署指南.md      # ✅ 详细发布指南（新增）
```

## 🎯 关键技术要点

### PyPI 发布要点
- **入口点**：`article-mcp = "main:main"` 
- **命令支持**：支持 `article-mcp server` 命令
- **依赖管理**：所有依赖在 `pyproject.toml` 中声明

### NPM 包装器要点
- **双重机制**：优先使用 `uvx`，失败时使用 Git 克隆
- **智能回退**：确保在各种环境下都能运行
- **临时目录**：自动管理临时文件清理

### 魔搭平台适配
- **命令限制**：严格使用 `uvx` 或 `npx`
- **版本管理**：使用 `@latest` 确保最新版本
- **环境变量**：统一在 `env` 字段管理

## ⚠️ 重要注意事项

### 部署检测要求
1. **命令约束**：只允许 `npx` 和 `uvx`
2. **JSON格式**：不支持注释
3. **路径限制**：不允许本地绝对路径
4. **参数限制**：不允许用户自定义参数

### 版本管理策略
- **PyPI包版本**：`article-mcp==0.2.0`
- **NPM包版本**：`@gqy20/article-mcp-wrapper@0.2.0`
- **统一更新**：两个平台同步发布新版本

## 🎉 成功指标

部署成功后，您的MCP服务将获得：
- 🏷️ **可部署标签**：通过自动化检测
- 🌐 **hosted标签**：公开服务标识
- ⚡ **秒级启动**：约1秒完成部署
- 🔗 **SSE地址**：自动生成的服务端点

## 📞 后续支持

如需帮助：
1. 📖 参考 `docs/发布部署指南.md` 
2. 🐛 在 GitHub 提交 Issue
3. 💬 联系魔搭平台技术支持

---

**推荐行动**: 直接使用 **`modelscope_plaza_pypi.json`** 配置，这是最符合魔搭要求且性能最佳的方案！