probnode-mcp 0.1.0__tar.gz

probnode_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.5
+Name: probnode-mcp
+Version: 0.1.0
+Summary: MCP server for ProbNode: Polymarket order books, trades and gaps for AI agents
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.2
+Requires-Dist: probnode-sdk>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# probnode-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that gives an AI agent ProbNode's Polymarket
+history: find markets, check recording coverage, list files with sizes and sha256, sign download
+links, and pull small windows of rows.
+
+```sh
+pip install ./packages/probnode ./packages/probnode-mcp   # from a checkout; on PyPI soon
+```
+
+```json
+{"mcpServers": {"probnode": {"command": "probnode-mcp", "env": {"PROBNODE_API_KEY": "pmd_..."}}}}
+```
+
+Tools: `datasets`, `search_markets`, `coverage`, `list_files`, `sign_files`, `timeseries`,
+`samples`. Every call goes through the same API, plan and limits as the `probnode` SDK; refusals
+come back as `{"error": ..., "status": ...}`. Bulk data travels as signed URLs, not through the
+model's context - `timeseries` returns at most 500 rows.

probnode_mcp-0.1.0/README.md

@@ -0,0 +1,18 @@
+# probnode-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that gives an AI agent ProbNode's Polymarket
+history: find markets, check recording coverage, list files with sizes and sha256, sign download
+links, and pull small windows of rows.
+
+```sh
+pip install ./packages/probnode ./packages/probnode-mcp   # from a checkout; on PyPI soon
+```
+
+```json
+{"mcpServers": {"probnode": {"command": "probnode-mcp", "env": {"PROBNODE_API_KEY": "pmd_..."}}}}
+```
+
+Tools: `datasets`, `search_markets`, `coverage`, `list_files`, `sign_files`, `timeseries`,
+`samples`. Every call goes through the same API, plan and limits as the `probnode` SDK; refusals
+come back as `{"error": ..., "status": ...}`. Bulk data travels as signed URLs, not through the
+model's context - `timeseries` returns at most 500 rows.

probnode_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "probnode-mcp"
+version = "0.1.0"
+description = "MCP server for ProbNode: Polymarket order books, trades and gaps for AI agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = ["probnode-sdk>=0.1.0", "mcp>=1.2,<2"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.3", "ruff>=0.6"]
+
+[project.scripts]
+probnode-mcp = "probnode_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/probnode_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

probnode_mcp-0.1.0/src/probnode_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for ProbNode. Run `probnode-mcp`."""
+
+__version__ = "0.1.0"

probnode_mcp-0.1.0/src/probnode_mcp/server.py

@@ -0,0 +1,146 @@
+"""ProbNode as MCP tools, for an AI agent working with Polymarket history.
+
+    {"mcpServers": {"probnode": {"command": "probnode-mcp",
+                                 "env": {"PROBNODE_API_KEY": "pn_..."}}}}
+
+Every tool is one ProbNode API call through `probnode.Client`, so an agent sees exactly what a
+customer's script sees: the same entitlements, the same quotas, the same refusals in words. Tools
+return small JSON; bulk data is handed over as signed URLs (`sign_files`) or a capped range query
+(`timeseries`), never streamed through the model's context.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+from probnode import Client, ProbNodeError
+
+#: Rows a `timeseries` call returns to the model at most. The API caps a window at 200,000 rows;
+#: that is a file, not context. More than this, the tool says so and suggests files instead.
+MAX_ROWS_TO_MODEL = 500
+
+mcp = FastMCP("probnode")
+_client: Client | None = None
+
+
+def client() -> Client:
+    global _client
+    if _client is None:
+        _client = Client()
+    return _client
+
+
+def _refusal(exc: ProbNodeError) -> dict[str, Any]:
+    return {"error": exc.detail, "status": exc.status}
+
+
+@mcp.tool()
+def datasets() -> Any:
+    """Datasets ProbNode holds (books, trades, gaps, markets, quotes, ohlcv_1m), their formats,
+    whether a paid plan is needed (tier "tape") and the first and last UTC hour held."""
+    try:
+        return client().datasets()
+    except ProbNodeError as exc:
+        return _refusal(exc)
+
+
+@mcp.tool()
+def search_markets(query: str, limit: int = 20) -> Any:
+    """Find Polymarket markets by words in their slug or title. Returns slugs, series, start and
+    end times, resolution and outcome token ids."""
+    try:
+        return client().markets(q=query, limit=min(max(limit, 1), 100))
+    except ProbNodeError as exc:
+        return _refusal(exc)
+
+
+@mcp.tool()
+def coverage(token_id: str, start: str | None = None, end: str | None = None) -> Any:
+    """How completely one outcome token was recorded, hour by hour: recorded ms, gaps and uptime.
+    Times are ISO UTC. Hours marked implied were recorded whole (no gap touched them)."""
+    try:
+        return client().coverage(token_id, start, end)
+    except ProbNodeError as exc:
+        return _refusal(exc)
+
+
+@mcp.tool()
+def list_files(
+    dataset: str,
+    format: str,
+    start: str,
+    end: str,
+    granularity: str = "hour",
+    market: list[str] | None = None,
+) -> Any:
+    """Files for a dataset and format over [start, end) (ISO UTC, on the hour, at most 31 days):
+    object path, rows, bytes and sha256 each, plus totals. granularity "hour" (all markets per
+    file) or "market_day" (one market, one UTC day). Needs an API key."""
+    try:
+        files = client().files(
+            dataset, format, start, end, granularity=granularity, market=market or ()
+        )
+    except ProbNodeError as exc:
+        return _refusal(exc)
+    return {
+        "total_files": len(files),
+        "total_bytes": sum(f.bytes for f in files),
+        "total_rows": sum(f.rows for f in files),
+        "files": [
+            {
+                "object_path": f.object_path,
+                "rows": f.rows,
+                "bytes": f.bytes,
+                "sha256": f.sha256,
+                "market": f.market,
+            }
+            for f in files[:200]
+        ],
+        "truncated": len(files) > 200,
+    }
+
+
+@mcp.tool()
+def sign_files(object_paths: list[str]) -> Any:
+    """Short-lived download URLs (about 15 minutes) for object paths from list_files. Each counts
+    against the account's daily signed-URL limit; tape data needs a paid plan."""
+    try:
+        return client().sign(object_paths)
+    except ProbNodeError as exc:
+        return _refusal(exc)
+
+
+@mcp.tool()
+def timeseries(dataset: str, market: str, start: str, end: str) -> Any:
+    """Rows of one dataset (e.g. quotes, trades, ohlcv_1m) for one market over a short window,
+    as JSON objects. For more than a few hundred rows use list_files + sign_files instead."""
+    try:
+        rows = client().timeseries(dataset, market, start, end, format="ndjson")
+    except ProbNodeError as exc:
+        return _refusal(exc)
+    if len(rows) > MAX_ROWS_TO_MODEL:
+        return {
+            "rows": rows[:MAX_ROWS_TO_MODEL],
+            "returned": MAX_ROWS_TO_MODEL,
+            "total": len(rows),
+            "note": "more rows than fit here; narrow the window or download files",
+        }
+    return {"rows": rows, "returned": len(rows), "total": len(rows)}
+
+
+@mcp.tool()
+def samples() -> Any:
+    """Free sample files - one market-day per dataset and format - with URLs that need no key."""
+    try:
+        return client().samples()
+    except ProbNodeError as exc:
+        return _refusal(exc)
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

