From 3de035dc8d5f6e60f83daf68a70e87a06fa75715 Mon Sep 17 00:00:00 2001 From: Bryan Thompson Date: Mon, 23 Feb 2026 18:51:43 -0600 Subject: [PATCH] Add MCPB packaging and Claude Code plugin for pdf-server (#491) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add MCPB packaging and Claude Code plugin for pdf-server Two distribution paths for the pdf-server: 1. **MCPB bundle** (Claude Desktop MCP Directory): - manifest.json: v0.3 manifest with tools, compatibility, privacy - .mcpbignore: excludes source/tests from bundle - icon.png: 64x64 PDF document icon 2. **Claude Code plugin** (plugin/): - .mcp.json: declares local stdio server via npx - commands: /pdf-research:read, /pdf-research:summarize - skills: pdf-reading skill for document navigation - Tested end-to-end: MCP server connects, all tools available The plugin uses a local stdio MCP server pattern — the first known instance in a knowledge-work plugin (all existing plugins use remote HTTP connectors). Co-Authored-By: Claude Opus 4.6 (1M context) * Run prettier:fix to satisfy CI formatting checks Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- examples/pdf-server/.mcpbignore | 21 ++++++++ examples/pdf-server/icon.png | Bin 0 -> 549 bytes examples/pdf-server/manifest.json | 48 ++++++++++++++++++ .../plugin/.claude-plugin/plugin.json | 8 +++ examples/pdf-server/plugin/.mcp.json | 8 +++ examples/pdf-server/plugin/CONNECTORS.md | 16 ++++++ examples/pdf-server/plugin/README.md | 40 +++++++++++++++ examples/pdf-server/plugin/commands/read.md | 21 ++++++++ .../pdf-server/plugin/commands/summarize.md | 23 +++++++++ .../plugin/skills/pdf-reading/SKILL.md | 35 +++++++++++++ 10 files changed, 220 insertions(+) create mode 100644 examples/pdf-server/.mcpbignore create mode 100644 examples/pdf-server/icon.png create mode 100644 examples/pdf-server/manifest.json create mode 100644 examples/pdf-server/plugin/.claude-plugin/plugin.json create mode 100644 examples/pdf-server/plugin/.mcp.json create mode 100644 examples/pdf-server/plugin/CONNECTORS.md create mode 100644 examples/pdf-server/plugin/README.md create mode 100644 examples/pdf-server/plugin/commands/read.md create mode 100644 examples/pdf-server/plugin/commands/summarize.md create mode 100644 examples/pdf-server/plugin/skills/pdf-reading/SKILL.md diff --git a/examples/pdf-server/.mcpbignore b/examples/pdf-server/.mcpbignore new file mode 100644 index 0000000..fe11c64 --- /dev/null +++ b/examples/pdf-server/.mcpbignore @@ -0,0 +1,21 @@ +# Source files (built output in dist/ is what we need) +*.ts +tsconfig*.json +vite.config.ts +src/ + +# Tests +*.test.* + +# Development assets +screenshot.png +grid-cell.png +pdf-icon.svg + +# Plugin directory (separate distribution path) +plugin/ + +# Git and CI +.git/ +.github/ +.gitignore diff --git a/examples/pdf-server/icon.png b/examples/pdf-server/icon.png new file mode 100644 index 0000000000000000000000000000000000000000..fb7ea3ec7e35192490d43a91bb5e5107d847191e GIT binary patch literal 549 zcmeAS@N?(olHy`uVBq!ia0vp^4j|0I1|(Ny7TyC=jKx9jP7LeL$-D$|Tv8)E(|mmy zw18|52FCVG1{RPKAeI7R1_tH@j10^`nh_+nfC(<^uz(rC1}St4blLz^*6-=!7*fIb zcD7+&i-CyC|7DK^L^vNQbm%QVHBY(S@k6e-_ZKp?7*=q$N0@QwFeok75tzY{(s+Q4fv-`JL4--0L4qZXL4e~8 zgIwDOE(W=#f+&X5n<7F(!$e$lE__z`>$js~O8K`n*4Y=9F3Vi=+KT%-z{vPvkUxyvMQMb35@icFr_P_Q!_mtmfGKC+kOQ>JGd);NVg#CJdRxv!7S){4O z81whg?og%=K08IGGOVk6cvp+DVp&X=7en~|4|!7=Y=ZS%RU1~vS8VrUn5Q{?k=18.0.0" } + }, + "privacy_policies": ["https://www.anthropic.com/privacy"] +} diff --git a/examples/pdf-server/plugin/.claude-plugin/plugin.json b/examples/pdf-server/plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..f7442e7 --- /dev/null +++ b/examples/pdf-server/plugin/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "pdf-research", + "version": "0.1.0", + "description": "Read, navigate, and analyze PDF documents — academic papers, reports, and local files. Uses a local PDF MCP server for interactive viewing and text extraction.", + "author": { + "name": "Anthropic" + } +} diff --git a/examples/pdf-server/plugin/.mcp.json b/examples/pdf-server/plugin/.mcp.json new file mode 100644 index 0000000..f81cdb2 --- /dev/null +++ b/examples/pdf-server/plugin/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "pdf": { + "command": "npx", + "args": ["@modelcontextprotocol/server-pdf", "--stdio"] + } + } +} diff --git a/examples/pdf-server/plugin/CONNECTORS.md b/examples/pdf-server/plugin/CONNECTORS.md new file mode 100644 index 0000000..39def09 --- /dev/null +++ b/examples/pdf-server/plugin/CONNECTORS.md @@ -0,0 +1,16 @@ +# Connectors + +## Local MCP Server + +This plugin uses a **local MCP server** instead of a remote connector. +The PDF server runs on your machine via `npx`. + +| Category | Server | How it runs | +| ---------- | ---------------------------------- | -------------------------------------- | +| PDF viewer | `@modelcontextprotocol/server-pdf` | Local stdio via `npx` (auto-installed) | + +### Requirements + +- Node.js >= 18 +- Internet access for remote PDFs (arXiv, bioRxiv, etc.) +- No API keys or authentication needed diff --git a/examples/pdf-server/plugin/README.md b/examples/pdf-server/plugin/README.md new file mode 100644 index 0000000..32a80ab --- /dev/null +++ b/examples/pdf-server/plugin/README.md @@ -0,0 +1,40 @@ +# PDF Research Plugin + +Read and analyze PDF documents using a local MCP server. Designed for +academic paper review, document analysis, and research workflows. + +## What It Does + +- **Open PDFs** from local files, arXiv, bioRxiv, and other academic sources +- **Interactive viewer** with search, navigation, and zoom +- **AI-powered analysis** -- summarize, extract key points, compare papers + +## Commands + +| Command | What it does | +| ------------------------- | ---------------------- | +| `/pdf-research:read` | Open a PDF for reading | +| `/pdf-research:summarize` | Summarize a document | + +## How It Works + +This plugin uses a **local MCP server** (`@modelcontextprotocol/server-pdf`) +that runs on your machine via `npx`. No API keys or remote services needed -- +the PDF server starts automatically when the plugin loads. + +This is different from other knowledge-work plugins which use remote HTTP +connectors. The local server pattern enables offline PDF access and avoids +the need for a remote deployment. + +## Requirements + +- Node.js >= 18 +- Internet for remote PDFs (arXiv, etc.) + +## Supported PDF Sources + +- Local files (file paths in your working directory) +- [arXiv](https://arxiv.org) papers +- [bioRxiv](https://biorxiv.org) / [medRxiv](https://medrxiv.org) preprints +- [chemRxiv](https://chemrxiv.org), [Zenodo](https://zenodo.org), [OSF](https://osf.io) +- [HAL Science](https://hal.science), [SSRN](https://ssrn.com) diff --git a/examples/pdf-server/plugin/commands/read.md b/examples/pdf-server/plugin/commands/read.md new file mode 100644 index 0000000..39817bc --- /dev/null +++ b/examples/pdf-server/plugin/commands/read.md @@ -0,0 +1,21 @@ +--- +description: Open a PDF for reading and analysis +--- + +# Read PDF + +Open a PDF document for interactive reading. Accepts local file paths, +arXiv URLs, or other academic paper URLs. + +## Instructions + +1. If the user provides a URL or file path, call `display_pdf` with that URL +2. If no URL given, call `list_pdfs` first to show available documents +3. After displaying, offer to summarize, extract key points, or answer questions + +## Supported Sources + +- Local files (drag-and-drop or file path) +- arXiv papers (arxiv.org/abs/... or arxiv.org/pdf/...) +- bioRxiv, medRxiv, chemRxiv preprints +- Zenodo, OSF, HAL, SSRN diff --git a/examples/pdf-server/plugin/commands/summarize.md b/examples/pdf-server/plugin/commands/summarize.md new file mode 100644 index 0000000..62ee4ba --- /dev/null +++ b/examples/pdf-server/plugin/commands/summarize.md @@ -0,0 +1,23 @@ +--- +description: Summarize the current PDF or a new document +--- + +# Summarize PDF + +Generate a structured summary of a PDF document. + +## Instructions + +1. If a PDF is already displayed, work with it +2. If user provides a new URL/path, call `display_pdf` first +3. Read through the document and produce: + - **Title and authors** (if academic paper) + - **Key findings** (3-5 bullet points) + - **Methodology** (brief summary) + - **Conclusions** + - **Relevance** — what makes this paper notable + +## Notes + +- For long documents, focus on abstract, introduction, and conclusion sections +- Ask the user which sections they care most about if the doc is very long diff --git a/examples/pdf-server/plugin/skills/pdf-reading/SKILL.md b/examples/pdf-server/plugin/skills/pdf-reading/SKILL.md new file mode 100644 index 0000000..2e79917 --- /dev/null +++ b/examples/pdf-server/plugin/skills/pdf-reading/SKILL.md @@ -0,0 +1,35 @@ +--- +name: pdf-reading +description: Read and navigate PDF documents using the local PDF server. Reference this when the user wants to open, read, search, or interact with any PDF file or academic paper. +--- + +# PDF Reading + +You have access to a local PDF server that provides interactive document viewing. + +## Available Tools + +- **list_pdfs** -- Show available PDFs. Call with no arguments. +- **display_pdf** -- Open a PDF in the interactive viewer. + - `url` (string): URL or local file path + - `page` (number, optional): Starting page number + +## How to Use + +**When the user mentions a PDF, paper, or document:** +1. If they give a URL or path, call `display_pdf` directly +2. If they say "open the paper" without specifying, call `list_pdfs` to show options +3. After displaying, offer to summarize, extract data, answer questions + +**arXiv shortcuts:** +- `arxiv.org/abs/2301.12345` is auto-converted to the PDF URL +- Users can just say "open arxiv 2301.12345" + +**Supported remote sources:** +arXiv, bioRxiv, medRxiv, chemRxiv, Zenodo, OSF, HAL Science, SSRN + +## Best Practices + +- Always display the PDF before trying to analyze it +- For multi-page documents, ask which section the user cares about +- When comparing papers, display them one at a time and note key differences