# Architecture ## Overview {{PROJECT_NAME}} is a Model Context Protocol (MCP) server that bridges AI assistants with a REST API. ``` AI Assistant <--> MCP (stdio) <--> ApiClient <--> REST API ``` ## Components ### `src/index.ts` — Server Entry Point Registers all MCP tools with `McpServer` from `@modelcontextprotocol/sdk`. Each tool maps to one or more API endpoints. Uses Zod schemas for input validation. Includes shared helpers: - `formatResponse()` — normalizes error/success responses into MCP text content - `paginationQuery()` — builds pagination query params - `ConnectionParam` / `PaginationParams` — reusable Zod parameter spreads ### `src/client.ts` — HTTP Client The `ApiClient` class handles all HTTP communication: - Uses `node:https` / `node:http` (not `fetch`) for reliable self-signed cert support - Supports GET, POST, PUT, PATCH, DELETE - JSON serialization/deserialization with error handling ### `src/config.ts` — Configuration Loader Loads connection details from `~/..json`. Supports multiple named connections with a configurable default. ### `src/types.ts` — Type Definitions TypeScript interfaces for `ApiConnection`, `ApiConfig`, and `ApiResponse`. ### `scripts/setup.mjs` — Interactive Setup Node.js script using `readline/promises` for interactive config creation. ## Design Decisions ### Why `node:https` instead of `fetch`? Node.js 24's built-in `fetch` does not honor self-signed certificate bypass. The classic `node:https` module with `rejectUnauthorized: false` works reliably across all Node.js versions. ### Why multiple named connections? Multi-instance support is a core use case — managing staging, production, and dev environments from a single MCP server. ## Data Flow 1. AI assistant sends a tool call via MCP stdio transport 2. `index.ts` validates parameters with Zod and resolves the connection 3. `ApiClient` constructs the API URL, attaches auth headers, and makes the HTTP request 4. Response is parsed as JSON and returned as MCP tool output ## Revision History | Date | Version | Author | Notes | | --- | --- | --- | --- | | 2026-05-07 | 0.0.1 | jmiller | Initial architecture document |