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