osm-edit-mcp / rules

---
description:
globs:
alwaysApply: true
---
# OSM Edit MCP Server - Project Structure Guide

## Core Project Files

### Main Server Implementation
- **[src/osm_edit_mcp/server.py](mdc:src/osm_edit_mcp/server.py)** - Primary MCP server with 31 tools for OSM operations
- **[main.py](mdc:main.py)** - Server entry point and startup script

### Configuration Files
- **[.env](mdc:.env)** - Environment configuration (never commit with real credentials)
- **[.env.example](mdc:.env.example)** - Configuration template with all available options
- **[pyproject.toml](mdc:pyproject.toml)** - Python package configuration and dependencies

### Testing Framework
- **[test_comprehensive.py](mdc:test_comprehensive.py)** - Complete test suite for all 31 MCP tools
- **[TESTING_CHECKLIST.md](mdc:TESTING_CHECKLIST.md)** - Systematic manual testing guide
- **[TEST_RESULTS_SUMMARY.md](mdc:TEST_RESULTS_SUMMARY.md)** - Analysis of test results and debugging guide

### Documentation
- **[README.md](mdc:README.md)** - Complete setup, configuration, and usage guide
- **[POLISH_SUMMARY.md](mdc:POLISH_SUMMARY.md)** - Summary of all enhancements made

## Architecture Overview

### Server Structure
The [server.py](mdc:src/osm_edit_mcp/server.py) contains:
- `OSMConfig` class with comprehensive configuration management
- 31 MCP tools organized in categories:
  - **Read Operations**: get_osm_node, get_osm_way, get_osm_relation, etc.
  - **Write Operations**: create_osm_node, update_osm_node, delete_osm_node, etc.
  - **Search Operations**: find_nearby_amenities, search_osm_elements, etc.
  - **Natural Language**: parse_natural_language_osm_request, create_place_from_description, etc.
  - **Utility Operations**: validate_coordinates, validate_osm_data, etc.

### Configuration System
Uses Pydantic BaseSettings for type-safe configuration with:
- Dev/prod API switching via `OSM_USE_DEV_API`
- Configurable logging levels
- Safety and rate limiting settings
- OAuth credentials management

### Testing Architecture
- **Automated Testing**: [test_comprehensive.py](mdc:test_comprehensive.py) runs all tools systematically
- **Manual Testing**: [TESTING_CHECKLIST.md](mdc:TESTING_CHECKLIST.md) provides step-by-step validation
- **Results Analysis**: Generated reports help identify and debug issues

## Development Workflow

1. **Configuration**: Create [.env](mdc:.env) with `install -m 600 .env.example .env` and customize it
2. **Testing**: Run [test_comprehensive.py](mdc:test_comprehensive.py) for validation
3. **Development**: Use development API (`OSM_USE_DEV_API=true`) for safe testing
4. **Documentation**: Update [README.md](mdc:README.md) for any new features