Forge MCP — freelance pipeline operations

Version: 1.0.0
Quality gate: .\make.ps1 (black, ruff, mypy, pytest cov≥90%, Martin limits)

Forge hunts public, ToS-safe job APIs, ranks listings by capability match and money heat, pushes HOT cards (Telegram + local digest), and tracks the pipeline from NEW → paid. Client pitches stay in the listing language; operator briefs are in Russian.

What is in scope / out of scope

Related MCP server: Escrow Sentinel

Install

pip install -e ".[dev]"
copy .env.example .env   # fill BOT_TOKEN + CHAT_ID
.\make.ps1               # must exit 0

CLIs: forge-hunt, forge-telegram-bot, forge-morning, forge-evening, forge-mcp.

Configuration

Secrets and knobs live in .env (gitignored). See .env.example.

Operations (money loop)

1. set_watchlist([...]) — narrow magnets

2. forge-hunt every ~30m — HOT + Telegram buttons

3. Copy PITCH → send → Proposed (target <15 min NEW→proposed)

4. forge-morning / forge-evening — queue + follow-ups + board pause

5. Won + log_win_reason → learning / A/B / packages

Windows schedules: scripts\schedule_hunt.ps1, schedule_rituals.ps1, schedule_bot.ps1
(scripts resolve project root from their own location).

MCP

{
  "mcpServers": {
    "forge": {
      "command": "python",
      "args": ["-m", "forge.presentation.mcp_server"]
    }
  }
}

Core tools: hunt_jobs, act_now, morning_digest, evening_followup, draft_proposal, brief_lead, rate_advice, check_red_flags, follow_ups, sla_status, chase_leads, package_prices, pause_weak_boards, platform_roi, board_advice, win_journal, log_win_reason, pitch_ab_stats, set_watchlist, pipeline_status, earnings_summary, capture_lead, scan_for_leads, hot_leads.

Architecture

src/forge/
  entities/         # Lead FSM, match, heat, gates, pricing, i18n
  use_cases/        # hunt, rituals, pipeline, learning, act-now
  interfaces/       # ports (repos, sources, notifier)
  infrastructure/   # SQLite, HTTP boards, Telegram, .env loader
  presentation/     # MCP + CLIs + composition root

Clean architecture: use cases depend on ports; composition wires adapters. Persistence: SQLite (~/.forge/forge.db by default) with additive migrations.

Quality / acceptance

See docs/ACCEPTANCE.md. Summary:

• .\make.ps1 exits 0

• ≥90% line coverage on forge (CLIs/MCP omitted by design)

• No secrets in repo; Telegram errors redacted

• Martin limits: file ≤300 lines, fn ≤25 lines, ≤4 args, CC≤10, nesting≤3

License

MIT — see LICENSE.