# PetPals KittyClaw MCP Server

MCP Server for managing KittyClaw task board — a safe control plane for AI agents without direct repository, shell, or git access.

## What This MCP Server Does

This MCP server allows ChatGPT to manage project workflows through KittyClaw (a kanban task board), while **never** gaining direct access to:
- Shell commands
- Git operations (commit, push, clone)
- Repository file editing
- Arbitrary HTTP requests

### Architecture

```
ChatGPT (via OpenAI MCP Tunnel)
  ↓ MCP stdio
PetPals KittyClaw MCP Server
  ↓ REST API (localhost:5230)
KittyClaw Task Board
  ↓ tickets / comments / status / evidence
Agents (Codex / Cursor / Jules / etc.)
  ↓ branch / worktree / validation output
PetPals Repository
  ↓ completion report / evidence
KittyClaw Review → Verified → Human Approval → Done
```

ChatGPT acts as **architect / planner / reviewer**.  
KittyClaw is the **control plane + evidence hub**.  
Agents are **executors**.  
Danil (you) is the **owner / final approver**.

## Installation

```bash
git clone https://github.com/Danissimode/petpals-kittyclaw-mcp.git
cd petpals-kittyclaw-mcp
npm install
npm run build
```

## Configuration

Copy the example policy and edit it:

```bash
mkdir -p ~/.config/petpals-kittyclaw-mcp
cp config/policy.example.yaml ~/.config/petpals-kittyclaw-mcp/policy.yaml
# Edit allowed_projects, labels, transitions as needed
```

Set environment variables (optional):

```bash
export KITTYCLAW_BASE_URL=http://localhost:5230
export KITTYCLAW_AUTHOR=chatgpt
export PETPALS_KITTYCLAW_POLICY=~/.config/petpals-kittyclaw-mcp/policy.yaml
export PETPALS_KITTYCLAW_AUDIT_LOG=~/.local/share/petpals-kittyclaw-mcp/audit.jsonl
```

## Running Locally (stdio)

```bash
npm run build
node dist/index.js
```

With custom config:

```bash
node dist/index.js --config ~/.config/petpals-kittyclaw-mcp/policy.yaml
```

## Connecting via OpenAI Secure MCP Tunnel

### 1. Initialize

```bash
export CONTROL_PLANE_API_KEY="sk-..."
export CONTROL_PLANE_TUNNEL_ID="tun_..."
./scripts/openai-tunnel-init-stdio.sh
```

### 2. Doctor Check

```bash
./scripts/openai-tunnel-doctor.sh
```

### 3. Run Tunnel

```bash
./scripts/openai-tunnel-run.sh
```

### 4. Emergency Stop

```bash
./scripts/emergency-stop.sh
```

## MCP Tools Exposed

### Read-Only Board Tools

| Tool | Description |
|------|-------------|
| `kitty.projects.list` | List allowed projects |
| `kitty.project.get` | Get project details |
| `kitty.board.summary` | Compact board snapshot |
| `kitty.columns.list` | List columns |
| `kitty.members.list` | List members |
| `kitty.labels.list` | List labels |
| `kitty.tickets.list` | List tickets (compact) |
| `kitty.ticket.get` | Get ticket details + comments |
| `kitty.comments.list` | List comments |
| `kitty.mentions.get` | Get mentions for handle |
| `kitty.blockers.list` | List blocked tickets |

### Mutating Ticket Tools

| Tool | Description |
|------|-------------|
| `kitty.ticket.create` | Create ticket with author |
| `kitty.ticket.add_comment` | Add comment with author |
| `kitty.ticket.update_description` | Update description |
| `kitty.ticket.assign_member` | Assign member |
| `kitty.ticket.set_priority` | Set priority (Idea/NiceToHave/Required/Critical) |
| `kitty.ticket.add_label` | Add label |
| `kitty.ticket.create_subtask` | Create subtask |
| `kitty.ticket.move_status` | Move status (with policy enforcement) |

### PetPals Governance Tools

| Tool | Description |
|------|-------------|
| `petpals.create_task_contract` | Attach structured Task Contract to ticket |
| `petpals.attach_acceptance_criteria` | Attach acceptance criteria |
| `petpals.attach_validation_commands` | Attach validation commands (text only) |
| `petpals.request_agent_completion_report` | Request structured completion report |
| `petpals.review_completion_report` | Review evidence and return verdict |
| `petpals.mark_ready_for_human_review` | Mark for human review |
| `petpals.reject_completion` | Reject completion with reason |
| `petpals.mark_verified` | Mark as verified (never Done) |
| `audit.recent` | Read recent audit events |

## Denied Tools (Explicitly Blocked)

These tools **do not exist** in this MCP server:

- `run_shell_command`
- `git_commit`, `git_push`
- `delete_ticket`, `delete_project`
- `move_to_done_without_review`
- `execute_agent_directly`
- `edit_repo_files`
- `apply_patch`
- `generic_http_request`
- `raw_openapi_call`

## Status Model

```
Backlog → Ready → InProgress → Review → ChangesRequested
                          ↓              ↓
                        Blocked      Verified → Done (owner only)
                                     ↓
                                  Rejected (owner only)
```

- **ChatGPT** can move: Backlog↔Ready, InProgress→Blocked/Review, Review→ChangesRequested/Verified, ChangesRequested→InProgress
- **Agent** can move: Ready→InProgress, InProgress→Review/Blocked
- **Owner** can move: Verified→Done, Any→Rejected

## Security Model

See [docs/security-model.md](docs/security-model.md) for full details.

Key principles:
- No shell execution
- No git operations
- No direct repo file access
- No generic HTTP proxy
- Comments are untrusted data (prompt injection protection)
- Owner-only Done transition
- Audit logging of all tool calls
- Secret redaction in outputs and logs

## Workflow

See [docs/petpals-workflow.md](docs/petpals-workflow.md) for the full PetPals evidence workflow.

## Tech Stack

- Node.js 20+
- TypeScript 5.7
- `@modelcontextprotocol/sdk` (stdio transport)
- `zod` (input validation)
- `undici` / native fetch (HTTP client)
- `yaml` (policy config)
- `vitest` (testing)

## License

MIT