# Code Generator MCP Template Server

An MCP (Model Context Protocol) server built using Python's `FastMCP` framework. It exposes 4 precise, structured code-generation tools backed by prompt templates to generate production-grade, parsed code using local or cloud-based OpenAI-compatible APIs (such as `llama-server`, `qwen-coder`, `coder-expert`, or OpenAI's API).

## 🚀 Features

Exposes 4 key MCP tools that use structured templates to instruct the model to think step-by-step and produce clean, executable code:

1. **`generate_standard_function`** (Template 1): Generates a standalone function based on constraints, edge cases, test cases, and external integration notes.
2. **`generate_codebase_context`** (Template 2): Generates a function that respects and integrates with existing codebase structures and dependencies.
3. **`generate_bugfix_refactor`** (Template 3): Focuses on refactoring or repairing current buggy implementations based on problem descriptions and test expectations.
4. **`generate_multi_function_module`** (Template 4): Generates a multi-function module, validating that there are no circular dependencies or undefined functions.

### ⚙️ Parser & Guardrails
- **Markdown Stripper**: Automatic code parsing (`extract_code_from_response`) strips any markdown code blocks (` ```python `) generated by instruct models, guaranteeing only raw executable code is returned.
- **Reasoning Fallback**: Correctly handles DeepSeek-style reasoning models or `llama-server` configurations where all output is redirected into the `reasoning_content` field instead of `content`.
- **Max Tokens Guardrail**: Enforces a `2048` token limit per request to prevent local model reasoning loops and timeouts.

---

## 🛠️ Configuration

Configure the server using command-line arguments or environment variables:

| Setting | CLI Argument | Environment Variable | Default Value | Description |
|---|---|---|---|---|
| **API URL** | `--api-url` | `CODE_GEN_API_URL` / `OPENAI_BASE_URL` | `https://api.openai.com/v1` | OpenAI-compatible endpoint |
| **Model** | `--model` | `CODE_GEN_MODEL` / `OPENAI_MODEL` | `gpt-4o` | The model name to target |
| **API Key** | `--api-key` | `CODE_GEN_API_KEY` / `OPENAI_API_KEY` | *(Empty)* | API token (optional for local endpoints) |

> [!WARNING]
> For security reasons, do not pass `--api-key` via command-line arguments as it will be visible in plain text in the host process table. **Use the environment variables instead.**

---

## 📦 Installation & Setup

You can install and configure the server either automatically using the installation script or manually via Python.

### Option 1: Quick Installation Script (Recommended)

The project includes an `install.sh` script that automatically builds a standalone executable using PyInstaller, installs it to `~/.local/bin/code-generator-mcp`, and configures your target AI coding agent.

1. Run the script and specify your target agent:
   ```bash
   chmod +x install.sh
   ./install.sh <agent_type>
   ```
    Supported `<agent_type>` values:
    - `claude-desktop` (Claude Desktop global configuration)
    - `claude-code` (Claude CLI global configuration at `~/.claude.json`)
    - `cursor` (Cursor editor global config at `~/.cursor/mcp.json`)
    - `codex` (Codex agent global config at `~/.codex/config.toml`)
    - `github-copilot` (VS Code workspace-specific config at `.vscode/mcp.json`)
    - `windsurf` (Windsurf IDE configuration at `~/.codeium/windsurf/mcp_config.json`)
    - `zed` (Zed editor config at `~/.config/zed/settings.json`)
    - `agy` (Antigravity settings config at `~/.gemini/settings.json`)

2. (Optional) Customize the endpoint and model in the agent's configuration file or environment variables after installation.

---

### Option 2: Manual Setup via Python

#### Prerequisites
- Python 3.10+
- Dependencies installed in virtual environment:
  ```bash
  python -m venv .venv
  source .venv/bin/activate
  pip install -r requirements.txt
  ```

#### Running Locally
To run the MCP server directly over standard input/output (stdio):
```bash
python src/code_generator_mcp/server.py --api-url http://localhost:8008/v1 --model coder-expert
```

#### Testing during development
You can use `mcp dev` (from MCP CLI) to test the server interactively in a development UI:
```bash
mcp dev src/code_generator_mcp/server.py -- --api-url http://localhost:8008/v1 --model coder-expert
```

---

## 🔌 Integration Setup

To manually use this server with your favorite MCP client (like Claude Desktop or Cursor):

### Claude Desktop Configuration
Open your Claude Desktop config file (usually located at `~/.config/Claude/claude_desktop_config.json` on Linux/macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows) and add the following entry:

```json
{
  "mcpServers": {
    "code-generator-mcp": {
      "command": "/path/to/project/.venv/bin/python",
      "args": [
        "/path/to/project/src/code_generator_mcp/server.py"
      ],
      "env": {
        "CODE_GEN_API_URL": "http://localhost:8008/v1",
        "CODE_GEN_MODEL": "coder-expert"
      }
    }
  }
}
```

---

## 🧪 Testing

The codebase includes a fully-featured unit and integration test suite using `pytest`. Run tests with:
```bash
.venv/bin/pytest
```