Location Grid MCP

位置网格MCP服务器

一项综合地理编码服务，结合了Nominatim地理编码与位置网格数据库查询功能，既可作为独立的Python库使用，也可作为人工智能助手的模型上下文协议（MCP）服务器提供服务。

🚀 特性

• 地址地理编码使用Nominatim将地址转换为经度、纬度坐标
• 网格ID查询从位置网格数据库中查找对应的网格ID
• MCP 服务器用于AI助手集成的完整模型上下文协议服务器
• Docker 支持使用Docker和Docker Compose进行容器化部署
• JSON API清理JSON响应，使用 lng， lat，以及 grid_id
• 错误处理使用JSON错误响应进行全面的错误处理
• SQLite 集成使用SQLite数据库进行高效的网格ID查询
• 健康检查为容器化部署内置健康监控

📋 目录

• 安装
• 快速入门
• 用法

- 独立的Python库 - MCP服务器 -

• API 参考
• 配置
• 数据库结构
• 故障排除
• 做出贡献

🛠 安装

先决条件

• Python 3.6+（推荐使用 Docker 时安装 Python 3.11+）
• 互联网连接（用于Nominatim API）
• SQLite数据库文件（db/location_grid.db）

本地安装

1. 克隆仓库：

   git clone 
   cd location-grid-mcp

1. 安装依赖项：

   pip install -r requirements.txt

1. 验证安装：

   python geocoder.py "New York City"

Docker 安装

1. 构建Docker镜像：

   docker build -t location-grid-mcp .

1. 使用 Docker Compose 运行：

   docker-compose up -d

🚀 快速入门

独立使用

# Command line geocoding
python geocoder.py "London, UK"

# Output:
{
  "lng": -0.1277653,
  "lat": 51.5074456,
  "grid_id": 100130785
}

MCP服务器使用情况

1. 启动MCP服务器：

   python mcp_server.py

1. 配置您的MCP客户端 （例如，在 mcp_config.json):

   {
     "mcpServers": {
       "location-grid-geocoder": {
         "command": "python",
         "args": ["/path/to/mcp_server.py"],
         "env": {
           "PYTHONPATH": "/path/to/location-grid-mcp"
         }
       }
     }
   }

Docker 使用方法

# Run with Docker Compose
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f location-grid-mcp

📖 使用方法

独立的Python库

from geocoder import SimpleGeocoder

# Initialize the geocoder
geocoder = SimpleGeocoder()

# Geocode an address (returns dictionary)
result = geocoder.geocode_address("Tokyo, Japan")
print(result)
# Output: {"lng": 139.7638947, "lat": 35.6768601, "grid_id": 100232965}

# Get result as JSON string
json_result = geocoder.geocode_address_json("Paris, France")
print(json_result)
# Output: '{"lng": 2.3522219, "lat": 48.856614, "grid_id": 100123456}'

# Get grid ID for specific coordinates
grid_id = geocoder._get_grid_id_by_coordinates(-74.006, 40.7128)
print(grid_id)  # Output: 100366035

MCP服务器工具

MCP服务器提供了两种主要工具：

1. geocode_address

对地址进行地理编码，以获取经度、纬度和网格ID。

参数：

• address (字符串)：要进行地理编码的地址或位置名称

示例：

{
  "address": "Sydney, Australia"
}

回答：

{
  "lng": 151.2082848,
  "lat": -33.8698439,
  "grid_id": 100003047
}

2. geocode_coordinates

获取给定经度和纬度坐标的网格ID。

参数：

• longitude (数字)：经度坐标
• latitude （数字）：纬度坐标

示例：

{
  "longitude": -74.006,
  "latitude": 40.7128
}

回答：

{
  "lng": -74.006,
  "lat": 40.7128,
  "grid_id": 100366035
}

Docker 部署

使用 Docker Compose（推荐）

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Rebuild and restart
docker-compose up --build -d

直接使用Docker

# Build image
docker build -t location-grid-mcp .

# Run container
docker run -d \
  --name location-grid-mcp \
  -v $(pwd)/db:/app/db \
  -v $(pwd)/logs:/app/logs \
  location-grid-mcp

# Check container status
docker ps

# View logs
docker logs location-grid-mcp

⚙️ 配置

MCP服务器配置

创建或更新您的MCP客户端配置文件：

{
  "mcpServers": {
    "location-grid-geocoder": {
      "command": "python",
      "args": ["/path/to/mcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/location-grid-mcp"
      }
    }
  }
}

Docker 环境变量

数据库配置

