# packages/mcp/

MCP (Model Context Protocol) server for OpenPets integration.

## Responsibility

Implements an MCP server exposing OpenPets functionality to AI agents via the Model Context Protocol. Provides tools for checking status, setting reactions, and displaying messages on the desktop pet.

## Design

**MCP Server Setup** (`server.ts`):
- `McpServer` from `@modelcontextprotocol/sdk`
- Three registered tools: `openpets_status`, `openpets_react`, `openpets_say`
- Tool annotations for read-only/idempotent hints
- Instructions for AI agents (safety guidelines)

**Tool Implementations** (`tools.ts`):
- Zod schemas for input validation (`saySchema`, `reactSchema`)
- Lease-aware operations (acquires lease on startup, heartbeat every 5s)
- Throttling integration for speech/reactions
- Error sanitization (hides IPC paths, tokens)

**Lifecycle Management** (`index.ts`):
- Startup lease acquisition (async, non-blocking)
- Heartbeat timer (5s interval, unref'd)
- Graceful shutdown on SIGINT/SIGTERM (release lease, close server)
- Stdio transport via `StdioServerTransport`

**Argument Parsing** (`args.ts`):
- `--pet <id>` for targeted pet selection
- `--help`, `--version` flags
- Pet ID validation (regex: `^[a-z0-9][a-z0-9_-]{0,63}$`)

**Build Integration** (`ensure-executable.ts`):
- Post-build chmod 0o755 for Unix binaries

## Flow

```
main()
    ↓
parseMcpArgs() → { petId?, help, version }
    ↓
createToolContext() → { client, configuredPetId }
    ↓
acquireStartupLease() → lease.lease set on success
    ↓
createOpenPetsMcpServer() → Register 3 tools
    ↓
server.connect(StdioServerTransport)
    ↓
[Heartbeat] Every 5s: client.heartbeatLease()
    ↓
[Shutdown] SIGINT/SIGTERM → releaseLease() → server.close()
```

## Integration Points

**Dependencies**:
- `@open-pets/client` - IPC communication
- `@modelcontextprotocol/sdk` - MCP protocol implementation
- `zod` - Schema validation

**CLI Integration**: Spawned by `@open-pets/cli` via `runMcp()` which forwards stdio and signals.

**Exports**:
- Binary: `open-pets-mcp` (stdio MCP server)
- No programmatic exports (MCP server is standalone)