automatic-disco

Local MCP server for English education content automation.

Quick Start

Start the MCP Server

Run the FastMCP server locally from the repository root with the default ./data storage:

PYTHONPATH=src .venv/bin/python -m automatic_disco.main

Use an explicit persistent data root when you do not want to use the repository ./data directory:

DATA_ROOT=/absolute/path/to/data PYTHONPATH=src .venv/bin/python -m automatic_disco.main

Registered MCP Tools

Current registered tools:

• health_check: Readiness probe with status, version, and started_at
• get_server_info: Server identity, supported formats, data_root, and backend_kind
• list_supported_formats: Complete format registry with blob/document counts
• ingest_file: Register one supported local source file as a document
• extract_text: Parse one ingested document into normalized Markdown text
• analyze_document: Build paragraphs, sentences, chunks, and metadata artifacts
• search_documents: Filter, sort, and paginate stored document summaries
• get_document: Fetch one stored document with blob and artifact pointers

The verified MVP workflow is health_check -> ingest_file -> extract_text -> analyze_document -> search_documents -> get_document.

See AGENTS.md for full tool list and docs/PRD.md for requirements.

Environment Variables

• DATA_ROOT: Root directory for persistent data (default: ./data)
• AD_REQUIRE_MOUNT: If "1", require DATA_ROOT to be a mount point (default: "0")

Development

# Validate code
.venv/bin/python scripts/validate.py

# Check Ralph Loop status
.venv/bin/python scripts/status.py

# Inspect repository structure
.venv/bin/python scripts/inspect_repo.py

Documentation

• AGENTS.md: Integration guide for MCP clients and agents
• docs/PRD.md: Product requirements
• docs/IMPLEMENTATION_PLAN.md: Ralph Loop task plan
• docs/design/: Detailed design docs