feat(mcp): add scrape_artist_socials, get_scraper_results, get_artist_posts tools

Draft
SW
9h ago
+1076-112

Before: an agent connected to the Recoup MCP server could read an artist's social profiles but had no way to start a socials scrape, check a scrape run, or read the artist's posts. Those only existed as REST routes.

After: three MCP tools expose them:

  • scrape_artist_socials (write, spends credits): starts a scrape of every social linked to the artist. Checks artist access, gates credits for all linked profiles ($0.05 each + $0.01 per requested post), charges only the runs that started, and registers them as one batch, exactly like POST /api/artist/socials/scrape.
  • get_scraper_results (read): run status, plus the dataset once SUCCEEDED. Same as GET /api/apify/runs/{runId}: requires a credential but is not owner-scoped (chat#1840).
  • get_artist_posts (read): saved posts across the artist's socials with the REST pagination defaults (page 1, limit 20, max 100). Same as GET /api/artists/{id}/posts.

Tracking and merge order

How

  • Shared domain logic for REST and MCP: lib/artist/runArtistSocialsScrape.ts (access check, socials lookup, credit gate, start via startArtistSocialsScrape), lib/apify/getScraperRunResults.ts, and lib/posts/getArtistPosts.ts (posts envelope). The REST handlers and tools only map results to their own response shapes; REST responses are unchanged. The usage label is ARTIST_SOCIALS_SCRAPE_MODEL_ID in lib/const.ts.
  • Tools live in lib/mcp/tools/artistSocials/ and are registered via registerAllArtistSocialsTools, so they are available to API-key callers and to full OAuth (mcp:tools) grants. Full OAuth also runs the existing prepareFullOAuthTool artist gate on artist_account_id.
  • Classified in fullOAuthToolPolicy (scrape is readOnly: false with a credit notice), scripts/mcp-oauth/tool-policy.json (scrape: mcp:write + mcp:spend) and docs/mcp-oauth-tool-qualification.md. Full catalog count 89 → 92.
  • Not added to the limited mcp:read/mcp:write grant (registerOAuthTools), which keeps its existing five-tool contract.

Tests

  • New: tool tests for all three tools, runArtistSocialsScrape, startArtistSocialsScrape, getScraperRunResults, getArtistPosts.
  • pnpm test: 1485 files / 9462 tests pass.
  • tsc -p tsconfig.build.json and pnpm typecheck:mcp-oauth: clean. eslint and prettier clean on changed files.

Generated by Claude Code

Summary by cubic

Adds MCP tools for starting artist social scrapes, checking scrape runs, and listing saved posts—capabilities previously only available through REST.

  • scrape_artist_socials checks artist access, gates the full credit cost, charges only runs that started, and returns an error listing every failure when no run started (nothing was charged); MCP charges use the REST route label so usage groups together.
  • get_scraper_results returns run status and the dataset after success; like the REST route, it requires a credential but is not owner-scoped.
  • get_artist_posts uses the REST pagination defaults.
  • REST and MCP share the scrape orchestration (runArtistSocialsScrape), run-result logic, and posts envelope; REST responses are unchanged.
  • The tools are included in full OAuth policies but not the limited OAuth grant.

Generated by Claude Code