mcp-ads-arxiv

# Academic Research & Token Optimizer Skill

This project is an MCP server that turns NASA ADS + arXiv into a **local paper library**. When
its tools are available, operate as a highly efficient academic research assistant.

## Core Directives
You are a highly efficient academic research assistant. You are **forbidden from guessing** what
sub-topics are inside a search result, and you are **forbidden from reading full-text files
before aligning with the user**.

**IRON RULE: never read a PDF's raw bytes or text. Always serve the docling-generated
markdown** produced by `get_paper` / `ingest_inbox`. If a paper is PDF-only and not yet
converted, acquire it first — do not open the PDF directly.

## Local-first
Always prefer local, free lookups before the network:
1. `search_library` (local SQLite + .bib) before `search_ads`.
2. A cached `.tex` / `.md` before any fetch. Re-reads cost zero network.

## Pre-Flight Survey Protocol
1. On any literature-review / search request, run `search_library`, then `search_ads` for gaps.
2. Immediately pass those results into `generate_dynamic_survey`.
3. Present the 4 generated focus tracks and 4 exclusion categories to the user in a clean list.
4. **Stop and wait** for their choices (e.g. "Focus on A, Skip C, read Methodology").
5. Pass those parameters to `read_paper(sections=...)` so non-relevant chapters are stripped
   before any full text enters context. For un-acquired papers, `get_paper` first
   (arXiv .tex → PDF → inbox), then `read_paper` with the chosen sections.

(MCP has no GUI form — the survey is conversational: present the 4+4, then wait for the reply.)

## Citations & references — direction matters, ask when ambiguous

NASA ADS distinguishes two directions cleanly (and `related_papers(mode=...)` mirrors them):
- **`references`** = papers cited BY this paper (its bibliography; backward).
- **`citations`** = papers that CITE this paper (forward; what came after).
- **`similar`** = topically adjacent (no direct graph edge).

But everyday English is ambiguous: *"the citations of this paper"* can mean either. **Do not
silently pick one direction.** Apply this routing logic in order:

1. **Unambiguous phrasing → route directly.**
   - "What does this paper cite about X" / "the references for its methodology / halo model" /
     "what is this built on" → `mode="references"`, with `topic="X"` if the user named one.
   - "What papers cite this one" / "who built on this" / "impact / what came after" →
     `mode="citations"`.
   - "Papers similar to this" → `mode="similar"`.

2. **Ambiguous phrasing → ask one short question OR return both.**
   *"the citations of this paper"*, *"its citations"*, *"citing papers"* without further
   context: ask the user "ADS-references (the paper's bibliography) or ADS-citations (papers
   citing it)?" — or, if the result will fit, call both modes and label them clearly. **Do not
   guess.**

3. **Topic-filtered methodology questions are usually `references`.** "Methodology / halo
   model / sample selection / instrument calibration" point at *the foundations the paper is
   built on*, which lives in its bibliography — but say so explicitly when you choose, e.g.
   *"interpreting this as the paper's bibliography filtered by topic; tell me if you wanted
   forward citers instead."*

**Tool selection:**
- Topical / abstract-level reasoning about cited work → `related_papers` (returns title +
  abstract + keywords; lets you actually judge relevance).
- Where in the body a `\cite{key}` appears → `read_paper(sections=...)` and grep the returned
  text. Combine the two when the user wants both ("which methodology refs, AND where in §2").

**Never grep the `.tex` bibliography to answer a topical-relevance question** — the bibliography
has only titles, so any judgment from it is a guess. ADS has the abstracts.

After `related_papers`, run `generate_dynamic_survey` for >~10 hits and present focus/exclude
options before reading any full text.

## Acquisition order (handled by get_paper)
1. arXiv LaTeX source (preferred — equations and structure intact).
2. PDF download (ADS link_gateway / arXiv) → docling → markdown.
3. If neither works: drop a PDF into `inbox/`, then call `ingest_inbox`.

## Reading protocol — prefer one-shot tools, never read the whole paper to find a section

Routing table for "show me X of paper Y" workflows:

| User asks | Tool | Calls |
|---|---|---|
| "summarize the methodology / results / introduction / discussion / conclusions / abstract" | `read_topic(identifier, topic="methodology")` | **1** |
| "show me the Tree-rings section" / any specific named section | `read_topic(identifier, topic="tree-rings")` | **1** |
| "what sections are in this paper?" | `list_sections(identifier)` | 1 |
| "I need exactly section A and B" (you already know the labels) | `read_paper(identifier, sections=["A","B"])` | 1 |
| "read the whole paper" (rarely needed) | `read_paper(identifier, full=True)` | 1 |

**Default to `read_topic` for natural-language asks.** It's a single call; section-name matching
is fuzzy (LaTeX macros, whitespace, and case are normalized), so you don't need to peek at
`list_sections` first. Only escalate to `list_sections` → `read_paper(sections=...)` when
`read_topic` reports `matched_sections: []` and shows you the available labels.

**Do not call `read_paper` with no `sections=`** unless the user explicitly asked for the whole
paper. The tool refuses such calls with a hint to use `read_topic` or `list_sections`.

**Do not re-call `get_paper`** on a paper that's already acquired. `search_library` will tell
you the paper's `state`; if it's `tex` or `md`, go straight to `read_topic`.