MCP Geocoder Rosetta

MCP罗塞塔地理编码器

一组不同语言和使用不同方法的模型上下文协议（MCP）地理编码器实现。对于希望创建自己的MCP工具的开发人员来说，这个存储库是一个“Rosetta Stone”。

什么是MCP？

模型上下文协议（MCP）是一种用于工具与人工智能模型交互的协议，允许人工智能在现实世界中执行操作，如进行API调用或访问数据库。MCP为AI模型使用工具和开发人员创建这些工具提供了一种标准化的方法。

实现

此存储库包含使用Google Maps API的地理编码工具的三种不同实现：

1. Python + urllib -使用Python的标准库，无需额外依赖
2. Python+谷歌地图SDK -使用官方的谷歌地图Python客户端
3. TypeScript+谷歌地图SDK -使用TypeScript和谷歌地图JavaScript客户端

实施方案比较

先决条件

• 谷歌地图API密钥(在这里买一个)
• Python 3.13+（用于Python实现）
• Node.js 16+（用于TypeScript实现）
• MCP CLI工具

设置

1.克隆存储库：

git clone https://github.com/yourusername/mcp-geocoder-rosetta.git
cd mcp-geocoder-rosetta

2.设置您的Google Maps API密钥：

# Set as environment variable
export GOOGLE_MAPS_API_KEY=your-api-key-here

# Or create .env files in each implementation directory
echo "GOOGLE_MAPS_API_KEY=your-api-key-here" > python-urllib/.env
echo "GOOGLE_MAPS_API_KEY=your-api-key-here" > python-googlemaps/.env
echo "GOOGLE_MAPS_API_KEY=your-api-key-here" > typescript-googlemaps/.env

3.安装MCP CLI：

# Using pip
pip install mcp[cli]

# Or using uv
uv pip install mcp[cli]

4.运行调试脚本以检查您的环境：

chmod +x debug_mcp.sh
./debug_mcp.sh

快速开始

使用urllib测试Python：

# Direct test with MCP client
python test_direct.py urllib

# Server CLI test
python test_server.py urllib

# Interactive client
python run_geocoder.py urllib

使用Google Maps SDK测试Python：

# Direct test with MCP client
python test_direct.py googlemaps

# Server CLI test
python test_server.py googlemaps

# Interactive client
python run_geocoder.py googlemaps

测试TypeScript：

# Simply run the client which will handle dependencies and server startup
python run_geocoder.py typescript

# The script will:
# - Check for npm and install dependencies if needed
# - Start the TypeScript server automatically
# - Connect and let you query addresses

个性化服务设置

带urllib的Python

cd python-urllib

# Method 1: Direct execution with dependencies
export GOOGLE_MAPS_API_KEY="your-api-key-here"
uv run --with mcp[cli] mcp run geocoder.py

# Method 2: Using virtual environment
uv venv -p 3.13 .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .
mcp run geocoder.py

Python与谷歌地图SDK

cd python-googlemaps

# Method 1: Direct execution with dependencies
export GOOGLE_MAPS_API_KEY="your-api-key-here"
uv run --with mcp[cli] --with googlemaps mcp run geocoder.py

# Method 2: Using virtual environment
uv venv -p 3.13 .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install googlemaps
uv pip install -e .
mcp run geocoder.py

TypeScript与谷歌地图SDK

# Method 1: Using run_geocoder.py (recommended)
# This automatically handles dependencies and server startup
python run_geocoder.py typescript

# Method 2: Manual setup
cd typescript-googlemaps

# Install dependencies
npm install

# Set up environment with your Google Maps API key
echo "GOOGLE_MAPS_API_KEY=your-api-key-here" > .env

# Run the MCP server directly (only if needed)
npm start

可用脚本

主要脚本

• run_geocoder.py：对于任何实现，使用服务器运行客户端
• test_direct.py：测试MCP与服务器的直接通信
• test_server.py：使用直接Python方法测试服务器
• debug_mcp.sh：用于故障排除的调试脚本

运行选项

• 常规模式: python run_geocoder.py
• 仅服务器模式: python run_geocoder.py --server-only
• 仅客户端模式: python run_geocoder.py --client-only

调试客户端-服务器连接

如果客户端连接到服务器时遇到问题，有几种调试方法：

方法1：分别运行服务器和客户端

在一个终端中运行服务器：

python run_geocoder.py urllib --server-only

然后在另一个终端中运行客户端：

python run_geocoder.py urllib --client-only

这有助于隔离问题是服务器、客户端还是它们之间的通信。

方法2：直接服务器测试

使用测试脚本直接测试服务器，而不涉及整个客户端：

# Test with a direct MCP connection:
python test_direct.py urllib

# Or test the server with direct Python:
python test_server.py urllib

这些脚本将启动服务器，测试基本连接，并运行一个示例地理编码请求。

常见问题

