Metadata-Version: 2.4
Name: loreto-mcp
Version: 0.1.3
Summary: MCP server for the Loreto skill generation API — use generate_skills inside Claude Code
Project-URL: Homepage, https://loreto.io
Project-URL: Documentation, https://loreto.io/docs-mcp
Project-URL: Repository, https://github.com/kopias/loreto-mcp
License: MIT
Keywords: ai,claude,loreto,mcp,model-context-protocol,skills
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

# loreto-mcp

Turn any YouTube video, article, PDF, or image into a reusable Claude Code skill — without leaving your editor.

---

## What it does

Loreto analyzes a content source and extracts **structured skill packages** that Claude Code can apply to future tasks. Each skill contains:

- **`SKILL.md`** — Principles, failure modes, implementation steps, and architectural patterns
- **`README.md`** — Overview and usage context
- **Reference files** — Supporting patterns and data structures
- **Test script** — Runnable validation for the skill's core concepts

Save skills to `.claude/skills/` and Claude picks them up automatically on relevant tasks — reducing hallucinations, token usage, and re-explaining the same concepts over and over.

---

## Sample skills

The [`sample-skills/`](./sample-skills/) folder contains real skills generated by Loreto from a single technical video on hybrid AI architecture. Browse them to see exactly what you get:

| Skill | What it teaches |
|---|---|
| [`designing-hybrid-context-layers`](./sample-skills/designing-hybrid-context-layers/) | Architect hybrid retrieval systems that combine vector search, graph traversal, and structured data |
| [`temporal-reasoning-sleuth`](./sample-skills/temporal-reasoning-sleuth/) | Enable agents to trace decision chains and reconstruct causal sequences across long time horizons |
| [`synthesizing-institutional-knowledge`](./sample-skills/synthesizing-institutional-knowledge/) | Capture and query organizational knowledge in a way AI agents can reliably reason over |
| [`diagnosing-rag-failure-modes`](./sample-skills/diagnosing-rag-failure-modes/) | Identify and fix the 7 most common RAG pipeline failure patterns |
| [`routing-work-across-ai-harnesses`](./sample-skills/routing-work-across-ai-harnesses/) | Dynamically route tasks to the right AI harness based on task type and context |
| [`evaluating-ai-harness-dimensions`](./sample-skills/evaluating-ai-harness-dimensions/) | Score and compare AI harness options across speed, cost, accuracy, and controllability |
| [`detecting-harness-lockin`](./sample-skills/detecting-harness-lockin/) | Spot vendor lock-in signals early and design for portability |
| [`benchmarking-ai-agents-beyond-models`](./sample-skills/benchmarking-ai-agents-beyond-models/) | Measure agent performance at the system level, not just model level |
| [`auditing-intelligence-context-fit`](./sample-skills/auditing-intelligence-context-fit/) | Audit whether the right intelligence layer is solving the right problem |

Each folder includes the full `SKILL.md`, `README.md`, and any reference files — ready to drop into `.claude/skills/`.

---

## Setup

### 1. Get an API key

Sign up at [loreto.io](https://loreto.io) to get your free API key (`lor_...`).

### 2. Install

```bash
pip install loreto-mcp
```

Or run directly without installing (requires [`uv`](https://docs.astral.sh/uv/)):

```bash
uvx loreto-mcp
```

### 3. Configure Claude Code

**User-scoped** (works across all your projects) — add to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "loreto": {
      "command": "uvx",
      "args": ["loreto-mcp"],
      "env": {
        "LORETO_API_KEY": "lor_..."
      }
    }
  }
}
```

**Project-scoped** (shared with your team) — add to `.mcp.json` at your project root:

```json
{
  "mcpServers": {
    "loreto": {
      "command": "uvx",
      "args": ["loreto-mcp"],
      "env": {
        "LORETO_API_KEY": "${LORETO_API_KEY}"
      }
    }
  }
}
```

### 4. Verify

Restart Claude Code and run `/mcp` — you should see `loreto` listed with `generate_skills` and `get_quota`.

---

## Usage

Once connected, just ask Claude Code naturally:

```
Use Loreto to extract skills from https://www.youtube.com/watch?v=...
```

```
Extract skills from this article and save them to .claude/skills/
```

```
Check my Loreto quota before we start.
```

Claude calls `generate_skills`, receives the full skill package, and can write the files directly to your project.

---

## Available tools

| Tool | Description |
|---|---|
| `generate_skills` | Extract ranked skill packages from a URL. Returns full file contents ready to save. |
| `get_quota` | Check calls used, monthly limit, and plan for your API key. |

### `generate_skills` parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `source` | `str` | required | URL to analyze — YouTube, article, public PDF, or image |
| `source_type` | `str` | `"auto"` | `"auto"` \| `"youtube"` \| `"article"` \| `"pdf"` \| `"image"` |
| `test_language` | `str` | `"python"` | `"python"` \| `"typescript"` \| `"javascript"` |
| `include_visuals` | `bool` | `true` | Embed Mermaid diagrams in `SKILL.md` |
| `context` | `str` | `null` | 1–3 sentence hint to guide extraction (max 500 chars) |
| `themes_to_process` | `list[str]` | `null` | Follow-up call: skill names from a previous response's queued themes |

---

## Supported sources

| Source | Notes |
|---|---|
| YouTube videos | Up to 60 minutes |
| Web articles | Any publicly accessible URL |
| PDFs | Up to 100 pages |
| Images | Diagrams, whiteboards, slides (up to 20 MB) |

---

## Configuration

| Environment variable | Required | Default | Description |
|---|---|---|---|
| `LORETO_API_KEY` | Yes | — | Your Loreto API key (`lor_...`) |
| `LORETO_BASE_URL` | No | `https://api.loreto.io` | Override for local development |

---

## Plans

Free and paid plans available. See [loreto.io/pricing](https://loreto.io/pricing) for current limits.

---

## License

MIT
