Frontapp-MCP: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is a Frontapp MCP Server - a Model Context Protocol server that enables Claude Code to interact with the Frontapp API. It provides comprehensive access to conversations, messages, contacts, teammates, tags, inboxes, comments, and analytics.

The server runs in a Docker container and communicates with Claude Code via stdio (standard input/output).

Development Commands

Building and Running

# Build TypeScript
npm run build

# Development with watch mode
npm run watch

# Start the server (requires FRONTAPP_API_TOKEN env var)
npm start

# Or use Docker (recommended)
make build    # Build Docker image
make up       # Start container
make down     # Stop container
make restart  # Restart container
make logs     # View logs
make shell    # Open shell in container

Docker Development

The project uses Docker Compose with a multi-stage build:

• Stage 1: Build TypeScript with full dependencies
• Stage 2: Production image with only runtime dependencies

# Direct Docker commands
docker compose build
docker compose up -d
docker compose logs -f

Architecture

Single-File MCP Server

The entire MCP server implementation is in frontapp_mcp.ts. It follows this structure:

1. FrontappMCPServer class - Main server implementation

   • constructor() - Initializes MCP Server and Axios instance with API token
   • setupHandlers() - Registers tool, resource, and request handlers
   • Private methods for each API operation (list/get/create/update/delete)

2. MCP Protocol Implementation:

   • ListToolsRequestSchema - Returns 20+ tool definitions
   • CallToolRequestSchema - Routes tool calls to appropriate API methods
   • ListResourcesRequestSchema - Exposes quick-access resources
   • ReadResourceRequestSchema - Fetches resource data

3. Communication Flow:

   Claude Code
     ↓ (stdio pipe)
   docker-mcp-wrapper.sh
     ↓ (docker exec)
   Docker Container
     ↓ (node dist/index.js)
   FrontappMCPServer
     ↓ (HTTPS with Bearer token)
   Frontapp API (api2.frontapp.com)