aircall-mcp-server: Instructions file for Codex

Aircall MCP Server

Type: Single-package TypeScript MCP server (stdio transport) Framework: @modelcontextprotocol/sdk + zod, compiled with TypeScript 6.0 (NodeNext ESM) Purpose: Exposes the Aircall Public API as 83 MCP tools, distributed to non-technical users as a one-click Claude Desktop extension (.mcpb)

Overview

Maintained by Cassia Research. Wraps https://api.aircall.io/v1 (and selected /v2 endpoints) with Basic auth, client-side rate limiting, and per-tool MCP annotations so clients like Claude Desktop can group read-only tools (36) apart from write tools (47) and gate destructive ones.

Commands

npm install            # install all deps (dev included)
npm run build          # tsc -> dist/
npm run dev            # tsc --watch
npm start              # run the built server (needs AIRCALL_API_ID/AIRCALL_API_TOKEN)
npm run lint           # eslint src (flat config, eslint 10) — 2 no-console warnings in
                       # src/index.ts are EXPECTED (intentional CLI output); do not "fix" them
npm run lint:fix       # eslint with autofix
npm run typecheck      # tsc --noEmit
npm run docs           # regenerate docs/tools/README.md from the BUILT server (build first)
npm run bundle         # full pipeline: install -> build -> prune prod -> pack aircall-mcp.mcpb (~2.7MB) -> reinstall dev deps

There is NO test suite (npm test does not exist). Verification is the stdio smoke test below — expect an initialize response naming aircall-mcp-server and a tools/list of 83 tools (36 in read-only mode with AIRCALL_READ_ONLY=true):

(printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'; sleep 2) \
  | AIRCALL_API_ID=test AIRCALL_API_TOKEN=test node dist/index.js

Directory Structure

src/
  index.ts             CLI entry: --api-id/--api-token/--tools/--read-only flags + env fallbacks
  server.ts            AircallMCPServer: registration, category/read-only filtering, MCP handlers,
                       buildAnnotations(); exports TOOL_CATEGORIES
  tools/
    calls.ts           24 tools incl. transcription + all Conversation Intelligence endpoints
    contacts.ts        12 tools (CRUD + phone/email management)
    users.ts           10 tools (CRUD, availability, start_call, dial, v2 user numbers)
    teams.ts           6 tools
    numbers.ts         5 tools (update_messages goes through PUT /numbers/:id)
    tags.ts            5 tools
    webhooks.ts        5 tools
    messages.ts        5 tools (send via /numbers/:id/messages/send + configuration)
    dialer.ts          6 tools (campaigns are PER-USER: /users/:user_id/dialer_campaign)
    company.ts         5 tools (ping, company, integration enable/disable)
  types/aircall.ts     API response types + READ_ONLY_TOOLS / WRITE_TOOLS registries
  utils/
    auth.ts            AircallClient: Basic auth, /v1 base ('/v2/...' paths hit v2), error handling
    format.ts          toIso(): safe timestamp conversion
    rate-limiter.ts    client-side limiter (Aircall allows 60 req/min)
scripts/
  generate-tool-docs.mjs   spawns dist/index.js, dumps tools/list into docs/tools/README.md
docs/                  guides + generated tool reference
manifest.json          MCPB extension manifest (user_config form, env mapping)
.mcpbignore            what stays out of the .mcpb bundle
.github/workflows/release.yml   tag-triggered release (builds + attaches .mcpb)