pdffigures-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Architecture

This is a FastAPI service that wraps PDFFigures 2.0, a Scala/JVM tool from Allen AI, to extract figures, tables, and captions from scholarly PDFs. It also exposes a FastMCP tool so AI agents can invoke extraction programmatically.

Client (HTTP/MCP) → FastAPI (app.py) → service.py (subprocess) → pdffigures2 JAR (Scala/JVM)
                                                      ↓
                                              Rendered PNGs + JSON metadata

• app/app.py — FastAPI server + FastMCP tool. Three entry points: REST API (/api/extract), MCP (/mcp), and static file serving (/resources). The core extraction logic (extract_pdf_logic) is shared between the REST and MCP paths. The MCP tool is extract_figures_from_pdf(pdf_url).
• app/service.py — Runs pdffigures2.jar via subprocess.run with a 180s timeout. Reads the output JSON metadata file after the JAR completes. This runs synchronously, so callers must use run_in_threadpool.
• app/utils.py — File I/O helpers (save_uploaded_file, read_output_file).
• figure_extractor.py — Standalone CLI client that POSTs a local PDF to the API and downloads the rendered figures. Run with python figure_extractor.py <path_to_pdf>.
• skills/pdffigures2/ — Agent Skill providing a non-MCP alternative. The CLI script (scripts/pdffigures2) is an API client that POSTs a local PDF to the extraction server and downloads rendered figures. Reads server URL from .env (copy .env.example to .env).

Commands

# Build and run with Docker
docker build -t pdf-extraction .
docker run -p 5001:5001 pdf-extraction

# Run locally (requires pdffigures2 JAR at the expected path)
python -m uvicorn app.app:app --host 0.0.0.0 --port 5001

# Test extraction via CLI
python figure_extractor.py <path-to-pdf>

# API docs
open http://localhost:5001/docs