How makenotion/notion-mcp-server works
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.