HackScout MCP

A Developer Tools MCP server for builders and agent runtimes that already have something worth submitting.

HackScout is a FastMCP server for developer workflows: agents and builders use it to pick where to submit, which track to target, and how to differentiate — using fit scoring, past-winner patterns, and public gallery intel.

The builder-facing Vite website is maintained and deployed separately in Ash-Blanc/hackscout-web.

It is not another hackathon listing feed. Given a live project, it answers:

1. Where should I submit?

2. Which track / sponsor challenge fits?

3. How crowded is the idea space, and what should I change?

Features

• Discover verified, fresh ongoing / upcoming hackathons (synthetic fixtures require explicit opt-in)

• Profile a project from repo, demo, pitch, or README

• Explainable project→hackathon fit scores

• Winner playbooks from past editions and similar events

• Public gallery crowding, nearest neighbors, differentiation moves

• Specialized scout agents (Agno + Nia-inspired roles) for multi-step plans

API keys are optional. Without them, the synthetic fixtures remain available for explicit local demos, but are never returned as live opportunities.

Related MCP server: Colosseum Copilot

Requirements

• Python 3.12+

• uv (recommended)

Install & run

git clone https://github.com/Ash-Blanc/hackscout-mcp.git
cd hackscout-mcp
cp .env.example .env
uv sync
uv run hackscout-mcp

Equivalents:

uv run python -m app.main
# or
uv run python main.py

Offline demo (no MCP client):

uv run python scripts/demo_flow.py

Connect an MCP client

Cursor

Add to your MCP config (Cursor Settings → MCP, or project .cursor/mcp.json):

{
  "mcpServers": {
    "hackscout": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/hackscout-mcp",
        "hackscout-mcp"
      ],
      "env": {
        "AGNO_MODEL_PROVIDER": "openrouter",
        "AGNO_MODEL_ID": "openai/gpt-4.1-nano",
        "OPENROUTER_API_KEY": ""
      }
    }
  }
}

Claude Desktop / other stdio clients

Same shape: command + args pointing at uv run --directory <repo> hackscout-mcp, with optional env keys from .env.example.

Remote HTTP (hosted)

1. Try Prefect Horizon first (free personal tier): docs/horizon.md
   Entrypoint: app/main.py:mcp → URL like https://<name>.fastmcp.app/mcp

2. Self-host (Fly / Render): docs/deploy.md

HACKSCOUT_TRANSPORT=http HACKSCOUT_BEARER_TOKEN=dev-secret uv run hackscout-mcp
# health: http://127.0.0.1:8000/health
# mcp:    http://127.0.0.1:8000/mcp

After the server starts, ask the agent things like:

• “Analyze this project and rank the best hackathons for it.”

• “Run submission_advisor in oracle mode for my project.”

• “What’s crowding the public gallery for this event, and how should I differentiate?”

More detail: docs/usage.md · tool catalog: docs/tools.md.

OpenAI Build Week (Codex + GPT-5.6)

HackScout is entered as a Developer Tools project on OpenAI Build Week. It is a pre-existing MCP server meaningfully extended during the submission period with Codex (GPT-5.6).

• Prior vs new work: docs/BUILD_WEEK_DELTA.md

• Judge path (stdio first): docs/JUDGE_QUICKSTART.md

• Codex MCP snippet: docs/codex-mcp.toml.snippet

• Offline eligibility smoke test: uv run python scripts/judge_smoke.py

How Codex accelerated the workflow

Codex (CLI, model family GPT-5.6 / gpt-5.6-terra) was used to:

1. Harden live gallery extraction and client fallbacks

2. Stabilize scout-agent report parsing / provider failures

3. Improve track ranking so MCP/agent tooling maps to Developer Tools

4. Expand local dogfood harnesses (scripts/live_smoke.py, scripts/dogfood.py)

Submit the /feedback Session ID from the primary Codex build thread on the Devpost form (also recorded in BUILD_WEEK_DELTA.md).

How GPT-5.6 is used

• Build-time: core Build Week deltas authored in Codex on GPT-5.6.

• Runtime (optional): configure Agno scout agents with OpenAI GPT-5.6, e.g. AGNO_MODEL_PROVIDER=openai and AGNO_MODEL_ID=gpt-5.6 (or the nano/mini variant available on your account). Without keys, deterministic agent fallbacks still work for judges.

Suggested workflows

Atomic tools (precise steps)

1. analyze_project — repo URL and/or pitch → project_id

2. rank_best_targets — top opportunities with score breakdowns

3. suggest_track_strategy — best track / positioning for a hackathon

4. build_winner_playbook — patterns from past / similar winners

5. extract_public_submissions → find_similar_submissions → suggest_differentiation_moves

Scout agents (multi-step)

Prefer agents when you want a phased, cited report instead of hand-chaining tools:

list_scout_agents
run_scout_agent(agent_id="submission_advisor", mode="oracle", project_id="...")
get_scout_run(run_id)

Modes: quick → deep → oracle (full ladder on submission_advisor).

LLM providers for scout agents

Atomic tools need no LLM. Scout agents use Agno — set AGNO_MODEL_PROVIDER + credentials. Details: docs/llm-providers.md.

# OpenRouter
AGNO_MODEL_PROVIDER=openrouter
AGNO_MODEL_ID=openai/gpt-4.1-nano
OPENROUTER_API_KEY=sk-or-...

# Together / Ollama / vLLM / LiteLLM / …
AGNO_MODEL_PROVIDER=openai_compatible
AGNO_MODEL_ID=your-model-id
OPENAI_COMPATIBLE_BASE_URL=https://api.together.xyz/v1
OPENAI_COMPATIBLE_API_KEY=...

Without credentials, agents fall back to deterministic runners so demos still work.

Scoring

overall = 0.24*theme + 0.18*stack + 0.18*feasibility
        + 0.16*sponsor_fit + 0.14*novelty
        + 0.10*competitive_pressure_adjustment

Weights and narrative templates are exposed as MCP resources (hackscout://scoring-framework).

Configuration

See .env.example. Common knobs:

Live-discovery trust policy: verify_hackathon_url must find page evidence, then ingest_hackathon_url stores a verified source record. Search and ranking only return records re-verified within HACKSCOUT_VERIFICATION_MAX_AGE_HOURS (72 by default). include_demo=true is solely for local fixture walkthroughs. | OPENAI_COMPATIBLE_BASE_URL | Any OpenAI-compatible gateway | | AZURE_OPENAI_* | Azure OpenAI / Foundry GPT (default provider) | | HACKSCOUT_DB_PATH | SQLite path (default ./data/hackscout.db) |

Guardrail: competitor tools only touch intentionally public galleries. No auth bypass.

Layout

app/
  main.py           # FastMCP server entry
  agents/           # Agno factory, toolkit, scout runners
  models/           # Hackathon, Project, Submission, FitScore
  services/         # clients, embeddings, ranking, seed data
  storage/          # SQLite + repositories
  tools/            # MCP tool modules
  prompts/          # prompt / resource templates
docs/               # architecture, usage, tools
scripts/demo_flow.py
tests/

Architecture notes: docs/architecture.md.

Development

uv sync --extra dev
uv run pytest

Want to contribute? See CONTRIBUTING.md.

License

MIT