rolli-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

MCP (Model Context Protocol) server for Rolli IQ — exposes social media search and analytics tools (keyword search, user search, topic trees, post retrieval) across X, Reddit, YouTube, Facebook, Instagram, Threads, Bluesky, and more.

Commands

• Build: npm run build (runs tsc, outputs to build/)
• Lint: npm run lint (runs eslint src/)
• Test: npm test (runs vitest run)
• Publish: npm publish --access public (publishes to npm under the @rolli org)

Architecture

TypeScript ESM project using @modelcontextprotocol/sdk and zod.

• src/index.ts — Entry point. Creates McpServer, registers all tools, connects via StdioServerTransport.
• src/api.ts — HTTP client wrapping fetch for the Rolli APIs. Reads ROLLI_API_TOKEN and ROLLI_USER_ID from env vars. Exports apiGet/apiPost/apiPut/apiPatch/apiDelete (base https://rolli.ai/api) and agentGet/agentPost/agentPatch/agentDelete (base https://agent.rolli.ai, overridable via ROLLI_AGENT_BASE_URL).
• src/tools/_shared.ts — Cross-cutting helpers: pollUntilDone (status polling with results-settling — a search reporting finished with a null results column is NOT terminal; the poll waits up to an extra settle window and the tool returns status: "results_pending" instead of ever presenting success with a null payload), serializeCapped (deterministic response-size cap, default 100 KB — trims the largest arrays from the end, keeps analytics/scalar fields, adds truncated: true + a truncation report), preflightCredits (checks GET /iq/credits before agent runs; fails open if the endpoint is unavailable), mergeUsageAndCredits, annotateResultsPending, stripReportHtml, errorToText, and the config setters. This file must be kept byte-identical to rolli-remote-mcp/src/tools/_shared.ts — the two servers are required to behave exactly the same; verify with diff after any change. The file is env-free: src/index.ts reads env vars and calls the setters at startup.
• src/tools/ — Each file exports a register(server: McpServer) function that registers one or more MCP tools:
  • keyword-search.ts — list_keyword_searches, keyword_search, get_keyword_search
  • user-search.ts — list_user_searches, user_search, get_user_search
  • experts.ts — list_expert_searches, expert_search, get_expert_search
  • topic-tree.ts — get_topic_tree
  • posts.ts — get_keyword_search_posts, get_user_search_posts
  • agent-runs.ts — list_agent_runs, start_agent_run, get_agent_run, cancel_agent_run, rerun_agent_run, update_agent_run, delete_agent_run
  • agent-schedules.ts — list_agent_schedules, create_agent_schedule, get_agent_schedule, update_agent_schedule, delete_agent_schedule, pause_agent_schedule, resume_agent_schedule, list_agent_schedule_runs
  • integration-setup.ts — get_integration_setup, update_integration_setup
  • usage.ts — get_usage