# instructa/mcp-starter architecture

> Architecture diagram of the GitHub repository instructa/mcp-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/instructa/mcp-starter
- Repository: https://github.com/instructa/mcp-starter

## Overview

##### Main Components
a. CLI Entrypoint
- Location: `bin/cli.mjs`
- Responsibility: Parses flags (`--stdio`, `--http`, `--sse`, `--port`, `--endpoint`), boots the server.
b. Transport Layer Adapters
- stdio adapter (default)
- HTTP/Streamable HTTP adapter (`--http`)
- SSE adapter (`--sse`, deprecated)
- Location: instantiated in `src/server.ts` based on CLI args.
c. MCP Server Core
- Location: `src/server.ts` + `src/index.ts`
- Responsibility: Implements the MCP protocol loop: receive request, parse, route to tools, send response.
d. Tool Registry & Execution
- Location: `src/tools/*.ts` (e.g., `mytool.ts`)
- Responsibility: Define one or more “tools” that the server can invoke.
e. Shared Types & Utilities
- Location: `src/types.ts`, `src/utils.ts`
- Responsibility: Type definitions for MCP messages, helper functions (e.g., JSON parsing, error handling).
f. External Clients
- Examples: Cursor AI, Claude GI, any MCP-compatible client
- Interaction: Connect to server via chosen transport, send/receive MCP messages.
g. Configuration & Metadata
- `.cursor/mcp.json`: example client config
- `package.json`, `build.config.ts`, `vite.config.ts`: build and publish settings

##### Relationships and Data Flows
- CLI Entrypoint → parses flags → selects Transport Adapter
- Transport Adapter ↔ (listens for) MCP Client requests
- Transport Adapter → forwards raw message → MCP Server Core
- MCP Server Core → parses message → dispatches to appropriate Tool
- Tool → processes logic → returns result to Core
- MCP Server Core → serializes result → hands back to Transport
- Transport Adapter → sends message → External Client

##### Architectural Patterns
- Modular Transport Strategy: Each transport (stdio, HTTP, SSE) implements the same interface—swapable at startup.
- Plugin-style Tools: You drop new `.ts` tool files into `src/tools` and register them in the core.
- Single Responsibility & Separation of Concerns:
- CLI: argument handling
- Transports: I/O concerns
- Core: protocol logic
- Tools: domain logic
- Utils/Types: shared helpers

##### Technologies
- Node.js + TypeScript (ts-node or build via Vite)
- MCP Protocol standard
- Vite / ESBuild for bundling (`vite.config.ts`, `build.config.ts`)
- Testing with Vitest/Jest (`tests/server.test.ts`)
- pnpm (lockfile present), Docker (optional containerization)

##### Detailed Elements to Capture
- CLI flags and how they instantiate the correct transport
- Configuration file `.cursor/mcp.json` as a bootstrap for local development
- Test harness (`tests/server.test.ts`) to illustrate quality assurance

Putting It All Together:
– Off to the side, place “Shared Types / Utils” as a resource that Core and Tools both import.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Clients"
        EC["Cursor AI, Claude GI, etc."]:::external
    end

    CLI["CLI Entrypoint\n(bin/cli.mjs)"]:::core
    click CLI "https://github.com/instructa/mcp-starter/blob/main/bin/cli.mjs"

    CLI -->|"flags: --stdio, --http, --sse\n--port, --endpoint"| TransportInterface

    subgraph "Transport Layer"
        TransportInterface["Transport Adapter Interface"]:::transport
        StdIO["StdIO Adapter"]:::transport
        HTTP["HTTP Adapter"]:::transport
        SSE["SSE Adapter (deprecated)"]:::transport

        TransportInterface --> StdIO
        TransportInterface --> HTTP
        TransportInterface --> SSE

        StdIO <-->|"MCP JSON Request/Response"| EC
        HTTP <-->|"MCP JSON Request/Response"| EC
        SSE <-->|"MCP JSON Request/Response"| EC
    end
    click TransportInterface "https://github.com/instructa/mcp-starter/blob/main/src/server.ts"
    click StdIO "https://github.com/instructa/mcp-starter/blob/main/src/server.ts"
    click HTTP "https://github.com/instructa/mcp-starter/blob/main/src/server.ts"
    click SSE "https://github.com/instructa/mcp-starter/blob/main/src/server.ts"

    TransportInterface -->|"forwards raw message"| Core

    subgraph "MCP Server Core"
        Core["MCP Server Core"]:::core
    end
    click Core "https://github.com/instructa/mcp-starter/blob/main/src/index.ts"

    Core -->|"dispatch to tools"| ToolRegistry

    subgraph "Tool Registry & Execution"
        ToolRegistry["Tool Registry"]:::tools
        MyTool["mytool.ts"]:::tools

        ToolRegistry --> MyTool
    end
    click MyTool "https://github.com/instructa/mcp-starter/blob/main/src/tools/mytool.ts"

    subgraph "Shared Resources"
        Types["Shared Types"]:::util
        Utils["Shared Utilities"]:::util
    end
    click Types "https://github.com/instructa/mcp-starter/blob/main/src/types.ts"
    click Utils "https://github.com/instructa/mcp-starter/blob/main/src/utils.ts"

    Core --> Types
    Core --> Utils
    MyTool --> Types
    MyTool --> Utils

    subgraph "Config, Build & Tests"
        Config[".cursor/mcp.json"]:::config
        BuildConfig["build.config.ts"]:::build
        ViteConfig["vite.config.ts"]:::build
        Tests["tests/server.test.ts"]:::test
        Package["package.json"]:::package
    end
    click Config "https://github.com/instructa/mcp-starter/blob/main/.cursor/mcp.json"
    click BuildConfig "https://github.com/instructa/mcp-starter/blob/main/build.config.ts"
    click ViteConfig "https://github.com/instructa/mcp-starter/blob/main/vite.config.ts"
    click Tests "https://github.com/instructa/mcp-starter/blob/main/tests/server.test.ts"
    click Package "https://github.com/instructa/mcp-starter/blob/main/package.json"

    CLI --> Config
    CLI --> Package
    CLI --> BuildConfig
    CLI --> ViteConfig
    Core --> Tests

    classDef transport fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    classDef core fill:#bbdefb,stroke:#1565c0,stroke-width:2px
    classDef tools fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px
    classDef util fill:#e0e0e0,stroke:#616161,stroke-width:2px
    classDef external fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px
    classDef config fill:#d7ccc8,stroke:#5d4037,stroke-width:2px
    classDef build fill:#f8bbd0,stroke:#ad1457,stroke-width:2px
    classDef test fill:#ffcdd2,stroke:#c62828,stroke-width:2px
    classDef package fill:#fff9c4,stroke:#f9a825,stroke-width:2px
```
