Metadata-Version: 2.4
Name: essencescholar-mcp
Version: 0.6.0
Summary: MCP server exposing EssenceScholar deep research and paper workflows as agent tools
Project-URL: Homepage, https://essencescholar.com
Project-URL: Repository, https://github.com/EssenceScholar/EssenceScholar-MCP
Author-email: EssenceScholar <admin@essencescholar.com>
License: MIT
Keywords: agent,economics,llm,mcp,research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp[cli]>=1.3
Requires-Dist: pypdf>=4
Description-Content-Type: text/markdown

# EssenceScholar MCP Server

MCP server exposing the [EssenceScholar](https://essencescholar.com) deep research pipeline and paper workflows as agent tools.

## Tools

**Research pipeline**
- **deep_research** — full literature review pipeline (2–8 min, searches EconPapers/arXiv/SSRN, enriches top papers, generates a structured draft)
- **deep_research_chat** — follow-up on an existing session (ask questions, expand, dig deeper)
- **list_deep_researches** — list all past research sessions
- **get_deep_research** — retrieve any past draft by ID

**Search & library**
- **search_econpapers** — raw EconPapers search, returns JSON paper objects
- **search_ssrn** — raw SSRN search, returns JSON paper objects
- **download_paper** — download a found paper (EconPapers/SSRN/arXiv/DOI URL) into your library and get its `paper_id`
- **upload_paper** — upload a local PDF into your library and get its `paper_id`
- **register_paper_text** — register a local PDF by extracting its text client-side (no server OCR); `paper_id` derived from the sha256 of the PDF bytes, so re-registering is a no-op
- **list_user_papers** — list papers in your library (resolve `paper_id`s; optional title filter)
- **search_paper_content** — server-grade RAG retrieval over one of your papers (the same hybrid BM25+semantic ranking a workflow step uses); returns ranked chunks + joined text
- **get_paper_context** — the server-held `{{variable}}` dict a workflow run would substitute (research_interests, missing/top/trending lit, author profiles, …) plus the paper's section inventory

**Workflows**
- **list_paper_workflows** — list available Agent Studio workflows (custom `wf_*` and system `wf_sys_*` pipelines)
- **run_paper_workflow** — run a workflow (by ID) on a paper in your library (server-executed)
- **run_workflow_on_pdf** — upload a local PDF and run a workflow on it in one call
- **get_workflow_definition** — fetch a workflow's raw declarative DAG (steps/prompts/deps) as JSON
- **compile_workflow_skill** — convert a workflow into a portable **skill** (`target=claude|codex|gemini`) your own agent runs, instead of executing it server-side

Typical flow: `search_econpapers` / `search_ssrn` → `download_paper` → `run_paper_workflow`.
Or, to reuse a workflow as an agent skill: `list_paper_workflows` → `compile_workflow_skill` → save the returned SKILL.md.
Compiled skills run client-side (Mode B): `register_paper_text` (local PDF) or `list_user_papers` → `get_paper_context` for the `{{variables}}` → `search_paper_content` per step for evidence.

## Setup

Add to your Claude config (`~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "essencescholar": {
      "command": "uvx",
      "args": ["essencescholar-mcp"],
      "env": {
        "ESSENCESCHOLAR_API_KEY": "sk_live_..."
      }
    }
  }
}
```

Get your API key from [essencescholar.com](https://essencescholar.com).
