Template
jmiller
8707d66108
Universal: Pre-Release / Build Pre-Release (${{ inputs.stability || github.ref_name }}) (push) Successful in 22s
Branch Policy Check / Verify merge target (pull_request) Successful in 2s
Universal: PR Check / Branch Policy (pull_request) Successful in 3s
Universal: PR Check / Secret Scan (pull_request) Successful in 7s
Generic: Project CI / Lint & Validate (pull_request) Successful in 24s
Universal: PR Check / Validate PR (pull_request) Successful in 7s
Universal: Auto-Assign / Assign unassigned issues and PRs (pull_request_target) Successful in 3s
Branch Cleanup / Delete merged branch (pull_request) Successful in 2s
RC Revert / Rename rc/ back to dev/ (pull_request) Has been skipped
Generic: Project CI / Tests (pull_request) Has been cancelled
Universal: PR Check / Build RC Package (pull_request) Has been cancelled
Universal: PR Check / Report Issues (pull_request) Has been cancelled
Standardize the template on `source/` as the source input directory and retire user-facing `src/` references, per issue #34. Changes: - git mv src -> source (history preserved for all .ts files) - source/*.ts: update PATH headers /src/ -> /source/ - tsconfig.json: rootDir and include point at source/ - package.json: lint script targets source/ - Makefile: add SRC_DIR := source (CI resolver source of truth) - README.md, CLAUDE.md, docs/ARCHITECTURE.md: source path refs -> source/ The `dist/` directory is retained solely as tsc's compiled build output (outDir), which is already gitignored and never committed/published; releases go through the MokoGIT release system. No new dist/ references were introduced. Authored-by: Moko Consulting
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
|
|
|
|
### `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 |
|