feat: add monitor_activity tool, realign env vars with scrapegraph-py #84

Track the latest push on scrapegraph-py PR #84:

- Base URL: https://api.scrapegraphai.com/v2 -> /api/v2 (matches py env.py)
- Env var: SGAI_TIMEOUT_S -> SGAI_TIMEOUT (default 120s)
  SGAI_TIMEOUT_S is kept as a legacy alias and still honored.
- New tool: monitor_activity (GET /monitor/:id/activity) with limit/cursor
  pagination, mirroring sgai.monitor.activity() in the Python/JS SDKs.
  Returns tick history (id, createdAt, status, changed, elapsedMs, diffs)
  plus nextCursor for paging.
- README.md, server.json, .agent docs: update base URL, env var names,
  and tool listing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: VinciGit00

.agent/README.md

@@ -379,7 +379,8 @@ npx @modelcontextprotocol/inspector scrapegraph-mcp
 ## 📅 Changelog
 
 ### April 2026
-- ✅ Migrated MCP client and tools to **API v2** ([scrapegraph-py#84](https://github.com/ScrapeGraphAI/scrapegraph-py/pull/84)): base `https://api.scrapegraphai.com/v2`, `SGAI-APIKEY` header (matches SDK wire format), new crawl/monitor/credits/history tools; removed sitemap, agentic_scrapper, status polling tools. Env vars aligned with SDK: `SGAI_API_URL`, `SGAI_TIMEOUT_S`.
+- ✅ Migrated MCP client and tools to **API v2** ([scrapegraph-py#84](https://github.com/ScrapeGraphAI/scrapegraph-py/pull/84)): base `https://api.scrapegraphai.com/api/v2`, `SGAI-APIKEY` header (matches SDK wire format), new crawl/monitor/credits/history tools; removed sitemap, agentic_scrapper, status polling tools. Env vars aligned with SDK: `SGAI_API_URL`, `SGAI_TIMEOUT` (legacy alias `SGAI_TIMEOUT_S` still honored).
+- ✅ Added `monitor_activity` tool for paginated tick history (GET /monitor/:id/activity), mirroring `sgai.monitor.activity()` in scrapegraph-py v2.
 
 ### January 2026
 - ✅ Added `time_range` parameter to SearchScraper for filtering results by recency (v1-era; **ignored on API v2**)

.agent/system/project_architecture.md

@@ -130,7 +130,7 @@ AI Assistant (Claude/Cursor)
     ↓ (stdio via MCP)
 FastMCP Server (this project)
     ↓ (HTTPS API calls)
-ScrapeGraphAI API (default https://api.scrapegraphai.com/v2)
+ScrapeGraphAI API (default https://api.scrapegraphai.com/api/v2)
     ↓ (web scraping)
 Target Websites
 ```
@@ -141,7 +141,7 @@ The server follows a simple, single-file architecture:
 
 **`ScapeGraphClient` Class:**
 - HTTP client wrapper for ScrapeGraphAI API v2 ([scrapegraph-py#84](https://github.com/ScrapeGraphAI/scrapegraph-py/pull/84))
-- Base URL: `https://api.scrapegraphai.com/v2` (override with env `SGAI_API_URL`)
+- Base URL: `https://api.scrapegraphai.com/api/v2` (override with env `SGAI_API_URL`)
 - Auth: `SGAI-APIKEY`, `X-SDK-Version: scrapegraph-mcp@2.0.0` (matches scrapegraph-py v2)
 - v2 methods include `scrape_v2`, `extract`, `search_api`, `crawl_*`, `monitor_*`, `credits`, `history`, plus compatibility wrappers used by MCP tools
 
@@ -188,7 +188,7 @@ The server follows a simple, single-file architecture:
 
 The server exposes many `@mcp.tool()` handlers (see repository `README.md` for the full table). The detailed subsections below still use **v1-style endpoint names** in several places; treat them as illustrative and prefer the v2 mapping in **API Integration**.
 
-**v2 tool names:** `markdownify`, `scrape`, `smartscraper`, `searchscraper`, `smartcrawler_initiate`, `smartcrawler_fetch_results`, `crawl_stop`, `crawl_resume`, `credits`, `sgai_history`, `monitor_create`, `monitor_list`, `monitor_get`, `monitor_pause`, `monitor_resume`, `monitor_delete`.
+**v2 tool names:** `markdownify`, `scrape`, `smartscraper`, `searchscraper`, `smartcrawler_initiate`, `smartcrawler_fetch_results`, `crawl_stop`, `crawl_resume`, `credits`, `sgai_history`, `monitor_create`, `monitor_list`, `monitor_get`, `monitor_pause`, `monitor_resume`, `monitor_delete`, `monitor_activity`.
 
 ### 1. `markdownify(website_url: str)`
 
@@ -391,7 +391,7 @@ If status is "completed":
 
 ### ScrapeGraphAI API
 
-**Base URL:** `https://api.scrapegraphai.com/v2` (configurable via `SGAI_API_URL`)
+**Base URL:** `https://api.scrapegraphai.com/api/v2` (configurable via `SGAI_API_URL`)
 
 **Authentication:**
 - Headers: `SGAI-APIKEY: <key>` (matches scrapegraph-py v2 wire format)
@@ -414,6 +414,7 @@ If status is "completed":
 | `/monitor/{id}` | GET, DELETE | `monitor_get`, `monitor_delete` |
 | `/monitor/{id}/pause` | POST | `monitor_pause` |
 | `/monitor/{id}/resume` | POST | `monitor_resume` |
+| `/monitor/{id}/activity` | GET | `monitor_activity` |
 
 **Request Format:**
 ```json

README.md

@@ -28,22 +28,22 @@ A production-ready [Model Context Protocol](https://modelcontextprotocol.io/intr
 
 ## API v2
 
-This MCP server targets **ScrapeGraph API v2** (`https://api.scrapegraphai.com/v2`), aligned 1:1 with
+This MCP server targets **ScrapeGraph API v2** (`https://api.scrapegraphai.com/api/v2`), aligned 1:1 with
 [scrapegraph-py PR #84](https://github.com/ScrapeGraphAI/scrapegraph-py/pull/84). Auth uses the
 `SGAI-APIKEY` header. Environment variables mirror the Python SDK:
 
-- **`SGAI_API_URL`** — override the base URL (default `https://api.scrapegraphai.com/v2`)
-- **`SGAI_TIMEOUT_S`** — request timeout in seconds (default `120`)
+- **`SGAI_API_URL`** — override the base URL (default `https://api.scrapegraphai.com/api/v2`)
+- **`SGAI_TIMEOUT`** — request timeout in seconds (default `120`)
 - **`SGAI_API_KEY`** — API key (can also be passed via MCP `scrapegraphApiKey` or `X-API-Key` header)
 
-> `SCRAPEGRAPH_API_BASE_URL` is still honored as a legacy alias for `SGAI_API_URL`.
+> Legacy aliases (still honored): `SCRAPEGRAPH_API_BASE_URL` for `SGAI_API_URL`, `SGAI_TIMEOUT_S` for `SGAI_TIMEOUT`.
 
 ## Key Features
 
 - **Scrape & extract**: `markdownify` / `scrape` (POST /scrape), `smartscraper` (POST /extract, URL only)
 - **Search**: `searchscraper` (POST /search; `num_results` clamped 3–20)
 - **Crawl**: Async multi-page crawl in **markdown** or **html** only; `crawl_stop` / `crawl_resume`
-- **Monitors**: Scheduled jobs via `monitor_create`, `monitor_list`, `monitor_get`, pause/resume/delete
+- **Monitors**: Scheduled jobs via `monitor_create`, `monitor_list`, `monitor_get`, pause/resume/delete, `monitor_activity` (paginated tick history)
 - **Account**: `credits`, `sgai_history`
 - **Easy integration**: Claude Desktop, Cursor, Smithery, HTTP transport
 - **Developer docs**: `.agent/` folder
@@ -83,6 +83,7 @@ That's it! The server is now available to your AI assistant.
 | `credits` | GET /credits |
 | `sgai_history` | GET /history |
 | `monitor_create`, `monitor_list`, `monitor_get`, `monitor_pause`, `monitor_resume`, `monitor_delete` | /monitor API |
+| `monitor_activity` | GET /monitor/:id/activity (paginated tick history: `id`, `createdAt`, `status`, `changed`, `elapsedMs`, `diffs`) |
 
 **Removed vs older MCP releases:** `sitemap`, `agentic_scrapper`, `markdownify_status`, `smartscraper_status` (no v2 endpoints).
 

server.json

@@ -24,7 +24,7 @@
           "name": "SGAI_API_KEY"
         },
         {
-          "description": "Override API base URL (default https://api.scrapegraphai.com/v2)",
+          "description": "Override API base URL (default https://api.scrapegraphai.com/api/v2)",
           "isRequired": false,
           "format": "string",
           "isSecret": false,
@@ -35,7 +35,7 @@
           "isRequired": false,
           "format": "string",
           "isSecret": false,
-          "name": "SGAI_TIMEOUT_S"
+          "name": "SGAI_TIMEOUT"
         }
       ]
     }

src/scrapegraph_mcp/server.py

@@ -24,9 +24,10 @@
 Removed on v2 (no API equivalent): sitemap, agentic_scrapper, markdownify_status, smartscraper_status.
 
 Environment variables (match scrapegraph-py v2):
-- SGAI_API_URL (default https://api.scrapegraphai.com/v2) — base URL override
-- SGAI_TIMEOUT_S (default 120) — request timeout in seconds
+- SGAI_API_URL (default https://api.scrapegraphai.com/api/v2) — base URL override
+- SGAI_TIMEOUT (default 120) — request timeout in seconds
 - SCRAPEGRAPH_API_BASE_URL — legacy alias for SGAI_API_URL (still honored)
+- SGAI_TIMEOUT_S — legacy alias for SGAI_TIMEOUT (still honored)
 
 ## Parameter Validation and Error Handling
 
@@ -87,8 +88,8 @@
 logger = logging.getLogger(__name__)
 
 MCP_SERVER_VERSION = "2.0.0"
-# Matches scrapegraph-py v2 (env.py): https://api.scrapegraphai.com/v2
-DEFAULT_API_BASE_URL = "https://api.scrapegraphai.com/v2"
+# Matches scrapegraph-py v2 (env.py): https://api.scrapegraphai.com/api/v2
+DEFAULT_API_BASE_URL = "https://api.scrapegraphai.com/api/v2"
 
 
 def _api_base_url() -> str:
@@ -101,8 +102,8 @@ def _api_base_url() -> str:
 
 
 def _api_timeout_s() -> float:
-    # SGAI_TIMEOUT_S mirrors scrapegraph-py v2 (default 120s).
-    val = os.environ.get("SGAI_TIMEOUT_S")
+    # SGAI_TIMEOUT mirrors scrapegraph-py v2 (default 120s); SGAI_TIMEOUT_S is a legacy alias.
+    val = os.environ.get("SGAI_TIMEOUT") or os.environ.get("SGAI_TIMEOUT_S")
     try:
         return float(val) if val else 120.0
     except ValueError:
@@ -545,6 +546,20 @@ def monitor_resume(self, monitor_id: str) -> Dict[str, Any]:
     def monitor_delete(self, monitor_id: str) -> Dict[str, Any]:
         return self._request("DELETE", f"/monitor/{monitor_id}")
 
+    def monitor_activity(
+        self,
+        monitor_id: str,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """GET /monitor/:id/activity — paginated tick history."""
+        params: Dict[str, Any] = {}
+        if limit is not None:
+            params["limit"] = limit
+        if cursor is not None:
+            params["cursor"] = cursor
+        return self._request("GET", f"/monitor/{monitor_id}/activity", params=params or None)
+
     def close(self) -> None:
         """Close the HTTP client."""
         self.client.close()
@@ -647,7 +662,7 @@ def web_scraping_guide() -> str:
 1. Use **markdownify** or **scrape** before **smartscraper** when you only need readable text.
 2. Multi-page **AI** extraction: run **smartscraper** per URL, or use **monitor_create** on a schedule.
 3. Poll **smartcrawler_fetch_results** until the crawl finishes.
-4. Override API host with env **SGAI_API_URL** if needed (default `https://api.scrapegraphai.com/v2`).
+4. Override API host with env **SGAI_API_URL** if needed (default `https://api.scrapegraphai.com/api/v2`).
 """
 
 
@@ -697,7 +712,7 @@ def quick_start_examples() -> str:
 limit: 10
 ```
 
-Auth: `SGAI_API_KEY` or MCP `scrapegraphApiKey`. Optional: `SGAI_API_URL`, `SGAI_TIMEOUT_S`.
+Auth: `SGAI_API_KEY` or MCP `scrapegraphApiKey`. Optional: `SGAI_API_URL`, `SGAI_TIMEOUT` (legacy: `SGAI_TIMEOUT_S`).
 """
 
 
@@ -712,11 +727,11 @@ def api_status() -> str:
     return """# ScapeGraph API Status (MCP v2)
 
 - **MCP package version**: 2.0.0 (matches [scrapegraph-py#84](https://github.com/ScrapeGraphAI/scrapegraph-py/pull/84) API surface)
-- **Default API base**: `https://api.scrapegraphai.com/v2` (override with `SGAI_API_URL`)
+- **Default API base**: `https://api.scrapegraphai.com/api/v2` (override with `SGAI_API_URL`)
 - **Auth headers**: `SGAI-APIKEY`, `X-SDK-Version: scrapegraph-mcp@2.0.0`
 
 ## Tools
-markdownify, scrape, smartscraper, searchscraper, smartcrawler_initiate, smartcrawler_fetch_results, crawl_stop, crawl_resume, generate_schema, credits, sgai_history, monitor_create, monitor_list, monitor_get, monitor_pause, monitor_resume, monitor_delete
+markdownify, scrape, smartscraper, searchscraper, smartcrawler_initiate, smartcrawler_fetch_results, crawl_stop, crawl_resume, generate_schema, credits, sgai_history, monitor_create, monitor_list, monitor_get, monitor_pause, monitor_resume, monitor_delete, monitor_activity
 
 ## Removed vs legacy MCP
 sitemap, agentic_scrapper, markdownify_status, smartscraper_status — not available on API v2.
@@ -2008,6 +2023,32 @@ def monitor_delete(monitor_id: str, ctx: Context) -> Dict[str, Any]:
         return {"error": str(e)}
 
 
+@mcp.tool(annotations={"readOnlyHint": True, "destructiveHint": False, "idempotentHint": True})
+def monitor_activity(
+    monitor_id: str,
+    ctx: Context,
+    limit: Optional[int] = None,
+    cursor: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Poll per-run tick history for a monitor (API v2 GET /monitor/:id/activity).
+
+    Returns the ticks produced on each scheduled run (`id`, `createdAt`, `status`,
+    `changed`, `elapsedMs`, `diffs`) plus `nextCursor` when more results are
+    available. Mirrors `sgai.monitor.activity()` in scrapegraph-py v2.
+
+    Args:
+        monitor_id: ID of the monitor (cronId returned by monitor_create).
+        limit: Page size, 1–100. Default 20 (server-side).
+        cursor: Opaque pagination cursor returned as `nextCursor` by a prior call.
+    """
+    try:
+        api_key = get_api_key(ctx)
+        client = ScapeGraphClient(api_key)
+        return client.monitor_activity(monitor_id, limit=limit, cursor=cursor)
+    except Exception as e:
+        return {"error": str(e)}
+
+
 # Add tool for basic scrape
 @mcp.tool(annotations={"readOnlyHint": True, "destructiveHint": False, "idempotentHint": True})
 def scrape(