# f/mcptools architecture

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

- Interactive diagram: https://gitdiagram.com/f/mcptools
- Repository: https://github.com/f/mcptools

## Overview

##### Project Type and Purpose
- This is a command-line interface (CLI) tool written in Go for interacting with Model Context Protocol (MCP) servers. It supports various operations such as listing tools, calling commands, interacting with resources, operating in mock mode, proxy mode, and even scaffolding new MCP projects.
- The tool is meant to act as both a client (sending commands to MCP servers) and, in certain modes (mock/proxy), a minimal server. Its purpose is to simplify interaction with MCP servers through a unified CLI interface.

##### File Structure
- The top-level directories (cmd, pkg, examples, templates, scripts, and .github) indicate clear separation of concerns:
- The cmd directory holds the main entry point (main.go) and all the subcommands (alias, call, shell, tools, etc.) under the commands subdirectory.
- The pkg directory contains reusable libraries (alias, client, jsonutils, mock, proxy, transport) that encapsulate core functionality such as network communication, JSON handling, and different modes of operation.
- The templates directory provides scaffolding for new MCP projects (with TypeScript support) indicating that part of the tool’s use is to generate new projects.
- The examples directory and scripts illustrate practical integrations and usage scenarios.
- The presence of CI/CD configuration files, linting and testing workflows, and Makefile shows an established build and testing process.

##### README for Additional Insights
- The README clearly explains how to use the MCP Tools CLI, its commands, transport options (stdio and HTTP SSE), interactive shell mode, and server aliases.
- It highlights two major server modes: mock (for testing) and proxy (for shell script/inline command integration), which affect how the CLI delegates or simulates MCP functionality.
- The README emphasizes independent, modular commands and transport layers so that components interact through well-defined interfaces (e.g., sending JSON-RPC 2.0 messages).

a. Main Components:
- User Interface (CLI Entry Point): Represented by cmd/mcptools/main.go and its command handlers (found in cmd/mcptools/commands).
- Command Handlers: Separate modules for commands (alias, call, shell, tools, version, new, mock, proxy) that parse user input and call relevant internal functions.
- Core Business Logic & Libraries: Located in the pkg directory with sub-packages:
- pkg/client: Handles communication to MCP servers (initiating JSON-RPC over different transports).
- pkg/transport: Implements transport layers for HTTP (SSE) and stdio.
- pkg/mock: Implements mock server functionality.
- pkg/proxy: Manages proxy mode, which registers and executes shell scripts as commands.
- pkg/jsonutils: Handles JSON formatting and output options.
- pkg/alias: Manages server alias registration and retrieval.
- External MCP Server Integration: Represent external MCP servers (whether real, mocked, or proxied) that the tool interacts with.
- Project Scaffolding: A component (supported by mcp new command and templates) that generates new MCP server projects, particularly with TypeScript (in the templates/ts directory).

b. Relationships and Interactions:
- The entry point (CLI) accepts commands and delegates processing to the respective command handler modules.
- Each command handler, in turn, calls into one or more pkg libraries that handle the actual implementation logic.
- The pkg/client and pkg/transport packages interact with external MCP servers via HTTP or stdio. They send commands formatted in JSON-RPC 2.0.
- The mock and proxy functionalities are treated as either simulators (for testing) or adapters (for shell integration) to provide responses following the MCP protocol.
- The scaffolding feature ties together template files from the templates directory with initialization logic from the CLI tool.

c. Architectural Patterns and Design Principles:
- Modular design and separation of concerns: The clear split between command-handling (cmd folder) and business logic (pkg folder).
- Command and Proxy Patterns: Each CLI command corresponds to a module that implements a specific “command,” and proxy mode uses scripts to extend functionality.
- Pluggable Transport Layers: The design allows multiple transport mechanisms (stdio vs. HTTP SSE) to be swapped depending on the use case.
- External Configuration: Managed via config files (e.g., aliases stored in $HOME/.mcpt) and template directories for scaffolding, which supports flexibility.

