bitscale-mcp 0.1.0__tar.gz

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

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install hatchling build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

bitscale_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: bitscale-mcp
+Version: 0.1.0
+Summary: MCP server for BitScale — connect your BitScale workspace to Claude
+Project-URL: Homepage, https://github.com/featherflow/bitscale-mcp
+Project-URL: Repository, https://github.com/featherflow/bitscale-mcp
+License: MIT
+Keywords: ai,bitscale,claude,mcp,model-context-protocol
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# BitScale MCP Server
+
+Connect your [BitScale](https://bitscale.ai) workspace to Claude via the [Model Context Protocol](https://modelcontextprotocol.io) (MCP).
+
+## Setup
+
+### 1. Install `uv` (one-time)
+
+**macOS / Linux**
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+**Windows**
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+### 2. Add to Claude Desktop config
+
+Open `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and add:
+
+```json
+{
+  "mcpServers": {
+    "bitscale": {
+      "command": "uvx",
+      "args": ["bitscale-mcp"],
+      "env": {
+        "BITSCALE_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart Claude Desktop
+
+That's it. No cloning, no pip install — `uvx` pulls and runs the package automatically.
+
+---
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_workspace_details` | Get workspace name, plan, and member info |
+| `list_grids` | List all Grids with optional search & pagination |
+| `get_grid_details` | Fetch a Grid's column schema and row data |
+| `run_grid` | Trigger a Grid run (full or selected rows) |
+| `get_run_status` | Poll the status of a Grid run |
+| `rotate_api_key` | Rotate the workspace API key |
+
+---
+
+## Usage Examples
+
+> *"List all my BitScale grids"*
+
+> *"Run the Leads Enrichment grid"*
+
+> *"What columns does my Outbound grid have?"*
+
+> *"Check the status of run xyz456 on grid abc123"*
+
+---
+
+## Claude Code
+
+```bash
+claude mcp add bitscale \
+  --command uvx \
+  --args bitscale-mcp \
+  --env BITSCALE_API_KEY=your_api_key_here
+```
+
+---
+
+## API Reference
+
+Requests hit `https://api.bitscale.ai/api/v1`, authenticated via `X-API-KEY`. Default rate limit: **5 req/s** per workspace.
+
+| Endpoint | Method | Tool |
+|----------|--------|------|
+| `/workspace` | GET | `get_workspace_details` |
+| `/grids` | GET | `list_grids` |
+| `/grids/:gridId` | GET | `get_grid_details` |
+| `/grids/:gridId/run` | POST | `run_grid` |
+| `/grids/:gridId/runs/:runId` | GET | `get_run_status` |
+| `/rotate-api-key` | POST | `rotate_api_key` |
+
+---
+
+## ⚠️ API Key Rotation
+
+Calling `rotate_api_key` immediately invalidates the current key. Update `BITSCALE_API_KEY` in your config and restart Claude Desktop after rotating.
+
+---
+
+## License
+
+MIT

bitscale_mcp-0.1.0/README.md

@@ -0,0 +1,101 @@
+# BitScale MCP Server
+
+Connect your [BitScale](https://bitscale.ai) workspace to Claude via the [Model Context Protocol](https://modelcontextprotocol.io) (MCP).
+
+## Setup
+
+### 1. Install `uv` (one-time)
+
+**macOS / Linux**
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+**Windows**
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+### 2. Add to Claude Desktop config
+
+Open `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and add:
+
+```json
+{
+  "mcpServers": {
+    "bitscale": {
+      "command": "uvx",
+      "args": ["bitscale-mcp"],
+      "env": {
+        "BITSCALE_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart Claude Desktop
+
+That's it. No cloning, no pip install — `uvx` pulls and runs the package automatically.
+
+---
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_workspace_details` | Get workspace name, plan, and member info |
+| `list_grids` | List all Grids with optional search & pagination |
+| `get_grid_details` | Fetch a Grid's column schema and row data |
+| `run_grid` | Trigger a Grid run (full or selected rows) |
+| `get_run_status` | Poll the status of a Grid run |
+| `rotate_api_key` | Rotate the workspace API key |
+
+---
+
+## Usage Examples
+
+> *"List all my BitScale grids"*
+
+> *"Run the Leads Enrichment grid"*
+
+> *"What columns does my Outbound grid have?"*
+
+> *"Check the status of run xyz456 on grid abc123"*
+
+---
+
+## Claude Code
+
+```bash
+claude mcp add bitscale \
+  --command uvx \
+  --args bitscale-mcp \
+  --env BITSCALE_API_KEY=your_api_key_here
+```
+
+---
+
+## API Reference
+
+Requests hit `https://api.bitscale.ai/api/v1`, authenticated via `X-API-KEY`. Default rate limit: **5 req/s** per workspace.
+
+| Endpoint | Method | Tool |
+|----------|--------|------|
+| `/workspace` | GET | `get_workspace_details` |
+| `/grids` | GET | `list_grids` |
+| `/grids/:gridId` | GET | `get_grid_details` |
+| `/grids/:gridId/run` | POST | `run_grid` |
+| `/grids/:gridId/runs/:runId` | GET | `get_run_status` |
+| `/rotate-api-key` | POST | `rotate_api_key` |
+
+---
+
+## ⚠️ API Key Rotation
+
+Calling `rotate_api_key` immediately invalidates the current key. Update `BITSCALE_API_KEY` in your config and restart Claude Desktop after rotating.
+
+---
+
+## License
+
+MIT

bitscale_mcp-0.1.0/main.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""
+BitScale MCP Server
+Exposes BitScale API endpoints as tools for Claude via the Model Context Protocol.
+
+Quickstart (no cloning needed):
+    Add to your claude_desktop_config.json:
+    {
+      "mcpServers": {
+        "bitscale": {
+          "command": "uvx",
+          "args": ["--from", "git+https://github.com/featherflow/bitscale-mcp", "bitscale-mcp"],
+          "env": { "BITSCALE_API_KEY": "your_key_here" }
+        }
+      }
+    }
+"""
+
+import os
+import json
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+# ── Configuration ────────────────────────────────────────────────────────────
+
+BITSCALE_API_BASE = "https://api.bitscale.ai/api/v1"
+API_KEY = os.environ.get("BITSCALE_API_KEY", "")
+
+# ── MCP Server ───────────────────────────────────────────────────────────────
+
+mcp = FastMCP("BitScale")
+
+
+def _headers() -> dict:
+    """Return the auth headers required by the BitScale API."""
+    if not API_KEY:
+        raise RuntimeError(
+            "BITSCALE_API_KEY environment variable is not set. "
+            "Set it before starting the server."
+        )
+    return {
+        "X-API-KEY": API_KEY,
+        "Content-Type": "application/json",
+    }
+
+
+def _get(path: str, params: dict | None = None) -> dict:
+    """Perform an authenticated GET request against the BitScale API."""
+    url = f"{BITSCALE_API_BASE}{path}"
+    with httpx.Client(timeout=30) as client:
+        response = client.get(url, headers=_headers(), params=params)
+    response.raise_for_status()
+    return response.json()
+
+
+def _post(path: str, body: dict | None = None) -> dict:
+    """Perform an authenticated POST request against the BitScale API."""
+    url = f"{BITSCALE_API_BASE}{path}"
+    with httpx.Client(timeout=60) as client:
+        response = client.post(url, headers=_headers(), json=body or {})
+    response.raise_for_status()
+    return response.json()
+
+
+# ── Tools ────────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def get_workspace_details() -> str:
+    """
+    Retrieve details about the current BitScale workspace associated with
+    the API key, including workspace ID, name, plan, and member count.
+
+    Returns workspace metadata such as id, name, plan tier, and members.
+    """
+    data = _get("/workspace")
+    return json.dumps(data, indent=2)
+
+
+@mcp.tool()
+def list_grids(
+    search: str = "",
+    page: int = 1,
+    limit: int = 20,
+) -> str:
+    """
+    List all Grids (spreadsheet-like tables) in the current workspace.
+
+    Args:
+        search: Optional keyword to filter grids by name.
+        page:   Page number for pagination (default: 1).
+        limit:  Number of grids per page (default: 20, max: 100).
+
+    Returns a paginated list of grids with their IDs, names, column
+    definitions, and row counts.
+    """
+    params: dict = {"page": page, "limit": limit}
+    if search:
+        params["search"] = search
+    data = _get("/grids", params=params)
+    return json.dumps(data, indent=2)
+
+
+@mcp.tool()
+def get_grid_details(grid_id: str) -> str:
+    """
+    Retrieve detailed information about a specific Grid, including its
+    column schema and current data rows.
+
+    Args:
+        grid_id: The unique identifier of the grid (e.g. "abc123").
+
+    Returns full grid metadata plus column definitions and row data.
+    """
+    if not grid_id:
+        raise ValueError("grid_id must not be empty")
+    data = _get(f"/grids/{grid_id}")
+    return json.dumps(data, indent=2)
+
+
+@mcp.tool()
+def run_grid(
+    grid_id: str,
+    row_ids: list[str] | None = None,
+) -> str:
+    """
+    Trigger a run (execution) of a specific Grid. Optionally run only
+    a subset of rows by providing their IDs.
+
+    Args:
+        grid_id: The unique identifier of the grid to run.
+        row_ids: Optional list of row IDs to run. If omitted, all rows
+                 are processed.
+
+    Returns a run object containing the run_id and initial status.
+    Use get_run_status to poll for completion.
+    """
+    if not grid_id:
+        raise ValueError("grid_id must not be empty")
+    body: dict = {}
+    if row_ids:
+        body["rowIds"] = row_ids
+    data = _post(f"/grids/{grid_id}/run", body)
+    return json.dumps(data, indent=2)
+
+
+@mcp.tool()
+def get_run_status(grid_id: str, run_id: str) -> str:
+    """
+    Check the status of a previously triggered Grid run.
+
+    Args:
+        grid_id: The unique identifier of the grid.
+        run_id:  The unique identifier of the run (returned by run_grid).
+
+    Returns the run object with status ("pending", "running", "completed",
+    or "failed"), progress information, and any error details.
+    """
+    if not grid_id:
+        raise ValueError("grid_id must not be empty")
+    if not run_id:
+        raise ValueError("run_id must not be empty")
+    data = _get(f"/grids/{grid_id}/runs/{run_id}")
+    return json.dumps(data, indent=2)
+
+
+@mcp.tool()
+def rotate_api_key() -> str:
+    """
+    Rotate the current workspace API key. The existing key is immediately
+    invalidated and a new key is returned.
+
+    WARNING: After calling this tool the BITSCALE_API_KEY environment
+    variable must be updated with the returned key, and the MCP server
+    must be restarted, otherwise subsequent tool calls will fail with 401.
+
+    Returns the new API key string.
+    """
+    data = _post("/rotate-api-key")
+    return json.dumps(data, indent=2)
+
+
+# ── Entry Point ──────────────────────────────────────────────────────────────
+
+def run():
+    """Entry point used by the pyproject.toml console script."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    run()

bitscale_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bitscale-mcp"
+version = "0.1.0"
+description = "MCP server for BitScale — connect your BitScale workspace to Claude"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = ["mcp", "bitscale", "claude", "ai", "model-context-protocol"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+bitscale-mcp = "main:run"
+
+[project.urls]
+Homepage = "https://github.com/featherflow/bitscale-mcp"
+Repository = "https://github.com/featherflow/bitscale-mcp"
+
+[tool.hatch.build.targets.wheel]
+include = ["main.py"]