mcp-server-pdfnoodle: Instructions file for Claude Code

CLAUDE.md - Project Guide for AI Assistants

Mandatory Rules for Every Change

IMPORTANT: Whenever you make ANY change to this project, you MUST:

1. Bump the version in package.json ("version" field) following semver:
   • Patch (x.x.X): bug fixes, small tweaks
   • Minor (x.X.0): new features, non-breaking changes
   • Major (X.0.0): breaking changes
2. Add a changelog entry in the ## Changelog table at the bottom of README.md, following the existing format:

   | <version> | <YYYY-MM-DD> | **<Type>**: Description of changes. |
   

   Types: Feature, Bug Fix, Refactor, Docs, Breaking Change

---

Project Overview

mcp-server-pdfnoodle is an MCP (Model Context Protocol) server that enables AI assistants (Claude, ChatGPT, etc.) to generate PDF documents through the pdf noodle API.

• Language: TypeScript (strict mode)
• Runtime: Node.js >= 18 (ES Modules)
• Protocol: MCP over stdio (JSON-RPC 2.0)
• License: MIT
• npm package: mcp-server-pdfnoodle
• Repository: https://github.com/pdfnoodle/mcp-server-pdfnoodle

Architecture

src/
├── index.ts          # CLI entry point (shebang, reads PDFNOODLE_API_KEY, starts server)
├── server.ts         # MCP server setup (createServer, tool registration loop)
├── client.ts         # PdfNoodleClient class (HTTP calls to api.pdfnoodle.com/v1/)
├── types.ts          # TypeScript interfaces (API responses, templates)
└── tools/
    ├── index.ts      # Tool registry (exports combined tools array)
    ├── templates.ts  # 4 template tools (list, get, getSchema, createWithAi)
    └── pdf.ts        # 3 PDF tools (generate, htmlToPdf, checkStatus)

Key design patterns:

• Tool-based architecture: each tool is an object with name, description, schema (Zod), and handler
• Single API client singleton (client in client.ts) shared across all tools
• Dual-mode PDF generation: sync (immediate) and async (polling via requestId)
• All tool handlers receive (apiKey, args) and return MCP content responses