fizzy-mcp AGENTS.md

@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 18+ (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
└── 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

Tool system

Tools are defined across three files that must stay in sync:

• definitions.ts — tool name, title, description, schema reference, annotations
• schemas.ts — Zod schema for input validation (field names here are what MCP clients send)
• handlers.ts — flat Record<toolName, handler> mapping; maps MCP args to client method calls