geoapify-mcp-server/MCP_TROUBLESHOOTING.md

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

# MCP服务器启动失败问题分析与解决方案

## 问题分析

### 错误信息
```
Error: Cannot find module 'C:\Users\张俊\AppData\Roaming\npm\node_modules\@travel-mcp\geoapify-server\bin\mcp-server.js'
```

### 根本原因
1. **包名不匹配**：npx寻找的包名与实际包名不一致
2. **包未发布**：`@travel-mcp/geoapify-server` 包还没有发布到npm registry
3. **bin配置问题**：package.json中的bin配置与使用的命令不匹配

## 解决方案

### 方案1：本地直接运行（推荐）

#### 1.1 直接运行MCP服务器
```bash
cd 新建文件夹
node bin/mcp-server.js
```

#### 1.2 使用npm脚本
```bash
cd 新建文件夹
npm run mcp
```

#### 1.3 修改MCP客户端配置
将 `mcp-client-config.json` 修改为：
```json
{
  "mcpServers": {
    "geoapify-maps": {
      "command": "node",
      "args": ["./bin/mcp-server.js"],
      "cwd": "./新建文件夹",
      "env": {
        "GEOAPIFY_API_KEY": "3234bd7e35264a8aa29fc15e89f8f76f",
        "NODE_ENV": "production"
      }
    }
  }
}
```

### 方案2：发布到npm（长期解决方案）

#### 2.1 登录npm
```bash
npm login
```

#### 2.2 发布包
```bash
cd 新建文件夹
npm publish
```

#### 2.3 使用npx运行
```bash
npx geoapify-mcp-server
```

### 方案3：本地安装

#### 3.1 全局安装本地包
```bash
cd 新建文件夹
npm install -g .
```

#### 3.2 运行
```bash
geoapify-mcp-server
```

## 测试验证

### 测试MCP协议通信
```bash
cd 新建文件夹
node test-mcp-local.js
```

### 测试API功能
```bash
cd 新建文件夹
npm run test-api
```

## 当前状态

- ✅ MCP服务器代码完整
- ✅ package.json配置已修复
- ✅ 本地运行配置已更新
- ❌ npm包未发布
- ❌ 依赖可能未安装

## 下一步操作

1. **立即解决**：使用方案1本地直接运行
2. **安装依赖**：`npm install`
3. **测试功能**：运行测试脚本
4. **发布包**：完成npm发布流程

## 常见问题

### Q: 为什么npx找不到包？
A: 因为包还没有发布到npm registry，npx无法下载安装。

### Q: 如何验证MCP服务器是否正常工作？
A: 运行 `node bin/mcp-server.js` 并发送JSON-RPC消息测试。

### Q: 如何更新MCP客户端配置？
A: 修改配置文件使用本地路径而不是npx命令。