talos-mcp-server: Instructions file for Codex

Agent Guidelines & Rules

This document defines the coding standards, architectural patterns, and best practices for the Talos MCP Server project. All usage of AI agents should strictly adhere to these guidelines.

🐍 Python Development

• Type Hinting: All functions and methods must have type hints. Use typing module (include List, Dict, Optional, Any, etc. or standard collections in Python 3.9+).
  • Example: def get_node_version(ip: str) -> Dict[str, Any]:
• Docstrings: Use Google-style docstrings for all modules, classes, and public functions.
• Pydantic: Use Pydantic models for data validation and schema definition, especially for MCP tools.
• AsyncIO: Use async/await for all I/O bound operations. Use anyio for compatibility where appropriate.
• Error Handling: Use try/except blocks judiciously. Create custom exception classes for domain-specific errors.
• Loguru: Use loguru (imported as logger) for all logging. Do NOT use Python's standard logging module.
• Read-Only Safety:
  • core/policy.py defines each canonical operation's execution class and exact native argv forms.
  • TalosClient and the tool registry enforce profile and allowlist access from that policy before every subprocess. is_mutation is a descriptive legacy flag, not an authorization gate.
• Black & Ruff: Ensure code is formatted with Black and linted with Ruff.

☸️ Helm & Kubernetes

• Chart Structure: Follow standard Helm chart structure (Chart.yaml, values.yaml, templates/).
• Values: Use camelCase for values in values.yaml. Document all values with comments.
• Templates:
  • Use {{ .Values.key | default "default" }} pattern.
  • Avoid hardcoding namespaces or resource names; use helper templates (e.g., _helpers.tpl) for naming.
• Resources: Define resources (requests/limits) for all containers.
• Labels: Ensure standard Kubernetes labels (app.kubernetes.io/name, etc.) are applied to all resources.