# makenotion/notion-mcp-server architecture

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

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

## Overview

##### Main Components
- Entry Points & Server Initialization:
- scripts/start-server.ts and src/init-server.ts serve as the launch points for the server.
- Core Server Functionality (inside src/openapi-mcp-server):
- auth Module: Contains authentication logic. Include its index file, template, and type definitions.
- client Module: Responsible for handling HTTP client operations – note that it includes tests for integration.
- mcp Module: Implements the MCP protocol aspects (e.g., proxying requests), with components like the proxy.ts.
- openapi Module: Contains functionality to parse and handle OpenAPI specifications and file uploads.
- Supporting Files:
- Build scripts, configuration (e.g., package.json, tsconfig.json), and test suites provide context but are not part of runtime architecture.
- External Dependencies:
- Notion API: While not hosted in the project, integration details in the README indicate how the MCP server acts on behalf of this external service.
- Environment variables as configured (e.g., OPENAPI_MCP_HEADERS).

##### Relationships & Data Flow
- The “start-server” script (entry point) initializes the server, hooking together the MCP, auth, client, and openapi modules.
- The auth module likely intercepts or processes requests that require authentication, using defined templates and types.
- The client module handles outgoing HTTP calls (e.g., communication with Notion or other APIs) and coordinates with the mcp and openapi modules.
- The mcp module acts as a mediator that maps high-level instructions into the appropriate series of API calls. For example, it might take a command like adding a page and direct that into API calls such as "v1/search" and "v1/comments".
- The openapi module plays a critical role in parsing and dealing with OpenAPI specifications, ensuring proper file upload handling and overall compliance with the protocol.

##### Architectural Patterns & Design Principles
- Modular Design: The code is partitioned into function-specific sub-modules (auth, client, mcp, openapi). This modular division is ideal for isolating responsibilities.
- Layered Communication: Input from an API request goes through the initialization layer, then through authentication and protocol conversion layers before reaching the client that interacts with Notion.
- Test-Driven: Presence of tests in each module indicates that the design is strongly oriented to verification at each layer.

##### Technologies & Frameworks
- Node.js with TypeScript is the main technology, as indicated by .ts files and tsconfig.json.
- Notion API integration is central to the project.
- npm is used for package management and build automation.

##### Final Advice
- Clarity and comprehensiveness – break down the project into the smallest logical components corresponding to actual directories/files.
- While high-level connections suffice, ensure you also incorporate any relevant lower-level interactions (like parsing of multipart forms in the openapi module) if they significantly alter the data flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Notion MCP Server"
        subgraph "Server Initialization"
            SS("Start Server"):::entrypoint
            IS("Init Server"):::entrypoint
        end
        subgraph "Core Modules"
            subgraph "Authentication Module"
                AuthIndex("Index"):::module
                AuthTemplate("Template"):::module
                AuthTypes("Types"):::module
            end
            subgraph "MCP Processing Module"
                McpProxy("Proxy"):::module
            end
            subgraph "HTTP Client Service"
                HttpClient("HTTP Client"):::module
            end
            subgraph "OpenAPI Handling Module"
                OpenApiParser("Parser"):::module
                OpenApiUpload("File Upload"):::module
            end
        end
    end

    Ext("Notion API"):::external

    %% Initialization linking to modules
    SS -->|"initialize"| AuthIndex
    SS -->|"initialize"| McpProxy
    SS -->|"initialize"| HttpClient
    SS -->|"initialize"| OpenApiParser

    IS -->|"initialize"| AuthIndex
    IS -->|"initialize"| McpProxy
    IS -->|"initialize"| HttpClient
    IS -->|"initialize"| OpenApiParser

    %% Module interactions
    McpProxy -->|"calls"| HttpClient
    HttpClient -->|"APIRequest"| Ext

    %% Click Events
    click SS "https://github.com/makenotion/notion-mcp-server/blob/main/scripts/start-server.ts"
    click IS "https://github.com/makenotion/notion-mcp-server/blob/main/src/init-server.ts"
    click AuthIndex "https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/index.ts"
    click AuthTemplate "https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/template.ts"
    click AuthTypes "https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/auth/types.ts"
    click HttpClient "https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/client/http-client.ts"
    click McpProxy "https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/mcp/proxy.ts"
    click OpenApiParser "https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/parser.ts"
    click OpenApiUpload "https://github.com/makenotion/notion-mcp-server/blob/main/src/openapi-mcp-server/openapi/file-upload.ts"

    %% Styles
    classDef entrypoint fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef module fill:#87CEFA,stroke:#1E90FF,stroke-width:2px;
    classDef external fill:#90EE90,stroke:#32CD32,stroke-width:2px;
```
