PDF Utilities

A VS Code extension that provides comprehensive PDF manipulation tools for GitHub Copilot Chat via Model Context Protocol (MCP).

Overview

This project combines an MCP server with a VS Code extension to enable AI assistants like GitHub Copilot to work with PDF files through natural language commands. Users can read, create, merge, split, and edit PDFs directly from their chat interface.

Architecture

pdf-utilities-mcp/
├── src/                   # MCP Server implementation
│   ├── index.ts          # Server entry point and tool registration
│   └── pdf-tools.ts      # PDF manipulation utilities
├── extension/            # VS Code Extension
│   ├── src/
│   │   ├── extension.ts # Extension activation and MCP integration
│   │   └── types.ts     # TypeScript type definitions
│   ├── resources/
│   │   └── instructions/ # Copilot Chat instruction files
│   └── mcp-server/      # Built MCP server (copied from ../dist)
└── dist/                # Compiled MCP server output

Features

• 📖 Read PDFs: Extract text content with optional page range selection
• 📊 Get Info: Retrieve metadata (pages, title, author, size, etc.)
• ✍️ Create PDFs: Generate new PDFs from text with formatting options
• 🔗 Merge: Combine multiple PDF files into one
• ✂️ Split: Extract specific pages or ranges
• 📝 Update Metadata: Modify title, author, subject, keywords
• 📄 Extract Pages: Save individual pages as separate files

Installation

For Users

Install from VS Code Marketplace:

1. Open VS Code
2. Search for "PDF Utilities" in Extensions
3. Click Install

For Developers

# Clone the repository
git clone https://github.com/GleidsonFerSanP/pdf-utilities-mcp.git
cd pdf-utilities-mcp

# Install MCP server dependencies
npm install

# Build MCP server
npm run build

# Install extension dependencies
cd extension
npm install

# Build extension
npm run compile

# Copy MCP server to extension
cd ..
npm run copy-to-extension

Development

Project Structure

MCP Server ( src/ ):

• Uses @modelcontextprotocol/sdk for standardized tool interface
• Implements 7 PDF tools using pdf-lib and pdf-parse
• Runs as Node.js process via stdio transport

VS Code Extension ( extension/ ):

• Registers MCP server with VS Code's lm.registerMcpServerDefinitionProvider
• Provides commands for configuration and server management
• Includes chat instructions for optimal Copilot integration

Building

# Build MCP server
npm run build

# Build extension
cd extension
npm run compile

# Copy server to extension folder
cd ..
npm run copy-to-extension

Testing

# Test MCP server directly
node dist/index.js

# Package extension for testing
cd extension
npm run package  # Creates .vsix file

# Install .vsix in VS Code for testing
# Extensions > ... > Install from VSIX

Development Workflow

1. Make changes to MCP server in src/
2. Run npm run build to compile
3. Run npm run copy-to-extension to update extension
4. Reload VS Code window to test changes
5. Check logs in Output panel > "PDF Utilities"

Publishing

Prerequisites

1. Create VS Code Publisher account at https://marketplace.visualstudio.com/
2. Generate Personal Access Token (PAT)
3. Update extension/.env with your PAT

Publish Steps

# Build everything
npm run build
cd extension
npm run compile
cd ..
npm run copy-to-extension

# Package extension
cd extension
npm run package

# Verify the .vsix file works
# Install it manually in VS Code and test

# Publish to marketplace
npm run publish

Version Management

Update version in both:

• package.json (root)
• extension/package.json

Follow semantic versioning: MAJOR. MINOR. PATCH

Configuration

Extension Settings

• pdfUtilities.autoStart: Auto-start MCP server (default: true)
• pdfUtilities.logLevel: Logging verbosity (default: info)
• pdfUtilities.maxPdfSize: Maximum file size in MB (default: 50)

MCP Server Configuration

The MCP server is configured via the extension and doesn't require separate configuration.

API Documentation

Tool: read_pdf

Extract text from PDF file.

Parameters:

• filePath (string, required): Absolute path to PDF
• pageRange (string, optional): Pages to extract (e.g., "1-5", "1, 3, 5-10")

Returns:

{
  text: string;
  pages: number;
  info: PDFInfo;
}

Tool: get_pdf_info

Get PDF metadata and information.

Parameters:

• filePath (string, required): Absolute path to PDF

Returns:

{
  pages: number;
  title?: string;
  author?: string;
  subject?: string;
  creator?: string;
  producer?: string;
  creationDate?: Date;
  modificationDate?: Date;
  fileSize: number;
  filePath: string;
}

Tool: create_pdf

Create new PDF from text content.

Parameters:

• content (string, required): Text content
• outputPath (string, required): Save location
• options (object, optional): Formatting options
  • title, author, subject (string): Metadata
  • fontSize (number): Text size (default: 12)
  • pageSize (string): Page size (default: "A4")

Returns:

{
  success: boolean;
  path: string;
  pages: number;
}

Tool: merge_pdfs

Combine multiple PDFs.

Parameters:

• filePaths (string[], required): PDFs to merge
• outputPath (string, required): Output location

Returns:

{
  success: boolean;
  path: string;
  pages: number;
}

Tool: split_pdf

Extract pages to new PDF.

Parameters:

• filePath (string, required): Source PDF
• pageRange (string, required): Pages to extract
• outputPath (string, required): Output location

Returns:

{
  success: boolean;
  path: string;
  pages: number;
}

Tool: update_pdf_metadata

Modify PDF metadata.

Parameters:

• filePath (string, required): PDF to update
• metadata (object, required): Fields to update
  • title, author, subject, keywords (string)
• outputPath (string, optional): Save location (defaults to overwrite)

Returns:

{
  success: boolean;
  path: string;
}

Tool: extract_pages

Extract pages to separate files.

Parameters:

• filePath (string, required): Source PDF
• pages (number[], required): Page numbers to extract
• outputDir (string, required): Output directory
• prefix (string, optional): Filename prefix (default: "page")

Returns:

{
  success: boolean;
  files: string[];
}

Troubleshooting

MCP Server Not Starting

Check Output panel:

View > Output > Select "PDF Utilities"

Look for initialization messages. If server fails:

1. Verify mcp-server/index.js exists in extension folder
2. Run rebuild: npm run build && npm run copy-to-extension
3. Reload VS Code

Tools Not Available in Copilot

1. Ensure extension is activated (check Extensions panel)
2. Verify MCP API is available (requires VS Code 1.85+)
3. Check that Copilot Chat is enabled
4. Restart Copilot: Command Palette > "GitHub Copilot: Restart Language Server"

Build Errors

Common issues:

• TypeScript errors: Run npm install in both root and extension folders
• Missing dependencies: npm install in correct directory
• Path issues: Use npm run copy-to-extension to sync files

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Please follow existing code style and conventions.

License

MIT License - see LICENSE file for details.

Support

• GitHub Issues
• Documentation

Credits

• Built with Model Context Protocol
• PDF processing by pdf-lib and pdf-parse
• Icon design: Custom SVG

---

Note: This project requires GitHub Copilot Chat and VS Code 1.85+ with MCP support.