4

ARCHITECTURE

Jonathan Miller edited this page 2026-05-20 01:24:26 +00:00

Table of Contents

• Architecture
• Overview
• Components
• src/index.ts -- Server Entry Point
• src/client.ts -- HTTP Client
• src/config.ts -- Configuration Loader
• src/types.ts -- Type Definitions
• scripts/setup.mjs -- Interactive Setup
• Design Decisions
• Why node:https instead of fetch?
• Why multiple named connections?
• Data Flow
• Revision History

← Home

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 ~/.<project>.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

---

Repo: Template-MCP . MokoStandards

Revision	Date	Author	Description
1.0	2026-05-09	Moko Consulting	Initial version