Jonathan Miller
36b642e23f
Universal: Cascade Main → Dev / Cascade main → branches (push) Successful in 1s
Universal: Changelog Validation / Validate CHANGELOG.md (push) Failing after 3s
Generic: Repo Health / Access control (push) Successful in 2s
MCP: Standards Compliance / Secret Scanning (push) Successful in 4s
MCP: Standards Compliance / Repository Structure Validation (push) Failing after 3s
MCP: Standards Compliance / License Header Validation (push) Failing after 4s
MCP: Standards Compliance / Coding Standards Check (push) Failing after 3s
MCP: Standards Compliance / Workflow Configuration Check (push) Failing after 4s
MCP: Standards Compliance / Documentation Quality Check (push) Failing after 3s
MCP: Tool Inventory / inventory (push) Failing after 16s
MCP: Standards Compliance / README Completeness Check (push) Failing after 3s
MCP: Standards Compliance / Git Repository Hygiene (push) Successful in 3s
MCP: Standards Compliance / Line Length Check (push) Failing after 5s
MCP: Standards Compliance / File Naming Standards (push) Successful in 4s
MCP: Build & Release / Build, Validate & Release (push) Failing after 33s
MCP: Standards Compliance / Insecure Code Pattern Detection (push) Successful in 5s
MCP: Build & Validate / build (20) (push) Failing after 41s
MCP: Build & Validate / build (22) (push) Failing after 41s
MCP: Standards Compliance / File Size Limits (push) Successful in 4s
MCP: Standards Compliance / Binary File Detection (push) Successful in 3s
MCP: Standards Compliance / Script Integrity Validation (push) Successful in 33s
MCP: Standards Compliance / TODO/FIXME Tracking (push) Successful in 3s
MCP: Standards Compliance / Version Consistency Check (push) Successful in 49s
MCP: Standards Compliance / Broken Link Detection (push) Successful in 4s
Universal: CodeQL Analysis / Analyze (actions) (push) Failing after 1m2s
MCP: Standards Compliance / Dead Code Detection (push) Successful in 20s
Universal: CodeQL Analysis / Analyze (javascript) (push) Failing after 1m5s
MCP: Standards Compliance / API Documentation Coverage (push) Successful in 5s
MCP: Standards Compliance / Accessibility Check (push) Successful in 4s
MCP: Standards Compliance / Performance Metrics (push) Successful in 4s
Universal: CodeQL Analysis / Security Scan Summary (push) Successful in 1s
MCP: Standards Compliance / Terraform Configuration Validation (push) Successful in 13s
MCP: Standards Compliance / Code Complexity Analysis (push) Successful in 46s
MCP: Standards Compliance / Code Duplication Detection (push) Successful in 46s
MCP: Standards Compliance / Unused Dependencies Check (push) Successful in 46s
MCP: Standards Compliance / Dependency Vulnerability Scanning (push) Successful in 48s
Universal: Sync Version on Merge / Propagate README version (push) Failing after 37s
MCP: Standards Compliance / Enterprise Readiness Check (push) Successful in 41s
MCP: Standards Compliance / Repository Health Check (push) Successful in 40s
MCP: Standards Compliance / Compliance Summary (push) Failing after 1s
Generic: Repo Health / Release configuration (push) Has been cancelled
Generic: Repo Health / Scripts governance (push) Has been cancelled
Generic: Repo Health / Repository health (push) Has been cancelled
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: mcp_windows.Documentation
|
|
PATH: /docs/ARCHITECTURE.md
|
|
VERSION: 01.00.00
|
|
BRIEF: Architecture overview and design decisions
|
|
-->
|
|
|
|
# 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 |
|