mcp-windows/docs/ARCHITECTURE.md

Architecture

Overview

mcp_windows 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