This is an MCP (Model Context Protocol) server that auto-generates AI-agent-friendly tools from the Notion REST API OpenAPI specification. It runs as a CLI tool (stdio transport) or an HTTP server (Streamable HTTP transport), exposing 24 tools covering users, search, blocks, pages, comments, data sources, and databases — including dedicated markdown read/write endpoints. The architecture follows a clean three-layer design: an OpenAPI-to-MCP converter (`parser.ts`) that transforms each operation into a tool with JSON Schema input/output; an MCP proxy (`proxy.ts`) that handles tool listing/calling and deserializes double-encoded JSON parameters (a known MCP client issue); and an HTTP client (`http-client.ts`) that executes the actual API calls using axios and openapi-client-axios. Notable engineering highlights include per-operation `Notion-Version` header sourcing from the spec (so each endpoint can pin its required API version), a per-request token passthrough mechanism for multi-tenant deployments, and comprehensive test coverage with snapshot tests locking the tool surface. The repo is well-structured TypeScript with clear separation of concerns, though the README signals that this local MCP server may be sunset in favor of a newer remote MCP offering.

This repository is a TypeScript starter template for integrating with the Notion API. It provides a minimal setup for a Node.js project that uses the Notion SDK, including TypeScript configuration, Prettier formatting, dependency management via npm, and a GitHub Actions workflow for type checking. The main application code in `src/index.ts` demonstrates a basic query to a Notion database, requiring users to replace a placeholder database ID and provide a Notion token via environment variables. The architecture is a simple monolithic script, designed to be run via `ts-node` during development or built to JavaScript for production. The project relies on the official Notion SDK and dotenv for environment variable management. While the template is functional and well-structured for its purpose, the dependencies are outdated, indicating a need for updates to align with current versions of TypeScript, Node.js types, and other tooling.