mcp-geocoder-rosetta

🚀 MCP 地理编码器罗塞塔项目

MCP 地理编码器罗塞塔项目致力于为采用不同编程语言和地理编码服务实现的 MCP（机器学习控制协议）地理编码工具打造一个统一的接口。它支持三种实现方式，能满足多样化的开发需求。

🚀 快速开始

安装与配置

克隆仓库

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

安装依赖

• Python 实现：

pip install googlemaps

• TypeScript 实现：

npm install typescript @types/node @googlemaps/google-maps-services-js --save

配置环境变量

在项目根目录下创建 .env 文件，并添加以下内容：

GOOGLE_MAPS_API_KEY=你的API密钥

启动实现

• 基于 urllib 的 Python 实现：

uv run --with mcp[cli] mcp run path/to/python-urllib/geocoder.py

• 基于 Google Maps SDK 的 Python 实现：

uv run --with mcp[cli] --with googlemaps mcp run path/to/python-googlemaps/gecoder.py

• TypeScript 实现：

npx tsx path/to/typescript/googlemaps/gecoder.ts

✨ 主要特性

• 统一接口：为不同实现的 MCP 地理编码工具提供统一接口。
• 多语言支持：涵盖 Python 和 TypeScript 两种编程语言的实现。
• 多方式调用：支持直接调用 Google Maps Geocoding API 和使用 Google Maps SDK 进行交互。

📦 安装指南

克隆仓库

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

安装依赖

• Python 实现：

pip install googlemaps

• TypeScript 实现：

npm install typescript @types/node @googlemaps/google-maps-services-js --save

配置环境变量

在项目根目录下创建 .env 文件，添加以下内容：

GOOGLE_MAPS_API_KEY=你的API密钥

💻 使用示例

启动不同实现

基于 urllib 的 Python 实现

uv run --with mcp[cli] mcp run path/to/python-urllib/geocoder.py

基于 Google Maps SDK 的 Python 实现

uv run --with mcp[cli] --with googlemaps mcp run path/to/python-googlemaps/gecoder.py

TypeScript 实现

npx tsx path/to/typescript/googlemaps/gecoder.ts

📚 详细文档

项目结构

• python-urllib/：使用 urllib 和 Google Maps API 的 Python 实现。
• python-googlemaps/：使用 Google Maps SDK 的 Python 实现。
• typescript-googlemaps/：TypeScript 实现，通过 Node.js 平台运行。
• mcp-client/：旧的 MCP 客户端实现（已弃用）。

集成到 Claude Desktop

添加 MCP 工具到配置

编辑 claude_desktop_config.json 文件，在 mcpServers 下添加以下内容：

TypeScript 实现

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

基于 Google Maps SDK 的 Python 实现

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

基于 urllib 的 Python 实现

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

注意事项

⚠️ 重要提示

• 一次仅安装一个地理编码实现，以避免工具歧义问题。
• 使用绝对路径配置 MCP 工具。
• 确保 JSON 配置格式正确（无尾随逗号，缩进正确）。

🔧 技术细节

支持的实现方式

• 基于 urllib 的 Python 实现：直接调用 Google Maps Geocoding API。
• 基于 Google Maps SDK 的 Python 实现：使用 Google 提供的 Python 库进行交互。
• TypeScript 实现：通过 Node.js 平台运行，同样调用 Google Maps Geocoding API。

📄 许可证

本项目遵循 MIT 许可证。详细信息请查看 LICENSE 文件。

其他说明

临时目录说明

仓库包含多个 temp/ 目录，用于动态生成测试和调试脚本：

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

这些目录已添加到 .gitignore，请勿提交到仓库。

已知问题

• 交互式输入在非交互式环境中表现不佳（如 Claude Code）。
• 不同实现之间的性能和可靠性可能存在差异。
• 旧的 MCP 客户端实现（mcp-client/）已弃用，不再维护。