MCP 地理编码器 Rosetta

本仓库收集了使用不同语言和方法实现的模型上下文协议 (MCP) 地理编码器。对于希望创建自己的 MCP 工具的开发者来说，本仓库就像一块“罗塞塔石碑”。

什么是 MCP？

模型上下文协议 (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 密钥：

# 设置为环境变量
export GOOGLE_MAPS_API_KEY=your-api-key-here

# 或者在每个实现目录中创建 .env 文件
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：

# 使用 pip
pip install mcp[cli]

# 或者使用 uv
uv pip install mcp[cli]

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

chmod +x debug_mcp.sh
./debug_mcp.sh

快速开始

测试 Python with urllib：

# 使用 MCP 客户端直接测试
python test_direct.py urllib

# Server CLI 测试
python test_server.py urllib

# 交互式客户端
python run_geocoder.py urllib

测试 Python with Google Maps SDK：

# 使用 MCP 客户端直接测试
python test_direct.py googlemaps

# Server CLI 测试
python test_server.py googlemaps

# 交互式客户端
python run_geocoder.py googlemaps

测试 TypeScript：

# 只需运行客户端，它将处理依赖项和服务启动
python run_geocoder.py typescript

# 该脚本将：
# - 检查 npm 并根据需要安装依赖项
# - 自动启动 TypeScript 服务器
# - 连接并让您查询地址

单独服务设置

Python with urllib

cd python-urllib

# 方法 1：直接执行，带依赖
export GOOGLE_MAPS_API_KEY="your-api-key-here"
uv run --with mcp[cli] mcp run geocoder.py

# 方法 2：使用虚拟环境
uv venv -p 3.13 .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
uv pip install -e .
mcp run geocoder.py

Python with Google Maps SDK

cd python-googlemaps

# 方法 1：直接执行，带依赖
export GOOGLE_MAPS_API_KEY="your-api-key-here"
uv run --with mcp[cli] --with googlemaps mcp run geocoder.py

# 方法 2：使用虚拟环境
uv venv -p 3.13 .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
pip install googlemaps
uv pip install -e .
mcp run geocoder.py

TypeScript with Google Maps SDK

# 方法 1：使用 run_geocoder.py (推荐)
# 这会自动处理依赖项和服务启动
python run_geocoder.py typescript

# 方法 2：手动设置
cd typescript-googlemaps

# 安装依赖
npm install

# 使用您的 Google Maps API 密钥设置环境
echo "GOOGLE_MAPS_API_KEY=your-api-key-here" > .env

# 直接运行 MCP 服务器 (仅在需要时)
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：直接服务器测试

使用测试脚本直接测试服务器，而无需涉及完整的客户端：

# 使用直接 MCP 连接进行测试：
python test_direct.py urllib

# 或者使用直接 Python 测试服务器：
python test_server.py urllib

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

常见问题

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

2. 找不到模块: 如果您收到“Module not found”错误，请安装所需的依赖项：

   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”
4. 编辑配置: 单击页面底部的“Edit Config”按钮，以在默认文本编辑器中打开配置文件

将 MCP 工具添加到配置

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

{
  "mcpServers": {
    "existing-server-1": {
      // 现有配置
    },
    "existing-server-2": {
      // 现有配置
    },
    
    // 在此处添加您的地理编码器实现
  }
}

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

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

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

TypeScript with Google Maps 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 with Google Maps 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"
    }
  }
}

注意: --with googlemaps 参数对于此实现正常工作至关重要。

Python with urllib

"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. 在设置中验证: 在开发者选项卡中，您现在应该在 MCP 服务器列表中看到您添加的地理编码器工具
4. 状态指示器: 当服务器成功启动时，将出现一个运行状态指示器

故障排除配置

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

许可证

本项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 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 密钥、依赖项）
• mcp tools 命令在当前 MCP CLI 版本中不可用，因此我们在 test_server.py 中使用直接 Python 方法
• 不同的实现具有不同的可用工具（只有 urllib 具有 debug_info）
• 非交互式环境中的长时间运行进程可能会超时（尤其是 TypeScript 启动）