# AI Code Editing - MCP Tool Specification

This document outlines the specification for tools within the AI Code Editing module that are intended to be integrated with the Model Context Protocol (MCP). These tools leverage Large Language Models (LLMs) to perform code generation and modification tasks.

## General Considerations

- **LLM Dependency**: These tools rely on external LLM providers (e.g., OpenAI, Anthropic). API keys and configurations for these services must be set up in the environment.
- **Prompt Engineering**: The quality of results will heavily depend on the clarity and specificity of the prompts provided to the tools.
- **Determinism**: LLM outputs can be non-deterministic. Multiple calls with the exact same input may yield slightly different results.

---

## Tool: `generate_code_snippet`

### 1. Tool Purpose and Description

Generates a snippet of code in a specified programming language based on a natural language prompt and optional existing code context.

### 2. Invocation Name

`generate_code_snippet`

### 3. Input Schema (Parameters)

| Parameter Name   | Type     | Required | Description                                                                                                | Example Value                                                                         |
| :--------------- | :------- | :------- | :--------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ |
| `prompt`         | `string` | Yes      | Natural language description of the code to be generated.                                                  | `"Create a Python function that calculates the factorial of a number recursively."`       |
| `language`       | `string` | Yes      | The target programming language for the generated code (e.g., "python", "javascript", "java").         | `"python"`                                                                            |
| `context_code`   | `string` | No       | Optional: Existing code snippet or broader context to guide the generation (e.g., surrounding code, class definition). | `"class MathUtils:
    # Function should be part of this class"`                    |
| `llm_provider`   | `string` | No       | Specify the LLM provider (e.g., "openai", "anthropic"). If omitted, a default provider will be used.       | `"openai"`                                                                            |
| `model_name`     | `string` | No       | Specify a particular model from the provider (e.g., "gpt-4", "claude-2"). If omitted, a default model is used. | `"gpt-3.5-turbo"`                                                                     |

### 4. Output Schema (Return Value)

| Field Name       | Type     | Description                                                                 | Example Value                                                                    |
| :--------------- | :------- | :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------- |
| `status`         | `string` | Generation status: "success", "failure".                                    | `"success"`                                                                      |
| `generated_code` | `string` | The code snippet generated by the LLM. Null if status is "failure".         | `"def factorial(n):
    if n == 0:
        return 1
    else:
        return n * factorial(n-1)"` |
| `error_message`  | `string` | Error description if `status` is "failure" (e.g., API error, content filtering). | `"LLM API request failed."`                                                      |

### 5. Error Handling

- Errors from the LLM provider (API issues, rate limits, content policies) will result in a "failure" status and an `error_message`.
- Invalid input parameters (e.g., unsupported `language`) can also lead to failure.

### 6. Idempotency

- **Idempotent**: Generally No.
- **Explanation**: LLMs are often non-deterministic by default to encourage creativity. Even with the same prompt, subsequent calls might produce slightly varied code, unless specific sampling parameters (like temperature=0) are enforced by the underlying implementation and supported by the LLM.

### 7. Usage Examples (for MCP context)

```json
{
  "tool_name": "generate_code_snippet",
  "arguments": {
    "prompt": "Write a Python function to find the largest element in a list.",
    "language": "python"
  }
}
```

### 8. Security Considerations

- **Prompt Injection**: Maliciously crafted prompts could potentially try to exploit the LLM or the system interpreting its output. Input sanitization or careful handling of prompts is important, though challenging.
- **Generated Code Quality**: Code generated by LLMs may contain bugs, inefficiencies, or security vulnerabilities. It should always be reviewed before use in production systems.
- **Data Privacy**: Prompts and context code sent to external LLM providers might be logged or used for training by the provider, depending on their terms of service. Avoid sending sensitive or proprietary information unless the provider and module configuration ensure appropriate data handling.

---

## Tool: `refactor_code_snippet`

### 1. Tool Purpose and Description

Takes an existing code snippet and a refactoring instruction (e.g., improve efficiency, add comments, convert to a different style) and returns the refactored code using an LLM.

### 2. Invocation Name

`refactor_code_snippet`

### 3. Input Schema (Parameters)

| Parameter Name            | Type     | Required | Description                                                                                                   | Example Value                                                                      |
| :------------------------ | :------- | :------- | :------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------- |
| `code_snippet`            | `string` | Yes      | The existing piece of code to be refactored.                                                                  | `"def f(n): return 1 if n==0 else n*f(n-1)"`                                        |
| `refactoring_instruction` | `string` | Yes      | Natural language instruction describing the desired refactoring (e.g., "add type hints", "make it iterative"). | `"Add type hints and a docstring to this Python factorial function."`                |
| `language`                | `string` | Yes      | The programming language of the `code_snippet` (e.g., "python", "javascript").                            | `"python"`                                                                         |
| `llm_provider`            | `string` | No       | Specify the LLM provider. Defaults to a configured provider.                                                  | `"anthropic"`                                                                      |
| `model_name`              | `string` | No       | Specify a particular model. Defaults to a model suitable for refactoring.                                   | `"claude-instant-1"`                                                               |

### 4. Output Schema (Return Value)

| Field Name        | Type     | Description                                                                                       | Example Value                                                                                                     |
| :---------------- | :------- | :------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------- |
| `status`          | `string` | Refactoring status: "success", "failure", "no_change_needed".                                     | `"success"`                                                                                                       |
| `refactored_code` | `string` | The refactored code snippet. May be same as input if no change was deemed necessary or possible.    | `"def factorial(n: int) -> int:
    \"\"\"Calculates factorial.\"\"\"
    return 1 if n == 0 else n * factorial(n - 1)"` |
| `explanation`     | `string` | Optional: An explanation from the LLM about the changes made or why no changes were made.         | `"Added type hints for n and the return value, and included a standard docstring."`                             |
| `error_message`   | `string` | Error description if `status` is "failure".                                                       | `"LLM could not understand the refactoring instruction for the given code."`                                  |

### 5. Error Handling

- Similar to `generate_code_snippet`, failures can occur due to LLM API issues or if the LLM cannot perform the requested refactoring.

### 6. Idempotency

- **Idempotent**: Generally No.
- **Explanation**: Similar to code generation, LLM-based refactoring can be non-deterministic. The exact output might vary on subsequent identical calls.

### 7. Usage Examples (for MCP context)

```json
{
  "tool_name": "refactor_code_snippet",
  "arguments": {
    "code_snippet": "for i in range(len(my_list)):
  print(my_list[i])",
    "refactoring_instruction": "Convert this Python loop to a more Pythonic way of iterating through a list.",
    "language": "python"
  }
}
```

### 8. Security Considerations

- **Instruction Injection**: Malicious `refactoring_instruction` could attempt to guide the LLM to produce harmful code.
- **Output Review**: Refactored code must be reviewed as it can introduce errors or vulnerabilities, just like newly generated code.
- **Data Privacy**: The `code_snippet` and `refactoring_instruction` are sent to an external LLM provider. Consider data privacy implications.

--- 
## Navigation Links

- **Parent**: [Project Overview](../README.md)
- **Module Index**: [All Agents](../../AGENTS.md)
- **Documentation**: [Reference Guides](../../../../docs/README.md)
- **Home**: [Root README](../../../README.md)
