# chy168/google-chat-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/chy168/google-chat-mcp-server
- Repository: https://github.com/chy168/google-chat-mcp-server

## Overview

##### Project Type and Purpose
- This is a Python-based full-stack integration tool.
- It provides an MCP (Model Control Protocol) server extension with Google Chat capabilities and a standalone OAuth2 authentication service.
- The MCP server (server.py + google_chat.py) implements FastMCP commands to list spaces and messages.
- The auth server (server_auth.py) implements a FastAPI app to handle Google OAuth2 flows and persist tokens.

##### Top-Level Components
- Auth Server (FastAPI)
- Entry point: server_auth.py
- OAuth2 flow with Google’s auth endpoints
- Reads credentials.json, writes token.json
- MCP Server (FastMCP)
- Entry point: server.py
- Uses google_chat.py for API calls
- Exposes MCP tools: get_chat_spaces(), get_space_messages()
- Google Chat API (External Service)
- Token Store (Local JSON file: token.json)
- Client (Browser or MCP client issuing commands)

##### Relationships and Data Flows
a. User opens browser → hits Auth Server (/auth) → redirected to Google OAuth2 page
b. Google returns authorization code → Auth Server exchanges code for tokens → saves tokens in token.json
c. MCP Server reads token.json → google_chat.py uses refresh/access tokens to call Google Chat API
d. Google Chat API returns spaces or messages → MCP Server formats results for the MCP client

##### Architectural Patterns and Principles
- Separation of concerns: Auth logic isolated in FastAPI service; Chat logic in MCP server.
- Token persistence: Simple local JSON storage module.
- Pluggable commands: FastMCP decorators in server.py register Google Chat tools.
- Configurable via mcp.json for integration into larger MCP deployments.

##### Key Technologies and Libraries
- FastAPI (Auth Server)
- FastMCP (MCP Server framework)
- google-auth, google-auth-oauthlib (OAuth2 flows)
- requests (HTTP calls to Google APIs)
- Python 3.8+

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Files
    subgraph "Configuration & Metadata"
        direction TB
        Credentials["credentials.json"]
        MCPConfig["mcp.json template"]
        README["README.md"]
        LICENSE["LICENSE"]
        pyproject["pyproject.toml"]
        requirements["requirements.txt"]
        uvlock["uv.lock"]
    end

    %% Main Flow
    CBrowser["Client/Browser"]:::client -->|"1. GET /auth"| AuthServer["Auth Server (FastAPI)\nserver_auth.py"]:::internal
    AuthServer -->|"2. redirect to Google OAuth2"| OAuthEP["Google OAuth2 Endpoint"]:::external
    OAuthEP -->|"3. callback with code"| AuthServer
    AuthServer -->|"4. store tokens"| TokenStore["Token Store\ntoken.json"]:::storage
    
    %% MCP Server and Module
    TokenStore -->|"5. read tokens"| MCPServer["MCP Server (FastMCP)\nserver.py"]:::internal
    subgraph "MCP Server Modules"
        direction TB
        google_module["google_chat.py"]:::internal
    end
    MCPServer --> google_module
    MCPServer -->|"6. REST calls"| GCAPI["Google Chat API"]:::external
    GCAPI -->|"7. spaces & messages JSON"| MCPServer
    MCPServer -->|"8. tool output"| MPCli["MCP Client/CLI"]:::client

    %% Tests
    tests["tests/"]:::validation

    %% Click Events
    click AuthServer "https://github.com/chy168/google-chat-mcp-server/blob/main/server_auth.py"
    click MCPServer "https://github.com/chy168/google-chat-mcp-server/blob/main/server.py"
    click google_module "https://github.com/chy168/google-chat-mcp-server/blob/main/google_chat.py"
    click src "https://github.com/chy168/google-chat-mcp-server/blob/main/src/mcp_gcp_chat_py/__init__.py"
    click tests "https://github.com/chy168/google-chat-mcp-server/blob/main/tests/__init__.py"
    click pyproject "https://github.com/chy168/google-chat-mcp-server/blob/main/pyproject.toml"
    click requirements "https://github.com/chy168/google-chat-mcp-server/blob/main/requirements.txt"
    click uvlock "https://github.com/chy168/google-chat-mcp-server/blob/main/uv.lock"
    click README "https://github.com/chy168/google-chat-mcp-server/blob/main/README.md"
    click LICENSE "https://github.com/chy168/google-chat-mcp-server/tree/main/LICENSE"

    %% Styles
    classDef internal fill:#cfe2f3,stroke:#0366d6,stroke-width:2px;
    classDef external fill:#ffe5b4,stroke:#d97706,stroke-width:2px,stroke-dasharray: 5 5;
    classDef storage fill:#d1e7dd,stroke:#198754,stroke-width:2px,shape:cylinder;
    classDef client fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef validation fill:#f8d7da,stroke:#d63384,stroke-width:2px,stroke-dasharray: 2 2;
```
