Skip to main content
Glama
deenesjakoruzh
jerpint

paperpal

by jerpint
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

paperpal

ML literature research for agents and humans: find it, verify it, score it, cite it.

paperpal is a plugin for coding agents (Claude Code, Codex, and any MCP client). It gives your agent a research methodology and the tools to follow it:

  • Find: semantic search over top-tier venues (NeurIPS, ICML, ICLR, AISTATS, …), Hugging Face papers (with community upvotes), today's daily papers, trending models

  • Verify: arXiv metadata (current title and version, venue hints), Semantic Scholar (venue, citations), and full text via arxiv-txt.org with regex grep, so numbers get quoted in context

  • Score: an evidence card per paper (venue from three sources, citations, age, code link) with a suggested 1–5 credibility band. You or your agent make the final call.

  • Cite: a barebones notes template, rendered to a static HTML page where every citation is a clickable link. Select all → paste into Google Docs, and links and tables survive. LaTeX ($..$, $$..$$) is rendered with KaTeX; only pages that contain math get a script.

LLMs can still hallucinate and semantic search is never perfect. paperpal is built around making every claim checkable.

Install

Claude Code

git clone https://github.com/jerpint/paperpal
claude --plugin-dir ./paperpal

The plugin registers the paperpal skill and the paperpal MCP server (run with uv).

Codex

paperpal ships a portable Agent Plugins 1.0.0 manifest and a local marketplace:

git clone https://github.com/jerpint/paperpal
codex plugin marketplace add ./paperpal
codex plugin add paperpal@paperpal-local
codex mcp list        # → paperpal

Claude Desktop, Cursor, or any MCP client

Add the server to your client's MCP config (for Claude Desktop on macOS, that's ~/Library/Application Support/Claude/claude_desktop_config.json; for Cursor, .cursor/mcp.json):

{
  "mcpServers": {
    "paperpal": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/paperpal", "paperpal-mcp"]
    }
  }
}

Skill only

Any agent that reads the open skills format can use the methodology without the server: copy skills/paperpal/ into your agent's skills folder (e.g. .agents/skills/ for Codex). The skill falls back to the CLI.

CLI

cd paperpal && uv sync
uv run paperpal -h

Requires uv and Python ≥ 3.11.

Related MCP server: Research Assistant

Use

Ask your agent things like:

  • "Find peer-reviewed evidence that alignment training reduces output diversity, and score each source."

  • "Was this arXiv paper accepted anywhere? Check the exact number it reports for X."

  • "Prep research notes on small language models for a Google Doc: pointers only, every citation linked."

Or drive it directly:

uv run paperpal top "persona consistency role-playing" --n 5    # top-tier venues
uv run paperpal hf "ternary quantization" --n 5                 # Hugging Face papers
uv run paperpal daily                                           # today's HF daily papers
uv run paperpal meta 2510.22954                                 # arXiv metadata + venue hints
uv run paperpal card 2510.22954                                 # evidence card → suggested band
uv run paperpal full 2310.11324 --grep "76 accuracy points"     # verify a number in the full text
uv run paperpal new notes.md --title "My topic"                 # start from the template
uv run paperpal render notes.md                                 # → notes.html (gdoc-pasteable)

Tools

MCP tool

CLI

what it does

search_top_tier

top

semantic search over top-tier venue papers (paperz)

search_hf

hf

Hugging Face papers search (recency, upvotes)

daily_papers

daily

today's Hugging Face daily papers

trending_models

trending

trending models on the Hub

arxiv_meta

meta

arXiv title, authors, versions, comment / journal-ref venue hints

s2_lookup

s2

Semantic Scholar venue and citation counts

evidence_card

card

credibility evidence + a suggested 1–5 band with reasons

abstract

abs

abstract, categories and BibTeX (arxiv-txt)

full_text

full

full paper text, or regex matches with context

render_notes

render

linkify citations and write static, gdoc-pasteable HTML

—

new

create a notes doc from the template

The methodology

The skill (skills/paperpal/SKILL.md) tells agents how to research. The full guide is METHODOLOGY.md, which also works standalone for humans. In short:

  1. Primary sources only. Papers, model cards, repos, vendor posts. Blog summaries are leads, not citations.

  2. Verify every kept item: metadata → top-tier venue → the exact number in the full text.

  3. Score credibility (1–5) on venue, lab, public code and data, age, and replication. Build arguments on ≥4.5, hedge 3–4, and footnote or drop ≤2.

  4. Tag everything:

    • source type: [peer-reviewed] [preprint] [industry] [secondary] [news]

    • status: known / inferred / unknown

  5. Pointers, not prose, unless asked to write.

  6. Every citation is a link. Render to static HTML before sharing.

Configuration

env var

purpose

S2_API_KEY

optional Semantic Scholar API key. Unauthenticated requests share a small rate limit.

paperpal throttles requests per host (arXiv ≈ 1 request / 3 s), retries on 406 / 429 / 5xx, and falls back from arXiv to Hugging Face to arxiv-txt for metadata.

Development

See AGENTS.md. Quick version:

uv sync
uv run pytest -q              # offline tests
claude plugin validate .      # Claude Code manifest

