# HackScout MCP

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

HackScout is a [FastMCP](https://gofastmcp.com) 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](https://github.com/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.

## Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (recommended)

## Install & run

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

Equivalents:

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

Offline demo (no MCP client):

```bash
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`):

```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`](.env.example).

### Remote HTTP (hosted)

1. **Try Prefect Horizon first (free personal tier):** **[docs/horizon.md](docs/horizon.md)**  
   Entrypoint: `app/main.py:mcp` → URL like `https://<name>.fastmcp.app/mcp`
2. **Self-host (Fly / Render):** **[docs/deploy.md](docs/deploy.md)**

```bash
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](docs/usage.md) · tool catalog: [docs/tools.md](docs/tools.md).

## OpenAI Build Week (Codex + GPT-5.6)

HackScout is entered as a **Developer Tools** project on [OpenAI Build Week](https://openai.devpost.com/). 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](docs/BUILD_WEEK_DELTA.md)
- **Judge path (stdio first):** [docs/JUDGE_QUICKSTART.md](docs/JUDGE_QUICKSTART.md)
- **Codex MCP snippet:** [docs/codex-mcp.toml.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:

| Agent | Role |
|--------|------|
| `opportunity_scout` | Discover / filter hackathons |
| `fit_strategist` | Fit score + track + go/no-go |
| `gallery_intel` | Public gallery crowding / differentiation |
| `winner_coach` | Past-edition / similar winner playbook |
| `submission_advisor` | End-to-end: DISCOVER → FIT → WINNERS → GALLERY → SYNTHESIZE |

```text
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](docs/llm-providers.md).

| Provider | Sketch |
|----------|--------|
| **Azure OpenAI / Foundry** (default) | `azure_openai` + `AZURE_OPENAI_*` · `gpt-4.1-nano` |
| **OpenRouter** | `openrouter` + `OPENROUTER_API_KEY` · e.g. `openai/gpt-4.1-nano` |
| **Any OpenAI-compatible** | `openai_compatible` + `OPENAI_COMPATIBLE_BASE_URL` + key |
| OpenAI / Anthropic / Google | `openai` / `anthropic` / `google` + usual API keys |

```bash
# 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

```text
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`](.env.example). Common knobs:

| Variable | Purpose |
|----------|---------|
| `FIRECRAWL_API_KEY` | Live event page ingestion |
| `TINYFISH_API_KEY` | Dynamic public gallery extraction |
| `APODEX_API_KEY` | Optional enrichment on `score_project_fit(enrich=true)` |
| `AGNO_MODEL_PROVIDER` / `AGNO_MODEL_ID` | Scout agent LLM (see [llm-providers](docs/llm-providers.md)) |
| `OPENROUTER_API_KEY` | OpenRouter |

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

```text
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](docs/architecture.md).

## Development

```bash
uv sync --extra dev
uv run pytest
```

Want to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](LICENSE)