feat(mcp): get_published_posts and get_published_post_stats tools

Draft
SW
5d ago
+815-89

Before: an MCP agent could not list the posts Recoup published or read their LinkedIn numbers. GET /api/posts and GET /api/posts/{id}/stats existed only over REST, and get_artist_posts returns scraped posts, which carry no post id that stats can take.

After: two MCP tools mirror those routes. get_published_posts lists the credential account's posts with optional artist_account_id, platform, status, limit (max 50) and offset, in the REST { status, posts } envelope. get_published_post_stats takes a post id and returns the REST { status, stats } envelope: LinkedIn company-page posts only, credits checked before LinkedIn is called, $0.001 charged after a successful read. REST rejections come back as tool errors with the same message.

How:

  • lib/publishing/getPosts.ts and lib/publishing/stats/getPostStats.ts hold the reads the handlers used to do inline; both handlers now call them, with REST bodies and status codes unchanged. getPostStats returns ok, insufficient_credits or rejected (with the REST status and message). It gates with checkCreditsAvailable, and the handler builds the same 402 body ensureCreditsOrShortCircuit did, so the three handler test files now mock checkCreditsAvailable instead.
  • Tools in lib/mcp/tools/posts/, registered from lib/mcp/tools/index.ts. No account_id input; the account comes from resolveAccountId.
  • fullOAuthToolPolicy.ts (main's readOnly/destructive/openWorld shape): get_published_posts is read-only, not destructive, closed world; get_published_post_stats is read-only, not destructive, open world (LinkedIn via Composio) with a $0.001 notice. Both are pinned in the fullOAuthCatalog annotation table. tool-policy.json: mcp:read for the list, mcp:read + mcp:spend for stats (like search_web). Two rows in docs/mcp-oauth-tool-qualification.md. Delegated catalog 96 tools, 95 non-app (main is at 94/93).

Tests (red first): getPosts.test.ts, getPostStats.test.ts (each rejection, credit shortfall, LinkedIn 502, DB error), and register-tool tests for both tools. After merging main on Nov 18: full suite 1,531 files, 10,055 tests passed; eslint and prettier clean on changed files. Preview checks: see the results comment (run on the pre-merge commit; the tool code is unchanged by the merge).

Merge sequencing: docs#40 (contract) -> this PR -> docs follow-up pinning the operation inventory.

Tracking: recoupable/app#2399


Generated by Claude Code