d. Relevant Technologies and Frameworks:
- Language: Go – files such as go.mod, go.sum indicate dependency management.
- Testing: A collection of *_test.go files across the project to ensure quality.
- CI/CD: GitHub workflows, golangci-lint, goreleaser configuration indicate continuous integration and release management processes.
- JSON-RPC 2.0: The protocol used to interact with MCP servers.

##### Extra Detail
- Including a small inset that shows the continuous integration pipelines and build/deployment process (Makefile, GitHub workflows, goreleaser configuration) as this emphasizes the maturity of the release process in production.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Entry Point"]:::cli
        CMDH["Command Handlers"]:::commands
    end

    %% Core Logic
    subgraph "Core Logic"
        CLIENT["Client Communication Layer"]:::client
        TRANSPORT["Transport Layers"]:::transport
        JSONUTIL["JSON Handling Utilities"]:::json
        ALIAS["Server Alias Management"]:::alias
        MOCK["Mock Server Functionality"]:::mock
        PROXY["Proxy Mode Functionality"]:::proxy
    end

    %% Project Scaffolding
    subgraph "Project Scaffolding"
        SCAFFOLD["Scaffolding Engine"]:::scaffold
    end

    %% External MCP Servers
    subgraph "External MCP Servers"
        MCP["MCP Servers"]:::external
    end

    %% CI/CD and Build Tools
    subgraph "Build & CI/CD"
        CICD["CI/CD Pipeline & Build Tools"]:::cicd
    end

    %% Connections
    CLI -->|"delegates"| CMDH
    CMDH -->|"invokes"| CLIENT
    CLIENT -->|"communicates_via"| TRANSPORT
    TRANSPORT -->|"sends_JSON-RPC"| MCP
    CMDH -->|"utilizes"| JSONUTIL
    CMDH -->|"retrieves"| ALIAS
    CMDH -->|"executes_mock"| MOCK
    CMDH -->|"executes_proxy"| PROXY
    CMDH -->|"triggers"| SCAFFOLD

    CLI ---|"configured_by"| CICD
    SCAFFOLD ---|"uses_templates"| CICD

    %% Click Events
    click CLI "https://github.com/f/mcptools/blob/master/cmd/mcptools/main.go"
    click CMDH "https://github.com/f/mcptools/tree/master/cmd/mcptools/commands"
    click CLIENT "https://github.com/f/mcptools/blob/master/pkg/client/client.go"
    click TRANSPORT "https://github.com/f/mcptools/tree/master/pkg/transport"
    click JSONUTIL "https://github.com/f/mcptools/tree/master/pkg/jsonutils"
    click ALIAS "https://github.com/f/mcptools/blob/master/pkg/alias/alias.go"
    click MOCK "https://github.com/f/mcptools/blob/master/pkg/mock/mock.go"
    click PROXY "https://github.com/f/mcptools/blob/master/pkg/proxy/proxy.go"
    click SCAFFOLD "https://github.com/f/mcptools/tree/master/templates/ts"

    %% Styles
    classDef cli fill:#ffcccc,stroke:#d62728,stroke-width:2px;
    classDef commands fill:#ffe6cc,stroke:#ff7f0e,stroke-width:2px;
    classDef client fill:#e6ffe6,stroke:#2ca02c,stroke-width:2px;
    classDef transport fill:#e6f7ff,stroke:#1f77b4,stroke-width:2px;
    classDef json fill:#f0e6ff,stroke:#9467bd,stroke-width:2px;
    classDef alias fill:#fff2e6,stroke:#8c564b,stroke-width:2px;
    classDef mock fill:#f9e6ff,stroke:#e377c2,stroke-width:2px;
    classDef proxy fill:#e6ffe6,stroke:#17becf,stroke-width:2px;
    classDef scaffold fill:#e6e6ff,stroke:#7f7f7f,stroke-width:2px;
    classDef external fill:#fffdd0,stroke:#bcbd22,stroke-width:2px;
    classDef cicd fill:#fbe4d5,stroke:#ff9896,stroke-width:2px;
```
