fizzy-mcp: Instructions file for Codex

@AGENTS.local.md

AGENTS.md

Project Overview

fizzy-mcp is an MCP (Model Context Protocol) server for the Fizzy project management tool. It exposes 40+ tools for managing boards, cards, columns, steps, comments, reactions, tags, and notifications.

Tech Stack

• Language: TypeScript 5.7 (ES2022, ESM modules)
• Runtime: Node.js 22+ (standard), Cloudflare Workers (production)
• MCP SDK: @modelcontextprotocol/sdk
• Validation: Zod
• Testing: Vitest
• Build: tsc (compile), tsx (dev)

Architecture

src/
├── index.ts              # CLI entry point, transport selection
├── server.ts             # MCP server setup, tool registration
├── client/
│   ├── fizzy-client.ts   # HTTP client with retry, ETag caching
│   └── types.ts          # API request/response interfaces
├── tools/
│   ├── definitions.ts    # Tool metadata (name, description, annotations)
│   ├── schemas.ts        # Zod input schemas
│   └── handlers.ts       # Tool execution logic
├── transports/
│   ├── stdio.ts          # IDE integrations (Cursor, VS Code)
│   ├── sse.ts            # Server-Sent Events (multi-user)
│   └── http.ts           # Streamable HTTP (multi-user)
├── utils/
│   ├── errors.ts         # Typed error classes (FizzyAPIError, etc.)
│   ├── logger.ts         # Structured stderr logging
│   ├── security.ts       # CORS, auth, localhost binding
│   ├── session-manager.ts
│   ├── etag-cache.ts
│   ├── card-resolver.ts  # card_id → card_number
│   ├── attachments.ts    # Upload input resolution + ActionText markup
│   ├── file-source.ts    # Injected local-file capability (stdio only)
│   ├── md5.ts            # Runtime-independent MD5 (upload checksums)
│   └── base64.ts         # btoa/atob helpers that also work on Workers
└── cloudflare/           # Workers deployment (Durable Objects)

Key flow

1. server.ts registers tools from tools/definitions.ts
2. Each tool call dispatches through executeToolHandler() in tools/handlers.ts
3. Handlers call FizzyClient methods which make HTTP requests to the Fizzy API
4. Responses are formatted as MCP text content