# ereminmaksim/mcp-by-doca-mayao architecture

> Architecture diagram of the GitHub repository ereminmaksim/mcp-by-doca-mayao, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ereminmaksim/mcp-by-doca-mayao
- Repository: https://github.com/ereminmaksim/mcp-by-doca-mayao

## Overview

#### Purpose and Interfaces
This is a read-only Model Context Protocol (MCP) server exposing MAYAO component documentation and onboarding guidance from bundled JSON data. It supports both networked MCP over HTTP and local MCP over stdio. Main entry points are `src/server.ts` (HTTP) and `src/stdio.ts` (stdio transport).

#### Transport and Session Boundary
The HTTP adapter serves health, metrics, and MCP endpoints; MCP clients initialize a JSON-RPC session, then pass `mcp-session-id` on subsequent requests. The stdio adapter exposes the same tool capability without HTTP/session-origin concerns.
- `src/http.ts`
- `src/server.ts`
- `src/stdio.ts`

#### MCP Tool Surface
Tool modules define the public read-only operations: list, retrieve, search, recommend, and compare components, plus retrieve/search onboarding content. These are the protocol-facing orchestration layer that validates inputs and delegates to services.
- `src/tools/listComponents.ts`
- `src/tools/compareComponents.ts`
- `src/tools/searchDocs.ts`

#### Domain Services and Search Flow
Services implement domain queries over the static catalog: component lookup/listing, onboarding lookup, and cross-document search. Recommendation and comparison tools compose this service-level data rather than calling an external documentation system.
- `src/services/components.ts`
- `src/services/onboarding.ts`
- `src/services/search.ts`

#### Source-of-Truth Data and Transformation
The repository embeds its documentation catalog as JSON. Transform modules convert raw data records into the shapes expected by services and MCP tool responses, creating a boundary between stored content and protocol/domain models.
- `src/data/componentsData.json`
- `src/data/onboardingData.json`
- `src/transforms/componentTransform.ts`
- `src/transforms/onboardingTransform.ts`

#### Schema and Validation Boundary
Shared and domain-specific schemas constrain component and onboarding request/data structures before tool or service processing. This keeps malformed MCP arguments from reaching data-query logic.
- `src/schemas/common.ts`
- `src/schemas/component.ts`
- `src/schemas/onboarding.ts`

#### Security, Operations, and Deployment
The HTTP runtime applies request-size limits, IP rate limiting, origin allow-listing, session TTL cleanup, concurrency/timeout/circuit-breaker controls, audit logging, and rolling metrics. Runtime configuration is environment-driven; Railway/Nixpacks deployment files indicate a Node/TypeScript service deployment with no database or external content API.
- `src/security.ts`
- `src/config.ts`
- `railway.json`
- `nixpacks.toml`

