ai-coding-gym-mcp 0.3.0
MCP server for AI Coding Gym - fetch and submit coding challenges
Requires Python: >=3.10
Keywords: mcp, model-context-protocol, coding-gym, ai

# AI Coding Gym - MCP Server

Local MCP server for interacting with the AI Coding Gym platform. Provides tools to fetch coding problems and submit solutions.

## Features

- **`/fetch`**: Fetch a coding problem and clone the repository to your local machine
- **`/submit`**: Submit your solution by committing and pushing changes

## Quick Start

### Installation

**Option 1: Install from PyPI**
```bash
pip install ai-coding-gym-mcp
```

**Option 2: Install from GitHub**
```bash
pip install git+https://github.com/yourusername/ai-coding-gym-mcp.git
```

**Option 3: Install from source**
```bash
git clone https://github.com/yourusername/ai-coding-gym-mcp.git
cd ai-coding-gym-mcp
pip install -e .
```

### Configure Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):

```json
{
  "mcpServers": {
    "ai-coding-gym": {
      "command": "ai-coding-gym-mcp"
    }
  }
}
```

### Configure VS Code (Copilot with MCP)

Add to your VS Code settings (`.vscode/settings.json` or User Settings):

```json
{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "text": "Use AI Coding Gym MCP tools for problem solving"
    }
  ],
  "mcp.servers": {
    "ai-coding-gym": {
      "command": "python",
      "args": ["-m", "server"],
      "cwd": "/path/to/ai-coding-gym-mcp"
    }
  }
}
```

Or if installed via pip, use the executable directly:

```json
{
  "mcp.servers": {
    "ai-coding-gym": {
      "command": "ai-coding-gym-mcp"
    }
  }
}
```

## Usage

### Running the MCP Server

The server uses stdio for communication with MCP clients:

```bash
python server.py
```

Or configure it in your MCP client settings (e.g., Claude Desktop).

### Tool: `/configure`

Configure the MCP server with your user ID. This generates an SSH key pair and registers it with the server.

**Parameters:**
- `user_id` (required): Your user ID for authentication
- `workspace_dir` (required): Default workspace directory for cloning repositories

**Example:**
```json
{
  "user_id": "user_123",
  "workspace_dir": "./workspace"
}
```

**What it does:**
1. Generates an SSH key pair locally (stored in `~/.mcp-keys/`)
2. Sends the public key to the server
3. Receives your repository name
4. Stores configuration for future use

### Tool: `/fetch`

Fetches a problem from the backend and clones the repository locally.
This tool is single-purpose: it does not install dependencies, run tests,
or perform any other follow-up actions after fetching.

**Parameters:**
- `problem_id` (required): Problem identifier (e.g., `"django__django-10097"`)
- `user_id` (optional): Your user ID (uses configured value if not provided)
- `workspace_dir` (optional): Local workspace directory (defaults to configured `workspace_dir`)

**Example:**
```json
{
  "problem_id": "django__django-10097"
}
```

**What it does:**
1. Uses your SSH key from `/configure` to access the repository
2. Clones only the specific problem branch (shallow clone)
3. Sets up the workspace at `workspace/{problem_id}/`
4. Does not run installs, tests, or any other post-fetch steps

### Tool: `/submit`

Submits your solution by committing changes and pushing to the remote repository.

**Parameters:**
- `problem_id` (required): Problem identifier
- `user_id` (optional): Your user ID (uses configured value if not provided)
- `commit_message` (required): Custom commit message
- `workspace_dir` (optional): Local workspace directory where the repo was cloned (defaults to configured `workspace_dir`)
- `force_push` (optional): Force push the branch (use with caution; default: `false`)

**Example:**
```json
{
  "problem_id": "django__django-10097",
  "commit_message": "Fixed the authentication bug",
  "workspace_dir": "./workspace",
  "force_push": false
}
```

**What it does:**
1. Stages all changes in the working directory (`git add -A`)
2. Commits with the provided message
3. Pushes to the remote branch using deployment key (optionally force-pushes)
4. Notifies the backend server about the submission

### Tool: `/reset`

Resets a problem repository back to the original setup commit.

**Parameters:**
- `problem_id` (required): Problem identifier
- `user_id` (optional): Your user ID (uses configured value if not provided)

**Example:**
```json
{
  "problem_id": "django__django-10097"
}
```

**What it does:**
1. Finds the original setup commit with a message that starts with `Setup SWE-bench instance:`
2. Resets the repo to that commit (`git reset --hard`)
3. Removes untracked files (`git clean -fd`)

## Backend API Endpoints

The MCP server connects to the hardcoded AI Coding Gym server and uses the following endpoints:

### POST `/api/configure`

**Request:**
```json
{
  "user_id": "user_123",
  "public_key": "ssh-rsa AAAAB3..."
}
```

**Response:**
```json
{
  "repo_name": "user_123-swebench",
  "repo_url": "git@github.com:AICodingGym/submission-user_123.git"
}
```

### POST `/api/submit`

**Request:**
```json
{
  "problem_id": "django__django-10097",
  "user_id": "user_123",
  "commit_hash": "abc123def456...",
  "branch": "django__django-10097-user_123",
  "commit_message": "Fixed the authentication bug",
  "timestamp": "2026-02-03T10:30:00"
}
```

**Response:**
```json
{
  "status": "success",
  "message": "Submission received"
}
```

## Security

- User SSH keys are stored in `~/.mcp-keys/` with 600 permissions
- Keys are generated locally and public key is shared with the server
- SSH host key checking is disabled for convenience (consider enabling in production)
- Configuration is cached in memory during the MCP server session

## Troubleshooting

**"No credentials found for problem_id"**
- Run `/configure` first to set up your credentials
- Then run `/fetch` to download the problem

**"Git clone/push failed"**
- Check network connectivity
- Verify deployment key is valid
- Ensure SSH agent isn't interfering

**"Directory already exists"**
- Remove the existing directory or use a different workspace location


## Development

The server uses:
- **mcp**: Model Context Protocol SDK
- **requests**: HTTP client for backend API calls
- **subprocess**: Git command execution with SSH key management

### Local Development

```bash
# Clone the repository
git clone https://github.com/yourusername/ai-coding-gym-mcp.git
cd ai-coding-gym-mcp

# Install in development mode
pip install -e .

# Run tests (if available)
pytest

# Test the server locally
python server.py
```

## Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## License

MIT