terraform-cloud-mcp

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. # Terraform Cloud MCP Development Guide ## Subtree Discovery System This project uses Claude Code's automatic subtree discovery for context-aware guidance. Component-specific CLAUDE.md files are automatically loaded when working in their directories: - **docs/** - Documentation standards and templates - **terraform_cloud_mcp/tools/** - MCP tools implementation patterns - **terraform_cloud_mcp/models/** - Pydantic models and validation - **terraform_cloud_mcp/utils/** - Utility functions and error handling - **terraform_cloud_mcp/api/** - API client patterns ## Working Directory Guidance ### When Working on Tool Implementation - **Directory**: `terraform_cloud_mcp/tools/` - **Context**: Automatic loading of tools-specific patterns - **Focus**: MCP function signatures, error handling, API integration ### When Working on Data Models - **Directory**: `terraform_cloud_mcp/models/` - **Context**: Automatic loading of model validation patterns - **Focus**: Pydantic models, validation rules, type definitions ### When Working on Utilities - **Directory**: `terraform_cloud_mcp/utils/` - **Context**: Automatic loading of utility function patterns - **Focus**: Error handling, API helpers, common operations ### When Working on API Client - **Directory**: `terraform_cloud_mcp/api/` - **Context**: Automatic loading of API client patterns - **Focus**: HTTP client, authentication, request handling ### When Working on Documentation - **Directory**: `docs/` - **Context**: Automatic loading of documentation standards - **Focus**: Templates, formatting, structure requirements ## Development Commands ### Quality Checks - **Format**: `ruff format .` - **Lint**: `ruff check .` - **Type Check**: `mypy .` - **Test**: `pytest` ### Build Commands - **Install**: `uv pip install -e .` - **Dev Install**: `uv pip install -e .[dev]` - **Requirements**: `uv pip compile requirements.in` ## Core Principles ### Decision-Making Process 1. **Use component guidance**: Let subtree discovery load relevant context 2. **Apply documented patterns**: Follow loaded component standards 3. **Avoid code inference**: Use documented criteria only 4. **Validate against patterns**: Check implementation against guidance ### Task Complexity Assessment - **Simple** (< 2 hours): Direct implementation, minimal planning - **Medium** (2-8 hours): Use TodoWrite for 3-5 tasks - **Complex** (> 8 hours): Use subagents (2-6) with comprehensive TodoWrite planning ## Documentation Standards ### Required Documentation Updates For any new implementation, always update: - **TASKS.md**: Move features from planned to completed status - **docs/API_REFERENCES.md**: Mark corresponding API sections as implemented - **docs/DEVELOPMENT.md**: Add new patterns if applicable - **docs/CONTRIBUTING.md**: Update contribution guidelines if new patterns introduced ### Implementation Standards - **Use utility functions**: `create_api_payload()`, `query_params()`, `@handle_api_errors` - **Apply response filtering**: Automatic filtering system in `utils/filters.py` handles all GET requests - **Follow component patterns**: Apply standards from automatically loaded component CLAUDE.md files - **Run quality checks**: Format, lint, type check before completion - **Update relevant documentation**: Maintain consistency across project ### Response Filtering Implementation Context This MCP server implements audit-safe response filtering with the following constraints: - **Primary use case**: Audit and compliance scenarios requiring complete data integrity - **Filtering approach**: Conservative token optimization (5-15% reduction) to preserve audit trails - **Critical preservation requirements**: - User accountability data (`created-at`, `updated-at`, `version-id`) - Security configuration (permissions, auth policies) - Change tracking (status timestamps, source information) - Operational context (status, timing, progress indicators) - **Decision principle**: Preserve fields when audit impact is uncertain - **Implementation location**: `utils/filters.py` with configurations in `configs/filter_configs.py` ## Task Management ### TodoWrite Usage Use TodoWrite for tasks with: - Multiple distinct steps (> 2) - Multiple file changes - Cross-component coordination - Medium to complex scope ### Progress Standards - Mark todos `in_progress` before starting - Mark `completed` immediately after finishing - Update status in real-time - Provide concise progress updates for major phases ## Memory System Maintenance ### Periodic Review Schedule - **Monthly**: Review component CLAUDE.md files for outdated patterns - **After major features**: Update decision matrices and workflow patterns - **When adding new domains**: Verify subtree discovery optimization - **Quality check failures**: Review and update development standards ### Maintenance Triggers - **New implementation patterns**: Update relevant component guidance - **API changes**: Review model and tool implementation standards - **Development workflow changes**: Update quality check commands - **Documentation structure changes**: Update docs/ guidance - **Filter configuration changes**: When new API fields appear, assess preservation vs. optimization trade-offs - **Compliance requirement changes**: Review filter configurations if audit use cases evolve ### Memory Optimization Indicators - **High context usage**: Review for redundant information across files - **Frequent cross-referencing**: Consider consolidating related guidance - **Outdated patterns**: Remove deprecated implementation approaches - **Missing decision criteria**: Add decision matrices for common scenarios