# Scroll MCP Server v0.2

🎯 **Vesuvius Challenge submission** — Automated quality audit & corpus navigation for the Herculaneum scrolls.

MCP Server for the Vesuvius Challenge papyrological corpus & open data.

Exposes scroll metadata, transcriptions, CT volumes, ML models, and documentation via the [Model Context Protocol](https://modelcontextprotocol.io).

## Quick Start

```bash
pip install scroll-mcp-server
scroll-mcp-server
```

Or with Claude Desktop — add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "scroll": {
      "command": "scroll-mcp-server"
    }
  }
}
```

## URI Scheme

```
scroll://                    → Root
├── catalog/scrolls          → Scroll inventory
├── catalog/vocabulary       → Papyrological glossary
├── scroll/{id}/metadata     → Scroll metadata
├── scroll/{id}/transcriptions → Deciphered text
├── scroll/{id}/volumes      → CT scan info
├── model/ink-detection      → ML models
├── docs/tutorials           → Tutorials
├── docs/formats/tifxyz      → Format specs
└── docs/open-problems       → Research challenges
```

## Tools

| Tool | Description |
|---|---|
| `search_corpus` | Search transcriptions & metadata |
| `get_scroll_catalog` | Filtered scroll inventory |
| `get_segment_data` | Segment metadata + download links |
| `get_tutorial` | Tutorial content |
| `get_format_spec` | Technical format specification |
| `get_model_info` | ML model metadata |
| `list_available_models` | Filtered model list |

## Prompts

| Prompt | Purpose |
|---|---|
| `explain_papyrus_context` | Historical/philosophical context of a passage |
| `suggest_research_direction` | Research recommendations from corpus state |

## Architecture

```
Client → FastMCP → ScrollDataLayer → Catalog (JSON) + Vesuvius (streaming) + Cache (LRU)
```

- **Catalogue JSON** — Lightweight index (~50 KB) for instant metadata responses
- **Data Layer** — Orchestrator with LRU cache, routes to the right source
- **Vesuvius Client** — Streaming proxy for CT volumes (no local storage)

## Development

```bash
git clone https://github.com/zengdard/scroll-mcp-server
cd scroll-mcp-server
pip install -e .
pytest tests/ -v
```

## Real Example — Scroll 1 Segment Audit

Un exemple complet avec données réelles du Scroll 1 (PHerc. Paris 4) est dans [`examples/`](./examples/) :

```bash
# Audit du mesh noisy (84k vertices) contre le volume CT
python examples/audit_demo.py --quick
```

Résultat :

```
Quality score:    0.431  ← mesh bruité, besoin de raffinement
Mean confidence:  0.942  ← bonne qualité CT
Mean distance:    3.88 voxels
🔴 CRITIQUE — 55650 vertices en drift
🟢 ANCRE — 6418 vertices stables
```

Voir le rapport complet : [`examples/AUDIT_REPORT.md`](./examples/AUDIT_REPORT.md)

## Submission

Ce projet est soumis au Scroll Prize. Voir [`SUBMISSION.md`](./SUBMISSION.md) pour les détails.

- **Team**: Individual — zengdard
- **Repo 1**: https://github.com/zengdard/scroll-mcp-server
- **Repo 2**: https://github.com/zengdard/scroll-label-refiner

## License

MIT