talos-mcp-server AGENTS.md

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:
  • All mutating tools (e.g., reboot, upgrade) MUST explicitly set is_mutation = True in their class definition.
  • The TalosClient and server.py enforce strict read-only mode validation based on this flag.
• 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.

🔌 API Design (MCP)

• Tools Definition:
  • Tools must have clear, descriptive names (e.g., talos_cluster_health not health).
  • Descriptions must be detailed enough for an LLM to understand when and how to use the tool.
  • Input schemas must be strict and validated.
• Resources:
  • Use URI schemes consistent with the domain (e.g., talos://<node>/<resource>).
  • Implement read_resource with proper error handling for invalid URIs.
• Prompts:
  • Prompt arguments should be self-explanatory.
  • Prompt templates should be flexible but guide the LLM towards a specific goal.