CoolFace
Apppublic

MCP-1st-Birthday/StoryCatcher

sourceHugging Faceapache-2.0updated 10mo agoView on Hugging Face
5likes
App README

Sponsors and Providers used: ----------------

  • —Nebius
  • —Google Gemini
  • —Anthropic (Claude)
  • —ElevenLabs (TTS)

Social Media Post ---------------- LinkedIn: https://www.linkedin.com/posts/daniel-ferreira-15c9_mcpbirthdayhackathon-modelcontextprotocol-activity-7400962073309982722-6ueK

Demo Link ---------------- Youtube: https://youtu.be/zk0X1OfvxMo

Project Overview ----------------

Dreamcatcher converts text prompts into structured outlines, multi-part stories, typeset PDFs and optional narration audio. The app is built as a FastAPI service that mounts a Gradio UI at the root and exposes a FastMCP Server (SSE) at /mcp for model discovery and tool calls.

Key points from the codebase:

  • —The FastMCP server (SSE) is initialized in server.py and mounted at /mcp (client SSE endpoint: /mcp/sse).
  • —The Gradio UI (the demo Blocks) is defined in app.py and mounted into FastAPI by server.py.
  • —Supported generation providers: Nebius (OpenAI-compatible via openai client with a Nebius base URL), Google Gemini (google.generativeai), Anthropic (Claude), and ElevenLabs for TTS.

Features --------

  • —Text-first workflows: the app works fully with text prompts to create outlines, story segments and PDFs.
  • —Dynamic model/voice discovery via MCP tools exposed by the server (fetch_nebius_models_tool, fetch_gemini_models_tool, fetch_anthropic_models_tool, fetch_elevenlabs_data_tool).
  • —Publish / persist generated works to a local library.json (and optionally sync to a Hugging Face dataset when HF_TOKEN is provided).

Requirements ------------

  • —Python 3.11 (the Spaces header and code target 3.11)
  • —See requirements.txt for the exact dependency list (Gradio, FastAPI, uvicorn, huggingface-hub, reportlab, mcp, google.generativeai, openai, anthropic, elevenlabs, etc.).

Quick Start — Local Development -------------------------------

  1. 1.Create and activate a Python 3.11 virtual environment.
  1. 1.Install dependencies:
powershell
python -m pip install -r requirements.txt
  1. 1.(Optional) Create a .env file or set environment variables for any providers you plan to use. HF_TOKEN is optional — the app will save generated novels to library.json locally even without it. If you provide HF_TOKEN, the app will attempt to upload/sync library.json to the configured Hugging Face dataset.
  1. 1.Run the server (default port 7860):
powershell
python server.py
  1. 1.Open the UI at: http://localhost:7860

Environment Variables ---------------------

  • —PORT — Optional. Port to listen on (default 7860).
  • —HF_TOKEN — Optional. When present, the LibraryManager will attempt to sync library.json with the configured DATASET_REPO on Hugging Face.

Provider API keys (set only if you plan to use each provider):

  • —NEBIUS_API_KEY — Nebius/OpenAI-compatible API key (used with an OpenAI client configured to Nebius base URL).
  • —GOOGLE_API_KEY — Google Gemini API key (used via google.generativeai).
  • —ANTHROPIC_API_KEY — Anthropic (Claude) API key.
  • —ELEVENLABS_API_KEY — ElevenLabs API key for TTS (voice/model discovery and audio generation).

Docker / Hugging Face Spaces ----------------------------

The repository includes a Spaces-compatible top-matter header. To build and run locally with Docker:

powershell
docker build -t dreamcatcher:latest .
docker run -e HF_TOKEN="<your-hf-token>" -p 7860:7860 dreamcatcher:latest

When deployed as a Hugging Face Space (Docker runtime), the header at the top of this README.md is used by the Spaces UI.

How It Works (brief) --------------------

  • —server.py initializes a FastMCP instance and mounts the SSE app at /mcp (so the Gradio UI can call server-side tools via SSE).
  • —Tool functions (registered with @mcp.tool()) perform tasks like generating outlines (generate_story_plan), creating content segments (write_content_segment), fetching model lists, and generating audio (generate_audio_narration).
  • —The Gradio UI (app.py) connects to the local MCP SSE endpoint (MCP_SSE_URL = "http://127.0.0.1:7860/mcp/sse") for model discovery and tool calls while running locally.

Notes & Behaviour -----------------

  • —Text-only usage is fully supported: you do not need any audio/TTS keys to generate outlines, story content and PDFs.
  • —If ElevenLabs credentials are provided, the UI can fetch voices/models and generate MP3 narration files saved locally.
  • —library.json is the local storage for published works. The LibraryManager writes to this file locally and will attempt to upload it to the configured Hugging Face dataset only if HF_TOKEN is present and valid.

Project Layout --------------

  • —server.py — FastMCP server, FastAPI app and Gradio mount (entry point for running locally or in Spaces).
  • —app.py — Gradio Blocks UI, client-side wiring, PDF generation, and the LibraryManager that handles local publishing / optional HF sync.
  • —requirements.txt — Python dependencies.
  • —library.json — Local saved library of generated works (created/updated at runtime).
  • —trials/ — Experimental files and earlier test scripts.

Troubleshooting ---------------

  • —If model discovery or calls fail, ensure the relevant provider key is set and valid.
  • —If the app can't fetch voices/models from ElevenLabs, audio features will gracefully return errors and the core text workflow will still operate.
  • —If port binding or CORS errors appear, confirm the PORT environment variable and that your firewall allows access.

Contributing ------------

Contributions welcome. If you want to improve provider abstractions, add more robust error handling, or provide CI/run scripts (Docker Compose, .env.example), please open an issue or send a PR.

References ----------

  • —Hugging Face Spaces config reference: https://huggingface.co/docs/hub/spaces-config-reference