mcp-development

MCP Development Patterns and Best Practices

Model Context Protocol (MCP) Implementation

Server Architecture

The MCP server in src/osm_edit_mcp/server.py follows FastMCP patterns:

from mcp.server.fastmcp import FastMCP
app = FastMCP("osm-edit-mcp")

@app.tool()
async def tool_name(param: str) -> str:
    """Tool description for AI assistant."""
    # Implementation

Tool Design Principles

1. Clear Tool Descriptions

• Write descriptions from AI assistant's perspective
• Include parameter explanations and expected outputs
• Mention any prerequisites (authentication, changesets, etc.)

2. Type Safety

• Use Pydantic models for complex parameters
• Implement proper type hints for all parameters
• Validate input data before processing

3. Error Handling Pattern

try:
    # OSM API operation
    result = await osm_client.operation()
    return {"success": True, "data": result}
except OSMAPIError as e:
    return {"success": False, "error": str(e)}

Authentication Flow

OAuth 2.0 Implementation

Based on .env.example configuration:

1. Initial Setup: User configures OAuth credentials
2. Token Request: Server requests authorization URL
3. User Authorization: User approves application
4. Token Exchange: Server exchanges code for access token
5. Token Storage: Securely store in keyring
6. Token Refresh: Automatic refresh when expired

Authentication State Management

• Check token validity before each API operation
• Implement graceful degradation for unauthenticated requests
• Provide clear error messages for authentication failures

OSM API Integration

Base URL Configuration

# Development (safe for testing)
OSM_API_BASE_URL = "https://api06.dev.openstreetmap.org"

# Production (requires extreme caution)
OSM_API_BASE_URL = "https://api.openstreetmap.org"

Request Patterns

1. Read Operations: Safe, no confirmation needed
   • Get node/way/relation by ID
   • Search within bounding box
   • Get changeset information