@rolli/mcp 1.0.0

package/README.md

@@ -0,0 +1,86 @@
+# rolli-mcp
+
+MCP server for [Rolli IQ](https://rolli.ai) — social media search and analytics across X, Reddit, Bluesky, YouTube, LinkedIn, Facebook, Instagram, and Weibo.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_keyword_searches` | List all keyword searches, filtered by status |
+| `keyword_search` | Create a keyword/hashtag search across social platforms |
+| `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 |
+| `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 |
+
+## Setup
+
+You need a Rolli account with API access. Get your API token and user ID from [rolli.ai](https://rolli.ai).
+
+### Claude Desktop
+
+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):
+
+```json
+{
+  "mcpServers": {
+    "rolli": {
+      "command": "npx",
+      "args": ["-y", "@rolli/mcp"],
+      "env": {
+        "ROLLI_API_TOKEN": "your_token",
+        "ROLLI_USER_ID": "your_user_id"
+      }
+    }
+  }
+}
+```
+
+### Smithery
+
+This server includes a `smithery.yaml` for deployment via [Smithery](https://smithery.ai). It will prompt for your API token and user ID during setup.
+
+## Usage Examples
+
+**Search for a keyword across social media:**
+> "Search for posts about 'artificial intelligence' on Twitter and Reddit from the last week"
+
+**Analyze a user profile:**
+> "Look up @elonmusk on Twitter and analyze their recent posts"
+
+**Get topic breakdown:**
+> "Show me the topic tree for my keyword search #123"
+
+## License
+
+MIT

package/build/api.d.ts

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

package/build/api.js

@@ -0,0 +1,33 @@
+const BASE_URL = "https://rolli.ai/api";
+const ROLLI_API_TOKEN = process.env.ROLLI_API_TOKEN;
+const ROLLI_USER_ID = process.env.ROLLI_USER_ID;
+if (!ROLLI_API_TOKEN || !ROLLI_USER_ID) {
+    console.error("Error: ROLLI_API_TOKEN and ROLLI_USER_ID environment variables are required.\n" +
+        "Set them in your MCP client configuration.");
+    process.exit(1);
+}
+const headers = {
+    "X-ROLLI-TOKEN": ROLLI_API_TOKEN,
+    "X-ROLLI-USER-ID": ROLLI_USER_ID,
+    "Content-Type": "application/json",
+};
+export async function apiGet(path) {
+    const res = await fetch(`${BASE_URL}${path}`, { headers });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`API error ${res.status}: ${text}`);
+    }
+    return res.json();
+}
+export async function apiPost(path, body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method: "POST",
+        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.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+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";
+const server = new McpServer({
+    name: "rolli-mcp",
+    version: "1.0.0",
+});
+registerKeywordSearch(server);
+registerUserSearch(server);
+registerTopicTree(server);
+registerPosts(server);
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("Rolli MCP server running on stdio");

package/build/tools/keyword-search.d.ts

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

package/build/tools/keyword-search.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { apiPost, apiGet } from "../api.js";
+export function register(server) {
+    server.tool("list_keyword_searches", "List all keyword searches. Returns a paginated list filtered by status.", {
+        show: z
+            .enum(["all", "started", "finished", "pending", "failed"])
+            .optional()
+            .describe("Filter by status (default: all)"),
+        page: z.number().optional().describe("Page number (100 results per page)"),
+    }, async (params) => {
+        try {
+            const queryParts = [];
+            if (params.show)
+                queryParts.push(`show=${params.show}`);
+            if (params.page !== undefined)
+                queryParts.push(`page=${params.page}`);
+            const query = queryParts.length ? `?${queryParts.join("&")}` : "";
+            const data = await apiGet(`/iq/keyword_search${query}`);
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
+            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.", {
+        query: z.string().describe("Search query (keyword or hashtag)"),
+        platforms: z
+            .array(z.enum(["twitter", "reddit", "bluesky", "youtube", "linkedin", "facebook", "instagram", "weibo"]))
+            .optional()
+            .describe("Platforms to search (default: twitter, reddit, bluesky, youtube)"),
+        start_date: z.string().optional().describe("Start date (YYYY-MM-DD)"),
+        end_date: z.string().optional().describe("End date (YYYY-MM-DD)"),
+        max_post: z.number().optional().describe("Maximum number of posts to retrieve (default: 100)"),
+    }, async (params) => {
+        try {
+            const body = { query: params.query };
+            if (params.platforms)
+                body.platforms = params.platforms;
+            if (params.start_date)
+                body.start_date = params.start_date;
+            if (params.end_date)
+                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) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: String(e) }], isError: true };
+        }
+    });
+    server.tool("get_keyword_search", "Get results for a keyword search by ID. Returns search status, analytics summary, and posts.", {
+        id: z.number().describe("Keyword search ID"),
+    }, async (params) => {
+        try {
+            const data = await apiGet(`/iq/keyword_search/${params.id}`);
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: String(e) }], isError: true };
+        }
+    });
+}

