mindcase-mcp 0.1.0__tar.gz

mindcase_mcp-0.1.0/.env.example

@@ -0,0 +1 @@
+MINDCASE_API_KEY=mk_live_your_api_key_here

mindcase_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

mindcase_mcp-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.DS_Store
+*.log

mindcase_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mindcase
+
+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.

mindcase_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: mindcase-mcp
+Version: 0.1.0
+Summary: MCP server for Mindcase — 30+ data collection agents accessible from Claude
+Project-URL: Homepage, https://mindcase.co
+Project-URL: Repository, https://github.com/mindcase-co/mindcase-mcp
+Project-URL: Documentation, https://docs.mindcase.co
+Author-email: Mindcase <team@mindcase.co>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Description-Content-Type: text/markdown
+
+# Mindcase MCP Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](https://opensource.org/licenses/MIT)
+
+MCP server for [Mindcase](https://mindcase.co) — access 30+ data collection agents from Claude. Scrape LinkedIn, Instagram, Google Maps, Amazon, YouTube, and more with natural language.
+
+## Quick Start
+
+### 1. Get an API key
+
+Sign up at [app.mindcase.co](https://app.mindcase.co) and create an API key in the API Console.
+
+### 2. Install and configure
+
+```bash
+git clone https://github.com/mindcase-co/mindcase-mcp.git
+cd mindcase-mcp
+cp .env.example .env
+```
+
+Edit `.env` and add your API key:
+```
+MINDCASE_API_KEY=mk_live_your_api_key_here
+```
+
+### 3. Add to Claude
+
+**Claude Code (CLI):**
+```bash
+claude mcp add mindcase -- uv --directory /path/to/mindcase-mcp run server.py
+```
+
+**Claude Desktop:**
+
+Add to your config (`~/.config/Claude/claude_desktop_config.json` on Mac/Linux):
+
+```json
+{
+  "mcpServers": {
+    "mindcase": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/mindcase-mcp", "run", "server.py"]
+    }
+  }
+}
+```
+
+No need to pass the API key in the config — it's read from the `.env` file automatically.
+
+### 4. Use it
+
+Ask Claude things like:
+- "Find coffee shops in Manhattan with ratings above 4.5"
+- "Search LinkedIn for AI startups in San Francisco"
+- "Get Instagram profiles for Nike, Adidas, and Puma"
+- "Scrape Amazon reviews for this product"
+- "Find Python developer jobs on Indeed in New York"
+
+## Available Tools
+
+### Utility Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_agents` | Browse all 30+ available data agents |
+| `check_credits` | Check your remaining credit balance |
+| `get_agent_details` | View parameters and pricing for a specific agent |
+
+### Data Collection Tools
+
+All agents from the Mindcase API are registered as individual tools:
+
+| Platform | Tools |
+|----------|-------|
+| **LinkedIn** | Profiles, Companies, Employees, Jobs, Posts, People Search, Company Search, Domain Lookup |
+| **Instagram** | Profiles, Posts, Comments |
+| **YouTube** | Videos, Channels, Comments, Shorts |
+| **Amazon** | Products, Reviews, Bestsellers, India Products |
+| **Google Maps** | Businesses, Reviews, Reverse Geocoding |
+| **Twitter / X** | Posts |
+| **TikTok** | Profiles |
+| **Reddit** | Posts |
+| **Shopify** | Products |
+| **Indeed** | Jobs |
+| **App Store** | Reviews |
+| **Flipkart** | Products |
+| **Myntra** | Products |
+
+Each tool accepts the agent's specific parameters and returns structured data in a table format.
+
+## How It Works
+
+1. On startup, the server fetches all available agents from the Mindcase API
+2. Each agent is registered as an MCP tool with its parameter schema
+3. When Claude calls a tool, the server runs the agent via the API
+4. The server polls for results and returns structured data to Claude
+
+## Configuration
+
+| Environment Variable | Description | Required |
+|---------------------|-------------|----------|
+| `MINDCASE_API_KEY` | Your Mindcase API key (`mk_live_...`) | Yes |
+
+## Documentation
+
+- [Mindcase API Docs](https://docs.mindcase.co)
+- [Agent Reference](https://docs.mindcase.co/agents-overview)
+- [Python SDK](https://github.com/mindcase-co/mindcase-python)
+- [Node.js SDK](https://github.com/mindcase-co/mindcase-node)
+
+## Privacy
+
+See [privacy-policy.md](privacy-policy.md) for details on data handling.
+
+## License
+
+MIT

mindcase_mcp-0.1.0/README.md

@@ -0,0 +1,117 @@
+# Mindcase MCP Server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](https://opensource.org/licenses/MIT)
+
+MCP server for [Mindcase](https://mindcase.co) — access 30+ data collection agents from Claude. Scrape LinkedIn, Instagram, Google Maps, Amazon, YouTube, and more with natural language.
+
+## Quick Start
+
+### 1. Get an API key
+
+Sign up at [app.mindcase.co](https://app.mindcase.co) and create an API key in the API Console.
+
+### 2. Install and configure
+
+```bash
+git clone https://github.com/mindcase-co/mindcase-mcp.git
+cd mindcase-mcp
+cp .env.example .env
+```
+
+Edit `.env` and add your API key:
+```
+MINDCASE_API_KEY=mk_live_your_api_key_here
+```
+
+### 3. Add to Claude
+
+**Claude Code (CLI):**
+```bash
+claude mcp add mindcase -- uv --directory /path/to/mindcase-mcp run server.py
+```
+
+**Claude Desktop:**
+
+Add to your config (`~/.config/Claude/claude_desktop_config.json` on Mac/Linux):
+
+```json
+{
+  "mcpServers": {
+    "mindcase": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/mindcase-mcp", "run", "server.py"]
+    }
+  }
+}
+```
+
+No need to pass the API key in the config — it's read from the `.env` file automatically.
+
+### 4. Use it
+
+Ask Claude things like:
+- "Find coffee shops in Manhattan with ratings above 4.5"
+- "Search LinkedIn for AI startups in San Francisco"
+- "Get Instagram profiles for Nike, Adidas, and Puma"
+- "Scrape Amazon reviews for this product"
+- "Find Python developer jobs on Indeed in New York"
+
+## Available Tools
+
+### Utility Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_agents` | Browse all 30+ available data agents |
+| `check_credits` | Check your remaining credit balance |
+| `get_agent_details` | View parameters and pricing for a specific agent |
+
+### Data Collection Tools
+
+All agents from the Mindcase API are registered as individual tools:
+
+| Platform | Tools |
+|----------|-------|
+| **LinkedIn** | Profiles, Companies, Employees, Jobs, Posts, People Search, Company Search, Domain Lookup |
+| **Instagram** | Profiles, Posts, Comments |
+| **YouTube** | Videos, Channels, Comments, Shorts |
+| **Amazon** | Products, Reviews, Bestsellers, India Products |
+| **Google Maps** | Businesses, Reviews, Reverse Geocoding |
+| **Twitter / X** | Posts |
+| **TikTok** | Profiles |
+| **Reddit** | Posts |
+| **Shopify** | Products |
+| **Indeed** | Jobs |
+| **App Store** | Reviews |
+| **Flipkart** | Products |
+| **Myntra** | Products |
+
+Each tool accepts the agent's specific parameters and returns structured data in a table format.
+
+## How It Works
+
+1. On startup, the server fetches all available agents from the Mindcase API
+2. Each agent is registered as an MCP tool with its parameter schema
+3. When Claude calls a tool, the server runs the agent via the API
+4. The server polls for results and returns structured data to Claude
+
+## Configuration
+
+| Environment Variable | Description | Required |
+|---------------------|-------------|----------|
+| `MINDCASE_API_KEY` | Your Mindcase API key (`mk_live_...`) | Yes |
+
+## Documentation
+
+- [Mindcase API Docs](https://docs.mindcase.co)
+- [Agent Reference](https://docs.mindcase.co/agents-overview)
+- [Python SDK](https://github.com/mindcase-co/mindcase-python)
+- [Node.js SDK](https://github.com/mindcase-co/mindcase-node)
+
+## Privacy
+
+See [privacy-policy.md](privacy-policy.md) for details on data handling.
+
+## License
+
+MIT

mindcase_mcp-0.1.0/mindcase_mcp/__init__.py

@@ -0,0 +1 @@
+"""Mindcase MCP Server — exposes 30+ data collection agents as Claude tools."""

mindcase_mcp-0.1.0/mindcase_mcp/api_client.py

@@ -0,0 +1,137 @@
+"""Thin HTTP client for the Mindcase REST API."""
+
+import asyncio
+import os
+import httpx
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass
+
+BASE_URL = "https://api.mindcase.co/api/v1"
+POLL_INTERVAL = 5  # seconds
+MAX_POLL_TIME = 300  # 5 minutes
+
+
+def _api_key() -> str:
+    key = os.environ.get("MINDCASE_API_KEY", "")
+    if not key:
+        raise RuntimeError(
+            "MINDCASE_API_KEY is not set. "
+            "Add it to your .env file or set it as an environment variable."
+        )
+    return key
+
+
+def _headers() -> dict:
+    return {
+        "Authorization": f"Bearer {_api_key()}",
+        "Content-Type": "application/json",
+        "User-Agent": "mindcase-mcp/0.1.0",
+    }
+
+
+def _handle_error(resp: httpx.Response) -> str:
+    """Extract a readable error message from an HTTP error response."""
+    try:
+        body = resp.json()
+        return body.get("detail", body.get("error", resp.text))
+    except Exception:
+        return resp.text
+
+
+# ── Sync methods (used during startup for agent registration) ────────────────
+
+
+def list_agents() -> list[dict]:
+    """Fetch all agents. Public endpoint — no auth required."""
+    resp = httpx.get(f"{BASE_URL}/agents/all", timeout=15)
+    resp.raise_for_status()
+    return resp.json().get("agents", [])
+
+
+def get_agent(group: str, slug: str) -> dict:
+    """Fetch agent details including parameter schema."""
+    resp = httpx.get(f"{BASE_URL}/agents/{group}/{slug}", headers=_headers(), timeout=15)
+    resp.raise_for_status()
+    return resp.json()
+
+
+# ── Async methods (used during tool execution) ──────────────────────────────
+
+
+async def async_run_agent(group: str, slug: str, params: dict) -> dict:
+    """Start an agent job. Returns job metadata."""
+    async with httpx.AsyncClient(timeout=30) as client:
+        resp = await client.post(
+            f"{BASE_URL}/agents/{group}/{slug}/run",
+            headers=_headers(),
+            json={"params": params},
+        )
+        if resp.status_code != 200:
+            return {"status": "error", "error": _handle_error(resp)}
+        return resp.json()
+
+
+async def async_get_job(job_id: str) -> dict:
+    """Get job status."""
+    async with httpx.AsyncClient(timeout=15) as client:
+        resp = await client.get(f"{BASE_URL}/jobs/{job_id}", headers=_headers())
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def async_get_results(job_id: str) -> dict:
+    """Get job results."""
+    async with httpx.AsyncClient(timeout=15) as client:
+        resp = await client.get(f"{BASE_URL}/jobs/{job_id}/results", headers=_headers())
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def async_get_credits() -> float:
+    """Get remaining credit balance."""
+    async with httpx.AsyncClient(timeout=15) as client:
+        resp = await client.get(f"{BASE_URL}/credits", headers=_headers())
+        resp.raise_for_status()
+        return resp.json().get("credits_remaining", 0)
+
+
+async def async_run_and_wait(group: str, slug: str, params: dict) -> dict:
+    """Run an agent and poll until results are ready."""
+    job = await async_run_agent(group, slug, params)
+
+    if job.get("status") == "error":
+        return job
+
+    job_id = job.get("job_id")
+    if not job_id:
+        return {"status": "error", "error": "No job_id returned", "response": job}
+
+    # Poll until done
+    elapsed = 0
+    while elapsed < MAX_POLL_TIME:
+        status_resp = await async_get_job(job_id)
+        status = status_resp.get("status", "unknown")
+
+        if status == "completed":
+            results = await async_get_results(job_id)
+            results["job_id"] = job_id
+            return results
+
+        if status == "failed":
+            return {
+                "status": "failed",
+                "error": status_resp.get("error_message", "Job failed"),
+                "job_id": job_id,
+            }
+
+        if status == "cancelled":
+            return {"status": "cancelled", "job_id": job_id}
+
+        await asyncio.sleep(POLL_INTERVAL)
+        elapsed += POLL_INTERVAL
+
+    return {"status": "error", "error": f"Job {job_id} timed out after {MAX_POLL_TIME}s"}