HackScout MCP

Hackathon intelligence for builders who already have something worth submitting.

HackScout is a FastMCP server that helps you pick where to submit, which track to target, and how to differentiate — using fit scoring, past-winner patterns, and public gallery intel.

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 ongoing / upcoming hackathons (seed data offline; Firecrawl for live pages)

• 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, curated seed hackathons and sample public submissions keep the full tool loop working offline.

Related MCP server: idea-reality-mcp

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.

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.

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:

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