# seonglae/mcp-notion architecture

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

- Interactive diagram: https://gitdiagram.com/seonglae/mcp-notion
- Repository: https://github.com/seonglae/mcp-notion

## Overview

##### And Highlight the Main Components
- Gateway/Entry Point: Illustrate components such as the gateway.ts and index.ts, which serve as the main endpoints/entrypoints into the server’s functionality.
- Prompts Module: Represent the “prompts” directory (with its index file and specific prompt handlers like summarize_note, suggest_refactor, etc.) that encapsulates all operations related to generating structured responses.
- Resources Module: Represent the “resources” directory that deals with accessing and converting Notion pages into Markdown notes with metadata (title, description, content, and MIME type).
- Tools Module: Represent the “tools” directory with functions such as search_notes, which performs query-based searches on Notion pages.
- Notion Integration/External Services: Emphasize the integration with Notion via the libraries (like @texonom/nclient), the usage of the ROOT_PAGE environment variable, and the API endpoints to interact with the actual Notion workspace.
- Remote Communication & Deployment: Include the SSEServerTransport framework and external integrations (for example, the integration with Claude Desktop and remote deployment instructions) that allow for remote use and inspector-based debugging.

##### Relationships and Data Flow
- That the Gateway (or main server entry point) accepts requests from either local scripts (via CLI commands) or remote clients.
- If the request is related to reading/notion page conversion, route it to the Resources module.
- If it involves searching through notes, route it to the Tools module.
- If it involves summarization or note analysis, route it to the Prompts module.
- That these modules may interact with each other and share a common set of Notion data (provided by the Notion integration libraries).

##### Architectural Patterns and Design Principles
- Modularity: Show a separation between distinct functionalities – note access, search, and prompt-driven processing – clearly defined in separate folders.
- External Integration: Emphasize the Notion integration and remote deployment options, including the flow from the environment variable configuration (ROOT_PAGE) to the context in which the server operates.
- Extensibility: Note how additional prompts or resources can be added easily by extending the respective module folders.

- Environmental configuration (environment variables like ROOT_PAGE) adjacent to the Gateway as they drive initial configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Notion MCP Server (notion-texonom)"
        GW["Gateway Module – Entry/Router"]:::core
        ENV["Env Config: ROOT_PAGE"]:::config
        PRM["Prompts Module – Analysis&Summarization"]:::core
        RES["Resources Module – NotionPageConverter"]:::core
        TLS["Tools Module – NotesSearch"]:::core
    end

    EXT["Notion Workspace/API"]:::external
    SSE["SSEServerTransport"]:::external
    INSP["MCP Inspector"]:::debug
    CLI["Local/Remote Client Requests"]:::client

    CLI --> GW
    ENV --> GW
    GW -->|"Routing:NotionConversion"| RES
    GW -->|"Routing:NoteSearch"| TLS
    GW -->|"Routing:PromptProcessing"| PRM
    RES -->|"Fetches"| EXT
    PRM -->|"Analyzes"| EXT
    TLS -->|"Queries"| EXT
    GW -->|"Communicates"| SSE
    GW -->|"Enables"| INSP
    PRM --- RES
    PRM --- TLS

    click GW "https://github.com/seonglae/mcp-notion/blob/main/src/gateway.ts"
    click GW "https://github.com/seonglae/mcp-notion/blob/main/src/index.ts"
    click PRM "https://github.com/seonglae/mcp-notion/tree/main/src/prompts"
    click PRM "https://github.com/seonglae/mcp-notion/blob/main/src/prompts/index.ts"
    click RES "https://github.com/seonglae/mcp-notion/tree/main/src/resources"
    click RES "https://github.com/seonglae/mcp-notion/blob/main/src/resources/index.ts"
    click TLS "https://github.com/seonglae/mcp-notion/tree/main/src/tools"
    click TLS "https://github.com/seonglae/mcp-notion/blob/main/src/tools/index.ts"

    classDef core fill:#E8F5E9,stroke:#1B5E20,stroke-width:2px;
    classDef external fill:#E3F2FD,stroke:#0D47A1,stroke-width:2px;
    classDef config fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef debug fill:#FFECB3,stroke:#FF6F00,stroke-width:2px;
    classDef client fill:#FCE4EC,stroke:#880E4F,stroke-width:2px;
```