该地理编码器使用位于（某处的）SQLite数据库 db/location_grid.db确保该文件存在且可访问。

🗄️ 数据库结构

地理编码器使用SQLite数据库（db/location_grid.db) 带着一个 location_grid 包含以下内容的表格：

🔧 API参考

SimpleGeocoder 类

__init__(db_path=None)

使用可选的数据库路径初始化地理编码器。

参数：

• db_path (字符串，可选)：SQLite 数据库的路径。默认为 ./db/location_grid.db

geocode_address(address)

将地址进行地理编码，并返回带有网格ID的坐标。

参数：

• address (str): 需要进行地理编码的地址或位置名称

返回：

• dict带有（或：包含）字典的 lng， lat， grid_id 成功的关键在于，或者 error 在失败时启用（或关注）关键（因素/环节）

geocode_address_json(address)

将地址进行地理编码，并将结果作为JSON字符串返回。

参数：

• address (str): 要进行地理编码的地址或位置名称

返回值：

• str包含地理编码结果的JSON字符串

响应格式

成功响应

{
  "lng": -74.0060152,
  "lat": 40.7127281,
  "grid_id": 100366035
}

错误响应

{
  "error": "Could not geocode address 'invalid_address' using Nominatim"
}

🐛 故障排除

常见问题

1. 数据库连接错误

Error: Failed to connect to database

解决方案： 确保数据库文件存在于 db/location_grid.db 并且可以访问。

2. Nominatim API 错误

Error: Could not geocode address using Nominatim

解决方案： 检查您的网络连接，并验证地址格式。

3. Docker 容器问题

Error: Container failed to start

解决方案：

• 检查Docker日志： docker logs location-grid-mcp
• 验证数据库文件是否存在
• 检查容器健康状况： docker-compose ps

4. MCP服务器连接问题

Error: MCP server not responding

解决方案：

• 验证服务器是否正在运行： python mcp_server.py
• 检查MCP配置文件
• 确保配置中的文件路径正确

健康检查

Docker 健康检查

# Check container health
docker ps

# View health check logs
docker inspect location-grid-mcp | grep -A 10 Health

手动健康检查

# Test geocoder functionality
python -c "from geocoder import SimpleGeocoder; g = SimpleGeocoder(); print(g.geocode_address('Test'))"

日志

Docker 日志

# View all logs
docker-compose logs

# Follow logs in real-time
docker-compose logs -f location-grid-mcp

# View specific service logs
docker-compose logs location-grid-mcp

应用程序日志

日志存储在 logs/ 在 Docker 中运行时的目录。

📁 项目结构

location-grid-mcp/
├── db/
│   └── location_grid.db          # SQLite database
├── documents/                     # Additional documentation
├── logs/                         # Application logs
├── backups/                      # Database backups
├── geocoder.py                   # Core geocoding library
├── mcp_server.py                 # MCP server implementation
├── mcp_config.json              # MCP client configuration
├── requirements.txt              # Python dependencies
├── Dockerfile                    # Docker image definition
├── docker-compose.yml           # Docker Compose configuration
├── docker-build.sh             # Docker build script
├── docker-run.sh               # Docker run script
├── docker-test.sh              # Docker test script
└── README.md                    # This file

🤝 贡献

1. 为仓库创建分支（或：克隆仓库）
2. 创建一个特性分支： git checkout -b feature/amazing-feature
3. 进行你的更改
4. 彻底测试：

   # Test standalone functionality
   python geocoder.py "Test Location"

   # Test MCP server
   python mcp_server.py

   # Test Docker deployment
   docker-compose up --build

1. 提交您的更改： git commit -m 'Add amazing feature'
2. 推送至分支： git push origin feature/amazing-feature
3. 提交一个拉取请求

开发环境设置

# Clone the repository
git clone 
cd location-grid-mcp

# Install development dependencies
pip install -r requirements.txt

# Run tests
python -m pytest tests/  # If tests exist

# Run linting
flake8 .  # If flake8 is configured

📄 许可证

这个项目是开源的。请查看许可证文件以了解详情。

🆘 支持

对于问题、疑问或贡献：

1. 创建一个问题 在仓库中
2. 检查现有问题 针对类似问题
3. 联系维护人员 对于紧急问题

寻求帮助

• 文档请查阅此README文件以及 documents/ 目录
• 问题搜索现有的GitHub问题
• 讨论使用 GitHub 讨论区提问
• 电子邮件对于紧急问题，请联系维护人员

______________________________________________________________________

为地理编码社区倾情打造