pdf-utilities-mcp: Instructions file for Codex

PDF Utilities MCP - AI Agent Guide

Version: 1.0.1
Last Updated: 2026-02-22
Project Type: Model Context Protocol Server + VS Code Extension

---

🎯 Project Overview

PDF Utilities MCP is a dual-component system that provides PDF manipulation capabilities to AI assistants through the Model Context Protocol (MCP). It consists of:

1. MCP Server (./src/) - Implements 7 PDF tools using pdf-lib and pdf-parse
2. VS Code Extension (./extension/) - Registers the MCP server and integrates with GitHub Copilot

Core Capabilities

• Read & extract text from PDFs (with page range support)
• Get PDF metadata (pages, title, author, size, dates)
• Create PDFs from text with formatting options
• Merge multiple PDFs into one
• Split PDFs by page range
• Update PDF metadata
• Extract individual pages to separate files

---

🚀 Quick Start for AI Agents

Critical Path Rule: Always Use Relative Paths

// ✅ CORRECT - Use relative paths
identify_context({ file_path: "./src/index.ts" })
start_session({ context: "mcp-server", files: ["./src/pdf-tools.ts"] })

// ❌ WRONG - Never use absolute paths
identify_context({ file_path: "/Users/username/project/src/index.ts" })

Essential MCP Workflow

1. Identify Where You Are

   identify_context({ file_path: "./src/index.ts" })
   // Returns: { project: "pdf-utilities-mcp", context: "mcp-server" }

1. Check Active Session

   get_current_focus()
   // Returns current session state or null if none active

1. Start Focused Work (or load guidelines if continuing)

   start_session({
     context: "mcp-server",
     current_focus: "implementing new PDF tool",
     objectives: ["Add watermark tool", "Update tool registry"]
   })
   // OR if session exists:
   get_merged_guidelines({ context: "mcp-server" })

1. Do Your Work - Implement, debug, or refactor

2. Save Progress

   create_checkpoint({
     summary: "Completed watermark tool implementation",
     next_focus: "Add tests for watermark feature"
   })