MCP server (for AI agents)

The project ships a stdio MCP server named yield-router exposing detection, planning, oracle ranking, network scoring and watcher alerts as five tools, all returning JSON in text content.

Registration

Requirements: Bun, then bun install in the repo root. Add to your MCP client config:

{
  "mcpServers": {
    "yield-router": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/effective-intelligence/src/mcp-server.ts"]
    }
  }
}

The server (src/mcp-server.ts, version 0.0.1) speaks MCP over stdio. stdout is reserved for the protocol; the only liveness log ("yield-router MCP server pret (stdio)") goes to stderr. It wraps the same modules as the CLIs (detect, plan, engine, scoring), no duplicated logic. A smoke test exists: bun run src/mcp-smoke.ts.

Every tool result is a single text content block containing pretty-printed JSON. Errors come back as {"error": "..."} with isError: true.

Tools

detect_hardware

No input. Detects OS, CPU, GPUs and RAM of the local machine and maps to a known profile.

{ "name": "detect_hardware", "arguments": {} }

Example return:

{
  "os": "linux",
  "cpuModel": "AMD Ryzen 9 7950X 16-Core Processor",
  "gpus": ["NVIDIA GeForce RTX 4090"],
  "memoryGb": 64,
  "profile": { "key": "rtx-4090", "label": "RTX 4090", "kind": "gpu" },
  "unmatched": []
}

get_machine_plan

Detects hardware, then builds THE allocation plan (primary + stack + total USD/day). Optional inputs: kwhUsd (positive number, $/kWh) and ipSlots (integer >= 0). Omitted values fall back to data/agent.json, then to defaults.

{ "name": "get_machine_plan", "arguments": { "kwhUsd": 0.10, "ipSlots": 1 } }

Example return:

{
  "profile": "rtx-4090",
  "plan": {
    "primary": { "slot": "GPU", "name": "Salad-class inference (estimate) [oracle, cash]", "usdDay": 3.5, "speculative": false },
    "nextBest": { "slot": "GPU", "name": "Rent on Vast.ai (137 asks, p25 $0.312/h)", "usdDay": 2.9, "speculative": false },
    "stack": [
      { "slot": "ip_slot", "name": "Grass (S3, listed) [tier B]", "usdDay": 0.02, "tier": "B", "speculative": false, "warning": "risque ban: respecter 1 device/1 IP" }
    ],
    "totalUsdDay": 3.52
  }
}

If the hardware maps to no profile, the tool returns an error listing the detected candidates and the supported profile keys.

get_yield_ranking

Oracle ranking of net USD/day for a given profile across mature markets (mining, NiceHash, Vast.ai rental, inference), from live third-party data. Inputs: profileKey (required, one of the keys in src/profiles.ts, e.g. rtx-4090), kwhUsd (optional).

{ "name": "get_yield_ranking", "arguments": { "profileKey": "rtx-4090", "kwhUsd": 0.10 } }

Example return (truncated):

{
  "profile": "rtx-4090",
  "ranking": [
    { "name": "Salad-class inference (estimate)", "category": "inference", "grossUsdDay": 3.83, "powerUsdDay": 0.36, "netUsdDay": 3.47, "notes": "static estimate, highly demand dependent" },
    { "name": "Rent on Vast.ai (137 asks, p25 $0.312/h)", "category": "rental", "grossUsdDay": 3.29, "powerUsdDay": 0.33, "netUsdDay": 2.96, "notes": "assumes 55% utilization, 20% host fee" },
    { "name": "Mine QUAI (kawpow)", "category": "mining", "grossUsdDay": 0.82, "powerUsdDay": 0.77, "netUsdDay": 0.05, "notes": "pool fees ~1% not deducted" }
  ]
}

Unknown profileKey returns an error listing supported profiles.

score_networks

No input. Scores the internal network registry (points programs, emissions plays, cash networks) and returns the list sorted by risk-adjusted USD/day.

{ "name": "score_networks", "arguments": {} }

Example return (one entry):

[
  {
    "key": "grass",
    "name": "Grass (S3, listed)",
    "tier": "B",
    "contends": "ip_slot",
    "grossUsdDay": 0.028,
    "riskAdjUsdDay": 0.017,
    "priceUsd": 0.34,
    "liquidityUsd": 1200000,
    "realizable": 0.83,
    "flags": ["prix par adresse contrat (solana)", "realizable 83%", "ban ToS eleve"],
    "notes": "1 device/1 IP/1 compte, zero-sum pool, bans automation sans appel"
  }
]

get_alerts

Returns the last N alert lines from data/alerts.jsonl (types: NEW_COIN, PROFIT_SPIKE, HASH_BID_SPIKE, RENTAL_PRICE_MOVE), produced by the watcher cron (bun run src/watch-cli.ts). Input: limit (optional integer, 1 to 500, default 20).

{ "name": "get_alerts", "arguments": { "limit": 5 } }

Example return:

{
  "count": 2,
  "alerts": [
    { "ts": "2026-07-25T14:00:03.120Z", "type": "HASH_BID_SPIKE", "subject": "KAWPOW", "detail": "paying NiceHash x2.10: un acheteur surencherit sur ce hash", "ratio": 2.1 },
    { "ts": "2026-07-25T14:00:03.120Z", "type": "NEW_COIN", "subject": "TARI/randomx", "detail": "nouveau coin minable detecte sur WhatToMine, evaluer la fenetre d'emission" }
  ]
}

If the alerts file does not exist yet, the tool returns { "alerts": [], "note": "data/alerts.jsonl absent: lancer bun run src/watch-cli.ts" }.

llms.txt

The repo root contains an llms.txt written for AI agents: a one-paragraph description of the two engines (Yield Oracle and Network Scorer), the MCP registration snippet, the five tool signatures, and the CLI equivalents. Point a crawling agent at it as the entry point; it links back to the README for data sources and roadmap.