# zcaceres/gtasks-mcp architecture

> Architecture diagram of the GitHub repository zcaceres/gtasks-mcp, 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/zcaceres/gtasks-mcp
- Repository: https://github.com/zcaceres/gtasks-mcp

## Overview

##### Project Type and Purpose
- This is a Node.js-based MCP (Modular Control Protocol) server written in TypeScript that integrates with Google Tasks. Its purpose is to allow operations like listing, reading, searching, creating, updating, deleting, and clearing tasks in Google Tasks.
- The README details features as “tools” (search, list, create, update, delete, clear) that interact with Google Tasks resources through an API. Authentication is also central (using OAuth credentials for the Google Cloud project).

##### Analyzing the File Structure
- Key Files and Directories:
- The root contains configuration files (package.json, tsconfig.json, smithery.yaml), a Dockerfile, licensing and README files.
- The “src” directory holds the TypeScript source code including:
▪ index.ts – likely the main entry point, handling server initialization and the routing for task operations.
▪ Tasks.ts – encapsulates the core logic related to tasks: interacting with the Google Tasks API for CRUD operations.
- This simple structure indicates a modular design with a clear separation between application entry and business logic.
- Inclusion of a Dockerfile suggests containerized deployment, while package.json provides dependency management.

##### Reviewing the README
- The README outlines six primary “tools” (each representing a feature) and details the inputs/outputs.
- It explains how to run the server (including an authentication flow), build the server, and integrate it with a desktop application.
- Key architectural hints include:
▪ A central API server (written in TypeScript) that processes incoming commands and routes them to the appropriate tasks functions.
▪ An authentication flow (triggered via a specific command-line argument) that opens a browser for OAuth authentication.
▪ Integration points for external systems (Google Tasks API and the desktop app via a configuration).

a. Main Components to Include:
- Client / Desktop App: Initiates requests or integrates the MCP server as shown in the usage section.
- MCP Server (Node.js/TypeScript Application):
▪ API Entry Point (index.ts) that receives and dispatches operations.
▪ Tasks Module (Tasks.ts) handling business logic for task operations.
▪ Authentication Module: Handles OAuth authentication flow and credentials management.
- Google Cloud / Google Tasks API: External service where actual task data is stored and managed.
- Additional Components:
▪ Containerization Unit (Docker) which encapsulates the server for deployment.
▪ Configuration & Build Tools (package.json, tsconfig.json, smithery.yaml, etc.)

b. Relationships and Interactions:
- Within the server, illustrate that the API entry point calls the Tasks module for each tool (search, list, create, update, delete, clear).
- A connection from the authentication module to Google OAuth services, then from the server to Google Tasks API.

c. Architectural Patterns & Design Principles:
- Modular Design: Separation of concerns by isolating task operations in the Tasks.ts module.
- API Gateway Pattern: The server acts as an intermediary between client requests and external Google services.
- Containerization: Deployment via Docker emphasizes a microservice style that encapsulates all dependencies.

d. Technologies and Frameworks:
- Node.js & TypeScript for the server’s runtime.
- Docker for containerized deployment.
- Google Tasks API and OAuth for authentication.
- Smithery tools for installation as noted in the README.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global nodes
    Client["Client/Desktop App"]:::client
    OAuth_Service["OAuth/Google Cloud"]:::external
    Google_Tasks_API["Google Tasks API"]:::external

    %% MCP Server subgraph
    subgraph "MCP Server (Node.js/TypeScript)"
        API_Entry["API Entry Point (index.ts)"]:::internal
        Tasks_Module["Tasks Module (Tasks.ts)"]:::internal
        Auth_Module["Authentication Module"]:::internal
    end

    %% Deployment and Configuration subgraph
    subgraph "Deployment & Config"
        Docker_Container["Containerization Unit (Dockerfile)"]:::deployment
        subgraph "Configuration & Build Tools"
            Package_json["package.json"]:::deployment
            Tsconfig["tsconfig.json"]:::deployment
            Smithery["smithery.yaml"]:::deployment
        end
    end

    %% Relationships
    Client -->|"SendsRequests"| API_Entry
    API_Entry -->|"CallsCRUDOperations"| Tasks_Module
    API_Entry -->|"InitiatesOAuth"| Auth_Module
    Auth_Module -->|"ConnectsTo"| OAuth_Service
    API_Entry -->|"InteractsWith"| Google_Tasks_API

    Docker_Container -->|"Deploys"| API_Entry
    Package_json -->|"Configures"| API_Entry
    Tsconfig -->|"Configures"| API_Entry
    Smithery -->|"Configures"| API_Entry

    %% Click Events
    click API_Entry "https://github.com/zcaceres/gtasks-mcp/blob/main/src/index.ts"
    click Tasks_Module "https://github.com/zcaceres/gtasks-mcp/blob/main/src/Tasks.ts"
    click Docker_Container "https://github.com/zcaceres/gtasks-mcp/tree/main/Dockerfile"
    click Package_json "https://github.com/zcaceres/gtasks-mcp/blob/main/package.json"
    click Tsconfig "https://github.com/zcaceres/gtasks-mcp/blob/main/tsconfig.json"
    click Smithery "https://github.com/zcaceres/gtasks-mcp/blob/main/smithery.yaml"

    %% Styles
    classDef client fill:#f9d,stroke:#333,stroke-width:2px;
    classDef internal fill:#ccf,stroke:#333,stroke-width:2px;
    classDef external fill:#cfc,stroke:#333,stroke-width:2px;
    classDef deployment fill:#fc9,stroke:#333,stroke-width:2px;
```
