@rolli/mcp 1.0.0 → 1.1.1

package/README.md

@@ -7,49 +7,25 @@ MCP server for [Rolli IQ](https://rolli.ai) — social media search and analytic
 | Tool | Description |
 |------|-------------|
 | `list_keyword_searches` | List all keyword searches, filtered by status |
-| `keyword_search` | Create a keyword/hashtag search across social platforms |
+| `keyword_search` | Create a keyword/hashtag search and return results when complete |
 | `get_keyword_search` | Get keyword search results (status, analytics, posts) |
 | `list_user_searches` | List all user searches, filtered by status |
-| `user_search` | Create a user profile search on a platform |
+| `user_search` | Create a user profile search and return results when complete |
 | `get_user_search` | Get user search results (profile, metrics, content analysis) |
 | `get_topic_tree` | Get conversation topic tree for a keyword search |
 | `get_keyword_search_posts` | Get raw posts from a keyword search |
 | `get_user_search_posts` | Get raw posts from a user search |
+| `get_integration_setup` | Get current integration settings (webhook URL, name) |
+| `update_integration_setup` | Set the webhook URL for search completion notifications |
+| `get_usage` | Get API usage data and per-user breakdowns |
 
 ## Setup
 
 You need a Rolli account with API access. Get your API token and user ID from [rolli.ai](https://rolli.ai).
 
-### Claude Desktop
+### Claude Desktop / Claude Code / VS Code / Cursor / Windsurf
 
-Add to your Claude Desktop config (`claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "rolli": {
-      "command": "npx",
-      "args": ["-y", "@rolli/mcp"],
-      "env": {
-        "ROLLI_API_TOKEN": "your_token",
-        "ROLLI_USER_ID": "your_user_id"
-      }
-    }
-  }
-}
-```
-
-### Claude Code
-
-```sh
-claude mcp add rolli -- npx -y @rolli/mcp
-```
-
-Then set the environment variables `ROLLI_API_TOKEN` and `ROLLI_USER_ID`.
-
-### VS Code / Cursor / Windsurf
-
-Add to your MCP settings (`.vscode/mcp.json` or equivalent):
+Add to your MCP config (`claude_desktop_config.json`, `.vscode/mcp.json`, or equivalent):
 
 ```json
 {
@@ -81,6 +57,12 @@ This server includes a `smithery.yaml` for deployment via [Smithery](https://smi
 **Get topic breakdown:**
 > "Show me the topic tree for my keyword search #123"
 
+**Check API usage:**
+> "How many searches have I used this month?"
+
+**Set up a webhook:**
+> "Set my webhook URL to https://myapp.com/rolli-callback"
+
 ## License
 
 MIT

package/build/api.d.ts

@@ -1,2 +1,3 @@
 export declare function apiGet(path: string): Promise<unknown>;
 export declare function apiPost(path: string, body: unknown): Promise<unknown>;
+export declare function apiPut(path: string, body: unknown): Promise<unknown>;

package/build/api.js

@@ -31,3 +31,15 @@ export async function apiPost(path, body) {
     }
     return res.json();
 }
+export async function apiPut(path, body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method: "PUT",
+        headers,
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`API error ${res.status}: ${text}`);
+    }
+    return res.json();
+}

package/build/index.js

@@ -5,6 +5,8 @@ import { register as registerKeywordSearch } from "./tools/keyword-search.js";
 import { register as registerUserSearch } from "./tools/user-search.js";
 import { register as registerTopicTree } from "./tools/topic-tree.js";
 import { register as registerPosts } from "./tools/posts.js";
+import { register as registerIntegrationSetup } from "./tools/integration-setup.js";
+import { register as registerUsage } from "./tools/usage.js";
 const server = new McpServer({
     name: "rolli-mcp",
     version: "1.0.0",
@@ -13,6 +15,8 @@ registerKeywordSearch(server);
 registerUserSearch(server);
 registerTopicTree(server);
 registerPosts(server);
+registerIntegrationSetup(server);
+registerUsage(server);
 const transport = new StdioServerTransport();
 await server.connect(transport);
 console.error("Rolli MCP server running on stdio");

package/build/tools/integration-setup.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function register(server: McpServer): void;

package/build/tools/integration-setup.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { apiGet, apiPut } from "../api.js";
+export function register(server) {
+    server.tool("get_integration_setup", "Get the current integration settings (webhook return URL and integration name).", {}, async () => {
+        try {
+            const data = await apiGet("/setup");
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: String(e) }], isError: true };
+        }
+    });
+    server.tool("update_integration_setup", "Update integration configuration. Set the webhook URL that receives notifications when a search completes.", {
+        return_url: z.string().describe("URL that will receive webhook notifications when a search completes"),
+    }, async (params) => {
+        try {
+            const data = await apiPut("/setup", { return_url: params.return_url });
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: String(e) }], isError: true };
+        }
+    });
+}

package/build/tools/keyword-search.js

@@ -1,5 +1,10 @@
 import { z } from "zod";
 import { apiPost, apiGet } from "../api.js";
+const POLL_INTERVAL_MS = 5_000;
+const MAX_POLL_MS = 10 * 60 * 1_000; // 10 minutes
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 export function register(server) {
     server.tool("list_keyword_searches", "List all keyword searches. Returns a paginated list filtered by status.", {
         show: z
@@ -22,7 +27,7 @@ export function register(server) {
             return { content: [{ type: "text", text: String(e) }], isError: true };
         }
     });
-    server.tool("keyword_search", "Create a keyword/hashtag search across social media platforms (X, Reddit, Bluesky, YouTube, LinkedIn, Facebook, Instagram, Weibo). Returns a search ID to retrieve results later.", {
+    server.tool("keyword_search", "Create a keyword/hashtag search across social media platforms (X, Reddit, Bluesky, YouTube, LinkedIn, Facebook, Instagram, Weibo). Polls until the search is complete and returns the full results.", {
         query: z.string().describe("Search query (keyword or hashtag)"),
         platforms: z
             .array(z.enum(["twitter", "reddit", "bluesky", "youtube", "linkedin", "facebook", "instagram", "weibo"]))
@@ -42,8 +47,21 @@ export function register(server) {
                 body.end_date = params.end_date;
             if (params.max_post !== undefined)
                 body.max_post = params.max_post;
-            const data = await apiPost("/iq/keyword_search", body);
-            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+            const createResult = await apiPost("/iq/keyword_search", body);
+            const searchId = createResult.keyword_search?.id ?? createResult.id;
+            if (searchId == null) {
+                return { content: [{ type: "text", text: JSON.stringify(createResult, null, 2) }] };
+            }
+            const startTime = Date.now();
+            while (Date.now() - startTime < MAX_POLL_MS) {
+                await sleep(POLL_INTERVAL_MS);
+                const data = await apiGet(`/iq/keyword_search/${searchId}`);
+                const status = data.keyword_search?.status ?? data.status;
+                if (status === "finished" || status === "failed") {
+                    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+                }
+            }
+            return { content: [{ type: "text", text: `Search ${searchId} timed out after 10 minutes. Use get_keyword_search to check status.` }], isError: true };
         }
         catch (e) {
             return { content: [{ type: "text", text: String(e) }], isError: true };

package/build/tools/usage.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function register(server: McpServer): void;

package/build/tools/usage.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { apiGet } from "../api.js";
+export function register(server) {
+    server.tool("get_usage", "Get API usage data. Returns search counts and per-user breakdowns. Optionally filter by month.", {
+        month: z
+            .string()
+            .optional()
+            .describe("Month to query (YYYY-MM format). Omit to get the last 12 months."),
+    }, async (params) => {
+        try {
+            const query = params.month ? `?month=${params.month}` : "";
+            const data = await apiGet(`/usage${query}`);
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: String(e) }], isError: true };
+        }
+    });
+}

package/build/tools/user-search.js

@@ -1,5 +1,10 @@
 import { z } from "zod";
 import { apiPost, apiGet } from "../api.js";
+const POLL_INTERVAL_MS = 5_000;
+const MAX_POLL_MS = 10 * 60 * 1_000; // 10 minutes
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 export function register(server) {
     server.tool("list_user_searches", "List all user searches. Returns a paginated list filtered by status.", {
         show: z
@@ -22,7 +27,7 @@ export function register(server) {
             return { content: [{ type: "text", text: String(e) }], isError: true };
         }
     });
-    server.tool("user_search", "Create a user profile search on a social media platform. Returns a search ID to retrieve results later.", {
+    server.tool("user_search", "Create a user profile search on a social media platform. Polls until the search is complete and returns the full results.", {
         query: z.string().describe("Username or profile URL to search"),
         platform: z.enum(["twitter", "facebook", "instagram"]).describe("Platform to search"),
         start_date: z.string().optional().describe("Start date (YYYY-MM-DD)"),
@@ -37,8 +42,21 @@ export function register(server) {
                 body.start_date = params.start_date;
             if (params.end_date)
                 body.end_date = params.end_date;
-            const data = await apiPost("/iq/user_search", body);
-            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+            const createResult = await apiPost("/iq/user_search", body);
+            const searchId = createResult.user_search?.id ?? createResult.id;
+            if (searchId == null) {
+                return { content: [{ type: "text", text: JSON.stringify(createResult, null, 2) }] };
+            }
+            const startTime = Date.now();
+            while (Date.now() - startTime < MAX_POLL_MS) {
+                await sleep(POLL_INTERVAL_MS);
+                const data = await apiGet(`/iq/user_search/${searchId}`);
+                const status = data.user_search?.status ?? data.status;
+                if (status === "finished" || status === "failed") {
+                    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+                }
+            }
+            return { content: [{ type: "text", text: `Search ${searchId} timed out after 10 minutes. Use get_user_search to check status.` }], isError: true };
         }
         catch (e) {
             return { content: [{ type: "text", text: String(e) }], isError: true };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rolli/mcp",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "MCP server for Rolli IQ — social media search and analytics across X, Reddit, Bluesky, YouTube, LinkedIn, Facebook, Instagram, and Weibo",
   "type": "module",
   "main": "build/index.js",
@@ -12,7 +12,8 @@
   ],
   "scripts": {
     "build": "tsc",
-    "prepare": "tsc"
+    "prepare": "tsc",
+    "test": "vitest run"
   },
   "keywords": [
     "mcp",
@@ -32,6 +33,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.15.3",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.18"
   }
 }