Football Content Agent

A football content brand that runs itself, end to end, with a human on the publish button. Live in production as @mandemfchq: it watches fixtures and news, drafts opinionated posts with match graphics, and publishes only after approval over Telegram.

Architecture · Runbook · The engine it runs on

At a glance

This repo is the live football implementation of the reusable ai-social-content-agent engine. It shows the engine connected to real football inputs: fixtures, news, lineups, player imagery, Telegram approval, and optional Instagram publishing.

Related MCP server: AgentReacher

Why this exists

This is the production proof for the ai-social-content-agent engine: the same approval-gated, human-in-the-loop core, specialized for football and running live for a real audience. The engine repo is the reusable version; this repo shows it holding up in the wild.

The interesting part is not "generate a caption." It is the operating system around that caption: event polling, ranking, state, an approval gate, async media jobs, image safety checks, deterministic fallbacks, and recovery when a provider fails or live data goes missing.

What it proves

How it works

flowchart TD
    Cron["Cron or operator"] --> MCP["FastMCP server (35 tools)"]
    Telegram["Telegram approval chat"] --> MCP
    MCP --> Football["API-Football + news"]
    MCP --> DB[("SQLite state")]
    MCP --> Images["Image source ladder"]
    Images --> Vision["Relevance + identity checks"]
    Vision --> Draft["Draft + Telegram preview"]
    Draft --> Approval{"Human: yes / edit / skip"}
    Approval -->|yes| Job["Async stylize job"]
    Approval -->|skip| DB
    Job --> Publish["Optional Instagram publish"]

Full detail in ARCHITECTURE.md. The generic, reusable engine behind this lives in ai-social-content-agent.

Quick start

python3 -m venv .venv && . .venv/bin/activate
make install
make test          # 67 tests, no live secrets needed
cp .env.example .env
make db-init

Built with

Python · MCP (FastMCP) · SQLite · API-Football · Telegram Bot API · Instagram Graph API · fal.ai / OpenAI image models.

Public-safe notes

A sanitized proof repo. It excludes private workspace memory, live hostnames, IPs, chat IDs, secrets, and deployment-specific paths. Keep real credentials in .env locally or in a server env file outside git.

License

MIT, see LICENSE. Use it as a reference implementation for your own human-approved content workflow.

Contact

Built and operated by Mira Solutions, an AI engineering and automation studio.

mira.solutions06@gmail.com