1. 缺少API密钥：确保您的Google Maps API密钥设置在 .env 每个实现目录中的文件或作为环境变量。

1. 未找到模块：如果出现“找不到模块”错误，请安装所需的依赖项：

   pip install googlemaps mcp[cli]

1. 连接问题：客户端和服务器通过标准输入/输出进行通信。如果有问题，请检查：

- Python版本兼容性（建议使用Python 3.13+） - MCP SDK版本兼容性 - 执行脚本的权限

1. 调试指南：运行附带的调试指南以获取更多帮助：

   ./debug_mcp.sh

调试脚本将：

- 检查您的Python安装 - 验证MCP模块安装 - 检查您的谷歌地图API密钥配置 - 测试urllib实现 - 提供故障排除命令参考

与Claude Desktop集成

访问配置文件

1. 打开克劳德桌面 应用
2. 访问设置：点击左下角的齿轮图标
3. 打开开发人员选项卡：点击侧边栏中的“开发人员”
4. 编辑配置：单击页面底部的“编辑配置”按钮，在默认文本编辑器中打开配置文件

将MCP工具添加到配置中

这 claude_desktop_config.json 文件包含一个JSON对象 mcpServers 作为MCP工具的顶级密钥。将您的地理编码器实现添加到此部分：

{
  "mcpServers": {
    "existing-server-1": {
      // existing configuration
    },
    "existing-server-2": {
      // existing configuration
    },
    
    // Add your geocoder implementations here
  }
}

⚠️ 重要提示：工具消除歧义警告 ⚠️

一次只安装其中一个地理编码器实现。拥有多个功能相似的MCP服务器可能会导致工具消歧问题，Claude可能不知道在处理请求时使用哪个地理编码工具。

以下是如何将每个实现添加到您的配置中：

TypeScript与谷歌地图SDK

"mcpServers": {
  "GeocoderNode": {
    "command": "npx",
    "args": [
      "tsx",
      "/path/to/mcp-geocoder-rosetta/typescript-googlemaps/geocoder.ts"
    ],
    "env": {
      "GOOGLE_MAPS_API_KEY": "your-api-key-here"
    }
  }
}

Python与谷歌地图SDK

"mcpServers": {
  "GeocoderGoogle": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "mcp[cli]",
      "--with",
      "googlemaps",
      "mcp",
      "run",
      "/path/to/mcp-geocoder-rosetta/python-googlemaps/geocoder.py"
    ],
    "env": {
      "GOOGLE_MAPS_API_KEY": "your-api-key-here"
    }
  }
}

备注：The --with googlemaps 参数对于此实现的正常工作至关重要。

带urllib的Python

"mcpServers": {
  "GeocoderREST": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "mcp[cli]",
      "mcp",
      "run",
      "/path/to/mcp-geocoder-rosetta/python-urllib/geocoder.py"
    ],
    "env": {
      "GOOGLE_MAPS_API_KEY": "your-api-key-here"
    }
  }
}

配置后

1. 保存文件 做出更改后
2. 返回克劳德桌面 -应用程序将自动重新加载配置
3. 在设置中验证：在“开发人员”选项卡中，您现在应该在MCP服务器列表中看到添加的地理编码工具
4. 状态指示：服务器成功启动时，将出现运行状态指示器

故障排除配置

• 确保你的JSON是有效的（没有尾随逗号，正确嵌套）
• 使用实现文件的绝对路径
• 检查环境变量是否设置正确
• 如果服务器无法启动，请检查该服务器的“高级选项”下拉列表以查看错误日志

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

项目结构说明

临时目录

存储库包含几个 temp/ 用于动态生成测试和调试脚本的目录：

• /temp/：主测试脚本的根临时目录
• python-urllib/temp/：包含用于测试urllib实现的脚本
• python-googlemaps/temp/：包含用于测试Google Maps API实现的脚本
• typescript-googlemaps/temp/：包含TypeScript测试工具的脚本

这些目录由测试脚本创建和使用，以生成用于连接到MCP服务器、诊断连接问题、验证工具可用性和测试功能的实用程序脚本。它们被添加到 .gitignore 并且不应提交到存储库。

MCP客户端目录

这 mcp-client/ 目录包含一个较旧的客户端实现，该实现在很大程度上已被中的直接MCP通信所取代 run_geocoder.py虽然在某些情况下仍被引用和用作回退，但主要功能现在直接使用MCP库进行更可靠的通信。

已知问题

• 交互式输入在非交互式环境（如Claude Code）中效果不佳
• 实现工作所需的一些环境设置（API密钥、依赖项）
• 这 mcp tools 命令在当前的MCP CLI版本中不可用，因此我们在test_server.py中使用直接的Python方法
• 不同的实现有不同的可用工具（只有urllib有debug_info）
• 在非交互式环境中长时间运行的进程可能会超时（尤其是TypeScript启动）