MCP Geocoder Rosetta

MCP Geocoder Rosetta

使用不同语言和不同方法实现的一组 Model Context Protocol（MCP）地理编码器。本仓库为希望创建自己的 MCP 工具的开发者提供了一份“罗塞塔石碑”。

什么是 MCP？

Model Context Protocol（MCP）是一种供工具与 AI 模型交互的协议，可让 AI 执行现实世界中的操作，例如调用 API 或访问数据库。MCP 为 AI 模型使用工具以及开发者创建这些工具提供了一种标准化方式。

实现方案

本仓库包含三种使用 Google Maps API 的地理编码工具实现：

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

实现方案对比

特性	Python + urllib	Python + Google Maps SDK	TypeScript + Google Maps SDK
依赖项	极少（标准库）	googlemaps、mcp	@googlemaps/google-maps-services-js、@mcp/sdk
设置复杂度	简单	中等	中等
错误处理	基础	增强	增强
代码规模	小	中	中
SDK 优势	无——直接调用 API	类型处理、验证	类型安全、Promise API

前置条件

• Google Maps 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

快速开始

测试 Python + urllib：

# 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

测试 Python + Google Maps SDK：

# 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

单项服务设置

Python + urllib

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 + Google Maps 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 + Google Maps 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 <implementation>
• 仅服务模式：python run_geocoder.py <implementation> --server-only
• 仅客户端模式：python run_geocoder.py <implementation> --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 密钥：请确保已在每个实现目录的 .env 文件中设置 Google Maps API 密钥，或将其设置为环境变量。

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

   pip install googlemaps mcp[cli]
   

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

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

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

   ./debug_mcp.sh
   

   调试脚本将：

   • 检查 Python 安装情况
   • 验证 MCP 模块是否已安装
   • 检查 Google Maps API 密钥配置
   • 测试 urllib 实现
   • 提供故障排除命令参考

与 Claude Desktop 集成

访问配置文件

1. 打开 Claude Desktop 应用程序
2. 访问设置：点击左下角的齿轮图标
3. 打开 Developer 选项卡：点击侧边栏中的“Developer”
4. 编辑配置：点击页面底部的“Edit Config”按钮，在默认文本编辑器中打开配置文件

将 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 在处理请求时无法确定应使用哪个地理编码工具。

以下是将每种实现添加到配置中的方法：

使用 Google Maps SDK 的 TypeScript

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

使用 Google Maps SDK 的 Python

"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"
    }
  }
}

注意：--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. 返回 Claude Desktop——应用程序会自动重新加载配置
3. 在设置中验证：在 Developer 选项卡中，你现在应该能在 MCP 服务列表中看到已添加的地理编码工具
4. 状态指示器：服务成功启动后会显示运行状态指示器

配置故障排除

• 确保 JSON 有效（没有尾随逗号，嵌套正确）
• 使用实现文件的绝对路径
• 检查环境变量是否已正确设置
• 如果服务启动失败，请检查该服务的“Advanced options”下拉菜单，查看错误日志

许可证

本项目采用 MIT License 授权——详情请参阅 LICENSE 文件。

项目结构说明

临时目录

该代码库包含多个 temp/ 目录，用于存放动态生成的测试和调试脚本：

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

测试脚本会创建并使用这些目录，生成用于连接 MCP 服务、诊断连接问题、验证工具可用性及测试功能的实用脚本。这些目录已添加到 .gitignore，不应提交到代码库。

MCP 客户端目录

mcp-client/ 目录包含较早的客户端实现，该实现已基本被 run_geocoder.py 中的直接 MCP 通信取代。虽然某些情况下仍会引用并将其用作后备方案，但现在主要功能直接使用 MCP 库，以实现更可靠的通信。

已知问题

• 在非交互式环境（如 Claude Code）中，交互式输入无法正常工作
• 某些实现需要进行环境配置才能运行（API key、依赖项）
• 当前版本的 MCP CLI 中没有 mcp tools 命令，因此我们在 test_server.py 中直接使用 Python
• 不同实现可用的工具各不相同（只有 urllib 提供 debug_info）
• 在非交互式环境中，长时间运行的进程可能会超时（尤其是 TypeScript 启动时）