geoapify-mcp-server/PUBLISH_COMPLETE_GUIDE.md

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

# NPM发布完整指南

## 🚀 快速发布

### 方法1：使用自动化脚本（推荐）
```bash
cd 新建文件夹
bash scripts/publish-npm.sh
```

### 方法2：手动发布
```bash
cd 新建文件夹

# 1. 检查NPM registry
npm config get registry
npm config set registry https://registry.npmjs.org/

# 2. 登录NPM
npm login

# 3. 检查包信息
npm view @travel-mcp/geoapify-server

# 4. 发布
npm publish

# 5. 验证
npm view @travel-mcp/geoapify-server
```

## 📋 发布前检查清单

### ✅ 必需条件
- [ ] NPM账号（https://www.npmjs.com/signup）
- [ ] 已登录NPM：`npm whoami`
- [ ] 使用官方registry：`npm config get registry`
- [ ] 包名可用：`npm view @travel-mcp/geoapify-server`
- [ ] 版本号唯一
- [ ] 所有依赖已安装：`npm install`

### ✅ 包信息检查
- [ ] package.json配置正确
- [ ] bin字段指向正确文件
- [ ] 描述和关键词完整
- [ ] 许可证信息正确

### ✅ 功能测试
- [ ] MCP服务器可以启动：`node bin/mcp-server.js`
- [ ] API功能正常：`npm run test-api`
- [ ] MCP协议测试通过：`npm run test-mcp`

## 🔧 常见问题解决

### 问题1：NPM登录失败
```bash
# 清除NPM缓存
npm cache clean --force

# 重新登录
npm logout
npm login
```

### 问题2：包名已存在
```bash
# 更新版本号
npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0
```

### 问题3：发布权限问题
```bash
# 检查包名是否被占用
npm view @travel-mcp/geoapify-server

# 如果需要，更改包名
# 编辑 package.json 中的 "name" 字段
```

## 📦 发布后验证

### 验证包可用性
```bash
# 查看包信息
npm view @travel-mcp/geoapify-server

# 测试安装
npm install -g @travel-mcp/geoapify-server

# 测试运行
npx @travel-mcp/geoapify-server
```

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

## 🎯 发布成功后

### 1. 更新文档
- 更新README.md
- 添加安装说明
- 更新使用示例

### 2. 测试部署
- 在新环境测试npx安装
- 验证MCP客户端集成
- 测试所有API功能

### 3. 版本管理
- 创建Git标签
- 更新CHANGELOG
- 准备下一版本

## 📞 支持

如果遇到问题：
1. 检查NPM状态：https://status.npmjs.org/
2. 查看NPM文档：https://docs.npmjs.com/
3. 检查包发布状态：https://www.npmjs.com/package/@travel-mcp/geoapify-server