Metadata-Version: 2.4
Name: ai-coding-gym-mcp
Version: 0.1.0
Summary: MCP server for AI Coding Gym - fetch and submit coding challenges
Home-page: https://github.com/yourusername/ai-coding-gym-mcp
Author: AICodingGym Team
Author-email: Your Name <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/ai-coding-gym-mcp
Project-URL: Issues, https://github.com/yourusername/ai-coding-gym-mcp/issues
Keywords: mcp,model-context-protocol,coding-gym,ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=0.9.0
Requires-Dist: requests>=2.31.0
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# 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": "python",
      "args": ["-m", "server"],
      "env": {
        "AI_CODING_GYM_SERVER": "https://your-server-url.com"
      }
    }
  }
}
```

See [INSTALLATION.md](INSTALLATION.md) for detailed setup instructions for Claude Desktop and VS Code.

## 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: `/fetch`

Fetches a problem from the backend and clones the repository locally.

**Parameters:**
- `problem_id` (required): Problem identifier (e.g., `"django__django-10097"`)
- `user_id` (required): Your user ID for authentication
- `server_url` (optional): Backend server URL (default: `"https://api.example.com"`)
- `workspace_dir` (optional): Local workspace directory (default: `"./workspace"`)

**Example:**
```json
{
  "problem_id": "django__django-10097",
  "user_id": "user_123",
  "server_url": "https://ai-coding-gym.example.com"
}
```

**What it does:**
1. Calls backend API to get repository URL and deployment key
2. Clones the repository to `workspace/{problem_id}/`
3. Checks out the problem-specific branch
4. Saves the problem statement to `PROBLEM_STATEMENT.md`

### Tool: `/submit`

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

**Parameters:**
- `problem_id` (required): Problem identifier
- `user_id` (required): Your user ID for authentication
- `server_url` (optional): Backend server URL (default: `"https://api.example.com"`)
- `commit_message` (optional): Custom commit message

**Example:**
```json
{
  "problem_id": "django__django-10097",
  "user_id": "user_123",
  "commit_message": "Fixed the authentication bug"
}
```

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

## Backend API Endpoints

The MCP server expects the following backend API endpoints:

### POST `/api/fetch-problem`

**Request:**
```json
{
  "problem_id": "django__django-10097",
  "user_id": "user_123"
}
```

**Response:**
```json
{
  "repo_url": "git@github.com:org/repo.git",
  "branch": "django__django-10097-user_123",
  "deploy_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----",
  "problem_statement": "# Problem Description\n\n..."
}
```

### POST `/api/submit`

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

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

## Security

- Deployment keys are stored in `~/.mcp-keys/` with 600 permissions
- Keys are scoped per problem and managed by the backend
- SSH host key checking is disabled for convenience (consider enabling in production)
- Credentials are cached in memory during the MCP server session

## Configuration

Default server URL is `https://api.example.com`. You can override it by passing `server_url` parameter to each tool call, or set it via environment variable:

```bash
export AI_CODING_GYM_SERVER="https://your-server.com"
```

## Troubleshooting

**"No credentials found for problem_id"**
- Run `/fetch` first to download the problem and credentials

**"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

## Publishing

See [PUBLISHING.md](PUBLISHING.md) for instructions on:
- Publishing to PyPI
- Publishing to GitHub
- Version management
- Release workflow

## 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