probnode_mcp-0.1.0/tests/test_tools.py

@@ -0,0 +1,77 @@
+"""The MCP tools against a stub client: they pass arguments through, cap what reaches the model,
+and turn API refusals into a JSON error instead of a crashed tool call."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import pytest
+from probnode import DataFile, ProbNodeError
+
+from probnode_mcp import server
+
+
+class Stub:
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, Any]] = []
+
+    def datasets(self) -> list[dict]:
+        return [{"code": "books"}]
+
+    def files(self, *args: Any, **kw: Any) -> list[DataFile]:
+        self.calls.append(("files", (args, kw)))
+        if args[0] == "secret":
+            raise ProbNodeError(402, "books need a paid plan")
+        return [
+            DataFile("books", "parquet", "2026-11-08", h, "s6", f"x/{h}", 10, 100, "ab" * 32)
+            for h in range(250)
+        ]
+
+    def sign(self, paths: list[str]) -> dict[str, str]:
+        return {p: f"https://lake/{p}" for p in paths}
+
+    def timeseries(self, *args: Any, **kw: Any) -> list[dict]:
+        assert kw["format"] == "ndjson"
+        return [{"i": i} for i in range(int(args[1]))]
+
+
+@pytest.fixture(autouse=True)
+def stub(monkeypatch: pytest.MonkeyPatch) -> Stub:
+    s = Stub()
+    monkeypatch.setattr(server, "_client", s)
+    return s
+
+
+def test_list_files_totals_and_truncates(stub: Stub) -> None:
+    out = server.list_files("books", "parquet", "a", "b", granularity="market_day", market=["m"])
+    assert out["total_files"] == 250 and out["total_bytes"] == 25_000
+    assert len(out["files"]) == 200 and out["truncated"] is True
+    assert stub.calls[0][1][1] == {"granularity": "market_day", "market": ["m"]}
+
+
+def test_refusal_is_returned_not_raised() -> None:
+    assert server.list_files("secret", "parquet", "a", "b") == {
+        "error": "books need a paid plan",
+        "status": 402,
+    }
+
+
+def test_timeseries_caps_rows_for_the_model() -> None:
+    small = server.timeseries("quotes", "3", "a", "b")
+    assert small["returned"] == 3 and small["total"] == 3
+    big = server.timeseries("quotes", "1000", "a", "b")
+    assert big["returned"] == server.MAX_ROWS_TO_MODEL and big["total"] == 1000 and big["note"]
+
+
+def test_every_tool_is_registered() -> None:
+    names = {t.name for t in asyncio.run(server.mcp.list_tools())}
+    assert names == {
+        "datasets",
+        "search_markets",
+        "coverage",
+        "list_files",
+        "sign_files",
+        "timeseries",
+        "samples",
+    }