Template

Files

T

Jonathan Miller 91b78f8da1 feat: initial MCP server template with placeholder-driven scaffolding

Template repository for creating MokoStandards-compliant MCP servers.
Includes 4-file src/ structure (index, client, config, types), setup
wizard, example tools, 12 CI/CD workflows, full docs, and {{placeholder}}
tokens for search-and-replace customization.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-05-07 14:39:19 -05:00

2.4 KiB

Raw Blame History

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

AI assistant sends a tool call via MCP stdio transport
index.ts validates parameters with Zod and resolves the connection
ApiClient constructs the API URL, attaches auth headers, and makes the HTTP request
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

2.4 KiB Raw Blame History