refactor(mcp): use Pydantic models for structured tool outputs and add AI-powered auto-fix generation (#1603)

* refactor(mcp): use Pydantic models for structured tool outputs

Replace dict-based return values with Pydantic models across all MCP tools
to enable structured output with automatic JSON schema generation and
type validation.

Changes:
- Add models.py with Pydantic models for all tool return types
  (DiagnosticResult, FormatContentResult, LintAndFormatResult, etc.)
- Update all tool implementations to return Pydantic models instead of dicts
- Fix SeveritySummary field name from 'I' to 'INFO' with alias for
  backward compatibility (resolves ruff E741 ambiguous variable name)

Bug fixes discovered during integration testing:
- Fix dict-style access (result["key"]) to attribute access (result.key)
  in registration.py context messages - Pydantic models use attributes
- Remove 'from __future__ import annotations' from registration.py as it
  breaks Pydantic's runtime type evaluation for Annotated fields

Testing:
- Update existing unit tests for new Pydantic model structure

* feat(mcp): add LLM-assisted auto-fix tools for Robot Framework issues

Add two new MCP tools that enable AI-powered fixing of linting issues:

- get_fix_context: Provides rich context for LLM fix generation including
  the problematic code snippet, issue details with fix_suggestion and
  rule_docs, and structured guidance for generating fixes

- apply_fix: Applies line-based replacements and validates fixes by
  re-linting. Detects if a fix made things worse and supports both
  preview mode and file overwriting

New Pydantic models:
- CodeSnippet, IssueForFix, GetFixContextResult
- FixReplacement, ApplyFixResult

This enables the workflow: get_fix_context → LLM generates fix → apply_fix
with validation, supporting use cases like fixing naming conventions,
adding missing documentation, and restructuring code.

* fix: update docs and remove duplicate line

* fix: replace lambda with attrgetter and replace list comprehension with a simpler approach

Author: mikeleppane

docs/integrations/ai.md

@@ -343,6 +343,75 @@ Explain a specific issue at a given line with surrounding context. More detailed
 - `related_issues`: Issues on nearby lines (within 2 lines)
 - `context`: Surrounding code with line numbers
 
+#### LLM-Assisted Fixing Tools
+
+These tools enable AI assistants to generate and apply intelligent fixes for Robot Framework code issues.
+
+##### get_fix_context
+
+Get rich context for LLM-assisted fixing of Robot Framework code issues. This tool provides everything an AI needs to generate a proper fix: the problematic code snippet, detailed issue information, rule documentation, and structured guidance.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `content` | string | Robot Framework source code (use this OR `file_path`) |
+| `file_path` | string | Absolute path to .robot or .resource file (use this OR `content`) |
+| `filename` | string | Virtual filename when using content (default: "stdin.robot") |
+| `line` | int | Specific line to get context for (None = all issues) |
+| `rule_ids` | list[str] | Filter to specific rule IDs (e.g., `["LEN01", "NAME02"]`) |
+| `context_lines` | int | Lines of context before and after target (default: 5) |
+
+**Returns:** Dictionary with:
+
+- `file_path`: File path if from file
+- `full_content`: The complete file/content being analyzed
+- `target_snippet`: The problematic code section with `content`, `start_line`, `end_line`
+- `issues`: List of issues with `rule_id`, `name`, `message`, `severity`, `line`, `column`, `fix_suggestion`, `rule_docs`
+- `llm_guidance`: Structured guidance for the LLM on how to generate the fix
+
+##### apply_fix
+
+Apply an LLM-generated fix to Robot Framework code. Takes a line-based replacement and applies it to the code, then validates the fix by re-linting to ensure issues were actually resolved.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `content` | string | Original Robot Framework source (use this OR `file_path`) |
+| `file_path` | string | Path to the file to fix (use this OR `content`) |
+| `filename` | string | Virtual filename when using content (default: "stdin.robot") |
+| `replacement` | object | The line-based replacement with `start_line`, `end_line`, `new_content` (required) |
+| `overwrite` | bool | Write the fix to disk - only with `file_path` (default: false) |
+| `validate` | bool | Re-lint to validate the fix resolved issues (default: true) |
+| `select` | list[str] | Rule IDs to check in validation |
+| `ignore` | list[str] | Rule IDs to ignore in validation |
+
+**Returns:** Dictionary with:
+
+- `success`: Whether the fix was successfully applied and validated
+- `file_path`: File path if written to disk
+- `written`: Whether the fix was written to disk
+- `new_content`: The content after applying the fix
+- `diff`: Unified diff showing the changes
+- `issues_before`: Number of issues before the fix
+- `issues_after`: Number of issues after the fix
+- `issues_fixed`: Number of issues resolved by the fix
+- `remaining_issues`: Issues that remain after the fix (limited to first 10)
+- `validation_error`: Error message if fix validation failed
+
+**Example workflow:**
+
+```python
+# 1. Get context for an issue at line 42
+context = get_fix_context(file_path="/path/to/test.robot", line=42)
+
+# 2. AI uses context.llm_guidance and context.issues to generate a fix
+
+# 3. Apply the fix
+apply_fix(
+    file_path="/path/to/test.robot",
+    replacement={"start_line": 42, "end_line": 43, "new_content": "    Log    Fixed code"},
+    overwrite=True
+)
+```
+
 #### Discovery Tools
 
 ##### list_rules
@@ -567,6 +636,15 @@ Once the MCP server is configured, you can use natural language to interact with
 >
 > "What issues in this code can be auto-fixed vs need manual changes?"
 
+#### LLM-Assisted Fixing
+
+**Get context and apply AI-generated fixes:**
+> "Get the context for the issue at line 42 in my test file so you can fix it"
+>
+> "Fix the naming issue at line 15 - get the context first, then generate and apply the fix"
+>
+> "Help me fix all the issues in this file one by one"
+
 #### Configuring Rules
 
 **Custom thresholds:**

pyproject.toml

@@ -186,10 +186,14 @@ extend-exclude = [
     "PERF401",  # list comprehension vs for loop is style choice
     "TRY300",   # return in try block is fine here
     "C401",     # set comprehension vs generator is style choice
+    "TC001",    # Pydantic models need runtime import for schema generation
     "TC002",    # Context must be runtime import for FastMCP dependency injection
     "D417",     # ctx param is injected by FastMCP, not user-facing
     "PLR0915",  # register_tools has many statements by design
 ]
+"src/robocop/mcp/tools/registration.py" = [
+    "FA102",    # can't use future annotations - breaks Pydantic runtime evaluation
+]
 # temporary because of the rules description
 "src/robocop/linter/rules/*" = ["D205"]
 # bug in typer where | None can't be used