# Asta MCP Servers

**MCP wrappers for Allen AI's Asta research tools — making CLI-only capabilities accessible to any chatbot or AI agent via the [Model Context Protocol](https://modelcontextprotocol.io).**

[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](https://github.com/maxwellsdm1867/asta-mcp/actions)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blueviolet)](https://modelcontextprotocol.io)

---

## Why This Exists

Allen AI's [Asta](https://allenai.org/asta) ecosystem provides powerful research tools, but some are only available as **CLI commands** (via [asta-plugins](https://github.com/allenai/asta-plugins)). This project wraps those CLI-only tools as **MCP servers**, so any MCP-compatible chatbot or agent can use them — not just agents with Bash access.

> **Already covered by official MCP servers (not duplicated here):**
> - **Paper search, citations, authors, snippets** — use the official [Asta Scientific Corpus MCP](https://allenai.org/asta/resources/mcp) at `asta-tools.allen.ai/mcp/v1`
> - **Experiment execution** — use [Panda's built-in MCP server](https://github.com/allenai/panda)
>
> **This project wraps what has no MCP equivalent:**
> - Document collection management (`asta-documents` CLI)
> - Deep literature search, report generation, PDF extraction, theory synthesis (Paper Finder API + Remote OCR API)

---

## Architecture

```
                        +-------------------+
                        |    MCP Client     |
                        | (ChatGPT, Claude, |
                        |  Cursor, etc.)    |
                        +--------+----------+
                                 | stdio
                    +------------+------------+
                    |                         |
           +-------v--------+       +--------v-------+
           |  asta-library   |       |  asta-reports  |
           |   (5 tools)     |       |   (4 tools)    |
           +-------+--------+       +--+----------+--+
                   |                    |          |
                   v                    v          v
           +-------------+      +----------+ +--------+
           |asta-documents|      |Paper     | |Remote  |
           |CLI (local)   |      |Finder API| |OCR API |
           +------+------+      +-----+----+ +---+----+
                  |                    |          |
            Local filesystem     Asta Gateway
                            (asta-gateway.apps.allenai.org)
```

---

## Quick Start

**1. Install**

```bash
uv pip install git+https://github.com/maxwellsdm1867/asta-mcp.git

# Or with pip
pip install git+https://github.com/maxwellsdm1867/asta-mcp.git
```

> **Prerequisites:** Python 3.11+

**2. Authenticate** (required for asta-reports)

```bash
# Option A: Use the Asta CLI (install from https://github.com/allenai/asta-plugins)
asta auth login

# Option B: Set a token directly
export ASTA_TOKEN="your-bearer-token"
```

> **Note:** asta-library works locally without auth. asta-reports requires auth for the Paper Finder and OCR APIs.

**3. Configure your MCP client** (see [Configuration](#configuration) below)

---

## Servers

### asta-library — 5 tools

MCP wrapper for the [`asta-documents` CLI](https://github.com/allenai/asta-resource-repository). Manages a local collection of research documents with search, tagging, and metadata.

> **CLI equivalent:** `asta documents ...` (requires Bash access)
> **This MCP server:** makes it available to any MCP client

| Tool | Description |
|------|-------------|
| `add_document` | Save a paper to the local index with URL, title, summary, tags, and MIME type |
| `search_documents` | Search your collection by content and tags |
| `list_documents` | Browse all saved documents, optionally filtered by tags |
| `get_document` | Get full metadata for a document by its 10-character ID |
| `manage_tags` | Add or remove tags on any document in the collection |

> **Example prompt:** "Save that paper to my library with the tags 'RAG' and 'NLP', then show me everything tagged 'RAG'."

> **Requires:** `asta-resource-repository` (`pip install asta-resource-repository`). Falls back to `uvx` if not installed.

---

### asta-reports — 4 tools

MCP wrapper for the Asta Paper Finder API and Remote OCR API. Provides deep literature search, structured report generation, PDF text extraction, and hypothesis synthesis.

> **CLI equivalents:** `asta literature find ...`, `asta pdf-extraction remote ...` (require Bash access)
> **This MCP server:** makes them available to any MCP client, plus adds report generation and theory synthesis

| Tool | Description |
|------|-------------|
| `find_literature` | AI-powered deep paper search with fast/diligent modes (30-60s) |
| `generate_report` | Synthesize a structured markdown literature review with references |
| `extract_pdf_text` | OCR and extract text from local PDFs, returned as markdown |
| `generate_theory` | Generate a hypothesis with supporting evidence and identified research gaps |

> **Example prompt:** "Generate a literature review on transformer efficiency methods with up to 20 papers, then extract the text from ~/Downloads/flash-attention.pdf."

---

## What to Use for What

| Need | Use |
|------|-----|
| Paper search, citations, authors, passage-level snippets | [Official Asta MCP](https://allenai.org/asta/resources/mcp) (`asta-tools.allen.ai/mcp/v1`) |
| Run computational experiments | [Panda's MCP server](https://github.com/allenai/panda) |
| Manage a local paper collection | **asta-library** (this project) |
| Deep literature search + reports + PDF extraction | **asta-reports** (this project) |
| All of the above via CLI | [asta-plugins](https://github.com/allenai/asta-plugins) |

---

## Configuration

### Claude Code

```json
{
  "mcpServers": {
    "asta-library": {
      "command": "asta-library-mcp"
    },
    "asta-reports": {
      "command": "asta-reports-mcp"
    }
  }
}
```

### Cursor

```json
{
  "mcpServers": {
    "asta-library": {
      "command": "asta-library-mcp",
      "args": []
    },
    "asta-reports": {
      "command": "asta-reports-mcp",
      "args": []
    }
  }
}
```

### Generic MCP Client

```bash
asta-library-mcp        # Document collection management
asta-reports-mcp        # Deep search, reports, PDF, theories

# Or as Python modules:
python -m asta_library
python -m asta_reports
```

---

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `ASTA_TOKEN` | For asta-reports | -- | Bearer token for the Asta gateway |
| `ASTA_TOOL_KEY` | No | -- | Alternative auth via Semantic Scholar API key |
| `ASTA_GATEWAY_URL` | No | `https://asta-gateway.apps.allenai.org` | Base URL for the Asta gateway |
| `ASTA_DOCUMENT_ROOT` | No | `~/.asta/documents` | Root directory for the local document index |

---

## Development

```bash
git clone https://github.com/maxwellsdm1867/asta-mcp.git
cd asta-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[all,dev]"
pytest tests/ -v
ruff check .
```

### Project Structure

```
asta-mcp/
  asta_library/        # Local document management (5 tools)
    server.py
    auth.py
  asta_reports/        # Deep search, reports, PDF, theories (4 tools)
    server.py
    auth.py
  tests/
  pyproject.toml
```

Built with [FastMCP](https://gofastmcp.com/) 3.x.

---

## License

[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)

## Credits

- **[Allen Institute for AI](https://allenai.org/)** — creators of the Asta research ecosystem
- **[Asta Project](https://allenai.org/asta)** — the platform these servers extend
- **[FastMCP](https://gofastmcp.com/)** — the Python MCP framework
- **[Model Context Protocol](https://modelcontextprotocol.io)** — the open protocol enabling AI agent tool use