geoapify-mcp-server/PUBLISH_GUIDE.md

Geoapify API MCP Server for location-based services - 一键部署的地理位置服务

# 🚀 NPM发布指南

## ✅ **准备工作已完成**

- ✅ NPM registry已切换到官方源
- ✅ package.json已优化
- ✅ 包名: `@travel-mcp/geoapify-server`
- ✅ 版本: `1.0.0`

## 📋 **发布步骤**

### 步骤1: 注册NPM账号（如果没有）

1. 访问: https://www.npmjs.com/signup
2. 填写信息注册账号
3. 验证邮箱

### 步骤2: NPM登录

在终端中运行：
```bash
npm login
```

输入您的：
- Username（用户名）
- Password（密码）
- Email（邮箱）

### 步骤3: 验证登录

```bash
npm whoami
```
应该显示您的用户名。

### 步骤4: 运行测试

```bash
node scripts/test-mcp.js unit
```
确保所有测试通过。

### 步骤5: 检查包内容

```bash
npm pack --dry-run
```
这会显示将要发布的文件列表。

### 步骤6: 发布包

```bash
npm publish
```

### 步骤7: 验证发布

```bash
npm view @travel-mcp/geoapify-server
```

## 🎯 **发布后的MCP配置**

发布成功后，用户可以使用以下配置：

```json
{
  "mcpServers": {
    "geoapify-maps": {
      "command": "npx",
      "args": ["-y", "@travel-mcp/geoapify-server"],
      "env": {
        "GEOAPIFY_API_KEY": "3234bd7e35264a8aa29fc15e89f8f76f"
      }
    }
  }
}
```

## 🔄 **恢复中国镜像（可选）**

发布完成后，可以恢复中国镜像：
```bash
npm config set registry https://registry.npmmirror.com
```

## 🧪 **测试发布的包**

```bash
# 测试全局安装
npm install -g @travel-mcp/geoapify-server

# 测试npx调用
npx @travel-mcp/geoapify-server

# 测试MCP功能
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx @travel-mcp/geoapify-server
```

## 🔧 **故障排除**

### 1. 登录失败
- 确保使用官方registry: `npm config get registry`
- 检查网络连接
- 尝试使用VPN

### 2. 包名冲突
如果包名已存在，修改package.json中的name：
```json
{
  "name": "@your-username/geoapify-server"
}
```

### 3. 权限问题
确保包是公开的：
```bash
npm access public @travel-mcp/geoapify-server
```

### 4. 发布失败
检查错误信息：
- 版本号是否已存在
- 包名是否符合规范
- 是否有必要的文件

## 📊 **发布清单**

- [ ] NPM账号已注册并验证
- [ ] 已登录NPM: `npm whoami`
- [ ] 测试通过: `node scripts/test-mcp.js unit`
- [ ] 包内容检查: `npm pack --dry-run`
- [ ] 发布包: `npm publish`
- [ ] 验证发布: `npm view @travel-mcp/geoapify-server`

## 🎉 **发布成功标志**

发布成功后，您会看到：
```
+ @travel-mcp/geoapify-server@1.0.0
```

然后可以在 https://www.npmjs.com/package/@travel-mcp/geoapify-server 查看您的包。

## 📚 **后续步骤**

1. **更新文档**: 在README.md中添加npm安装说明
2. **版本管理**: 后续更新使用 `npm version patch/minor/major`
3. **CI/CD**: 考虑设置自动发布流程

---

**现在开始执行发布步骤吧！**