Twilio

Automatically converts OpenAPI 3.0 specifications into Model Context Protocol (MCP) tool definitions by parsing OpenAPI schemas, extracting operation metadata, and generating MCP-compatible tool schemas with parameter validation. Uses @apidevtools/swagger-parser to validate and dereference OpenAPI specs, then transforms operation objects into MCP InputSchema structures with proper type mapping and constraint preservation.

Translates MCP tool call requests into authenticated HTTP API calls by mapping MCP parameters to HTTP request components (path, query, body), handling multiple authentication schemes (Basic, Bearer, API Key), and managing credential injection from environment variables or configuration. Implements a generic HTTP client utility that constructs requests according to OpenAPI operation specifications and handles response serialization back to MCP format.

Routes incoming MCP tool call requests to the correct OpenAPI operation handler by matching the tool name to an operation ID from the OpenAPI spec. Extracts parameters from the MCP request, maps them to the appropriate HTTP request components (path, query, body), invokes the HTTP client with the constructed request, and returns the response in MCP format. Implements a dispatch mechanism that handles both generic OpenAPI tools and custom Twilio-specific tool implementations.

Provides command-line interfaces (openapi-mcp-server and twilio-mcp-server) that instantiate and start MCP servers with configuration from command-line arguments and environment variables. The CLI parses arguments for OpenAPI spec location, authentication credentials, and server options, creates the appropriate server instance (generic or Twilio-specific), and starts listening for MCP client connections on stdio.

Implements the Model Context Protocol server-side using stdio transport, handling MCP message serialization/deserialization, request routing, and response formatting. Uses @modelcontextprotocol/sdk to manage the MCP protocol layer, listening for tool call requests on stdin and writing responses to stdout in JSON-RPC format, enabling integration with MCP-compatible clients like Claude Desktop.

Extends the generic OpenAPI MCP server with Twilio-specific tools and custom implementations for common Twilio operations (sending messages, managing phone numbers, configuring accounts). The TwilioOpenAPIMCPServer class inherits from OpenAPIMCPServer and adds custom tool handlers that wrap Twilio API calls with domain-specific logic, parameter validation, and response formatting tailored to Twilio's API patterns.

Implements the MCP tools/list endpoint to advertise available tools to MCP clients by introspecting the OpenAPI specification and generating tool metadata (name, description, input schema). When a client connects, the server responds to the tools/list request with a complete inventory of available operations, each with full parameter schemas, descriptions, and required field information extracted from the OpenAPI spec.

Validates MCP tool call parameters against OpenAPI schemas before making HTTP requests, performing type checking, required field validation, and constraint enforcement (min/max values, string patterns, enum values). Coerces parameters to the correct types (string to number, boolean parsing) based on OpenAPI type definitions, returning validation errors to the MCP client if parameters don't match the schema.

Manages API credentials (API keys, tokens, account IDs) by reading them from environment variables at server startup and injecting them into HTTP requests without exposing them in logs or responses. Supports multiple authentication schemes (Basic Auth, Bearer Token, API Key headers) by mapping OpenAPI security schemes to environment variable names, enabling secure credential handling for AI-driven API access.

Catches HTTP errors and API failures, normalizing them into MCP-compatible error responses with meaningful error messages and status codes. Maps HTTP error codes to MCP error formats, preserves API error details (error messages, error codes, validation failures) in the response, and provides structured error information that helps AI assistants understand what went wrong and how to retry.

Manages a multi-package npm workspace where the Twilio-specific MCP server depends on the generic OpenAPI MCP server package. Uses npm workspaces and a prepare script to ensure the generic package is built before the Twilio package, maintaining the correct build order and dependency resolution across packages. Enforces Node.js version requirements (>=20.0.0) at the workspace level.

Parses OpenAPI 3.0 specifications (JSON or YAML) and dereferences all schema references ($ref) to create a fully resolved specification tree. Uses @apidevtools/swagger-parser to handle remote references, circular references, and schema composition, enabling the MCP server to work with complex OpenAPI specs that use modular schema definitions and external references.