Geocoding Tool

Converta nomes de cidades e localizações em coordenadas de latitude e longitude usando a API gratuita OpenStreetMap Nominatim. Nenhuma chave de API é necessária.

GitHub
5

Documentação

Servidor MCP de Geocoding

Um servidor Model Context Protocol (MCP) que fornece coordenadas de latitude/longitude para cidades e locais usando a API OpenStreetMap Nominatim.

Recursos

  • 🌍 Geocodificação Global: Obtenha coordenadas para qualquer local no mundo
  • 🆓 API Gratuita: Usa OpenStreetMap Nominatim (nenhuma chave de API necessária)
  • 🔌 Integração MCP: Funciona com Cursor, VS Code, Claude Desktop e outras ferramentas compatíveis com MCP
  • 📦 Instalação Fácil: Instale via PyPI com uvx geocode-mcp
  • ⚙️ Ferramentas Modernas: Construído com Python 3.12+, async/await e testes abrangentes

Início Rápido

Instalação

Instale o pacote do PyPI usando uvx (recomendado):

uvx geocode-mcp

Ou instale com pip:

pip install geocode-mcp

Configuração MCP

Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "geocoding": {
      "command": "uvx",
      "args": ["geocode-mcp"]
    }
  }
}

Consulte o diretório config/ para exemplos específicos de diferentes ferramentas.

Ferramentas Disponíveis

mcp_geocoding_get_coordinates

Obtenha coordenadas de latitude e longitude para uma cidade ou local.

Parâmetros:

  • location (obrigatório): Nome da cidade, endereço ou local (ex.: "Nova York", "Paris, França", "123 Main St, Seattle")
  • limit (opcional): Número máximo de resultados a retornar (padrão: 1, máximo: 10)

Exemplo de Uso:

Get coordinates for Tokyo, Japan
Find the latitude and longitude of London, UK  
What are the coordinates for New York City?
Get coordinates for "1600 Pennsylvania Avenue, Washington DC" with limit 5

Formato de Resposta:

{
  "query": "Tokyo, Japan",
  "results_count": 1,
  "coordinates": [
    {
      "latitude": 35.6762,
      "longitude": 139.6503,
      "display_name": "Tokyo, Japan",
      "place_id": "282885117",
      "type": "city",
      "class": "place",
      "importance": 0.9,
      "bounding_box": {
        "south": 35.619,
        "north": 35.739,
        "west": 139.619,
        "east": 139.682
      }
    }
  ]
}

Guias de Integração

Cursor

Copie a configuração de config/cursor-mcp.json para as configurações MCP do seu Cursor.

VS Code

Copie a configuração de config/vscode-mcp.json para as configurações MCP do seu VS Code.

Claude Desktop

Copie a configuração de config/claude-desktop.json para o arquivo de configuração do seu Claude Desktop.

Consulte o README de configuração para instruções detalhadas de configuração.

Desenvolvimento

Configuração

# Clone the repository
git clone https://github.com/X-McKay/geocode-mcp.git
cd geocode-mcp

# Install with development dependencies
pip install -e ".[dev]"

Executando Testes

# Run all tests
pytest

# Run with coverage
pytest --cov=src/geocode_mcp --cov-report=html

# Run specific test files
pytest tests/test_geocoding.py -v
pytest tests/test_mcp_server.py -v

Qualidade de Código

# Format code
ruff format

# Lint code
ruff check

# Run all checks
ruff check && ruff format --check

Desenvolvimento Local

Para desenvolvimento e testes locais, você pode executar o servidor diretamente:

python -m geocode_mcp.server

Ou use a configuração de desenvolvimento no seu cliente MCP:

{
  "mcpServers": {
    "geocoding": {
      "command": "python",
      "args": ["-m", "geocode_mcp.server"],
      "cwd": "/path/to/geocode-mcp",
      "env": {
        "PYTHONPATH": "/path/to/geocode-mcp/src"
      }
    }
  }
}

Estrutura do Projeto

