mcp-server-flipt: Instructions file for Claude Code

AGENTS.md

This file provides guidance to AI agents when working with code in this repository.

Project Overview

A pnpm-workspace monorepo of Model Context Protocol (MCP) servers for Flipt feature flags, exposing Flipt's REST APIs as MCP tools and prompts over STDIO transport:

• packages/mcp-server-flipt — npm @flipt-io/mcp-server-flipt, targets the Flipt v1 API (namespaces, flags, segments, rules, rollouts, constraints, variants, distributions, evaluation).
• packages/mcp-server-flipt-v2 — npm @flipt-io/mcp-server-flipt-v2, targets the Flipt v2 API (everything above plus environments and branch environments).

Commands

Run from the repository root:

pnpm install       # install all workspace dependencies
pnpm -r build      # compile both packages to their dist/ (postbuild chmods dist + bin/cli.js)
pnpm -r check      # typecheck only (tsc --noEmit)
pnpm -r test       # Jest (ts-jest); tests live in each package's src/tests/
pnpm lint          # ESLint over packages/*/src, excludes generated + tests
pnpm lint:fix
pnpm fmt           # Prettier write
pnpm fmt:check

# scope to one package (dev runs from source with tsx)
pnpm --filter @flipt-io/mcp-server-flipt-v2 dev
pnpm --filter @flipt-io/mcp-server-flipt-v2 test

To run a single test: pnpm --filter <pkg> exec jest path/to/tests/foo.test.ts or ... exec jest -t "test name".

Runtime configuration comes from env vars (or a .env file, loaded via dotenv): FLIPT_URL (default http://localhost:8080), optional FLIPT_API_KEY (sent as a Bearer token), and — v2 only — FLIPT_ENVIRONMENT (default environment when a tool call omits environmentKey; defaults to default).

Architecture

Both packages follow the same shape: src/index.ts registers every tool and prompt inline via server.tool(name, [description,] zodShape, handler) against a single McpServer; handlers call the package's Flipt client, return results as JSON text content, catch errors and return isError: true; resource-style URIs (flipt://...) are attached in _meta; startServer() wires the STDIO transport; bin/cli.js is the published entrypoint requiring dist/index.js. Anything logged from server code must go to stderr (console.error) — stdout carries the JSON-RPC stream.