strand-mcp 0.1.0__tar.gz

strand_mcp-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.egg-info/
+dist/
+build/
+uv.lock

strand_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: strand-mcp
+Version: 0.1.0
+Summary: MCP server for the Strand Platform — exposes upload / predict / job lifecycle to Claude, Cursor, and any other MCP-aware agent.
+Project-URL: Homepage, https://strandai.com
+Project-URL: Documentation, https://app.strandai.com/docs/api
+Project-URL: Repository, https://github.com/Strand-AI/strand-official
+Author-email: Strand AI <engineering@strandai.bio>
+License: Apache-2.0
+Keywords: anthropic,claude,h&e,mcp,pathology,spatial-omics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: strand-sdk>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# strand-mcp
+
+MCP server for the Strand Platform. Exposes upload / estimate / predict / job-lifecycle as MCP tools so any agent (Claude Code, Cursor, etc.) can run H&E → spatial-proteomics inference end-to-end.
+
+## Install
+
+```bash
+pip install strand-mcp
+```
+
+Or from this repo:
+
+```bash
+cd sdks/mcp-server
+pip install -e .
+```
+
+## Auth
+
+Generate an API key at <https://app.strandai.com/settings/api-keys> and export it:
+
+```bash
+export STRAND_API_KEY=sk-strand-...
+```
+
+The server also reads `STRAND_BASE_URL` (defaults to `https://app.strandai.com`) if you need to point at staging.
+
+## Wire into Claude Code
+
+Add to `~/.claude/mcp.json` (or your project's `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "strand": {
+      "command": "strand-mcp",
+      "env": {
+        "STRAND_API_KEY": "sk-strand-..."
+      }
+    }
+  }
+}
+```
+
+Then in Claude Code you can ask things like:
+
+> Upload `~/slides/biopsy.svs` to Strand, run prediction for CD3, CD8, and Ki67, wait for the job, and download results into `~/results/`.
+
+Claude calls the tools in sequence — no glue code needed.
+
+## Tools
+
+| Tool               | Purpose                                                                     |
+| ------------------ | --------------------------------------------------------------------------- |
+| `upload_slide`     | Upload a local WSI; returns `upload_id` + dimensions                        |
+| `estimate_run`     | Patch count + credit cost for a `(upload_id, markers)` pair                 |
+| `set_sample_mpp`   | Set user-reported slide microns per pixel before inference                  |
+| `submit_run`       | Kick off a Lattice inference job; returns `job_id`                            |
+| `get_job`          | Point-in-time status snapshot                                               |
+| `cancel_job`       | Cancel an in-flight job and refund its reserved credits                     |
+| `wait_for_job`     | Block until terminal state (uses SSE under the hood)                        |
+| `download_results` | Pull OME-Zarr results into a local directory                                |
+| `download_ome_tiff` | Render and download a completed job as a single OME-TIFF file              |
+
+## Smoke test
+
+```bash
+STRAND_API_KEY=sk-strand-... strand-mcp
+```
+
+The server listens on stdio and waits for an MCP client to attach.
+
+## Dev
+
+```bash
+cd sdks/mcp-server
+pip install -e ".[dev]" || pip install -e .
+python -m strand_mcp
+```

strand_mcp-0.1.0/README.md

@@ -0,0 +1,79 @@
+# strand-mcp
+
+MCP server for the Strand Platform. Exposes upload / estimate / predict / job-lifecycle as MCP tools so any agent (Claude Code, Cursor, etc.) can run H&E → spatial-proteomics inference end-to-end.
+
+## Install
+
+```bash
+pip install strand-mcp
+```
+
+Or from this repo:
+
+```bash
+cd sdks/mcp-server
+pip install -e .
+```
+
+## Auth
+
+Generate an API key at <https://app.strandai.com/settings/api-keys> and export it:
+
+```bash
+export STRAND_API_KEY=sk-strand-...
+```
+
+The server also reads `STRAND_BASE_URL` (defaults to `https://app.strandai.com`) if you need to point at staging.
+
+## Wire into Claude Code
+
+Add to `~/.claude/mcp.json` (or your project's `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "strand": {
+      "command": "strand-mcp",
+      "env": {
+        "STRAND_API_KEY": "sk-strand-..."
+      }
+    }
+  }
+}
+```
+
+Then in Claude Code you can ask things like:
+
+> Upload `~/slides/biopsy.svs` to Strand, run prediction for CD3, CD8, and Ki67, wait for the job, and download results into `~/results/`.
+
+Claude calls the tools in sequence — no glue code needed.
+
+## Tools
+
+| Tool               | Purpose                                                                     |
+| ------------------ | --------------------------------------------------------------------------- |
+| `upload_slide`     | Upload a local WSI; returns `upload_id` + dimensions                        |
+| `estimate_run`     | Patch count + credit cost for a `(upload_id, markers)` pair                 |
+| `set_sample_mpp`   | Set user-reported slide microns per pixel before inference                  |
+| `submit_run`       | Kick off a Lattice inference job; returns `job_id`                            |
+| `get_job`          | Point-in-time status snapshot                                               |
+| `cancel_job`       | Cancel an in-flight job and refund its reserved credits                     |
+| `wait_for_job`     | Block until terminal state (uses SSE under the hood)                        |
+| `download_results` | Pull OME-Zarr results into a local directory                                |
+| `download_ome_tiff` | Render and download a completed job as a single OME-TIFF file              |
+
+## Smoke test
+
+```bash
+STRAND_API_KEY=sk-strand-... strand-mcp
+```
+
+The server listens on stdio and waits for an MCP client to attach.
+
+## Dev
+
+```bash
+cd sdks/mcp-server
+pip install -e ".[dev]" || pip install -e .
+python -m strand_mcp
+```

strand_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "strand-mcp"
+version = "0.1.0"
+description = "MCP server for the Strand Platform — exposes upload / predict / job lifecycle to Claude, Cursor, and any other MCP-aware agent."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Strand AI", email = "engineering@strandai.bio" }]
+keywords = ["mcp", "anthropic", "claude", "spatial-omics", "h&e", "pathology"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "strand-sdk>=0.1.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+strand-mcp = "strand_mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://strandai.com"
+Documentation = "https://app.strandai.com/docs/api"
+Repository = "https://github.com/Strand-AI/strand-official"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/strand_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

strand_mcp-0.1.0/src/strand_mcp/__init__.py

@@ -0,0 +1,23 @@
+"""Strand Platform MCP server.
+
+Exposes the Strand Python SDK as MCP tools so any MCP-aware agent
+(Claude Code, Cursor, etc.) can run H&E → spatial-proteomics inference
+end-to-end.
+
+Tools:
+    - list_slides / list_runs            inventory
+    - upload_slide(path)                  upload a local WSI
+    - estimate_run(upload_id, markers)    cost/patch estimate
+    - submit_run(upload_id, markers)      kick off a job
+    - get_job(job_id)                     status snapshot
+    - wait_for_job(job_id, timeout_s)     block until terminal
+    - download_results(job_id, dest_dir)  pull zarr results to disk
+
+Auth is via STRAND_API_KEY env var (matches strand-sdk).
+"""
+
+from __future__ import annotations
+
+from .server import build_server
+
+__all__ = ["build_server"]

strand_mcp-0.1.0/src/strand_mcp/__main__.py

@@ -0,0 +1,15 @@
+"""CLI entry: `strand-mcp` runs the stdio MCP server."""
+
+from __future__ import annotations
+
+import asyncio
+
+from .server import run_stdio
+
+
+def main() -> None:
+    asyncio.run(run_stdio())
+
+
+if __name__ == "__main__":
+    main()

strand_mcp-0.1.0/src/strand_mcp/server.py

@@ -0,0 +1,324 @@
+"""MCP server implementation.
+
+Stateless tools that wrap the Strand Python SDK. Each tool resolves the
+SDK client lazily so server startup never fails when STRAND_API_KEY is
+missing — the failure is surfaced when an actual tool runs.
+
+Spelled-out tool schemas (no auto-generation from typing) so MCP clients
+see clean field names + descriptions in the tool catalog.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import mcp.types as mcp_types
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+
+
+def _get_client():  # type: ignore[no-untyped-def]
+    """Lazy SDK client. Raises a tool-friendly error if creds are missing."""
+
+    api_key = os.environ.get("STRAND_API_KEY")
+    if not api_key:
+        raise RuntimeError(
+            "STRAND_API_KEY is not set. Generate one at https://app.strandai.com/settings/api-keys "
+            "and pass it via env to this MCP server."
+        )
+    try:
+        from strand import Client  # type: ignore[import-not-found]
+    except ImportError as e:
+        raise RuntimeError(
+            "strand-sdk is not installed. `pip install strand-sdk` (or install this "
+            "package, which depends on it)."
+        ) from e
+    base_url = os.environ.get("STRAND_BASE_URL") or "https://app.strandai.com"
+    return Client(api_key=api_key, base_url=base_url)
+
+
+def _json(obj: Any) -> list[mcp_types.TextContent]:
+    """Serialize a dataclass / dict / primitive to a single TextContent.
+
+    Dataclasses get vars()'d; datetimes get iso-formatted; everything else
+    falls through to json's default (str()).
+    """
+    from dataclasses import asdict, is_dataclass
+    from datetime import datetime
+
+    def encode(v: Any) -> Any:
+        if is_dataclass(v):
+            return asdict(v)
+        if isinstance(v, datetime):
+            return v.isoformat()
+        if isinstance(v, list):
+            return [encode(x) for x in v]
+        if isinstance(v, dict):
+            return {k: encode(x) for k, x in v.items()}
+        return v
+
+    return [mcp_types.TextContent(type="text", text=json.dumps(encode(obj), indent=2, default=str))]
+
+
+TOOLS: list[mcp_types.Tool] = [
+    mcp_types.Tool(
+        name="upload_slide",
+        description=(
+            "Upload a local H&E whole-slide image (TIFF / SVS / NDPI / PNG) to the Strand platform. "
+            "Returns the upload id, GCS path, and the slide's pixel dimensions once the dimension "
+            "pre-pass completes (width_px / height_px may be null for non-image WSIs while the "
+            "OpenSlide sidecar runs)."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "Absolute path to the local WSI file.",
+                },
+                "content_type": {
+                    "type": "string",
+                    "description": "MIME type override. Defaults to image/tiff for unknown extensions.",
+                },
+            },
+            "required": ["path"],
+        },
+    ),
+    mcp_types.Tool(
+        name="estimate_run",
+        description=(
+            "Estimate the credit cost + patch count for a prediction run on an uploaded slide. "
+            "Does NOT reserve credits."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "upload_id": {"type": "string"},
+                "markers": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Marker names to predict (e.g. ['CD3', 'CD8', 'Ki67']).",
+                },
+            },
+            "required": ["upload_id", "markers"],
+        },
+    ),
+    mcp_types.Tool(
+        name="set_sample_mpp",
+        description=(
+            "Set a slide's user-reported base-level microns per pixel before inference. "
+            "This value takes precedence over embedded slide metadata. Omit mpp_y for "
+            "isotropic pixels."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "sample_id": {"type": "string"},
+                "mpp_x": {
+                    "type": "number",
+                    "exclusiveMinimum": 0,
+                    "maximum": 100,
+                },
+                "mpp_y": {
+                    "type": "number",
+                    "exclusiveMinimum": 0,
+                    "maximum": 100,
+                    "description": "Optional vertical microns per pixel. Defaults to mpp_x.",
+                },
+            },
+            "required": ["sample_id", "mpp_x"],
+        },
+    ),
+    mcp_types.Tool(
+        name="submit_run",
+        description=(
+            "Submit a prediction job: H&E → multiplex protein channels via Lattice. Returns the "
+            "job id; the job runs asynchronously. Credits are reserved atomically; this fails with "
+            "'insufficient_credits' if the org balance is short."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "upload_id": {"type": "string"},
+                "markers": {"type": "array", "items": {"type": "string"}},
+            },
+            "required": ["upload_id", "markers"],
+        },
+    ),
+    mcp_types.Tool(
+        name="get_job",
+        description=(
+            "Point-in-time status snapshot for a job. Returns status, progress, markers, "
+            "timestamps, and error_message if failed."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {"job_id": {"type": "string"}},
+            "required": ["job_id"],
+        },
+    ),
+    mcp_types.Tool(
+        name="cancel_job",
+        description=(
+            "Cancel an in-flight job, refund its reserved credits, and release the organization's "
+            "concurrent-job slot. Returns an error if the job is already terminal."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {"job_id": {"type": "string"}},
+            "required": ["job_id"],
+        },
+    ),
+    mcp_types.Tool(
+        name="wait_for_job",
+        description=(
+            "Block until a job reaches a terminal state (completed | failed | cancelled). Uses the "
+            "SSE stream under the hood so updates arrive promptly. timeout_s defaults to 600 (10 min)."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "job_id": {"type": "string"},
+                "timeout_s": {"type": "number", "default": 600},
+            },
+            "required": ["job_id"],
+        },
+    ),
+    mcp_types.Tool(
+        name="download_results",
+        description=(
+            "Download a completed job's OME-Zarr result tree to a local directory. Streams the "
+            "files via the API-key zarr proxy. Returns the local root path. Fails if the job is "
+            "not yet completed."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "job_id": {"type": "string"},
+                "dest_dir": {
+                    "type": "string",
+                    "description": "Local directory to write into. Created if it doesn't exist.",
+                },
+            },
+            "required": ["job_id", "dest_dir"],
+        },
+    ),
+    mcp_types.Tool(
+        name="download_ome_tiff",
+        description=(
+            "Request an OME-TIFF export for a completed job, wait for rendering, and download "
+            "the file. Use download_results instead when you need the original OME-Zarr tree."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "job_id": {"type": "string"},
+                "path": {
+                    "type": "string",
+                    "description": "Local .ome.tiff destination path. Parent directories are created.",
+                },
+                "timeout_s": {
+                    "type": "number",
+                    "default": 1800,
+                    "description": "Maximum seconds to wait for the export.",
+                },
+            },
+            "required": ["job_id", "path"],
+        },
+    ),
+]
+
+
+def build_server() -> Server:
+    """Construct the MCP Server with all Strand tools registered."""
+
+    server: Server = Server("strand-mcp")
+
+    @server.list_tools()
+    async def _list_tools() -> list[mcp_types.Tool]:
+        return TOOLS
+
+    @server.call_tool()
+    async def _call_tool(name: str, args: dict[str, Any]) -> list[mcp_types.TextContent]:
+        try:
+            return _dispatch(name, args)
+        except Exception as e:  # noqa: BLE001 - surface tool failures as text content
+            return [mcp_types.TextContent(type="text", text=f"error: {type(e).__name__}: {e}")]
+
+    return server
+
+
+def _dispatch(name: str, args: dict[str, Any]) -> list[mcp_types.TextContent]:
+    client = _get_client()
+    try:
+        if name == "upload_slide":
+            path = Path(args["path"]).expanduser().resolve()
+            if not path.exists():
+                raise FileNotFoundError(f"file not found: {path}")
+            upload = client.uploads.upload_file(
+                str(path), content_type=args.get("content_type")
+            )
+            return _json(upload)
+
+        if name == "estimate_run":
+            est = client.predict.estimate(args["upload_id"], args["markers"])
+            return _json(est)
+
+        if name == "set_sample_mpp":
+            result = client.samples.set_mpp(
+                args["sample_id"],
+                args["mpp_x"],
+                args.get("mpp_y"),
+            )
+            return _json(result)
+
+        if name == "submit_run":
+            job = client.predict.submit(args["upload_id"], args["markers"])
+            return _json({"job_id": job.id, "reserved_credits": job.reserved_credits})
+
+        if name == "get_job":
+            # client.jobs.get() already calls refresh() internally — return the
+            # cached status snapshot.
+            job = client.jobs.get(args["job_id"])
+            return _json(job.status)
+
+        if name == "cancel_job":
+            job = client.jobs.cancel(args["job_id"])
+            return _json(job.status)
+
+        if name == "wait_for_job":
+            job = client.jobs.get(args["job_id"])
+            final = job.wait(timeout=float(args.get("timeout_s", 600)))
+            return _json(final)
+
+        if name == "download_results":
+            job = client.jobs.get(args["job_id"])
+            dest = Path(args["dest_dir"]).expanduser().resolve()
+            dest.mkdir(parents=True, exist_ok=True)
+            # SDK signature is (path: str | None) → Path; pass str so positional
+            # type matches.
+            written = job.download_results(str(dest))
+            return _json({"path": str(written)})
+
+        if name == "download_ome_tiff":
+            job = client.jobs.get(args["job_id"])
+            path = Path(args["path"]).expanduser().resolve()
+            written = job.export_ome_tiff(
+                str(path),
+                timeout=float(args.get("timeout_s", 1800)),
+            )
+            return _json({"path": str(written), "format": "ome-tiff"})
+
+        raise ValueError(f"unknown tool: {name}")
+    finally:
+        client.close()
+
+
+async def run_stdio() -> None:
+    """Entry point for `strand-mcp` (stdio transport)."""
+    server = build_server()
+    async with stdio_server() as (read, write):
+        await server.run(read, write, server.create_initialization_options())

strand_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import pytest
+
+import strand_mcp.server as server_module
+
+
+class FakeSamples:
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, float, float | None]] = []
+
+    def set_mpp(self, sample_id: str, mpp_x: float, mpp_y: float | None) -> dict[str, Any]:
+        self.calls.append((sample_id, mpp_x, mpp_y))
+        return {
+            "id": sample_id,
+            "userMpp": {"x": mpp_x, "y": mpp_x if mpp_y is None else mpp_y},
+        }
+
+
+class FakeClient:
+    def __init__(self) -> None:
+        self.samples = FakeSamples()
+        self.closed = False
+
+    def close(self) -> None:
+        self.closed = True
+
+
+def test_set_sample_mpp_tool_schema() -> None:
+    tool = next(item for item in server_module.TOOLS if item.name == "set_sample_mpp")
+    assert tool.input_schema["required"] == ["sample_id", "mpp_x"]
+    assert tool.input_schema["properties"]["mpp_x"]["exclusiveMinimum"] == 0
+    assert tool.input_schema["properties"]["mpp_x"]["maximum"] == 100
+
+
+@pytest.mark.parametrize("mpp_y", [None, 0.25])
+def test_dispatch_set_sample_mpp(
+    monkeypatch: pytest.MonkeyPatch,
+    mpp_y: float | None,
+) -> None:
+    client = FakeClient()
+    monkeypatch.setattr(server_module, "_get_client", lambda: client)
+    args: dict[str, Any] = {"sample_id": "sample-1", "mpp_x": 0.26}
+    if mpp_y is not None:
+        args["mpp_y"] = mpp_y
+
+    content = server_module._dispatch("set_sample_mpp", args)
+
+    assert client.samples.calls == [("sample-1", 0.26, mpp_y)]
+    assert client.closed is True
+    payload = json.loads(content[0].text)
+    assert payload["userMpp"] == {"x": 0.26, "y": 0.26 if mpp_y is None else mpp_y}