recreation-mcp-server: Instructions file for Codex

AI Agent Guidelines for Recreation MCP Server

This document provides guidance for AI coding assistants working on this project. It captures the conventions, patterns, and practices established during development.

Project Philosophy

Clean, Simple, Fast - The guiding principle for all code:

• Clean: Easy to read and understand
• Simple: Minimal complexity, straightforward solutions
• Fast: Performance matters, but clarity comes first

Architecture Patterns

Project Structure

recreation-mcp-server/
├── cmd/server/          # Application entry point
├── internal/            # Private application code
│   ├── api/            # External API clients (NPS, Recreation.gov, Weather)
│   ├── cache/          # Caching layer with TTL/LRU
│   ├── config/         # Configuration management
│   ├── mcp/            # MCP protocol implementation
│   └── models/         # Shared data types
├── pkg/util/           # Public utility packages
├── testdata/           # Test fixtures (JSON responses)
├── docs/               # GitHub Pages website
└── scripts/            # Helper scripts for testing

Code Organization Principles

1. Internal vs Public: All application logic lives in internal/. Only truly reusable utilities go in pkg/.

2. API Clients: Each external API gets its own file in internal/api/:

   • nps.go - National Park Service
   • recreation.go - Recreation.gov
   • weather.go - OpenWeatherMap

3. MCP Layer: Separated into two files:

   • server.go - Server setup and tool registration
   • handlers.go - Tool implementations and schemas

4. Test Files: Co-located with source files using _test.go suffix

Code Conventions

Error Handling

• Always return errors, don't panic
• Wrap errors with context: fmt.Errorf("failed to fetch parks: %w", err)
• Log errors before returning them to users
• Use MCP-compliant error responses with error codes

Naming Conventions

• Files: Snake case (e.g., http_client.go)
• Packages: Single word, lowercase (e.g., cache, config)
• Structs: PascalCase (e.g., SearchParksInput)
• Functions: camelCase for private, PascalCase for exported
• Constants: PascalCase (e.g., DefaultCacheTTL)