Main entry points: [`src/tools/listComponents.ts`](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/tools/listComponents.ts) (Read-only tools), [`src/server.ts`](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/server.ts) (HTTP server), [`src/services/components.ts`](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/services/components.ts) (Component service), [`src/services/search.ts`](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/services/search.ts) (Cross-document search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transports["Transports"]
  node_mcp_clients(("MCP clients<br/>external client"))
  node_http_server["HTTP server<br/>HTTP runtime<br/>[server.ts]"]
  node_http_adapter["HTTP adapter<br/>transport adapter<br/>[http.ts]"]
  node_stdio_adapter["stdio adapter<br/>stdio runtime<br/>[stdio.ts]"]
end

subgraph group_mcp["MCP API"]
  node_tool_surface{{"Read-only tools<br/>MCP tool modules<br/>[listComponents.ts]"}}
  node_compare_tool{{"Compare components<br/>MCP tool module"}}
  node_search_tool{{"Search documentation<br/>MCP tool module<br/>[searchDocs.ts]"}}
  node_shared_schemas["Shared schemas<br/>validation schemas<br/>[common.ts]"]
  node_component_schemas["Component schemas<br/>validation schemas<br/>[component.ts]"]
  node_onboarding_schemas["Onboarding schemas<br/>validation schemas<br/>[onboarding.ts]"]
end

subgraph group_domain["Domain and Content"]
  node_component_service["Component service<br/>domain service<br/>[components.ts]"]
  node_onboarding_service["Onboarding service<br/>domain service<br/>[onboarding.ts]"]
  node_search_service["Cross-document search<br/>search service<br/>[search.ts]"]
  node_component_transform["Component transform<br/>data transform"]
  node_onboarding_transform["Onboarding transform<br/>data transform"]
  node_components_data[("Component catalog<br/>bundled JSON")]
  node_onboarding_data[("Onboarding catalog<br/>bundled JSON")]
end

subgraph group_operations["Operations"]
  node_security["Security controls<br/>HTTP middleware<br/>[security.ts]"]
  node_runtime_config["Runtime configuration<br/>environment config<br/>[config.ts]"]
  node_deployment["Railway deployment<br/>deployment manifest<br/>[railway.json]"]
  node_build_deployment["Nixpacks build<br/>build manifest<br/>[nixpacks.toml]"]
end

node_mcp_clients -->|"HTTP MCP"| node_http_server
node_http_server -->|"protects requests"| node_security
node_http_server -->|"routes MCP"| node_http_adapter
node_http_adapter -->|"dispatches tools"| node_tool_surface
node_stdio_adapter -->|"dispatches tools"| node_tool_surface
node_tool_surface -->|"validates"| node_shared_schemas
node_tool_surface -->|"validates"| node_component_schemas
node_tool_surface -->|"validates"| node_onboarding_schemas
node_tool_surface -->|"queries"| node_component_service
node_tool_surface -->|"queries"| node_onboarding_service
node_compare_tool -->|"composes"| node_component_service
node_search_tool -->|"queries"| node_search_service
node_component_service -->|"uses"| node_component_transform
node_onboarding_service -->|"uses"| node_onboarding_transform
node_search_service -->|"searches components"| node_component_service
node_search_service -->|"searches onboarding"| node_onboarding_service
node_component_transform -->|"transforms"| node_components_data
node_onboarding_transform -->|"transforms"| node_onboarding_data
node_http_server -.->|"reads"| node_runtime_config
node_security -.->|"reads limits"| node_runtime_config
node_deployment -.->|"deploys"| node_http_server
node_build_deployment -.->|"builds"| node_http_server

click node_http_server "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/server.ts"
click node_http_adapter "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/http.ts"
click node_stdio_adapter "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/stdio.ts"
click node_tool_surface "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/tools/listComponents.ts"
click node_compare_tool "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/tools/compareComponents.ts"
click node_search_tool "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/tools/searchDocs.ts"
click node_shared_schemas "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/schemas/common.ts"
click node_component_schemas "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/schemas/component.ts"
click node_onboarding_schemas "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/schemas/onboarding.ts"
click node_component_service "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/services/components.ts"
click node_onboarding_service "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/services/onboarding.ts"
click node_search_service "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/services/search.ts"
click node_component_transform "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/transforms/componentTransform.ts"
click node_onboarding_transform "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/transforms/onboardingTransform.ts"
click node_components_data "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/data/componentsData.json"
click node_onboarding_data "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/data/onboardingData.json"
click node_security "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/security.ts"
click node_runtime_config "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/config.ts"
click node_deployment "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/railway.json"
click node_build_deployment "https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/nixpacks.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp_clients,node_http_server,node_http_adapter,node_stdio_adapter toneBlue
class node_tool_surface,node_compare_tool,node_search_tool,node_shared_schemas,node_component_schemas,node_onboarding_schemas toneAmber
class node_component_service,node_onboarding_service,node_search_service,node_component_transform,node_onboarding_transform,node_components_data,node_onboarding_data toneMint
class node_security,node_runtime_config,node_deployment,node_build_deployment toneRose
```

## Components

### Transports

- **MCP clients**: external client
- [HTTP server](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/server.ts): HTTP runtime · Serves health, metrics, and session-bound MCP requests. · `src/server.ts`
- [HTTP adapter](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/http.ts): transport adapter · Manages JSON-RPC session requests via mcp-session-id. · `src/http.ts`
- [stdio adapter](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/stdio.ts): stdio runtime · Exposes MCP tools locally without HTTP session handling. · `src/stdio.ts`

### MCP API

- [Read-only tools](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/tools/listComponents.ts): MCP tool modules · Validates and orchestrates component and onboarding operations. · `src/tools/listComponents.ts`
- [Compare components](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/tools/compareComponents.ts): MCP tool module · `src/tools/compareComponents.ts`
- [Search documentation](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/tools/searchDocs.ts): MCP tool module · `src/tools/searchDocs.ts`
- [Shared schemas](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/schemas/common.ts): validation schemas · `src/schemas/common.ts`
- [Component schemas](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/schemas/component.ts): validation schemas · `src/schemas/component.ts`
- [Onboarding schemas](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/schemas/onboarding.ts): validation schemas · `src/schemas/onboarding.ts`

### Domain and Content

- [Component service](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/services/components.ts): domain service · Lists and retrieves catalog content for recommendation and comparison. · `src/services/components.ts`
- [Onboarding service](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/services/onboarding.ts): domain service · `src/services/onboarding.ts`
- [Cross-document search](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/services/search.ts): search service · `src/services/search.ts`
- [Component transform](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/transforms/componentTransform.ts): data transform · Maps raw component records to domain and tool response shapes. · `src/transforms/componentTransform.ts`
- [Onboarding transform](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/transforms/onboardingTransform.ts): data transform · Maps raw onboarding records to domain and tool response shapes. · `src/transforms/onboardingTransform.ts`
- [Component catalog](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/data/componentsData.json): bundled JSON · Embedded source-of-truth component documentation. · `src/data/componentsData.json`
- [Onboarding catalog](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/data/onboardingData.json): bundled JSON · Embedded source-of-truth onboarding content. · `src/data/onboardingData.json`

### Operations

- [Security controls](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/security.ts): HTTP middleware · Applies origin, rate, size, timeout, concurrency, and session protections. · `src/security.ts`
- [Runtime configuration](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/src/config.ts): environment config · `src/config.ts`
- [Railway deployment](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/railway.json): deployment manifest · Node/TypeScript deployment definition. · `railway.json`
- [Nixpacks build](https://github.com/ereminmaksim/mcp-by-doca-mayao/blob/main/nixpacks.toml): build manifest · `nixpacks.toml`

## Connections

- MCP clients → HTTP server: HTTP MCP
- HTTP server → Security controls: protects requests
- HTTP server → HTTP adapter: routes MCP
- HTTP adapter → Read-only tools: dispatches tools
- stdio adapter → Read-only tools: dispatches tools
- Read-only tools → Shared schemas: validates
- Read-only tools → Component schemas: validates
- Read-only tools → Onboarding schemas: validates
- Read-only tools → Component service: queries
- Read-only tools → Onboarding service: queries
- Compare components → Component service: composes
- Search documentation → Cross-document search: queries
- Component service → Component transform: uses
- Onboarding service → Onboarding transform: uses
- Cross-document search → Component service: searches components
- Cross-document search → Onboarding service: searches onboarding
- Component transform → Component catalog: transforms
- Onboarding transform → Onboarding catalog: transforms
- HTTP server → Runtime configuration: reads
- Security controls → Runtime configuration: reads limits
- Railway deployment → HTTP server: deploys
- Nixpacks build → HTTP server: builds