Skip to main content
Glama

terraform-cloud-mcp

CLAUDE.md7.58 kB
# CLAUDE.md for utils/ This file provides guidance about shared utility functions for consistent operations across the Terraform Cloud MCP implementation. ## Context Activation This guidance activates when: - Working in `terraform_cloud_mcp/utils/` directory - Creating/editing utility functions (*.py) - Implementing shared functionality (decorators, helpers, formatters) - Adding error handling or payload creation utilities **Companion directories**: tools/ (for usage), models/ (for integration), api/ (for requests) ## Utility Architecture The utils directory provides common functionality to maintain consistency and reduce code duplication: ### Core Utilities - **decorators.py**: `handle_api_errors` decorator for consistent error handling - **env.py**: Centralized environment variable management (tokens, feature flags) - **payload.py**: JSON:API payload creation and relationship management - **request.py**: Query parameter transformation for API requests - **filters.py**: Response filtering system for token optimization ## Implementation Standards ### Error Handling Pattern - **@handle_api_errors decorator**: Apply to all API functions for consistent error formatting - **Error format**: `{"error": "message"}` (never expose sensitive data) - **Success preservation**: Decorator preserves successful responses without modification ### Environment Management - **get_tfc_token()**: Centralized TFC_TOKEN access (never use direct os.getenv) - **should_enable_delete_tools()**: Safety control for destructive operations - **Centralized access**: All environment variables managed through utils/env.py ### Payload Creation - **create_api_payload()**: JSON:API compliant payload creation from Pydantic models - **add_relationship()**: Standardized relationship management for JSON:API - **query_params()**: Pydantic model to API parameter transformation for list/filter operations ### Query Parameter Transformation The `query_params()` function transforms Pydantic model fields to API parameters using consistent naming conventions: - **Pagination**: `page_number` → `page[number]`, `page_size` → `page[size]` - **Filters**: `filter_name` → `filter[name]`, `filter_permissions_update` → `filter[permissions][update]` - **Search**: `search_term` → `search[term]`, `search_user` → `search[user]` - **Query**: `query_email` → `q[email]`, `query_name` → `q[name]` - **Direct params**: `q`, `search`, `sort` mapped directly Usage pattern for all list operations: See `../tools/workspaces.py:list_workspaces` for the standard query parameter transformation approach. ### Parameter Model Integration Functions use direct parameters with optional params objects. See `../tools/variables.py:create_workspace_variable` for the pattern of combining direct and optional parameters with request models. ## Usage Standards ### Core Requirements - **Error handling**: Always use `@handle_api_errors` for API functions (never duplicate logic) - **Environment access**: Use utility functions instead of direct `os.getenv()` calls - **Payload creation**: Use `create_api_payload()` and `add_relationship()` for JSON:API operations - **Parameter handling**: Use `query_params()` for all list/filter operations - **Response filtering**: Review filter configurations when implementing new tools - check for new fields to filter ### Validated Audit-Safe Filtering System **✅ FULLY TESTED AND VERIFIED**: All 7 tool categories validated for 100% audit compliance: - **User accountability**: `created-at`, `updated-at`, `version-id` always preserved - **Security configuration**: All permission and auth fields preserved - **Change tracking**: Status timestamps, source tracking, version data preserved - **Operational context**: Status, timing, progress data for monitoring tools - **Decision context**: Cost data, assessments, diagnostics for analysis tools - **Conservative 5-15% token reduction**: Balanced optimization vs. complete audit capability - **Audit-first principle**: When in doubt, preserve the field rather than filter it ### Development Guidelines - **New utilities**: Place in appropriate module, document with type hints and examples - **Consistency**: Maintain established patterns, consistent return types and error formats - **Reusability**: Write utilities to be domain-agnostic and broadly applicable ## Error Handling Decision Matrix ### When to Use Decorator Only - Standard CRUD operations with predictable API responses (200, 201, 204, 4xx, 5xx) - Most list and get operations without complex parameter validation - Tools that don't require business logic validation before API calls ### When to Add Custom Logic (WITH Decorator) - Parameter validation requiring specific error messages beyond Pydantic - API responses needing special status code interpretation - Multi-step operations with intermediate error handling needs - File operations requiring size/format validation ### Error Response Standards - **Format**: `{"error": "descriptive message"}` (never expose sensitive data) - **Success**: 200/201 return raw API response; 204 returns `{"status": "success", "status_code": 204}` - **Consistency**: Always preserve @handle_api_errors decorator even with custom logic ## Development Standards ### Quality Checks - **Format**: `ruff format .` - **Lint**: `ruff check .` - **Type Check**: `mypy .` - **Test**: `pytest` ### Utility-Specific Requirements - All functions must include proper error handling and consistent response format - Apply security guidelines for sensitive data redaction - Follow established patterns for error decoration and type safety - Test with comprehensive quality check sequence after utility changes ### Code Style Requirements - Type hints required for all parameters and return values - Apply async patterns where appropriate - Follow security practices for sensitive data handling - Maintain consistent naming conventions ## Integration Guidelines ### Tool Integration When utilities are used in tools: - Apply `@handle_api_errors` decorator to all API functions - Use `create_api_payload()` for JSON:API compliant requests - Apply `query_params()` for all list/filter operations - Use centralized environment variable access ### Model Integration When utilities work with models: - Use `create_api_payload()` with Pydantic model instances - Apply `query_params()` for transforming model data to API parameters - Handle model validation errors appropriately - Ensure proper type safety throughout ### API Client Integration When utilities work with API client: - Use utilities for consistent request formatting - Apply error handling decorators - Use centralized token management - Ensure proper response handling ## Implementation Workflow ### New Utility Development Process 1. **Define function signature**: Include proper type hints 2. **Implement core logic**: Follow established patterns 3. **Add error handling**: Apply consistent response formats 4. **Test thoroughly**: Cover success, error, and edge cases 5. **Document function**: Include usage examples and cross-references 6. **Update status**: Implementation tracking ### Quality Validation Checklist For each utility implementation: - [ ] Function includes proper error handling and consistent response format - [ ] Type hints provided for all parameters and return values - [ ] Documentation includes usage examples and patterns - [ ] Security guidelines followed for sensitive data handling - [ ] Quality checks passed: format, lint, type check - [ ] Tests cover all scenarios: success, error, edge cases

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/severity1/terraform-cloud-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server