# Paperclip AI Adapter for Antigravity CLI

MCP (Model Context Protocol) server adapter that integrates [Paperclip AI](https://paperclip.ing) agent orchestration platform with Antigravity CLI.

Paperclip AI is an open-source control plane for managing teams of AI agents as a virtual company — with org charts, Kanban boards, budgets, goals, and approval gates.

## Features

- **Agent Management**: Create, list, update, wake, pause, and terminate AI agents
- **Issue Tracking**: Full Kanban board (Backlog → Todo → In Progress → Done) with atomic checkout
- **Projects**: Organize work into strategic projects
- **Goals**: Hierarchical objectives (Company → Project → Agent → Task)
- **Approvals**: Governance gates for human-in-the-loop decisions
- **Budget Control**: Set spending limits per agent/department
- **Escape Hatch**: Raw API request tool for any endpoint

## Installation

```bash
npm install
npm run build
```

## Configuration

| Variable | Required | Default | Description |
|:---------|:---------|:--------|:------------|
| `PAPERCLIP_API_KEY` | Yes | - | Your Paperclip API key |
| `PAPERCLIP_API_URL` | No | `https://localhost:3100` | API base URL |
| `PAPERCLIP_ORG_ID` | No | - | Your organization ID |

## Usage with Antigravity CLI

Add to your `.agents/mcp_config.json`:

```json
{
  "mcpServers": {
    "paperclip": {
      "command": "node",
      "args": ["<path-to>/paperclip-ai-adapter/dist/index.js"],
      "env": {
        "PAPERCLIP_API_KEY": "your-api-key",
        "PAPERCLIP_API_URL": "http://localhost:3100"
      }
    }
  }
}
```

Or for global usage, add to `~/.gemini/config/mcp_config.json`.

## Available MCP Tools (28 tools)

### Agents (8 tools)
| Tool | Description |
|:-----|:------------|
| `paperclip_list_agents` | List all agents with filters |
| `paperclip_create_agent` | Create/hire a new agent |
| `paperclip_get_agent` | Get agent details |
| `paperclip_update_agent` | Update agent config |
| `paperclip_delete_agent` | Terminate an agent |
| `paperclip_wake_agent` | Wake agent to start working |
| `paperclip_pause_agent` | Pause an agent |
| `paperclip_set_agent_budget` | Set agent budget limit |

### Issues (10 tools)
| Tool | Description |
|:-----|:------------|
| `paperclip_list_issues` | List issues with filters |
| `paperclip_create_issue` | Create a new issue |
| `paperclip_get_issue` | Get issue details |
| `paperclip_update_issue` | Update an issue |
| `paperclip_delete_issue` | Delete an issue |
| `paperclip_checkout_issue` | Atomically claim an issue |
| `paperclip_release_issue` | Release a claimed issue |
| `paperclip_list_comments` | List issue comments |
| `paperclip_add_comment` | Comment on an issue |
| `paperclip_get_issue_cost` | Get issue cost summary |

### Projects (3 tools)
| Tool | Description |
|:-----|:------------|
| `paperclip_list_projects` | List all projects |
| `paperclip_create_project` | Create a project |
| `paperclip_get_project` | Get project details |

### Goals (3 tools)
| Tool | Description |
|:-----|:------------|
| `paperclip_list_goals` | List goals with filters |
| `paperclip_create_goal` | Create a goal |
| `paperclip_get_goal` | Get goal details |

### Approvals (3 tools)
| Tool | Description |
|:-----|:------------|
| `paperclip_list_approvals` | List approval requests |
| `paperclip_create_approval` | Create approval request |
| `paperclip_approval_decision` | Approve or reject |

### Company (3 tools)
| Tool | Description |
|:-----|:------------|
| `paperclip_get_company` | Get company info |
| `paperclip_whoami` | Get current identity |
| `paperclip_api_request` | Raw API escape hatch |

## Development

```bash
npm run dev      # Watch mode with tsx
npm run build    # Build TypeScript
npm run test     # Run tests
npm run lint     # Lint
```

## Self-hosting Paperclip

```bash
npx paperclipai onboard --yes
```

Default URL: `http://localhost:3100`

## License

MIT