PetPals KittyClaw MCP Server

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

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:

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):

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)

npm run build
node dist/index.js

With custom config:

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

Connecting via OpenAI Secure MCP Tunnel

1. Initialize

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

2. Doctor Check

./scripts/openai-tunnel-doctor.sh

3. Run Tunnel

./scripts/openai-tunnel-run.sh

4. Emergency Stop

./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 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 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