teamretro-mcp-server copilot-instructions.md

Copilot Coding Agent Instructions

Project Overview

This is a TypeScript MCP (Model Context Protocol) server that integrates with the TeamRetro API. It acts as a bridge between AI clients and TeamRetro's platform, providing 20+ tools for managing teams, users, actions, retrospectives, agreements, health checks, health models, and reports.

The server communicates over stdio using the @modelcontextprotocol/sdk.

Tech Stack

• Runtime: Node.js ≥ 18
• Language: TypeScript (ES2020 target, ES2022 modules)
• Package Manager: pnpm (v9, lockfile version 9.0)
• Schema Validation: Zod
• Build: tsc + tsc-alias (for path alias resolution)

Build & Run Commands

pnpm install          # Install dependencies (also runs build via "prepare" script)
pnpm run build        # Clean build: rimraf dist && tsc && tsc-alias
pnpm run watch        # Dev mode with auto-rebuild
pnpm run start        # Run the server: node dist/index.js
pnpm run inspector    # Build and launch MCP inspector (requires .env file)
pnpm run clean        # Remove dist/

Build Errors to Watch For

• The pnpm install step triggers prepare which runs pnpm run build. If pnpm is not installed globally, install it first: npm install -g pnpm@9.
• The TEAMRETRO_API_KEY environment variable is required at runtime. Without it, the server will throw a TeamRetroError with code CONFIG_ERROR on startup. For build-only tasks, this is not needed.

Testing

There is no test infrastructure in this project. The test script in package.json is: echo "Error: no test specified" && exit 0. Do not add test frameworks unless explicitly asked to.

Project Structure

src/
├── index.ts                  # Entry point: TeamRetroMCPServer class, stdio transport
├── config.ts                 # Environment variable loading via env-var
├── tools.ts                  # Tool registry: aggregates all feature tools, creates schemas & handlers
├── features/                 # Feature modules (one per API domain)
│   ├── actions/              # Each feature has: service.ts + tools.ts
│   ├── agreements/
│   ├── health-checks/
│   ├── health-models/
│   ├── reports/
│   ├── retrospectives/
│   ├── team-members/
│   ├── teams/
│   └── users/
├── schemas/                  # Zod schemas for API entities
│   ├── generic.ts            # Shared schemas: pagination, id, name, email, date, tags
│   ├── Action.ts
│   ├── Agreement.ts
│   ├── Base.ts
│   ├── HealthCheck.ts
│   ├── HealthModel.ts
│   ├── Retrospective.ts
│   ├── Team.ts
│   └── User.ts
├── services/
│   └── TeamRetro.service.ts  # Abstract HTTP client base class (get/post/patch/put/delete)
├── types/                    # TypeScript type declarations
│   ├── api.d.ts              # Global API response types (ListApiResponse, SingleApiResponse)
│   ├── config.d.ts           # Global config types (TeamRetroConfig, LogConfig)
│   ├── errors.d.ts           # TeamRetroError class
│   └── tool.ts               # Tool/Tools types
└── utils/
    ├── error.ts              # ErrorMCP class and formatClientError
    ├── formatter.ts          # Markdown table/item formatting for "simple" response mode
    ├── logger.ts             # File-based logger singleton
    ├── tools.ts              # createToolResponse, toolErrorHandlers
    └── url.ts                # URL search params helper