general

Core Principles

Maximize Library Usage

• Always leverage the official @googlemaps/google-maps-services-js library
• Use library types as the foundation, avoiding custom type definitions where possible
• Let the library handle validation and API interaction details

Type Management Strategy

• Use TypeScript utility types (Omit, Pick, &) to derive types from the library
• Override only what's necessary for MCP/LLM simplicity:
  • Enums → strings (e.g., Language enum → string)
  • Complex unions → single format (e.g., LatLng union → string only)
  • Optional fields that need different handling
• Never create parallel type hierarchies - derive from the source

Direct API Responses

• Return Google API responses directly without unnecessary wrappers
• Don't add metadata that can become stale (versions, timestamps)
• Trust the official API response structure

Tool Design for LLMs

• Split multi-mode operations into separate, single-purpose tools
• Keep parameter schemas flat and predictable
• Use descriptive tool names that clearly indicate their purpose
• Provide comprehensive descriptions and examples in tool schemas

Avoid Maintenance Burdens

• No hardcoded version strings that need manual updates
• No constants that duplicate library information
• Let TypeScript's type system enforce correctness
• Do not maintain backwards compatibility

Development Practices

• Type Safety First: Let TypeScript catch errors at compile time
• Validate at Boundaries: Validate MCP inputs before passing to library
• Fail Fast: Return errors immediately, don't suppress them
• Keep It Simple: If the library provides it, use it directly
• Document Intent: Comments should explain "why", not "what". Do not write comments for self documenting code.

Testing Approach

• Focus on parameter validation and transformation logic
• Mock the Google Maps client for unit tests
• Use real API calls only for integration tests
• Test error handling paths explicitly