# PICO-8 MCP Server

An MCP server for working with PICO-8 game carts, built on top of [shrinko8](https://github.com/thisismypassport/shrinko8).

## Features

### Code Analysis Tools
- **count_tokens** - Count tokens, characters, and compressed size
- **analyze_cart** - List functions, globals, and code metrics
- **validate_cart** - Validate cart with token limits and linting
- **search_code** - Search for code patterns across carts
- **compare_carts** - Compare two cart versions with diff

### Cart Manipulation
- **read_cart** - Read cart sections (code, gfx, map, sfx, music)
- **minify_cart** - Minify carts to reduce token count
- **list_carts** - List all carts in a directory with metadata

### Documentation Resources
- **add_documentation** - Fetch and save PICO-8 documentation from URLs
- **Resources** - Saved documentation is available as MCP resources (e.g., `pico8://docs/api`)

## Installation

### Prerequisites

- Python 3.8+
- [uv](https://github.com/astral-sh/uv) package manager

### Setup

1. Clone the repository:
```bash
git clone https://github.com/YOUR_USERNAME/pico8-mcp-server.git
cd pico8-mcp-server
```

2. Initialize the shrinko8 submodule:
```bash
git submodule update --init --recursive
```

3. Install dependencies:
```bash
uv sync
```

### For Claude Code (VSCode)

Add the server using the Claude CLI:

```bash
cd /Users/ebonura/Desktop/repos/pico8-mcp-server
claude mcp add pico8 --scope project -- uv run server.py
```

Or manually create a `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "pico8": {
      "command": "uv",
      "args": ["run", "/Users/ebonura/Desktop/repos/pico8-mcp-server/server.py"]
    }
  }
}
```

### For Claude Desktop

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

```json
{
  "mcpServers": {
    "pico8": {
      "command": "uv",
      "args": ["--directory", "/Users/ebonura/Desktop/repos/pico8-mcp-server", "run", "server.py"]
    }
  }
}
```

## Usage Examples

Once configured, you can ask Claude:

- "Count the tokens in my horizon-glide cart"
- "Analyze the code structure of v0.16.p8"
- "Search for all uses of 'terrain' in my carts"
- "Compare v0.15.p8 and v0.16.p8"
- "List all carts in the horizon-glide directory"
- "Validate my cart and show any errors"

### Adding Documentation

You can fetch and save PICO-8 documentation:

```
"Fetch the PICO-8 API reference from https://pico-8.fandom.com/wiki/APIReference
and save it as 'api'"
```

Once saved, Claude can automatically reference the documentation when helping with PICO-8 code.

## License

MIT (inherits from shrinko8)