Template-NPM/docs/ARCHITECTURE.md

<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
SPDX-License-Identifier: GPL-3.0-or-later

# FILE INFORMATION
DEFGROUP: {{PROJECT_NAME}}.Documentation
PATH: /docs/ARCHITECTURE.md
VERSION: 01.00.00
BRIEF: Architecture overview and design decisions
-->

# 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

### `source/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

### `source/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

### `source/config.ts` — Configuration Loader

Loads connection details from `~/.<project>.json`. Supports multiple named connections with a configurable default.

### `source/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 |