core-development

You are an expert in Python backend development for the Cycloid MCP Server using FastMCP 3.0.

Key Principles

• Use standalone @tool() and @resource() decorators (not class-based MCPMixin)
• Inject CLIMixin via Depends(get_cli) from src.dependencies
• Use ToolError from fastmcp.exceptions for tool-level errors
• Leverage centralized type definitions from src.types
• Apply proper import organization (stdlib → third-party → local)
• JSON-only output (no table formatting)
• Follow FastMCP logging with get_logger from fastmcp.utilities.logging

Core Development Guidelines

1. Architecture Patterns

   • Components are plain async functions in src/components/ — auto-discovered by FileSystemProvider
   • No base classes, no MCPMixin, no ComponentRegistry
   • CLI injection via Depends(get_cli) — never instantiate CLIMixin directly in tools
   • Use execute_cli_command with auto_parse parameter for CLI calls
   • Use process_cli_response for standardized response processing

2. Type Safety & Imports

   • Import common types from src.types (JSONDict, JSONList, CliFlags, OptionalString, etc.)
   • Import order: stdlib → third-party → local (src.)
   • FastMCP Depends import needs # type: ignore[reportAttributeAccessIssue]
   • Depends(get_cli) defaults need # type: ignore[reportCallInDefaultInitializer]

3. Error Handling

   • Use ToolError from fastmcp.exceptions for validation errors, not-found, etc.
   • Use CycloidCLIError from src.exceptions for CLI execution failures
   • Log with get_logger(__name__) from fastmcp.utilities.logging

4. CLI Integration

   • Use execute_cli_command with auto_parse=True for parsed JSON responses
   • Use execute_cli_command with auto_parse=False for raw CLIResult
   • Use process_cli_response for consistent response handling
   • Never cache CLI API responses (dynamic data)
   • Output format is always JSON (hardcoded --output json)

5. Testing

   • Use pytest + pytest-asyncio with FastMCP's Client
   • Register functions via server.add_tool() / server.add_resource()
   • Mock CLIMixin with @patch and AsyncMock
   • Tool errors raise ToolError exceptions in client

6. Code Quality

   • Pyright strict mode (pyrightconfig.json)
   • black (88 char), isort (black profile), flake8 (100 char max)
   • Python 3.12+ (CI runs 3.13)

Dependencies

• Python 3.12+
• FastMCP 3.0+
• pytest, pytest-asyncio
• pyright, flake8, black, isort