Metadata-Version: 2.4
Name: stewreads-mcp
Version: 0.1.2
Summary: Local MCP server that turns AI conversations into polished ebooks and delivers them to Kindle or email
Project-URL: Homepage, https://stewreads.com
Keywords: mcp,claude,kindle,epub,automation,local
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: pypandoc-binary>=1.15
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"

# stewreads

![StewReads Pixel Art](assets/stewreads-text-pixel.png)

StewReads is a local MCP server that transforms AI conversations into clean, well-formatted ebooks. Everything runs on your machine, with no account and no cloud backend required. Generate EPUB files from your chats and send them directly to Kindle or any email address. Works with Claude Desktop and other MCP-compatible clients.

## Website vs Local Package
The official StewReads website is [stewreads.com](https://stewreads.com). This PyPI package, `stewreads-mcp`, is the local-first MCP version for people who want to run ebook generation from Claude Desktop on their own machine. Installing this package does not connect to a StewReads cloud backend.

## Features
- Local-first MCP server with no login or cloud backend
- Local stdio MCP server (no backend calls)
- EPUB generation from markdown
- Save generated ebooks to a configured local directory
- Send generated EPUB files by email via built-in Gmail SMTP (App Password)
- Optional MP3 audiobook generation via ElevenLabs TTS

## Use Cases
- Learn a new topic with Claude and turn the discussion into a polished ebook for later reading.
- Generate a focused ebook before a flight and read offline on your e-reader.
- Turn long planning or research chats into one clean document you can revisit anytime.
- Create Kindle-ready study notes from tutoring or interview-prep conversations.
- Save and share AI-generated explainers with friends or teammates over email.

## Requirements
- Python 3.10+
- uv for repo development

## Install From PyPI
Install the released package:

```bash
pip install stewreads-mcp
```

macOS install:
```bash
brew install uv
```

## Setup From Repo
Clone and install from this repository:

```bash
git clone git@github.com:ankitvg/stewreads-local.git
cd stewreads-local
uv sync
```

This includes pandoc via `pypandoc-binary`, so no separate pandoc install is required.

## Update Dependencies
```bash
uv sync
```

## Configuration
Create `~/.config/stewreads/config.toml`:

```toml
[paths]
output_dir = "/Users/you/Projects/generated_books"

[email]
from_email = "you@gmail.com"
default_to_email = "kindle-or-reader@example.com"
```

> **Important (Kindle Users):** For Kindle delivery to work, you MUST add your `from_email` to your [Approved Personal Document E-mail List](https://www.amazon.com/gp/help/customer/display.html?nodeId=GX9XLEVV8G4DB28H) in your Amazon account settings. Otherwise, Amazon will block the incoming ebook for security.

Optional environment overrides:
- `STEWREADS_CONFIG_PATH` (path to config file)
- `STEWREADS_OUTPUT_DIR` (overrides configured output dir)
- `STEWREADS_FROM_EMAIL` (overrides sender email)
- `STEWREADS_DEFAULT_TO_EMAIL` (overrides default recipient email)

Required secret for email sending:
- `STEWREADS_GMAIL_APP_PASSWORD` (Gmail App Password)

Audiobook environment variables (used only when `save_ebook(..., create_audio=true)`):
- `ELEVENLABS_API_KEY` (required to generate MP3 files)
- `ELEVENLABS_VOICE_ID` (optional voice override)

Audiobook defaults:
- Voice: Rachel (`21m00Tcm4TlvDq8ikWAM`)
- Model: `eleven_multilingual_v2`
- Output format: `mp3_44100_128`

## Run MCP Server
```bash
uv run stewreads-mcp
```

## Claude Desktop (Mac) Example
Add to Claude Desktop's `claude_desktop_config.json` MCP config:

```json
{
  "mcpServers": {
    "stewreads": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/you/Projects/stewreads-local",
        "run",
        "stewreads-mcp"
      ],
      "env": {
        "STEWREADS_CONFIG_PATH": "/Users/you/.config/stewreads/config.toml",
        "STEWREADS_GMAIL_APP_PASSWORD": "your-16-char-app-password",
        "ELEVENLABS_API_KEY": "your-elevenlabs-api-key",
        "ELEVENLABS_VOICE_ID": "21m00Tcm4TlvDq8ikWAM"
      }
    }
  }
}
```

## Exposed MCP Tools
- `get_stew_prompt()`
- `get_stew_config()`
- `get_email_status()`
- `save_stew_config(output_dir)`
- `save_ebook(markdown, title, filename?, original_prompt?, create_audio?)`
- `email_ebook(to_email?, ebook_path?, subject?, body?)`

## Async Audiobook Behavior
When you call `save_ebook(..., create_audio=true)`:
- EPUB save completes first and Claude can return that result immediately.
- MP3 generation continues in the background and may still be running after the response.
- The response includes `audio_status="generating"` and an `audio_path` you can check in your output directory.

## First-Time Claude Flow
1. Call `get_stew_config()`.
2. If `configured` is `false`, ask the user for their preferred output directory and call `save_stew_config(output_dir=...)`.
3. Call `save_ebook(...)` after config is set.
4. Call `get_email_status()` before sending.
5. Call `email_ebook(...)` to send the latest EPUB (or specify `ebook_path`).

## Testing (Local Development)
Run tests:

```bash
uv run --with pytest python -m pytest -q tests
```

Optional lint check:

```bash
uv run --with ruff ruff check src tests
```

## Dev Shell Safety
When running multi-step shell commands, you may see `set -euo pipefail`:
- `-e`: stop on command failure.
- `-u`: fail on unset variables.
- `-o pipefail`: fail if any command in a pipeline fails.