package/build/tools/posts.d.ts

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

package/build/tools/posts.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { apiGet } from "../api.js";
+export function register(server) {
+    server.tool("get_keyword_search_posts", "Get raw posts from a keyword search. Returns the actual social media posts matching the search query.", {
+        search_id: z.number().describe("Keyword search ID"),
+        platform: z
+            .enum(["all", "twitter", "reddit", "bluesky", "youtube", "instagram", "facebook", "weibo", "linkedin"])
+            .optional()
+            .describe("Filter by platform (default: all)"),
+    }, async (params) => {
+        try {
+            const query = params.platform ? `?platform=${params.platform}` : "";
+            const data = await apiGet(`/iq/keyword_search/${params.search_id}/posts_data${query}`);
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: String(e) }], isError: true };
+        }
+    });
+    server.tool("get_user_search_posts", "Get raw posts from a user search. Returns the actual social media posts from the searched user profile.", {
+        search_id: z.number().describe("User search ID"),
+    }, async (params) => {
+        try {
+            const data = await apiGet(`/iq/user_search/${params.search_id}/posts_data`);
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: String(e) }], isError: true };
+        }
+    });
+}

package/build/tools/topic-tree.d.ts

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

package/build/tools/topic-tree.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { apiGet } from "../api.js";
+export function register(server) {
+    server.tool("get_topic_tree", "Get the conversation topic tree for a keyword search. Shows how topics and subtopics are distributed across the search results.", {
+        search_id: z.number().describe("Keyword search ID"),
+        platform: z
+            .enum(["twitter", "bluesky", "youtube"])
+            .optional()
+            .describe("Filter by platform"),
+    }, async (params) => {
+        try {
+            const query = params.platform ? `?platform=${params.platform}` : "";
+            const data = await apiGet(`/iq/keyword_search/${params.search_id}/topic_tree${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.d.ts

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

package/build/tools/user-search.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { apiPost, apiGet } from "../api.js";
+export function register(server) {
+    server.tool("list_user_searches", "List all user searches. Returns a paginated list filtered by status.", {
+        show: z
+            .enum(["all", "started", "finished", "pending", "failed"])
+            .optional()
+            .describe("Filter by status (default: all)"),
+        page: z.number().optional().describe("Page number (100 results per page)"),
+    }, async (params) => {
+        try {
+            const queryParts = [];
+            if (params.show)
+                queryParts.push(`show=${params.show}`);
+            if (params.page !== undefined)
+                queryParts.push(`page=${params.page}`);
+            const query = queryParts.length ? `?${queryParts.join("&")}` : "";
+            const data = await apiGet(`/iq/user_search${query}`);
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
+            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.", {
+        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)"),
+        end_date: z.string().optional().describe("End date (YYYY-MM-DD)"),
+    }, async (params) => {
+        try {
+            const body = {
+                query: params.query,
+                platform: params.platform,
+            };
+            if (params.start_date)
+                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) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: String(e) }], isError: true };
+        }
+    });
+    server.tool("get_user_search", "Get results for a user search by ID. Returns profile info, metrics, and content analysis.", {
+        id: z.number().describe("User search ID"),
+    }, async (params) => {
+        try {
+            const data = await apiGet(`/iq/user_search/${params.id}`);
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: String(e) }], isError: true };
+        }
+    });
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@rolli/mcp",
+  "version": "1.0.0",
+  "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",
+  "bin": {
+    "rolli-mcp": "build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc"
+  },
+  "keywords": [
+    "mcp",
+    "rolli",
+    "social-media",
+    "analytics",
+    "search",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3"
+  }
+}