Skip to content

Latest commit

 

History

History
67 lines (47 loc) · 2.36 KB

CLAUDE.md

File metadata and controls

67 lines (47 loc) · 2.36 KB

CLAUDE.md

This file provides guidance for Claude Code when working with this repository.

Project Overview

This is the Notion MCP Server - an MCP (Model Context Protocol) server that exposes the Notion API as MCP tools. It auto-generates tools from an OpenAPI specification.

Architecture

scripts/notion-openapi.json    # OpenAPI spec (source of truth for all tools)
        ↓
src/init-server.ts             # Loads & validates spec, creates MCPProxy
        ↓
src/openapi-mcp-server/
├── openapi/parser.ts          # Converts OpenAPI → MCP tools
├── mcp/proxy.ts               # Registers tools with MCP server
└── client/http-client.ts      # Executes API calls

Key Patterns

Adding New Endpoints

Only modify scripts/notion-openapi.json. Tools are auto-generated from the spec - no code changes needed elsewhere.

Tool Generation Flow

  1. OpenAPIToMCPConverter.convertToMCPTools() iterates all paths/operations
  2. Each operation becomes an MCP tool (name = operationId)
  3. Parameters + requestBody → inputSchema
  4. Response schema → returnSchema
  5. MCPProxy.setupHandlers() registers tools with the MCP SDK

Naming Conventions

  • Tool names come from OpenAPI operationId (e.g., retrieve-a-database)
  • Names are truncated to 64 chars and converted to title case for display

Common Commands

npm run build      # TypeScript compilation + CLI bundling
npm test           # Run vitest tests
npm run dev        # Start dev server with hot reload

File Structure

  • scripts/notion-openapi.json - OpenAPI 3.1.0 spec defining all Notion API endpoints
  • scripts/start-server.ts - Entry point
  • src/init-server.ts - Server initialization
  • src/openapi-mcp-server/ - Core MCP server implementation
    • openapi/parser.ts - OpenAPI to MCP conversion (529 lines)
    • mcp/proxy.ts - MCP tool registration and execution (209 lines)
    • client/http-client.ts - HTTP request execution (198 lines)

Testing

Tests are in __tests__ directories adjacent to source files. Run with npm test.

API Version

Uses Notion API version 2025-09-03 (Data Source Edition). The spec includes both:

  • /v1/databases/{database_id} - Traditional database endpoints
  • /v1/data_sources/{data_source_id} - New data source endpoints