# baonguyen09/github-second-brain architecture

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

- Interactive diagram: https://gitdiagram.com/baonguyen09/github-second-brain
- Repository: https://github.com/baonguyen09/github-second-brain

## Overview

##### Project type and purpose
- This is an open-source, self-hosted MCP (Model Context Protocol) server packaged as a Dockerized Python application.
- Its purpose is to expose tools over MCP so an AI assistant (LLM) can fetch targeted information (directory tree, file contents, issue context) from arbitrary GitHub repositories without exceeding its context window.

##### File structure
- Top level
- Dockerfile – builds the MCP server image
- .github/workflows/docker-publish.yml – CI/CD pipeline to build & push the image to GitHub Container Registry
- mcp/ – core Python application
- Under mcp/
- main.py – MCP server entrypoint (registers tools, handles requests)
- requirements.txt – Python dependencies
- tools/
– fetch_directory_tree.py
– fetch_file_contents.py
– fetch_issue_context.py
– custom_errors.py
- assets/images and README.md provide documentation and branding.

##### README for additional insights
- The README describes the MCP tools and their use cases.
- It shows how AI clients (e.g., Claude Desktop, Cursor) integrate by running the Docker container locally and making tool calls.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors and external services
    Developer["Developer"]:::external
    AIClient["AI Client (LLM)"]:::external
    GitHubAPI["GitHub REST API"]:::external
    ContainerRegistry[(ghcr.io)]:::registry

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        GitHubActions["GitHub Actions\n(docker-publish.yml)"]:::ci
    end

    %% Documentation
    subgraph Documentation
        direction TB
        README["README.md"]:::docs
        Images["assets/images"]:::docs
    end

    %% Containerized MCP Server
    subgraph "MCP Server (Docker Container)" 
        direction TB
        DockerImage["Dockerfile"]:::container
        subgraph "Core Application"
            direction TB
            MCPMain["mcp/main.py"]:::module
            Requirements["mcp/requirements.txt"]:::module
            DockerIgnore["mcp/.dockerignore"]:::module
            subgraph "Tools Module"
                direction TB
                DirTree["fetch_directory_tree.py"]:::module
                FileContents["fetch_file_contents.py"]:::module
                IssueContext["fetch_issue_context.py"]:::module
                Errors["custom_errors.py"]:::module
            end
        end
    end

    %% Flows
    Developer -->|"push code"| GitHubActions
    GitHubActions -->|"build & push image"| ContainerRegistry
    AIClient -->|"pull image & run"| DockerImage
    AIClient -->|"send MCP request"| MCPMain
    MCPMain -->|"dispatch to tools"| DirTree
    MCPMain -->|"dispatch to tools"| FileContents
    MCPMain -->|"dispatch to tools"| IssueContext
    DirTree -->|"call GitHub API"| GitHubAPI
    FileContents -->|"call GitHub API"| GitHubAPI
    IssueContext -->|"call GitHub API"| GitHubAPI
    GitHubAPI -->|"return data"| MCPMain
    MCPMain -->|"respond via MCP"| AIClient
    Developer -->|"write docs"| README
    Developer -->|"add images"| Images

    %% Click Events
    click DockerImage "https://github.com/baonguyen09/github-second-brain/tree/main/Dockerfile"
    click GitHubActions "https://github.com/baonguyen09/github-second-brain/blob/main/.github/workflows/docker-publish.yml"
    click MCPMain "https://github.com/baonguyen09/github-second-brain/blob/main/mcp/main.py"
    click Requirements "https://github.com/baonguyen09/github-second-brain/blob/main/mcp/requirements.txt"
    click DockerIgnore "https://github.com/baonguyen09/github-second-brain/blob/main/mcp/.dockerignore"
    click DirTree "https://github.com/baonguyen09/github-second-brain/blob/main/mcp/tools/fetch_directory_tree.py"
    click FileContents "https://github.com/baonguyen09/github-second-brain/blob/main/mcp/tools/fetch_file_contents.py"
    click IssueContext "https://github.com/baonguyen09/github-second-brain/blob/main/mcp/tools/fetch_issue_context.py"
    click Errors "https://github.com/baonguyen09/github-second-brain/blob/main/mcp/tools/custom_errors.py"
    click README "https://github.com/baonguyen09/github-second-brain/blob/main/README.md"
    click Images "https://github.com/baonguyen09/github-second-brain/tree/main/assets/images"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef ci fill:#ffd,stroke:#b55,stroke-width:1px
    classDef registry fill:#cfc,stroke:#363,stroke-width:1px
    classDef container fill:#ccf,stroke:#336,stroke-width:1px
    classDef module fill:#eef,stroke:#446,stroke-width:1px
    classDef docs fill:#ffe,stroke:#aa6,stroke-width:1px
```