geocode-mcp/
├── src/geocode_mcp/       # Main source code
│   └── server.py          # MCP server implementation
├── tests/                 # Test suite
│   ├── test_geocoding.py  # Geocoding functionality tests
│   ├── test_mcp_server.py # MCP server integration tests
│   ├── test_mcp.py        # MCP protocol tests
│   └── test_vscode.py     # VS Code integration tests
├── config/                # Configuration examples
│   ├── cursor-mcp.json    # Cursor configuration
│   ├── vscode-mcp.json    # VS Code configuration
│   ├── claude-desktop.json # Claude Desktop configuration
│   └── README.md          # Configuration guide
├── docs/                  # Documentation
├── pyproject.toml         # Project configuration
├── requirements.txt       # Production dependencies
├── requirements-dev.txt   # Development dependencies
└── README.md             # This file

Referência da API

Funções Principais

async def geocode_location(location: str, limit: int = 1) -> dict[str, Any]:
    """
    Geocode a location using OpenStreetMap Nominatim API.
    
    Args:
        location: The location to geocode
        limit: Maximum number of results (1-10)
        
    Returns:
        Dictionary containing query, results_count, and coordinates
    """

Servidor MCP

O servidor implementa o Model Context Protocol e fornece a ferramenta mcp_geocoding_get_coordinates para uso em aplicativos compatíveis com MCP.

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de recurso (git checkout -b feature/amazing-feature)
  3. Faça suas alterações
  4. Execute os testes (pytest)
  5. Execute o linting (ruff check && ruff format)
  6. Faça commit das suas alterações (git commit -m 'Add amazing feature')
  7. Envie para o branch (git push origin feature/amazing-feature)
  8. Abra um Pull Request

Consulte CONTRIBUTING.md para mais detalhes.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

Agradecimentos

  • OpenStreetMap por fornecer o serviço gratuito de geocodificação Nominatim
  • Model Context Protocol pela especificação do protocolo
  • A equipe do SDK Python MCP pelas excelentes ferramentas make lint

Formatar código

make format

Verificação de tipos

make type-check

Executar todas as verificações

make check-all


### Testing

```bash
# Run all tests
make test

# Run with coverage
make test-cov

# Run specific test categories
pytest tests/test_geocoding.py -v  # Geocoding tests
pytest tests/test_mcp.py -v        # MCP server tests
python tests/test_mcp_server.py    # Integration tests
python tests/test_vscode.py        # VSCode tests

Instalação

# Install production dependencies
make install

# Install development dependencies
make install-dev

Configuração

Integração com Cursor

Consulte o Guia de Integração com Cursor para instruções detalhadas de configuração.

Integração com VSCode

Execute os testes de integração do VSCode:

python tests/test_vscode.py

Referência da API

Função de Geocodificação

async def geocode_location(location: str, limit: int = 1) -> dict[str, Any]:
    """Geocode a location using Nominatim API."""

Servidor MCP

O servidor fornece a ferramenta get_coordinates que pode ser chamada via protocolo MCP.

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de recurso
  3. Faça suas alterações
  4. Execute os testes: make test
  5. Execute o linting: make lint
  6. Envie um pull request

Consulte CONTRIBUTING.md para mais detalhes.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

Agradecimentos

  • OpenStreetMap por fornecer o serviço de geocodificação Nominatim
  • MCP pela especificação do protocolo

---

## 🚀 Quick Setup Instructions

1. **Create Project Folder:**
   ```bash
   mkdir mcp-geocoding-server-python
   cd mcp-geocoding-server-python

  1. Copie os Arquivos: Copie cada seção de arquivo acima para arquivos com os respectivos nomes

  2. Instale as Dependências:

    pip install -r requirements.txt

  3. Execute o Servidor:

    python geocoding_server.py

  4. Configure o Cliente MCP: Adicione à configuração do seu cliente MCP (como Claude Desktop):

    {
  "mcpServers": {
    "geocoding": {
      "command": "python",
      "args": ["/full/path/to/mcp-geocoding-server-python/geocoding_server.py"]
    }
  }
}