Roadmap

  • BibTeX export (the arxiv-txt parser already captures BibTeX)

  • More venue sources for the evidence card

License

MIT

Available Tools

2 tools
fetch_paper_details_from_arxivB

Get the Arxiv info for a list of papers.

Args:
    arxiv_ids (list[str] | str): The IDs of the papers to get the Arxiv info for, e.g. ["2503.01469", "2503.01470"]
ParametersJSON Schema
NameRequiredDescriptionDefault
arxiv_idsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool fetches info but doesn't describe key behaviors like whether it's a read-only operation, error handling for invalid IDs, rate limits, or authentication needs. This is a significant gap for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, with the main purpose stated first and parameter details following. It uses two sentences efficiently, with no wasted words, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (1 parameter) and the presence of an output schema, the description is somewhat complete but has gaps. It covers the basic purpose and parameter usage but lacks behavioral details and usage guidelines. With an output schema, it doesn't need to explain return values, but overall it's only minimally adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaningful semantics beyond the input schema. The schema has 0% description coverage, but the description explains that 'arxiv_ids' can be a list or string and provides an example (e.g., ["2503.01469", "2503.01470"]), clarifying usage. With only one parameter, this compensates well for the low schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get the Arxiv info for a list of papers.' It specifies the verb ('Get') and resource ('Arxiv info'), making it understandable. However, it doesn't explicitly differentiate from the sibling tool 'semantic_search_papers_on_huggingface', which appears to be a search tool rather than a direct fetch by ID, so it misses full sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention the sibling tool or any other context for usage, such as prerequisites or scenarios where this tool is preferred over others. This leaves the agent without explicit direction on tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

semantic_search_papers_on_huggingfaceB

Search for papers on HuggingFace using semantic search.

Args:
    query (str): The query term to search for. It will automatically determine if it should use keywords or a natural language query, so format your queries accordingly.
    top_n (int): The number of papers to return. Default is 10, but you can set it to any number.

Returns:
    str: A list of papers with the title, summary, ID, and upvotes.
ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
top_nNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that the query 'will automatically determine if it should use keywords or a natural language query,' which adds some context about the tool's behavior. However, it lacks details on rate limits, authentication needs, error handling, or what happens with invalid inputs, which are important for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, with the core purpose stated first. The Args and Returns sections are structured clearly, though the 'Returns' section could be more concise (e.g., listing fields without full sentences). Overall, it's efficient with minimal waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (2 parameters, no annotations, but with an output schema), the description is reasonably complete. It explains the parameters and return format, and the output schema likely covers the return structure in detail. However, it could benefit from more behavioral context (e.g., search scope, limitations) to be fully comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds significant meaning beyond the input schema, which has 0% description coverage. It explains that 'query' can be keywords or natural language and will be automatically interpreted, and it specifies the default and flexibility for 'top_n'. This compensates well for the schema's lack of descriptions, though it doesn't cover all possible edge cases (e.g., query length limits).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Search for papers on HuggingFace using semantic search.' This specifies the verb (search), resource (papers on HuggingFace), and method (semantic search). However, it doesn't explicitly differentiate from the sibling tool 'fetch_paper_details_from_arxiv' (which appears to fetch details rather than search), so it doesn't reach the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. While it mentions semantic search, it doesn't explain when to prefer this over keyword-based search or the sibling tool. There's no mention of prerequisites, limitations, or typical use cases, leaving the agent with minimal context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updates
    • First observedfetch_paper_details_from_arxiv
    • First observedsemantic_search_papers_on_huggingface
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.3/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one fetches details for specific Arxiv papers by ID, while the other performs semantic searches on HuggingFace. There is no overlap in functionality or ambiguity between them.

Naming Consistency5/5

Both tools follow a consistent snake_case naming pattern with descriptive verb_noun structures (fetch_paper_details_from_arxiv and semantic_search_papers_on_huggingface). The naming is predictable and readable throughout.

Tool Count2/5

With only two tools, the server feels under-scoped for a paper-related domain. It lacks basic operations like listing papers, filtering, or managing collections, which limits its utility for comprehensive paper handling tasks.

Completeness2/5

The toolset is severely incomplete for paper management. It covers fetching details and searching, but misses essential CRUD operations (e.g., saving, organizing, or annotating papers) and lacks integration between the two sources, leaving significant gaps in workflow coverage.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • arxivsub-mcp

    arxivsub
    A
    license
    A
    quality
    F
    maintenance
    Enables searching arXiv and top AI conferences, finding related papers, generating research insights, and managing a personal library via MCP tools.
    5
    32 npm
    MIT

  • Research Assistant

    pytholic
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables searching arXiv papers, extracting paper information, listing paper topics, and generating structured research prompts through MCP tools, resources, and prompts.
    -

  • ResearchMCP

    Adityay009
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables LLMs to search arXiv, extract and analyze paper content, and build a personal semantically-searchable research library with saved papers and notes.
    -

  • ArXiv MCP Server

    joohyukjung
    A
    license
    A
    quality
    C
    maintenance
    Enables AI assistants to search and access arXiv papers through MCP. Supports paper filtering, downloading, and local storage for efficient access.
    10
    Apache 2.0

Appeared in Searches