socialcrawl-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ridio Company
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# socialcrawl-mcp
+
+[![npm version](https://img.shields.io/npm/v/socialcrawl-mcp.svg)](https://www.npmjs.com/package/socialcrawl-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+MCP server for SocialCrawl — access 21+ social media platforms through one unified API.
+
+## What it does
+
+SocialCrawl MCP gives AI agents instant access to 21 social media platforms and 105 endpoints through a single, unified API. Retrieve profiles, posts, comments, search results, trending content, and analytics from TikTok, Instagram, YouTube, Twitter/X, LinkedIn, Reddit, and more — no per-platform authentication required. Agents discover available endpoints dynamically, so they always work with the latest capabilities without any hardcoded platform logic.
+
+## Quick Setup
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "socialcrawl": {
+      "command": "npx",
+      "args": ["-y", "socialcrawl-mcp"],
+      "env": {
+        "SOCIALCRAWL_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root or `~/.cursor/mcp.json` globally:
+
+```json
+{
+  "mcpServers": {
+    "socialcrawl": {
+      "command": "npx",
+      "args": ["-y", "socialcrawl-mcp"],
+      "env": {
+        "SOCIALCRAWL_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### VS Code (Claude Code)
+
+Add to `.vscode/mcp.json` in your project or your user settings:
+
+```json
+{
+  "servers": {
+    "socialcrawl": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "socialcrawl-mcp"],
+      "env": {
+        "SOCIALCRAWL_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## Get Your API Key
+
+1. Sign up at [socialcrawl.com](https://socialcrawl.com) — no credit card required
+2. Receive 100 free credits instantly upon registration
+3. Copy your API key from the dashboard and paste it into your config
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `socialcrawl_list_platforms` | Discover all 21 supported platforms with their slugs and endpoint counts |
+| `socialcrawl_list_endpoints` | See all endpoints, required parameters, and credit costs for a specific platform |
+| `socialcrawl_request` | Make any SocialCrawl API call — fetch profiles, posts, comments, search results, and more |
+| `socialcrawl_get_docs` | Access detailed API documentation for a platform or specific endpoint |
+
+## Example
+
+**User prompt:** "Get the TikTok profile for charlidamelio"
+
+**Agent flow:**
+
+1. Calls `socialcrawl_list_endpoints` with `platform: "tiktok"` to discover available endpoints
+2. Finds `user/info` endpoint — takes a `username` parameter, costs 1 credit
+3. Calls `socialcrawl_request` with `platform: "tiktok"`, `endpoint: "user/info"`, `params: { username: "charlidamelio" }`
+4. Returns profile data: follower count, bio, video count, verification status, and more
+
+## Supported Platforms
+
+| Platform | Endpoints |
+|----------|-----------|
+| TikTok | 24 |
+| Instagram | 12 |
+| YouTube | 11 |
+| Facebook | 12 |
+| X (Twitter) | 6 |
+| LinkedIn | 6 |
+| Reddit | 7 |
+| Threads | 5 |
+| Pinterest | 4 |
+| Google | 4 |
+| Truth Social | 3 |
+| Twitch | 2 |
+| Snapchat | 1 |
+| Kick | 1 |
+| Amazon | 1 |
+| Linktree | 1 |
+| Linkbio | 1 |
+| Linkme | 1 |
+| Komi | 1 |
+| Pillar | 1 |
+| Utility | 1 |
+
+**Total: 105 endpoints across 21 platforms**
+
+## Credit System
+
+| Tier | Cost | Share of Endpoints |
+|------|------|--------------------|
+| Standard | 1 credit | ~90% |
+| Advanced | 5 credits | ~8% |
+| Premium | 10 credits | ~2% |
+
+New accounts receive 100 free credits — enough to make 100 standard requests or explore multiple platforms before committing to a paid plan.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

package/dist/__tests__/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/client.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { makeRequest } from "../client.js";
+describe("API client", () => {
+    const originalEnv = process.env;
+    beforeEach(() => {
+        process.env = { ...originalEnv, SOCIALCRAWL_API_KEY: "sc_test_key" };
+    });
+    afterEach(() => {
+        process.env = originalEnv;
+        vi.restoreAllMocks();
+    });
+    it("returns error when API key is empty", async () => {
+        process.env.SOCIALCRAWL_API_KEY = "";
+        const result = await makeRequest({ platform: "tiktok", resource: "profile", params: { handle: "test" } });
+        expect(result).toContain("No API key configured");
+        expect(result).toContain("SOCIALCRAWL_API_KEY");
+    });
+    it("returns error when API key is not set", async () => {
+        delete process.env.SOCIALCRAWL_API_KEY;
+        const result = await makeRequest({ platform: "tiktok", resource: "profile", params: { handle: "test" } });
+        expect(result).toContain("No API key configured");
+    });
+    it("builds correct URL with params", async () => {
+        let capturedUrl = "";
+        vi.stubGlobal("fetch", async (url) => {
+            capturedUrl = url;
+            return new Response(JSON.stringify({ success: true, data: {} }), { status: 200 });
+        });
+        await makeRequest({ platform: "tiktok", resource: "profile", params: { handle: "charlidamelio" } });
+        expect(capturedUrl).toContain("/v1/tiktok/profile");
+        expect(capturedUrl).toContain("handle=charlidamelio");
+    });
+    it("builds correct URL without params", async () => {
+        let capturedUrl = "";
+        vi.stubGlobal("fetch", async (url) => {
+            capturedUrl = url;
+            return new Response(JSON.stringify({ success: true, data: {} }), { status: 200 });
+        });
+        await makeRequest({ platform: "tiktok", resource: "songs/popular" });
+        expect(capturedUrl).toContain("/v1/tiktok/songs/popular");
+        expect(capturedUrl).not.toContain("?");
+    });
+    it("maps 401 to invalid API key message", async () => {
+        vi.stubGlobal("fetch", async () => new Response(JSON.stringify({ success: false, error: { type: "INVALID_API_KEY", message: "Invalid key" } }), { status: 401 }));
+        const result = await makeRequest({ platform: "tiktok", resource: "profile", params: { handle: "test" } });
+        expect(result).toContain("Invalid API key");
+    });
+    it("maps 402 to insufficient credits message", async () => {
+        vi.stubGlobal("fetch", async () => new Response(JSON.stringify({ success: false, error: { type: "INSUFFICIENT_CREDITS", message: "No credits" }, credits_remaining: 0 }), { status: 402 }));
+        const result = await makeRequest({ platform: "tiktok", resource: "profile", params: { handle: "test" } });
+        expect(result).toContain("Insufficient credits");
+        expect(result).toContain("socialcrawl.com/billing");
+    });
+    it("maps 404 to endpoint not found message", async () => {
+        vi.stubGlobal("fetch", async () => new Response(JSON.stringify({ success: false, error: { type: "ENDPOINT_NOT_FOUND" } }), { status: 404 }));
+        const result = await makeRequest({ platform: "tiktok", resource: "fake", params: {} });
+        expect(result).toContain("not found");
+        expect(result).toContain("socialcrawl_list_endpoints");
+    });
+    it("maps 503 to platform unavailable message", async () => {
+        vi.stubGlobal("fetch", async () => new Response(JSON.stringify({ success: false, error: { type: "PLATFORM_UNAVAILABLE" } }), { status: 503 }));
+        const result = await makeRequest({ platform: "tiktok", resource: "profile", params: { handle: "test" } });
+        expect(result).toContain("temporarily unavailable");
+    });
+    it("maps 502 to upstream error with refund note", async () => {
+        vi.stubGlobal("fetch", async () => new Response(JSON.stringify({ success: false, error: { type: "UPSTREAM_ERROR" } }), { status: 502 }));
+        const result = await makeRequest({ platform: "tiktok", resource: "profile", params: { handle: "test" } });
+        expect(result).toContain("Upstream error");
+        expect(result).toContain("auto-refunded");
+    });
+});
+//# sourceMappingURL=client.test.js.map

package/dist/__tests__/client.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.js","sourceRoot":"","sources":["../../src/__tests__/client.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/data-integrity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/data-integrity.test.js

@@ -0,0 +1,107 @@
+import { describe, it, expect } from "vitest";
+import { PLATFORMS, findPlatform, getAllPlatformSlugs } from "../data/platforms.js";
+import { ENDPOINTS, findEndpoint, getEndpointsByPlatform } from "../data/endpoints.js";
+import { getDoc, getAvailableTopics } from "../data/docs.js";
+describe("Platform data integrity", () => {
+    it("has exactly 21 platforms", () => {
+        expect(PLATFORMS).toHaveLength(21);
+    });
+    it("every platform has a non-empty slug, name, and description", () => {
+        for (const platform of PLATFORMS) {
+            expect(platform.slug).toBeTruthy();
+            expect(platform.name).toBeTruthy();
+            expect(platform.description).toBeTruthy();
+            expect(platform.endpointCount).toBeGreaterThan(0);
+        }
+    });
+    it("has no duplicate platform slugs", () => {
+        const slugs = PLATFORMS.map((p) => p.slug);
+        expect(new Set(slugs).size).toBe(slugs.length);
+    });
+    it("findPlatform returns correct platform", () => {
+        const tiktok = findPlatform("tiktok");
+        expect(tiktok).toBeDefined();
+        expect(tiktok.name).toBe("TikTok");
+    });
+    it("findPlatform returns undefined for unknown slug", () => {
+        expect(findPlatform("nonexistent")).toBeUndefined();
+    });
+    it("getAllPlatformSlugs returns 21 slugs", () => {
+        expect(getAllPlatformSlugs()).toHaveLength(21);
+    });
+});
+describe("Endpoint data integrity", () => {
+    it("has at least 100 endpoints", () => {
+        expect(ENDPOINTS.length).toBeGreaterThanOrEqual(100);
+    });
+    it("every endpoint has required fields", () => {
+        for (const endpoint of ENDPOINTS) {
+            expect(endpoint.platform).toBeTruthy();
+            expect(endpoint.resource).toBeTruthy();
+            expect(endpoint.method).toBe("GET");
+            expect(["standard", "advanced", "premium"]).toContain(endpoint.creditTier);
+            expect([1, 5, 10]).toContain(endpoint.creditCost);
+            expect(endpoint.archetype).toBeTruthy();
+            expect(endpoint.summary).toBeTruthy();
+        }
+    });
+    it("creditCost matches creditTier", () => {
+        const tierCosts = { standard: 1, advanced: 5, premium: 10 };
+        for (const endpoint of ENDPOINTS) {
+            expect(endpoint.creditCost).toBe(tierCosts[endpoint.creditTier]);
+        }
+    });
+    it("every endpoint belongs to a known platform", () => {
+        const slugs = new Set(getAllPlatformSlugs());
+        for (const endpoint of ENDPOINTS) {
+            expect(slugs.has(endpoint.platform)).toBe(true);
+        }
+    });
+    it("every platform has endpoints matching its declared count", () => {
+        for (const platform of PLATFORMS) {
+            const endpoints = getEndpointsByPlatform(platform.slug);
+            expect(endpoints.length).toBe(platform.endpointCount);
+        }
+    });
+    it("every param has name, description, and example", () => {
+        for (const endpoint of ENDPOINTS) {
+            for (const param of endpoint.params) {
+                expect(param.name).toBeTruthy();
+                expect(param.description).toBeTruthy();
+                expect(param.example).toBeTruthy();
+            }
+        }
+    });
+    it("findEndpoint returns correct endpoint", () => {
+        const ep = findEndpoint("tiktok", "profile");
+        expect(ep).toBeDefined();
+        expect(ep.archetype).toBe("Author");
+        expect(ep.params.length).toBeGreaterThan(0);
+        expect(ep.params[0].name).toBe("handle");
+    });
+    it("findEndpoint returns undefined for unknown resource", () => {
+        expect(findEndpoint("tiktok", "nonexistent")).toBeUndefined();
+    });
+});
+describe("Documentation data integrity", () => {
+    it("has overview, full, authentication, credits, and errors topics", () => {
+        expect(getDoc("overview")).toBeTruthy();
+        expect(getDoc("full")).toBeTruthy();
+        expect(getDoc("authentication")).toBeTruthy();
+        expect(getDoc("credits")).toBeTruthy();
+        expect(getDoc("errors")).toBeTruthy();
+    });
+    it("has documentation for every platform", () => {
+        for (const platform of PLATFORMS) {
+            const doc = getDoc(platform.slug);
+            expect(doc, `Missing docs for platform: ${platform.slug}`).toBeTruthy();
+        }
+    });
+    it("getDoc returns undefined for unknown topic", () => {
+        expect(getDoc("nonexistent")).toBeUndefined();
+    });
+    it("getAvailableTopics returns at least 26 topics", () => {
+        expect(getAvailableTopics().length).toBeGreaterThanOrEqual(26);
+    });
+});
+//# sourceMappingURL=data-integrity.test.js.map

package/dist/__tests__/data-integrity.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-integrity.test.js","sourceRoot":"","sources":["../../src/__tests__/data-integrity.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/preflight.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/preflight.test.js

@@ -0,0 +1,28 @@
+import { describe, it, expect } from "vitest";
+import { request } from "../tools/request.js";
+describe("Pre-flight validation", () => {
+    it("rejects unknown platform", async () => {
+        const result = await request({ platform: "fakebook", resource: "profile" });
+        expect(result).toContain("Unknown platform");
+        expect(result).toContain("socialcrawl_list_platforms");
+    });
+    it("rejects unknown resource for valid platform", async () => {
+        const result = await request({ platform: "tiktok", resource: "nonexistent" });
+        expect(result).toContain("Unknown resource");
+        expect(result).toContain("socialcrawl_list_endpoints");
+    });
+    it("rejects missing required params", async () => {
+        const result = await request({ platform: "tiktok", resource: "profile", params: {} });
+        expect(result).toContain("Missing required parameter");
+        expect(result).toContain("handle");
+    });
+    it("rejects when no params provided but endpoint requires them", async () => {
+        const result = await request({ platform: "tiktok", resource: "profile" });
+        expect(result).toContain("Missing required parameter");
+    });
+    it("passes validation for endpoints with no required params", async () => {
+        const result = await request({ platform: "tiktok", resource: "songs/popular" });
+        expect(result).toContain("No API key configured");
+    });
+});
+//# sourceMappingURL=preflight.test.js.map

package/dist/__tests__/preflight.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.test.js","sourceRoot":"","sources":["../../src/__tests__/preflight.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAE9C,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,EAAE,CAAC,0BAA0B,EAAE,KAAK,IAAI,EAAE;QACxC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;QAC5E,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;QAC7C,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,4BAA4B,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;QAC3D,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,CAAC;QAC9E,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;QAC7C,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,4BAA4B,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,KAAK,IAAI,EAAE;QAC/C,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QACtF,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,4BAA4B,CAAC,CAAC;QACvD,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4DAA4D,EAAE,KAAK,IAAI,EAAE;QAC1E,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;QAC1E,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,4BAA4B,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,KAAK,IAAI,EAAE;QACvE,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC,CAAC;QAChF,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,uBAAuB,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/truncation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/truncation.test.js

@@ -0,0 +1,36 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { makeRequest } from "../client.js";
+import { CHARACTER_LIMIT } from "../constants.js";
+describe("Response truncation", () => {
+    const originalEnv = process.env;
+    beforeEach(() => {
+        process.env = { ...originalEnv, SOCIALCRAWL_API_KEY: "sc_test_key" };
+    });
+    afterEach(() => {
+        process.env = originalEnv;
+        vi.restoreAllMocks();
+    });
+    it("does not truncate responses under the limit", async () => {
+        const shortBody = JSON.stringify({ success: true, data: "short" });
+        vi.stubGlobal("fetch", async () => new Response(shortBody, { status: 200 }));
+        const result = await makeRequest({ platform: "tiktok", resource: "profile", params: { handle: "test" } });
+        expect(result).toBe(shortBody);
+        expect(result).not.toContain("truncated");
+    });
+    it("truncates responses over the character limit", async () => {
+        const longBody = "x".repeat(CHARACTER_LIMIT + 1000);
+        vi.stubGlobal("fetch", async () => new Response(longBody, { status: 200 }));
+        const result = await makeRequest({ platform: "tiktok", resource: "profile", params: { handle: "test" } });
+        expect(result).toContain("truncated");
+        expect(result).toContain(CHARACTER_LIMIT.toLocaleString());
+        expect(result.length).toBeLessThan(longBody.length);
+    });
+    it("reports full response length when truncating", async () => {
+        const fullLength = CHARACTER_LIMIT + 5000;
+        const longBody = "x".repeat(fullLength);
+        vi.stubGlobal("fetch", async () => new Response(longBody, { status: 200 }));
+        const result = await makeRequest({ platform: "tiktok", resource: "profile", params: { handle: "test" } });
+        expect(result).toContain(fullLength.toLocaleString());
+    });
+});
+//# sourceMappingURL=truncation.test.js.map

package/dist/__tests__/truncation.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncation.test.js","sourceRoot":"","sources":["../../src/__tests__/truncation.test.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,7 @@
+interface RequestOptions {
+    platform: string;
+    resource: string;
+    params?: Record<string, string>;
+}
+export declare function makeRequest(options: RequestOptions): Promise<string>;
+export {};

package/dist/client.js

@@ -0,0 +1,86 @@
+import { TIMEOUT_MS, CHARACTER_LIMIT } from "./constants.js";
+function getBaseUrl() {
+    return process.env.SOCIALCRAWL_BASE_URL ?? "https://api.socialcrawl.com";
+}
+function getApiKey() {
+    return process.env.SOCIALCRAWL_API_KEY ?? "";
+}
+export async function makeRequest(options) {
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        return "Error: No API key configured. Set SOCIALCRAWL_API_KEY in your MCP server environment. Get a free key at socialcrawl.com (100 credits, no credit card required).";
+    }
+    const url = buildUrl(options);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const response = await fetch(url, {
+            method: "GET",
+            headers: {
+                "x-api-key": apiKey,
+            },
+            signal: controller.signal,
+        });
+        const body = await response.text();
+        if (!response.ok) {
+            return formatHttpError(response.status, body, options);
+        }
+        return truncateResponse(body);
+    }
+    catch (error) {
+        if (error instanceof DOMException && error.name === "AbortError") {
+            return `Error: Request timed out after ${TIMEOUT_MS / 1000} seconds. The platform may be experiencing delays.`;
+        }
+        if (error instanceof TypeError && (error.message.includes("fetch") || error.message.includes("network"))) {
+            return `Error: Could not reach SocialCrawl API at ${getBaseUrl()}. Check your network connection.`;
+        }
+        return `Error: Unexpected error — ${error instanceof Error ? error.message : String(error)}`;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+function buildUrl(options) {
+    const base = `${getBaseUrl()}/v1/${options.platform}/${options.resource}`;
+    if (!options.params || Object.keys(options.params).length === 0) {
+        return base;
+    }
+    const searchParams = new URLSearchParams(options.params);
+    return `${base}?${searchParams.toString()}`;
+}
+function formatHttpError(status, body, options) {
+    let parsed = null;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        // body is not JSON, use raw text
+    }
+    const errorType = parsed?.error?.type ?? "UNKNOWN_ERROR";
+    const errorMessage = parsed?.error?.message ?? body;
+    switch (status) {
+        case 401:
+            return "Error: Invalid API key. Check your SOCIALCRAWL_API_KEY configuration.";
+        case 402:
+            return `Error: Insufficient credits (${parsed?.credits_remaining ?? 0} remaining). Top up at socialcrawl.com/billing.`;
+        case 400:
+            return `Error: ${errorMessage}`;
+        case 404:
+            return `Error: Endpoint /v1/${options.platform}/${options.resource} not found. Use socialcrawl_list_endpoints to see available endpoints for ${options.platform}.`;
+        case 503:
+            return `Error: Platform ${options.platform} is temporarily unavailable. Try again shortly.`;
+        case 502:
+            return "Error: Upstream error fetching data. Credits have been auto-refunded.";
+        case 429:
+            return "Error: Too many concurrent requests. Wait a moment and try again.";
+        default:
+            return `Error (${status}): ${errorType} — ${errorMessage}`;
+    }
+}
+function truncateResponse(body) {
+    if (body.length <= CHARACTER_LIMIT) {
+        return body;
+    }
+    return `${body.slice(0, CHARACTER_LIMIT)}\n\n[Response truncated at ${CHARACTER_LIMIT.toLocaleString()} characters. Full response was ${body.length.toLocaleString()} characters.]`;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const CHARACTER_LIMIT = 25000;
+export declare const TIMEOUT_MS = 30000;
+export declare const CREDIT_COSTS: Record<string, number>;
+export declare const SERVER_NAME = "socialcrawl-mcp";
+export declare const SERVER_VERSION = "1.0.0";

package/dist/constants.js

@@ -0,0 +1,10 @@
+export const CHARACTER_LIMIT = 25_000;
+export const TIMEOUT_MS = 30_000;
+export const CREDIT_COSTS = {
+    standard: 1,
+    advanced: 5,
+    premium: 10,
+};
+export const SERVER_NAME = "socialcrawl-mcp";
+export const SERVER_VERSION = "1.0.0";
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AACtC,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC;AAEjC,MAAM,CAAC,MAAM,YAAY,GAA2B;IAClD,QAAQ,EAAE,CAAC;IACX,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,EAAE;CACH,CAAC;AAEX,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAC7C,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC"}

package/dist/data/docs.d.ts

@@ -0,0 +1,3 @@
+export declare const DOCS: Record<string, string>;
+export declare function getDoc(topic: string): string | undefined;
+export declare function getAvailableTopics(): string[];