Template
Jonathan Miller
91b78f8da1
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>
74 lines
2.4 KiB
Markdown
74 lines
2.4 KiB
Markdown
<!--
|
|
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
|
|
|
|
### `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 |
|