mapcoder

# MapCoder Plugin for Claude Code

A multi-agent code generation plugin that replicates the human programming cycle through four specialized agents: Retrieval, Planning, Coding, and Debugging. Port of [MapCoder: Multi-Agent Code Generation for Competitive Problem Solving](https://github.com/Md-Ashraful-Pramanik/MapCoder)

## Overview

<p align="center">
• 🐱 <a href="https://github.com/Md-Ashraful-Pramanik/MapCoder" target="_blank">Code</a> 
• 📃 <a href="https://arxiv.org/abs/2405.11403" target="_blank">Paper</a>
• 🌐 <a href="https://md-ashraful-pramanik.github.io/mapcoder.github.io/" target="_blank">Website</a>
</p>

MapCoder implements a systematic approach to solving coding problems:

![](https://github.com/Md-Ashraful-Pramanik/MapCoder/blob/master/images/MapCoder-Overview.png)

## Quick Start

### Installation
```
/plugin marketplace add NewJerseyStyle/Claude-plugins-marketplace
/plugin install mapcoder@code-agent-ports
```

### Basic Usage

```bash
# Solve a coding problem (defaults to Python)
/mapcoder implement binary search

# Specify a language
/mapcoder --lang javascript implement a debounce function

# Use sandbox for safer execution
/mapcoder --sandbox implement file operations

# Read problem from file
/mapcoder problem.txt
```

## Available Skills

| Skill | Description |
|-------|-------------|
| `/mapcoder` | Full pipeline: retrieve → plan → code → debug |
| `/mapcoder-retrieve` | Generate similar problems from knowledge |
| `/mapcoder-plan` | Create algorithmic plans |
| `/mapcoder-code` | Implement code from plans |
| `/mapcoder-debug` | Fix failing code |

## Language Support

Default language is Python. Supported languages:

| Language | Flag | Example |
|----------|------|---------|
| Python | `--lang python` | `/mapcoder --lang python two sum` |
| JavaScript | `--lang javascript` | `/mapcoder --lang javascript two sum` |
| TypeScript | `--lang typescript` | `/mapcoder --lang typescript two sum` |
| Rust | `--lang rust` | `/mapcoder --lang rust two sum` |
| Go | `--lang go` | `/mapcoder --lang go two sum` |
| Java | `--lang java` | `/mapcoder --lang java two sum` |
| C++ | `--lang cpp` | `/mapcoder --lang cpp two sum` |

## RAG Integration (Optional)

MapCoder can integrate with external knowledge bases for enhanced retrieval for best performance. Two options are supported:

### Option A: crawl4ai-rag (Full-featured)

Best for teams with existing infrastructure who want powerful web crawling and RAG capabilities.

**Requirements:**
- Docker
- Supabase with pgvector extension
- OpenAI API key

**Setup:**
1. Follow the setup guide at: [https://github.com/coleam00/mcp-crawl4ai-rag](https://github.com/coleam00/mcp-crawl4ai-rag)
2. Start the MCP server: `docker-compose up -d`
3. Edit `.mcp.json` in this plugin and set `"disabled": false` for `crawl4ai-rag`

### Option B: mcp-rag-server (Lightweight)

Best for local development with minimal setup.

**Setup:**
1. Install nodejs: [Tutorial](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
2. Install RAG server by terminal command: `npm install -g mcp-rag-server` (Follow the setup guide at: [https://github.com/kwanLeeFrmVi/mcp-rag-server#installation](https://github.com/kwanLeeFrmVi/mcp-rag-server#installation))
3. Edit `.mcp.json` in this plugin and set `"disabled": false` for `rag-server`

## Sandbox Execution (Recommended)

For safer code execution, especially when working with file operations or untrusted problems, use the sandbox feature.

### Setup

1. Install Docker: https://docs.docker.com/get-docker/

2. Build the sandbox image:
   ```bash
   cd mapcoder-plugin
   docker build -t mapcoder-sandbox -f Dockerfile.sandbox .
   ```

3. Verify it works:
   ```bash
   ./scripts/sandbox-runner.sh python -c "print('Hello, Sandbox!')"
   ```

### Usage

Add `--sandbox` flag to any `/mapcoder` command:

```bash
/mapcoder --sandbox implement file deletion utility
```

### Configuration

Environment variables for sandbox:

| Variable | Default | Description |
|----------|---------|-------------|
| `MAPCODER_SANDBOX_IMAGE` | `mapcoder-sandbox` | Docker image name |
| `MAPCODER_TIMEOUT` | `30` | Execution timeout (seconds) |
| `MAPCODER_MEMORY` | `256m` | Memory limit |
| `MAPCODER_CPU` | `1` | CPU limit |

## Safety Warnings

### Direct Execution (Default)

When running without `--sandbox`, code executes directly on your system.

**Recommendations:**
- Back up important files before running
- Review generated code before allowing execution
- Do not use on production systems
- Avoid problems involving file system operations without sandbox

### Code Review

The plugin validates syntax before execution but cannot guarantee code safety. Always review:
- File operations (read, write, delete)
- Network operations
- System commands
- Any code that modifies state

## Configuration

### Hook Configuration

Edit `hooks/hooks.json` to customize validation:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python scripts/validate-code.py \"$TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}
```

## Troubleshooting

### Plugin not loading

```bash
# Check plugin structure
ls -la .claude-plugin/
# Should show plugin.json

# Verify JSON is valid
python -c "import json; json.load(open('.claude-plugin/plugin.json'))"
```

### Sandbox not working

```bash
# Check Docker is running
docker info

# Check image exists
docker images | grep mapcoder-sandbox

# Rebuild if needed
docker build -t mapcoder-sandbox -f Dockerfile.sandbox .
```

### Tests timing out

Increase timeout:
```bash
export MAPCODER_TIMEOUT=60
/mapcoder --sandbox "solve complex problem"
```

## License

MIT License - See [LICENSE](LICENSE.md) file for details.

## Acknowledgments

Based on the MapCoder paper: "[MapCoder: Multi-Agent Code Generation for Competitive Problem Solving](https://arxiv.org/abs/2405.11403)"

```
@article{islam2024mapcoder,
  title={MapCoder: Multi-Agent Code Generation for Competitive Problem Solving},
  author={Islam, Md Ashraful and Ali, Mohammed Eunus and Parvez, Md Rizwan},
  journal={arXiv preprint arXiv:2405.11403},
  year={2024}
}
```