mesharc 0.3.2__tar.gz → 0.3.4__tar.gz

{mesharc-0.3.2 → mesharc-0.3.4}/CHANGELOG.md

@@ -6,6 +6,37 @@ All notable changes to this package are recorded here. The format follows
 
 ## Unreleased
 
+## 0.3.4 - 2026-10-07
+
+### Added
+
+- **`cancel_job(kind, id, project_id=None)`**, an eighteenth MCP tool: it stops a crawl, run or batch that is still going. It's the counterpart to `get_job`.
+  - Until now an assistant had no way out of a job that should not finish. `start_run` and `recrawl_pages` answer 409 while a run is going, and nothing could stop that run.
+  - It uses the API's existing cancels: `POST /projects/{id}/runs/{run_id}/cancel`, `DELETE /crawl/{id}` and `DELETE /scrape/{id}`.
+  - Queued work is dropped at once, and a page being read finishes first. Pages already read stay readable, and nothing is deleted.
+  - A job that already finished is left as it is and reported with its status, so asking twice is harmless.
+  - It needs write access and is marked destructive (a stop cannot be resumed).
+- **`list_runs(project_id, limit=25)`**, a nineteenth MCP tool. It lists a project's runs newest first, so an assistant can find a run id for `list_pages`, `get_page`, `get_changes` or `search_pages`, see whether a run is still going before `start_run`, or pick the one to stop. Until now only `get_project`'s last run and `start_run`'s answer gave a run id. It's read-only, over the existing `GET /projects/{id}/runs`, and keeps only the fields that pick a run (no config, link graph or engine profile).
+- **`MeshArc.cancel_batch(batch_id)`**: stops a scrape batch, or a one-URL scrape still going. It's the client's counterpart to `Crawl.cancel()` and `runs.cancel()`.
+
+### Changed
+
+- `start_run`, `recrawl_pages` and `get_job` say that `cancel_job` stops a running job; `cancel_job` and the `run_id` parameters point to `list_runs`. The server's instructions and the README name them too.
+
+## 0.3.3 - 2026-10-07
+
+### Changed
+
+- **Tool descriptions are written in short lines, one fact each.** Glama's grader scored 0.3.2's tools A (4.6/5). The points it took off were for clauses chained by semicolons, and for descriptions that added nothing about the inputs beyond the schema. Each description now keeps its purpose and when-to-use lines, and adds:
+  - **Inputs:** how the inputs work together. Examples: `formats` only picks which stored bodies come back; path globs match the path, never the host; a `get_page` url must match apart from scheme and trailing slash; `recrawl_pages` resolves '/pricing' against the project's site.
+  - **Access:** whether a read-only connection may call it, and that errors come back as `{error, status}`.
+  - **Returns and limits:** the answer's shape and its limits. Examples: `list_pages` returns up to 500 rows, shallowest first; `list_projects` returns everything, oldest first; `get_changes` answers 409 for a run still going; `get_job` answers 404 once a crawl has expired.
+- Apart from the fix below, behaviour is unchanged. Only the text an assistant reads differs.
+
+### Fixed
+
+- `list_projects` returns each project's `status` (draft, crawling, healthy or failing). It asked the API for `health`, which no project carries, so every row said `health: null`.
+
 ## 0.3.2 - 2026-10-06
 
 ### Changed

{mesharc-0.3.2/mesharc.egg-info → mesharc-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mesharc
-Version: 0.3.2
+Version: 0.3.4
 Summary: Python client for the MeshArc API: a URL in, clean content out, and a record of what changed.
 License-Expression: MIT
 Project-URL: Homepage, https://mesharc.dev
@@ -279,13 +279,13 @@ MESHARC_API_KEY=mesharc_... mesharc-mcp          # serves over stdio
 claude mcp add mesharc -e MESHARC_API_KEY=mesharc_... -- mesharc-mcp
 ```
 
-Tools: `scrape_urls`, `extract_url`, `map_site`, `crawl_site`, `keep_crawl_as_project`, `list_projects`, `describe_project_config`, `get_project`, `create_project`, `update_project`, `start_run`, `list_pages`, `get_page`, `get_changes`, `search_pages`, `recrawl_pages`, `get_job`. Every tool is a call through this client.
+Tools: `scrape_urls`, `extract_url`, `map_site`, `crawl_site`, `keep_crawl_as_project`, `list_projects`, `describe_project_config`, `get_project`, `create_project`, `update_project`, `start_run`, `list_runs`, `list_pages`, `get_page`, `get_changes`, `search_pages`, `recrawl_pages`, `get_job`, `cancel_job`. Every tool is a call through this client.
 
 A result with many pages in it is a map, not the territory: a crawl answers with an index of the pages read (up to 500, fewer if the budget needs the room), an excerpt of as many as a 60,000-character budget pays for (fifty at most), and a count of each page's links rather than the links. Ask for the one page you want on its own with `get_job(kind="crawl", id=…, url=…)`, or carry on through the crawl with `cursor=`. A multi-URL scrape past its budget counts the rest by status and names any that did not come back ok. One page asked for on its own -- `extract_url`, `get_page`, `scrape_urls` with a single url -- comes back whole, capped at 12,000 characters.
 
-Hosted, a connection can be approved read-only, and read-only cuts in a place worth knowing: it reads the whole workspace, but it cannot reach the site. Anything that fetches is a write, because it leaves the workspace and usually spends its credits -- `map_site` is the one that fetches and costs nothing, and it is gated with the rest. `list_projects`, `get_project`, `describe_project_config`, `list_pages`, `get_page`, `get_changes`, `search_pages` and `get_job` work; the nine that fetch or write -- `scrape_urls`, `extract_url`, `map_site`, `crawl_site`, `keep_crawl_as_project`, `create_project`, `update_project`, `start_run`, `recrawl_pages` -- answer `{"code": "read_only"}` with what to do about it, until the app is reconnected with write access.
+Hosted, a connection can be approved read-only, and read-only cuts in a place worth knowing: it reads the whole workspace, but it cannot reach the site. Anything that fetches is a write, because it leaves the workspace and usually spends its credits -- `map_site` is the one that fetches and costs nothing, and it is gated with the rest. `list_projects`, `get_project`, `describe_project_config`, `list_runs`, `list_pages`, `get_page`, `get_changes`, `search_pages` and `get_job` work; the ten that fetch or write -- `scrape_urls`, `extract_url`, `map_site`, `crawl_site`, `keep_crawl_as_project`, `create_project`, `update_project`, `start_run`, `recrawl_pages`, `cancel_job` -- answer `{"code": "read_only"}` with what to do about it, until the app is reconnected with write access.
 
-Hosted, a tool that would hold a connection open for minutes — a crawl, a run you asked to wait for, a multi-URL scrape — hands back a job after `MESHARC_MCP_WAIT` seconds (25 by default, because many MCP hosts time a tool call out sooner). The work carries on server-side and `get_job` picks it up. Run locally, those tools block as they always have.
+Hosted, a tool that would hold a connection open for minutes — a crawl, a run you asked to wait for, a multi-URL scrape — hands back a job after `MESHARC_MCP_WAIT` seconds (25 by default, because many MCP hosts time a tool call out sooner). The work carries on server-side; `get_job` picks it up and `cancel_job` stops it. Run locally, those tools block as they always have.
 
 ### Hosting it yourself
 

{mesharc-0.3.2 → mesharc-0.3.4}/README.md

@@ -243,13 +243,13 @@ MESHARC_API_KEY=mesharc_... mesharc-mcp          # serves over stdio
 claude mcp add mesharc -e MESHARC_API_KEY=mesharc_... -- mesharc-mcp
 ```
 
-Tools: `scrape_urls`, `extract_url`, `map_site`, `crawl_site`, `keep_crawl_as_project`, `list_projects`, `describe_project_config`, `get_project`, `create_project`, `update_project`, `start_run`, `list_pages`, `get_page`, `get_changes`, `search_pages`, `recrawl_pages`, `get_job`. Every tool is a call through this client.
+Tools: `scrape_urls`, `extract_url`, `map_site`, `crawl_site`, `keep_crawl_as_project`, `list_projects`, `describe_project_config`, `get_project`, `create_project`, `update_project`, `start_run`, `list_runs`, `list_pages`, `get_page`, `get_changes`, `search_pages`, `recrawl_pages`, `get_job`, `cancel_job`. Every tool is a call through this client.
 
 A result with many pages in it is a map, not the territory: a crawl answers with an index of the pages read (up to 500, fewer if the budget needs the room), an excerpt of as many as a 60,000-character budget pays for (fifty at most), and a count of each page's links rather than the links. Ask for the one page you want on its own with `get_job(kind="crawl", id=…, url=…)`, or carry on through the crawl with `cursor=`. A multi-URL scrape past its budget counts the rest by status and names any that did not come back ok. One page asked for on its own -- `extract_url`, `get_page`, `scrape_urls` with a single url -- comes back whole, capped at 12,000 characters.
 
-Hosted, a connection can be approved read-only, and read-only cuts in a place worth knowing: it reads the whole workspace, but it cannot reach the site. Anything that fetches is a write, because it leaves the workspace and usually spends its credits -- `map_site` is the one that fetches and costs nothing, and it is gated with the rest. `list_projects`, `get_project`, `describe_project_config`, `list_pages`, `get_page`, `get_changes`, `search_pages` and `get_job` work; the nine that fetch or write -- `scrape_urls`, `extract_url`, `map_site`, `crawl_site`, `keep_crawl_as_project`, `create_project`, `update_project`, `start_run`, `recrawl_pages` -- answer `{"code": "read_only"}` with what to do about it, until the app is reconnected with write access.
+Hosted, a connection can be approved read-only, and read-only cuts in a place worth knowing: it reads the whole workspace, but it cannot reach the site. Anything that fetches is a write, because it leaves the workspace and usually spends its credits -- `map_site` is the one that fetches and costs nothing, and it is gated with the rest. `list_projects`, `get_project`, `describe_project_config`, `list_runs`, `list_pages`, `get_page`, `get_changes`, `search_pages` and `get_job` work; the ten that fetch or write -- `scrape_urls`, `extract_url`, `map_site`, `crawl_site`, `keep_crawl_as_project`, `create_project`, `update_project`, `start_run`, `recrawl_pages`, `cancel_job` -- answer `{"code": "read_only"}` with what to do about it, until the app is reconnected with write access.
 
-Hosted, a tool that would hold a connection open for minutes — a crawl, a run you asked to wait for, a multi-URL scrape — hands back a job after `MESHARC_MCP_WAIT` seconds (25 by default, because many MCP hosts time a tool call out sooner). The work carries on server-side and `get_job` picks it up. Run locally, those tools block as they always have.
+Hosted, a tool that would hold a connection open for minutes — a crawl, a run you asked to wait for, a multi-URL scrape — hands back a job after `MESHARC_MCP_WAIT` seconds (25 by default, because many MCP hosts time a tool call out sooner). The work carries on server-side; `get_job` picks it up and `cancel_job` stops it. Run locally, those tools block as they always have.
 
 ### Hosting it yourself
 

{mesharc-0.3.2 → mesharc-0.3.4}/mesharc/__init__.py

@@ -31,7 +31,7 @@ from urllib.parse import parse_qs, urlparse
 
 import httpx
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"
 __all__ = ["MeshArc", "MeshArcError", "MeshArcTimeoutError", "Crawl"]
 
 DEFAULT_BASE = "https://api.mesharc.dev"
@@ -432,6 +432,12 @@ class MeshArc:
             time.sleep(poll)
             self._h.pace()
 
+    def cancel_batch(self, batch_id: str) -> None:
+        """Stop a scrape: every run of a batch, or a one-URL scrape still going.
+        Queued pages are dropped; a page being read finishes first, and pages
+        already read stay readable."""
+        self._h("DELETE", f"/scrape/{batch_id}")
+
     def crawl(self, url: str, wait: bool = False, poll: float = 3.0, timeout: float = 3600,
               idempotency_key: Optional[str] = None, **opts: Any) -> Crawl:
         """Crawl a site once, with no project to set up first.

{mesharc-0.3.2 → mesharc-0.3.4}/mesharc/mcp.py

@@ -83,7 +83,8 @@ INSTRUCTIONS = (
     "crawl_site to crawl a whole site once without setting a project up first "
     "(keep_crawl_as_project turns one of those into a watched project afterwards). "
     "The project tools are for a site watched over time: its pages, its change record, "
-    "and search inside a run. Blocked pages are reported as blocked, never as missing."
+    "and search inside a run. A long tool may hand back a job: get_job follows it and cancel_job stops it. "
+    "Blocked pages are reported as blocked, never as missing."
 )
 
 # The tools, in the order they are declared, with how each was registered.
@@ -92,7 +93,7 @@ INSTRUCTIONS = (
 # on a second server later, built with auth in its constructor. The registry is
 # what carries the descriptions across: a description is the only thing an
 # assistant has to pick a tool by, and re-registering without them would leave
-# seventeen nameless verbs.
+# nineteen nameless verbs.
 _TOOLS: "list[tuple]" = []
 
 # What each tool does to the world, in the hints MCP clients read. A tool that
@@ -111,7 +112,7 @@ def _acts(*, destructive=False, idempotent=False, open_world=True):
 # The parameters most tools share, described once.
 ProjectId = Annotated[str, Field(description="The project's id, as list_projects or create_project returns it.")]
 RunId = Annotated[str | None, Field(
-    description="A run's id, from start_run or the runId a list_pages answer carries; "
+    description="A run's id, from list_runs, start_run or the runId a list_pages answer carries; "
                 "leave empty for the last finished run.")]
 Schedule = Literal["manual", "hourly", "daily", "weekly"]
 FetchConfig = Annotated[dict | None, Field(
@@ -533,7 +534,7 @@ def _scopes():
     return list(getattr(at, "scopes", None) or []) if at else []
 
 
-# Nine of the seventeen tools need write, including every one that fetches a
+# Ten of the nineteen tools need write, including every one that fetches a
 # page: fetching spends the workspace's credits, so it is not a read however
 # it reads to an assistant asking for one URL. The API answers "this needs the
 # member role", which is true and tells an assistant nothing it can act on --
@@ -591,14 +592,20 @@ def _safe(fn):
 
 @tool(title="Scrape a list of URLs",
       annotations=_acts(idempotent=True),
-      description="Fetch known URLs (1 to 500) once and return each page's content, markdown by default; no project "
-                  "is created. For one page with every format or browser steps use extract_url; to find pages by "
-                  "following links use crawl_site; to list a site's URLs without fetching them use map_site. "
-                  "Each page costs the credits of the engine that read it (1 plain fetch, 4 browser render), and a "
-                  "page the site refuses is free. A single URL answers in the same request; a list waits for the "
-                  "batch, and a large one comes back as an index with excerpts inside 60,000 characters. Hosted, a "
-                  "batch still going after the time budget comes back as a job for get_job, and repeating the same "
-                  "call returns that job instead of starting another.")
+      description="Fetch known URLs (1 to 500) once and return each page's content. No project is created.\n"
+                  "Use extract_url for one page with browser steps or structured fields, crawl_site to discover "
+                  "pages by following links, and map_site to list a site's URLs without fetching them.\n"
+                  "Inputs: `formats` only picks which stored bodies come back (e.g. 'markdown,text'); how a page is "
+                  "fetched and extracted is `config`. A PDF, Word or spreadsheet URL is read as text unless "
+                  "parse_documents is false.\n"
+                  "Cost: the credits of the engine that read each page (1 plain fetch, 4 browser render). A page "
+                  "the site refuses is free.\n"
+                  "Returns: one URL answers in the same request. A list waits for the batch, and a large batch is "
+                  "an index plus excerpts inside 60,000 characters. Hosted, a batch still going after the time "
+                  "budget comes back as a job for get_job. Repeating the same call returns that job instead of "
+                  "starting another.\n"
+                  "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
+                  "{error, status}.")
 def scrape_urls(urls: Annotated[list[str], Field(
                     description="The pages to fetch: 1 to 500 absolute http(s) URLs.")],
                 config: FetchConfig = None,
@@ -633,16 +640,21 @@ def scrape_urls(urls: Annotated[list[str], Field(
 
 @tool(title="Extract one page in full",
       annotations=_acts(),
-      description="Fetch one URL exactly as a project with the given settings would, and return the whole page: "
-                  "the bodies config's formats ask for plus the raw html (each capped at 12,000 characters), head "
-                  "and extracted fields, its images, and which engine read it -- without its link list. Use it "
-                  "for a single page that needs browser steps, structured fields or a settings trial before "
-                  "create_project; for plain content of one or many known URLs use scrape_urls, and get_page "
-                  "reads a page a project already stored without fetching. It climbs the fetch ladder -- plain "
-                  "http first, a browser only when the page needs one or render_js is 'always' -- and costs the "
-                  "credits of the rung that read it (1 to 4 for most pages, +1 when formats ask for a "
-                  "screenshot). Browser `actions` in config (click, type, select, press, wait, scroll; repeat "
-                  "'until_gone' for Load-more buttons; `each` to act on every match) run before the page is read.")
+      description="Fetch one URL exactly as a project with the given settings would, and return the whole page: the "
+                  "bodies config's formats ask for plus the raw html (each capped at 12,000 characters), head and "
+                  "extracted fields, its images, and which engine read it. The link list is left out.\n"
+                  "Use it for one page that needs browser steps, structured fields, or a settings trial before "
+                  "create_project. For plain content of known URLs use scrape_urls. To read a page a project "
+                  "already stored, without fetching, use get_page.\n"
+                  "Inputs: browser `actions` in config (click, type, select, press, wait, scroll; repeat "
+                  "'until_gone' for Load-more buttons; `each` to act on every match) run before the page is read. A "
+                  "parse_documents key in config wins over the parse_documents argument.\n"
+                  "Behaviour: it climbs the fetch ladder, plain http first and a browser only when the page needs "
+                  "one or render_js is 'always'. It costs the credits of the rung that read it (1 to 4 for most "
+                  "pages, +1 when formats ask for a screenshot). A page the site refuses comes back marked blocked, "
+                  "at no cost, rather than as an error.\n"
+                  "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
+                  "{error, status}.")
 def extract_url(url: Annotated[str, Field(description="The absolute http(s) URL of the page to read.")],
                 config: FetchConfig = None,
                 parse_documents: ParseDocuments = True) -> dict:
@@ -658,12 +670,18 @@ def extract_url(url: Annotated[str, Field(description="The absolute http(s) URL
 
 @tool(title="Map a site's declared URLs",
       annotations=_acts(),
-      description="List every URL a site declares in its sitemaps -- found through robots.txt and the well-known "
-                  "paths, each index file walked to its children -- without fetching any of the pages. Use it "
-                  "first, to see how big a site is and what sections it has, before crawl_site or create_project; "
-                  "it cannot read page content (scrape_urls or crawl_site do) and misses pages a site links to but "
-                  "does not declare. Costs 1 credit per sitemap file read, usually 1 in total, never per URL. "
-                  "Returns the discovery method, totals, up to `limit` URLs and the section names.")
+      description="List every URL a site declares in its sitemaps (found through robots.txt and the well-known "
+                  "paths, each index file walked to its children) without fetching any of the pages.\n"
+                  "Use it first, to see how big a site is and what sections it has, before crawl_site or "
+                  "create_project. It cannot read page content (scrape_urls or crawl_site do), and it misses pages "
+                  "a site links to but does not declare.\n"
+                  "Inputs: `url` can be any page of the site, since discovery starts at the site's root. `search` "
+                  "is a case-insensitive substring of the full URL, with no wildcards, applied before `limit`. "
+                  "`totals` still count every declared URL.\n"
+                  "Cost: 1 credit per sitemap file read (usually 1 in total), never per URL.\n"
+                  "Returns: the discovery method, totals, up to `limit` URLs and the section names.\n"
+                  "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
+                  "{error, status}.")
 def map_site(url: Annotated[str, Field(description="Any URL on the site, usually its home page.")],
              search: Annotated[str | None, Field(
                  description="Keep only URLs containing this text, e.g. '/blog/'; omit for all.")] = None,
@@ -681,16 +699,22 @@ def map_site(url: Annotated[str, Field(description="Any URL on the site, usually
 
 @tool(title="Crawl a whole site once",
       annotations=_acts(idempotent=True),
-      description="Crawl a site once from a start URL -- following its links and reading its sitemap, up to "
-                  "`limit` pages -- and return what it found, without setting up a project. Use it to read a site "
-                  "or section whose page URLs you do not know; for known URLs use scrape_urls, and to watch a site "
-                  "over time use create_project (or keep_crawl_as_project on this crawl afterwards). Each page "
-                  "costs the credits of the engine that read it (usually 1 to 4) and refused pages are free. It "
-                  "waits for the crawl, minutes for a large limit; hosted, a crawl still going after the time "
-                  "budget comes back as a job for get_job, and repeating the call returns the same crawl. The "
-                  "answer is an index of the pages read plus excerpts inside 60,000 characters; get_job with "
-                  "`url` reads one page in full and with `cursor` the next window. The crawl is kept for a day; "
-                  "pass the result's crawl_id to keep_crawl_as_project to keep it for good.")
+      description="Crawl a site once from a start URL, following its links and reading its sitemap up to `limit` "
+                  "pages, and return what it found. No project is set up.\n"
+                  "Use it to read a site or section whose page URLs you do not know. For known URLs use "
+                  "scrape_urls. To watch a site over time use create_project, or keep_crawl_as_project on this "
+                  "crawl afterwards.\n"
+                  "Inputs: include_paths and exclude_paths match the URL path only, never the host, and pages they "
+                  "leave out do not count toward `limit`. '/blog/*' takes the blog index and everything under it. "
+                  "`max_depth` counts link hops from the start URL (0 = that page only).\n"
+                  "Cost: the credits of the engine that read each page (usually 1 to 4). Refused pages are free.\n"
+                  "Behaviour: it waits for the crawl, minutes for a large limit. Hosted, a crawl still going after "
+                  "the time budget comes back as a job for get_job, and repeating the call returns the same crawl.\n"
+                  "Returns: an index of the pages read plus excerpts inside 60,000 characters. get_job with `url` "
+                  "reads one page in full, and with `cursor` the next window. The crawl is kept for a day; pass its "
+                  "crawl_id to keep_crawl_as_project to keep it for good.\n"
+                  "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
+                  "{error, status}.")
 def crawl_site(url: Annotated[str, Field(description="The absolute http(s) URL to start from, e.g. the home page.")],
                limit: Annotated[int, Field(
                    description="The most pages to read, 1 to 5,000 (default 50); the plan's page cap also applies.")]
@@ -740,12 +764,19 @@ def crawl_site(url: Annotated[str, Field(description="The absolute http(s) URL t
 
 @tool(title="Keep a crawl as a project",
       annotations=_acts(open_world=False),
-      description="Turn a crawl_site crawl into a project, so the site is watched over time and each later run "
-                  "is compared against this one. Nothing is fetched again and it costs no credits: the crawl's "
-                  "pages become the project's first run. Use it after crawl_site when the site is worth watching; "
-                  "to start a watched site from scratch use create_project. Without it a crawl and its pages "
-                  "expire after a day. It counts toward the plan's project limit (refused with plan_limit when "
-                  "full). Returns the new project, whose id the other project tools take.")
+      description="Turn a crawl_site crawl into a project, so the site is watched over time and each later run is "
+                  "compared with this one.\n"
+                  "Use it after crawl_site when the site is worth watching. To start a watched site from scratch "
+                  "use create_project.\n"
+                  "Inputs: `crawl_id` must be a crawl this workspace started, kept within a day. After that the "
+                  "crawl and its pages have expired and the call answers 404. A `schedule` other than 'manual' "
+                  "starts runs on its own, and each run spends credits.\n"
+                  "Behaviour: nothing is fetched again and it costs no credits; the crawl's pages become the "
+                  "project's first run. It counts toward the plan's project limit and is refused with plan_limit "
+                  "when that is full.\n"
+                  "Returns: the new project, whose id the other project tools take.\n"
+                  "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
+                  "{error, status}.")
 def keep_crawl_as_project(crawl_id: Annotated[str, Field(
                               description="The crawl_id a crawl_site answer (or get_job on a crawl) returned.")],
                           name: Annotated[str | None, Field(
@@ -762,13 +793,17 @@ def keep_crawl_as_project(crawl_id: Annotated[str, Field(
 
 @tool(title="List all projects",
       annotations=READS_STORED,
-      description="List every project in the workspace -- the sites it watches over time -- with each one's id, "
-                  "name, seed URL, host, schedule, page count, coverage, last run and health. Call it first to "
-                  "find a project_id for the other project tools, or to check whether a site is already watched "
-                  "before create_project; get_project gives one project's full settings. Reads only what is "
-                  "stored: free, and it fetches nothing. A key limited to some projects sees only those.")
+      description="List every project in the workspace (the sites it watches over time) with each one's id, name, "
+                  "seed URL, host, schedule, page count, coverage, last run and status (draft, crawling, healthy or "
+                  "failing).\n"
+                  "Call it first to find a project_id for the other project tools, or to check whether a site is "
+                  "already watched before create_project. get_project gives one project's full settings.\n"
+                  "Returns: all projects in one answer, oldest first, with no paging. A key limited to some "
+                  "projects sees only those.\n"
+                  "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
+                  "{error, status}.")
 def list_projects() -> list | dict:
-    return _safe(lambda: [{k: p.get(k) for k in ("id", "name", "seed", "host", "schedule", "pages", "coverage", "lastRun", "health")}
+    return _safe(lambda: [{k: p.get(k) for k in ("id", "name", "seed", "host", "schedule", "pages", "coverage", "lastRun", "status")}
                           for p in _client().projects.list()])
 
 
@@ -821,11 +856,16 @@ CONFIG_GUIDE = {
 
 @tool(title="Describe project settings",
       annotations=READS_STORED,
-      description="List the project settings an assistant can set -- each key with its meaning and its default "
-                  "-- plus the valid schedules and how path globs work. Read it before create_project, "
-                  "update_project or a `config` argument whenever the request names a section, schedule, format, "
-                  "limit or behaviour: keys are exact and guessed names are refused. It describes settings in "
-                  "general; get_project shows the values one project has. Free, and it fetches nothing.")
+      description="List the project settings an assistant can set, each with its meaning and default, plus the "
+                  "valid schedules and how path globs work.\n"
+                  "Read it before create_project, update_project or any `config` argument whenever the request "
+                  "names a section, schedule, format, limit or behaviour. Keys are exact, and guessed names are "
+                  "refused.\n"
+                  "It describes settings in general. get_project shows the values one project has.\n"
+                  "Returns: `settings` as [{key, meaning, default}], `other_keys` (accepted but rarely needed), "
+                  "`schedules`, and a `note` on path globs.\n"
+                  "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
+                  "{error, status}.")
 def describe_project_config() -> dict:
     def go():
         with _client() as s:
@@ -841,24 +881,34 @@ def describe_project_config() -> dict:
 
 @tool(title="Get one project",
       annotations=READS_STORED,
-      description="Read one project in full: its settings (config), schedule, retention, coverage and last run. "
-                  "Read it before update_project, to see the values you are about to change; list_projects is "
-                  "the lighter way to find projects, and list_pages or get_changes read what its runs found. "
-                  "Free, fetches nothing; an unknown or hidden project answers 404. The webhook signing secret "
-                  "is withheld from the answer.")
+      description="Read one project in full: its settings (config), schedule, retention, coverage and last run.\n"
+                  "Read it before update_project, to see the values you are about to change. list_projects is the "
+                  "lighter way to find projects. list_pages and get_changes read what its runs found.\n"
+                  "Inputs: `project_id` is the 32-character hex id that list_projects shows, not the project's name "
+                  "or URL. An unknown id, or a project the key cannot see, answers 404.\n"
+                  "Returns: the project's id, name, seed, host, schedule, config, retention, pages, coverage, "
+                  "status, lastRun, nextRunAt and changeSummary. The webhook signing secret is withheld.\n"
+                  "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
+                  "{error, status}.")
 def get_project(project_id: ProjectId) -> dict:
     return _safe(lambda: _client().projects.get(project_id))
 
 
 @tool(title="Create a watched project",
       annotations=_acts(),
-      description="Create a project that watches a site over time: it is crawled on its schedule and each run is "
-                  "compared with the last, recording pages added, modified and removed. Use it when the request "
-                  "is to monitor or track a site; for a one-off read use crawl_site (keep_crawl_as_project can "
-                  "turn that into a project later), and check list_projects first so the site is not added "
-                  "twice. Creating it reads the site's robots.txt and sitemaps but fetches no pages; every run "
-                  "then spends credits per page. Refused when the plan's project limit is reached. Returns the "
-                  "project, whose id start_run takes to crawl it now.")
+      description="Create a project that watches a site over time. It is crawled on its schedule and each run is "
+                  "compared with the last, recording pages added, modified and removed.\n"
+                  "Use it when the request is to monitor or track a site. For a one-off read use crawl_site (and "
+                  "keep_crawl_as_project later if it is worth keeping). Check list_projects first so the site is "
+                  "not added twice.\n"
+                  "Inputs: `seed` fixes the project's host for good; no later update can move it to another site. A "
+                  "`schedule` other than 'manual' starts runs on its own. Unknown `config` keys are refused, and "
+                  "values above the plan's caps (such as max_pages) are lowered to them.\n"
+                  "Behaviour: creating it reads the site's robots.txt and sitemaps but fetches no pages. Every run "
+                  "then spends credits per page. It is refused when the plan's project limit is reached.\n"
+                  "Returns: the new project, in get_project's shape; start_run takes its id to crawl it now.\n"
+                  "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
+                  "{error, status}.")
 def create_project(seed: Annotated[str, Field(
                        description="Where the crawl starts: a public site's URL or bare domain, e.g. "
                                    "'https://example.com/blog/' or 'example.com'. The project covers that host.")],
@@ -877,12 +927,16 @@ def create_project(seed: Annotated[str, Field(
 
 @tool(title="Update a project's settings",
       annotations=_acts(destructive=True, idempotent=True, open_world=False),
-      description="Change an existing project's name, schedule or settings. Only what you pass changes: in "
-                  "`config` only the keys given are replaced, the rest stay; a replaced value is not kept. Call "
-                  "get_project first to see the current values, and describe_project_config for valid keys; to "
-                  "start a different site use create_project instead. Nothing is fetched and no credits are "
-                  "spent now; the next run uses the new settings, and a settings change that alters how pages "
-                  "are read starts a fresh comparison baseline. Returns the updated project.")
+      description="Change an existing project's name, schedule or settings.\n"
+                  "Call get_project first to see the current values, and describe_project_config for valid keys. To "
+                  "watch a different site use create_project instead.\n"
+                  "Inputs: only what you pass changes. In `config` only the keys given are replaced and the rest "
+                  "stay. A replaced value is gone, not versioned.\n"
+                  "Behaviour: nothing is fetched and no credits are spent now. The next run uses the new settings. "
+                  "A change that alters how pages are read starts a fresh comparison baseline.\n"
+                  "Returns: the updated project, in get_project's shape.\n"
+                  "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
+                  "{error, status}.")
 def update_project(project_id: ProjectId,
                    name: Annotated[str | None, Field(description="A new name; omit to leave it.")] = None,
                    schedule: Annotated[Schedule | None, Field(
@@ -907,16 +961,19 @@ def update_project(project_id: ProjectId,
 
 @tool(title="Start a project run now",
       annotations=_acts(),
-      description="Crawl a project's site now with its saved settings, outside its schedule; the run is then "
-                  "compared with the last one. Use it after create_project or update_project, or when fresh "
-                  "results are wanted; to re-read only a few pages use recrawl_pages, and for a site with no "
-                  "project use crawl_site. Every page read costs credits (usually 1 to 4) and a run stops when "
-                  "the credit budget runs out, keeping what it read; it is refused with 409 while a run of the "
-                  "project is already queued or running, and 402 when no credits are left. Without wait it "
-                  "returns the queued run at once; with wait it returns the finished run, except hosted, where "
-                  "a run still going after "
-                  "the time budget comes back as a job for get_job. Results are read with list_pages and "
-                  "get_changes.")
+      description="Crawl a project's site now with its saved settings, outside its schedule. The run is then "
+                  "compared with the last one.\n"
+                  "Use it after create_project or update_project, or when fresh results are wanted. To re-read only "
+                  "a few pages use recrawl_pages. For a site with no project use crawl_site.\n"
+                  "Cost: every page read costs credits (usually 1 to 4). A run stops when the credit budget runs "
+                  "out and keeps what it read.\n"
+                  "Refusals: 409 while a run of the project is already queued or running (cancel_job stops it), and "
+                  "402 when no credits are left.\n"
+                  "Returns: without wait, the queued run at once. With wait, the finished run, except hosted, where "
+                  "a run still going after the time budget comes back as a job for get_job. Read the results with "
+                  "list_pages and get_changes.\n"
+                  "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
+                  "{error, status}.")
 def start_run(project_id: ProjectId,
               wait: Annotated[bool, Field(
                   description="true waits for the run to finish (minutes for a large site); false (default) "
@@ -934,14 +991,49 @@ def start_run(project_id: ProjectId,
     return _safe(go)
 
 
+# A run as list_runs shows it: what an assistant needs to pick one, without
+# the config, link graph and engine profile a run record also carries.
+RUN_FIELDS = ("id", "status", "trigger", "scope", "pagesN", "changedN", "counts", "coverage", "stop",
+              "startedAt", "elapsed", "baseline", "rebaselined")
+
+
+@tool(title="List a project's runs",
+      annotations=READS_STORED,
+      description="List a project's runs, newest first, with each run's id, status, trigger, pages read, pages "
+                  "changed, coverage, stop reason and start time.\n"
+                  "Use it to find a run_id for list_pages, get_page, get_changes or search_pages, to see whether a "
+                  "run is still going before start_run, or to pick the run to stop with cancel_job. get_project "
+                  "shows only the last run.\n"
+                  "Inputs: `limit` caps how many come back (1 to 100, default 25). Older runs are not paged here.\n"
+                  "Returns: {runs: [{id, status, trigger, scope, pagesN, changedN, counts, coverage, stop, "
+                  "startedAt, elapsed, baseline, rebaselined}]}. trigger is manual, scheduled, api or recrawl; "
+                  "scope is how many URLs a recrawl_pages run listed (0 for a full run); changedN is null before a "
+                  "run has a change record.\n"
+                  "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
+                  "{error, status}.")
+def list_runs(project_id: ProjectId,
+              limit: Annotated[int, Field(
+                  description="How many runs to return, newest first: 1 to 100 (default 25).")] = 25) -> dict:
+    """The runs of one project, so a run id can be found without guessing:
+    the tools that read a run take one, and get_project shows only the last."""
+    def go():
+        rows = _client().runs.list(project_id, limit=max(1, min(limit, 100)))
+        return {"runs": [{k: r.get(k) for k in RUN_FIELDS} for r in rows]}
+    return _safe(go)
+
+
 @tool(title="List a run's pages",
       annotations=READS_STORED,
-      description="List the pages one project run stored -- the last finished run unless run_id is given -- "
-                  "with each page's url, status, depth, word count and when it last changed, up to 500 rows, "
-                  "plus the runId. Use it to see what a crawl covered or to pick a URL; get_page reads one of "
-                  "them in full, search_pages finds pages by their text, and get_changes lists only what "
-                  "changed. Free and reads only what is stored: it never fetches the site. A project with no "
-                  "finished run answers with no pages.")
+      description="List the pages one project run stored, with each page's url, status, depth, word count and when "
+                  "it last changed, plus the run's link-graph summary and its runId.\n"
+                  "Use it to see what a crawl covered or to pick a URL. get_page reads one page in full, "
+                  "search_pages finds pages by their text, and get_changes lists only what changed.\n"
+                  "Inputs: `run_id` is a run's id, not a number or a date. Leave it empty for the latest finished "
+                  "run; a project with no finished run answers with no pages.\n"
+                  "Returns: up to 500 rows, shallowest pages first. A larger run is cut at 500, so use search_pages "
+                  "to find pages beyond that.\n"
+                  "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
+                  "{error, status}.")
 def list_pages(project_id: ProjectId, run_id: RunId = None) -> dict:
     def go():
         r = _client().pages(project_id, run_id)
@@ -953,31 +1045,40 @@ def list_pages(project_id: ProjectId, run_id: RunId = None) -> dict:
 @tool(title="Get one stored page",
       annotations=READS_STORED,
       description="Read one page a project run stored, in full: its markdown and other bodies (each capped at "
-                  "12,000 characters), head fields (title, description, canonical, h1), extracted fields, and "
-                  "its versions across runs. Use it when you know the page's URL; list_pages or search_pages "
-                  "finds the URL first, and for a page from a crawl_site crawl use get_job with url instead. "
-                  "Free and reads only what is stored, so it never fetches the site -- use extract_url for a "
-                  "live copy. A URL the run did not store answers 404.")
+                  "12,000 characters), head fields (title, description, canonical, h1), extracted fields, and its "
+                  "versions across runs.\n"
+                  "Use it when you know the page's URL; list_pages or search_pages finds it first. For a page from "
+                  "a crawl_site crawl use get_job with url instead. For a live copy use extract_url.\n"
+                  "Inputs: `url` is an address, not a search term. The scheme and a trailing slash may differ, but "
+                  "the rest of the URL, query string included, must match exactly. `run_id` pins that run's copy; "
+                  "without it, the newest copy across the project's last 50 runs.\n"
+                  "A URL the run did not store answers 404.\n"
+                  "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
+                  "{error, status}.")
 def get_page(project_id: ProjectId,
              url: Annotated[str, Field(
                  description="The page's full URL as list_pages or search_pages shows it; the other scheme or "
                              "trailing slash is matched too.")],
              run_id: Annotated[str | None, Field(
-                 description="A run's id, from start_run or a list_pages answer, to read that run's copy; leave "
+                 description="A run's id, from list_runs or start_run, to read that run's copy; leave "
                              "empty for the newest copy across the project's recent runs.")] = None) -> dict:
     return _safe(lambda: _trim_page(_client().page(project_id, url, run_id)))
 
 
 @tool(title="Get what changed in a run",
       annotations=READS_STORED,
-      description="Report what changed in a project run against the run before it -- the last finished run "
-                  "unless run_id is given: pages added, modified and removed, head-field changes (title, "
-                  "description, canonical...), and the run's coverage, with up to 200 entries per list plus the "
-                  "runs a record exists for. Use it to answer 'what changed on the site'; list_pages shows every "
-                  "page whatever changed, and get_page shows one page's text and versions. Removals are withheld "
-                  "when the crawl reached under 90% of the site, so a blocked crawl never reports the site as "
-                  "gone. A project's first run is a baseline with nothing to compare. Free and reads only what "
-                  "is stored.")
+      description="Report what changed in a project run against the run before it: pages added, modified and "
+                  "removed, head-field changes (title, description, canonical), and the run's coverage.\n"
+                  "Use it to answer 'what changed on the site'. list_pages shows every page whatever changed, and "
+                  "get_page shows one page's text and versions.\n"
+                  "Inputs: `run_id` picks the run whose record to read, and that run is always compared with the "
+                  "run just before it. Leave it empty for the latest finished run. A run still going answers 409.\n"
+                  "Behaviour: removals are withheld when the crawl reached under 90% of the site, so a blocked "
+                  "crawl never reports the site as gone. A project's first run is a baseline with nothing to "
+                  "compare.\n"
+                  "Returns: up to 200 entries per list, plus the runs a record exists for.\n"
+                  "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
+                  "{error, status}.")
 def get_changes(project_id: ProjectId, run_id: RunId = None) -> dict:
     def go():
         r = _client().changes(project_id, run_id)
@@ -991,12 +1092,18 @@ def get_changes(project_id: ProjectId, run_id: RunId = None) -> dict:
 
 @tool(title="Search a run's stored pages",
       annotations=READS_STORED,
-      description="Find which pages of a project run contain some text or an element -- the last finished run "
-                  "unless run_id is given -- returning the matching URLs with how many pages were scanned. Use "
-                  "it to locate pages by what they say or contain; list_pages lists every page and get_page "
-                  "then reads one in full. It scans the stored copies and never fetches the site, so it is free "
-                  "and as fresh as the run. A selector search needs the run to have kept html (the rawHtml "
-                  "format); when none was kept the answer says so rather than reporting no matches.")
+      description="Find which pages of a project run contain some text or an element, and return the matching URLs "
+                  "with how many pages were scanned.\n"
+                  "Use it to locate pages by what they say or contain. list_pages lists every page, and get_page "
+                  "then reads one in full. It cannot search a crawl_site crawl or the live site: use get_job or "
+                  "extract_url for those.\n"
+                  "Inputs: a selector search needs the run to have kept html (the rawHtml format). When none was "
+                  "kept, the answer says so rather than reporting no matches. Leave run_id empty for the latest "
+                  "finished run.\n"
+                  "Returns: up to 500 hits, each {url, count, snippet}, with `scanned`, `noBody` and `truncated` "
+                  "(true when more pages matched). It is as fresh as the run.\n"
+                  "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
+                  "{error, status}.")
 def search_pages(project_id: ProjectId,
                  q: Annotated[str, Field(
                      description="What to look for, 1 to 200 characters. In content mode every word must "
@@ -1011,29 +1118,43 @@ def search_pages(project_id: ProjectId,
 
 @tool(title="Re-crawl chosen pages",
       annotations=_acts(),
-      description="Fetch specific pages of a project again now, as a small run of their own whose record "
-                  "compares just those pages with the last full run. Use it to check a few pages you expect "
-                  "changed without crawling the whole site; start_run re-crawls everything, and extract_url "
-                  "reads a page outside any project. Each page costs credits (usually 1 to 4). The URLs must be "
-                  "on the project's site; refused with 409 while another run of the project is queued or "
-                  "running. Returns the queued run; follow it with get_job (kind 'run') and read results with "
-                  "get_changes.")
+      description="Fetch specific pages of a project again now, as a small run of their own whose record compares "
+                  "just those pages with the last full run.\n"
+                  "Use it to check a few pages you expect changed without crawling the whole site. start_run "
+                  "re-crawls everything, and extract_url reads a page outside any project.\n"
+                  "Inputs: a path such as '/pricing' is resolved against the project's site. A URL on another site "
+                  "is refused with 400 naming it, before anything runs.\n"
+                  "Cost: each page costs credits (usually 1 to 4). A page that fails is recorded in the run with "
+                  "its status, not dropped.\n"
+                  "Refusals: 409 while another run of the project is queued or running; cancel_job stops it.\n"
+                  "Returns: the queued run. Follow it with get_job (kind 'run') and read the results with "
+                  "get_changes.\n"
+                  "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
+                  "{error, status}.")
 def recrawl_pages(project_id: ProjectId,
                   urls: Annotated[list[str], Field(
-                      description="1 to 500 full URLs on the project's site to fetch again.")]) -> dict:
+                      description="1 to 500 pages on the project's site to fetch again: full URLs, or paths "
+                                  "such as '/pricing'.")]) -> dict:
     return _safe(lambda: _client().recrawl(project_id, urls))
 
 
 @tool(title="Follow a long-running job",
       annotations=READS_STORED,
-      description="Check on a job a long tool handed back -- a crawl from crawl_site, a run from start_run or "
-                  "recrawl_pages, or a batch from scrape_urls -- and, once it has finished, return the same "
-                  "result the original tool would have given; while it is still going, its status and counts. "
-                  "Call it when a tool answered with status 'running' and a job; calling the original tool "
-                  "again is not needed and would not start a second job. For a crawl it is also how to read "
-                  "further: `url` returns one page in full (even mid-crawl) and `cursor` the next window of "
-                  "pages. For a project's stored pages use get_page instead. Free: it only reads stored "
-                  "results and never fetches.")
+      description="Check on a job a long tool handed back (a crawl from crawl_site, a run from start_run or "
+                  "recrawl_pages, or a batch from scrape_urls) and return its result once it has finished.\n"
+                  "Call it when a tool answered with status 'running' and a job. Calling the original tool again is "
+                  "not needed and would not start a second job. For a project's stored pages use get_page instead. "
+                  "To stop a job use cancel_job.\n"
+                  "Inputs: for a crawl, `url` returns one page in full (even mid-crawl) and `cursor` the next "
+                  "window of pages.\n"
+                  "Returns: while it runs, {status: 'running', job, counts}. Once finished, a crawl gives "
+                  "crawl_site's answer (crawl_id, status, pages, index, counts, stop, note, and cursor when there "
+                  "is more), a batch gives scrape_urls' answer, and a run gives the run record (id, status, "
+                  "counts).\n"
+                  "Behaviour: a crawl expires a day after it started unless it was kept, and then the call answers "
+                  "404.\n"
+                  "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
+                  "{error, status}.")
 def get_job(kind: Annotated[Literal["crawl", "run", "batch"], Field(
                 description="What the job is: 'crawl' (crawl_site), 'run' (start_run, recrawl_pages) or "
                             "'batch' (scrape_urls); the 'job' object a tool returned names it.")],
@@ -1093,7 +1214,78 @@ def get_job(kind: Annotated[Literal["crawl", "run", "batch"], Field(
     return _safe(go)
 
 
-# Stdio's server, built now that the seventeen are declared. Hosted mode
+# What a stop means, said once for every kind of job.
+CANCEL_NOTE = ("queued work is dropped at once; a page being read finishes first, then the job "
+               "stops. Pages already read stay readable, and nothing is deleted.")
+
+
+@tool(title="Cancel a running job",
+      annotations=_acts(destructive=True, idempotent=True, open_world=False),
+      description="Stop a crawl, run or batch that is still going: a crawl started too wide, a run that blocks the "
+                  "next one, or a batch of the wrong URLs.\n"
+                  "Use it when the work should not finish. To check on a job without stopping it use get_job. "
+                  "start_run and recrawl_pages answer 409 while a run is going, so stop that run here first.\n"
+                  "Inputs: `kind` and `id` come from the 'job' object a long tool returned, or from crawl_site's "
+                  "crawl_id. A run also needs its project_id; list_runs shows which of a project's runs is still "
+                  "going.\n"
+                  "Behaviour: queued work is dropped at once, and a page being read finishes first. Pages already "
+                  "read stay readable and nothing is deleted. It cannot be undone: run the work again to resume. A "
+                  "job that already finished is left as it is.\n"
+                  "Returns: {kind, id, outcome, note}. outcome is 'cancelled' (it never started), 'cancelling' (it "
+                  "stops after the page in hand), or the status of a job that had already ended.\n"
+                  "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
+                  "{error, status}.")
+def cancel_job(kind: Annotated[Literal["crawl", "run", "batch"], Field(
+                   description="What the job is: 'crawl' (crawl_site), 'run' (start_run, recrawl_pages) or "
+                               "'batch' (scrape_urls); the 'job' object a tool returned names it.")],
+               id: Annotated[str, Field(
+                   description="The job's id, from that 'job' object, or a crawl_site answer's crawl_id.")],
+               project_id: Annotated[str | None, Field(
+                   description="Required for a run: the project it belongs to (the 'job' object carries "
+                               "it). Ignored for a crawl or a batch.")] = None) -> dict:
+    """The way out of a job that should not finish: a crawl started too wide, a
+    run that blocks the next one (start_run and recrawl_pages answer 409 while
+    one is going), a batch of the wrong URLs. Every kind stops the same way,
+    through the API's own cancel; a job already finished is left as it is and
+    reported with its status (a crawl or batch is checked first and nothing is
+    sent; a run's cancel goes to the API, which changes nothing on a finished
+    run), so asking twice is harmless."""
+    def go():
+        s = _client()
+        if kind == "run":
+            if not project_id:
+                return {"error": "a run needs its project_id", "code": "validation"}
+            r = s.runs.cancel(project_id, id) or {}
+            # The API says what it did: cancelled (it never started), cancelling
+            # (it stops after the page in hand), or the status of a run that had
+            # already ended.
+            return {"kind": "run", "id": id, "project_id": project_id,
+                    "outcome": r.get("outcome") or "no job", "note": CANCEL_NOTE}
+        if kind == "crawl":
+            job = s.get_crawl(id)
+            status = job.envelope.get("status")
+            if not _running(status):
+                return {"kind": "crawl", "id": id, "outcome": status,
+                        "note": "the crawl had already finished; nothing to stop"}
+            job.cancel()
+            return {"kind": "crawl", "id": id,
+                    "outcome": "cancelled" if status == "queued" else "cancelling", "note": CANCEL_NOTE}
+        if kind == "batch":
+            # Only the status is wanted: a format the API does not keep a body
+            # for returns the rows without markdown, where the default would
+            # carry every page of a finished 500-url batch just to read one word.
+            status = s.batch(id, formats="none").get("status")
+            if not _running(status):
+                return {"kind": "batch", "id": id, "outcome": status,
+                        "note": "the batch had already finished; nothing to stop"}
+            s.cancel_batch(id)
+            return {"kind": "batch", "id": id,
+                    "outcome": "cancelled" if status == "queued" else "cancelling", "note": CANCEL_NOTE}
+        return {"error": f"kind must be crawl, run or batch, not {kind!r}", "code": "validation"}
+    return _safe(go)
+
+
+# Stdio's server, built now that the nineteen are declared. Hosted mode
 # builds its own in `authorize`, because auth is set in the constructor.
 server = _build()
 
@@ -1220,7 +1412,7 @@ def _transport_security(public_url):
 
 
 def authorize(issuer, public, secret):
-    """The hosted server: the same seventeen tools, with OAuth attached.
+    """The hosted server: the same nineteen tools, with OAuth attached.
 
     A server of its own rather than the stdio one with auth bolted on after
     the fact. `token_verifier` and `auth` are constructor arguments, and

{mesharc-0.3.2 → mesharc-0.3.4/mesharc.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mesharc
-Version: 0.3.2
+Version: 0.3.4
 Summary: Python client for the MeshArc API: a URL in, clean content out, and a record of what changed.
 License-Expression: MIT
 Project-URL: Homepage, https://mesharc.dev
@@ -279,13 +279,13 @@ MESHARC_API_KEY=mesharc_... mesharc-mcp          # serves over stdio
 claude mcp add mesharc -e MESHARC_API_KEY=mesharc_... -- mesharc-mcp
 ```
 
-Tools: `scrape_urls`, `extract_url`, `map_site`, `crawl_site`, `keep_crawl_as_project`, `list_projects`, `describe_project_config`, `get_project`, `create_project`, `update_project`, `start_run`, `list_pages`, `get_page`, `get_changes`, `search_pages`, `recrawl_pages`, `get_job`. Every tool is a call through this client.
+Tools: `scrape_urls`, `extract_url`, `map_site`, `crawl_site`, `keep_crawl_as_project`, `list_projects`, `describe_project_config`, `get_project`, `create_project`, `update_project`, `start_run`, `list_runs`, `list_pages`, `get_page`, `get_changes`, `search_pages`, `recrawl_pages`, `get_job`, `cancel_job`. Every tool is a call through this client.
 
 A result with many pages in it is a map, not the territory: a crawl answers with an index of the pages read (up to 500, fewer if the budget needs the room), an excerpt of as many as a 60,000-character budget pays for (fifty at most), and a count of each page's links rather than the links. Ask for the one page you want on its own with `get_job(kind="crawl", id=…, url=…)`, or carry on through the crawl with `cursor=`. A multi-URL scrape past its budget counts the rest by status and names any that did not come back ok. One page asked for on its own -- `extract_url`, `get_page`, `scrape_urls` with a single url -- comes back whole, capped at 12,000 characters.
 
-Hosted, a connection can be approved read-only, and read-only cuts in a place worth knowing: it reads the whole workspace, but it cannot reach the site. Anything that fetches is a write, because it leaves the workspace and usually spends its credits -- `map_site` is the one that fetches and costs nothing, and it is gated with the rest. `list_projects`, `get_project`, `describe_project_config`, `list_pages`, `get_page`, `get_changes`, `search_pages` and `get_job` work; the nine that fetch or write -- `scrape_urls`, `extract_url`, `map_site`, `crawl_site`, `keep_crawl_as_project`, `create_project`, `update_project`, `start_run`, `recrawl_pages` -- answer `{"code": "read_only"}` with what to do about it, until the app is reconnected with write access.
+Hosted, a connection can be approved read-only, and read-only cuts in a place worth knowing: it reads the whole workspace, but it cannot reach the site. Anything that fetches is a write, because it leaves the workspace and usually spends its credits -- `map_site` is the one that fetches and costs nothing, and it is gated with the rest. `list_projects`, `get_project`, `describe_project_config`, `list_runs`, `list_pages`, `get_page`, `get_changes`, `search_pages` and `get_job` work; the ten that fetch or write -- `scrape_urls`, `extract_url`, `map_site`, `crawl_site`, `keep_crawl_as_project`, `create_project`, `update_project`, `start_run`, `recrawl_pages`, `cancel_job` -- answer `{"code": "read_only"}` with what to do about it, until the app is reconnected with write access.
 
-Hosted, a tool that would hold a connection open for minutes — a crawl, a run you asked to wait for, a multi-URL scrape — hands back a job after `MESHARC_MCP_WAIT` seconds (25 by default, because many MCP hosts time a tool call out sooner). The work carries on server-side and `get_job` picks it up. Run locally, those tools block as they always have.
+Hosted, a tool that would hold a connection open for minutes — a crawl, a run you asked to wait for, a multi-URL scrape — hands back a job after `MESHARC_MCP_WAIT` seconds (25 by default, because many MCP hosts time a tool call out sooner). The work carries on server-side; `get_job` picks it up and `cancel_job` stops it. Run locally, those tools block as they always have.
 
 ### Hosting it yourself
 

{mesharc-0.3.2 → mesharc-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mesharc"
-version = "0.3.2"
+version = "0.3.4"
 description = "Python client for the MeshArc API: a URL in, clean content out, and a record of what changed."
 readme = "README.md"
 requires-python = ">=3.10"

{mesharc-0.3.2 → mesharc-0.3.4}/tests/test_behaviour.py

@@ -128,6 +128,6 @@ def test_pace_waits_out_the_window_only_when_nearly_out(monkeypatch):
 def test_the_mcp_server_offers_the_verbs_and_the_config_tools():
     source = (pathlib.Path(mesharc.__file__).parent / "mcp.py").read_text(encoding="utf-8")
     for name in ("scrape_urls", "extract_url", "map_site", "crawl_site", "keep_crawl_as_project",
-                 "list_projects", "get_changes", "search_pages", "recrawl_pages", "get_job",
+                 "list_projects", "get_changes", "search_pages", "recrawl_pages", "get_job", "cancel_job", "list_runs",
                  "describe_project_config", "get_project", "create_project", "update_project"):
         assert f"def {name}(" in source, name

{mesharc-0.3.2 → mesharc-0.3.4}/tests/test_client.py

@@ -120,3 +120,9 @@ def test_export_streams_to_a_file(tmp_path):
 def test_a_204_returns_none():
     arc = scripted((204, None))
     assert arc.revoke_key("k1") is None
+
+
+def test_cancel_batch_deletes_the_scrape():
+    arc = scripted((204, None))
+    assert arc.cancel_batch("b1") is None
+    assert (arc.calls[0].method, arc.calls[0].url.path) == ("DELETE", "/api/v1/scrape/b1")

mesharc-0.3.4/tests/test_definitions.py

@@ -0,0 +1,192 @@
+"""What an assistant reads before it calls a tool.
+
+A tool is chosen and filled in from its definition alone: the description, the
+parameters' descriptions and the hints on what it does to the world. Every
+parameter went undescribed until 0.3.2, and directories that grade
+definitions marked the whole server down for it. These keep it from
+drifting back.
+"""
+import asyncio
+
+import pytest
+
+mcp_mod = pytest.importorskip("mesharc.mcp", reason="needs the mcp extra")
+
+# The tools that only read what the workspace has stored. Everything else
+# reaches a site or changes the workspace, and a read-only connection is
+# refused it -- the same nine the read_only answer is about.
+READ_ONLY = {"list_projects", "describe_project_config", "get_project", "list_runs", "list_pages",
+             "get_page", "get_changes", "search_pages", "get_job"}
+
+
+def _tools():
+    return {t.name: t for t in asyncio.run(mcp_mod.server.list_tools())}
+
+
+def test_all_nineteen_are_listed():
+    assert len(_tools()) == 19
+
+
+def test_every_parameter_is_described():
+    for name, t in _tools().items():
+        for param, schema in (t.input_schema.get("properties") or {}).items():
+            assert (schema.get("description") or "").strip(), f"{name}.{param} has no description"
+
+
+def test_every_tool_has_a_title_and_a_description():
+    for name, t in _tools().items():
+        assert t.title and t.title != name and len(t.title) > len(name), name
+        assert len((t.description or "").split()) >= 20, name
+
+
+def test_the_hints_say_which_tools_only_read():
+    for name, t in _tools().items():
+        a = t.annotations
+        assert a is not None, name
+        assert a.read_only_hint is (name in READ_ONLY), name
+        if name in READ_ONLY:
+            assert a.destructive_hint is False and a.open_world_hint is False, name
+
+
+def test_only_the_tools_that_overwrite_or_stop_are_destructive():
+    # update_project replaces values; cancel_job stops work that cannot be
+    # resumed where it was. Nothing else changes what is already there.
+    destructive = {n for n, t in _tools().items() if t.annotations.destructive_hint}
+    assert destructive == {"update_project", "cancel_job"}
+
+
+def test_fixed_choices_are_listed():
+    tools = _tools()
+
+    def enum(tool, param):
+        schema = tools[tool].input_schema["properties"][param]
+        options = [schema] + list(schema.get("anyOf") or [])
+        return next(o["enum"] for o in options if "enum" in o)
+
+    assert enum("get_job", "kind") == ["crawl", "run", "batch"]
+    assert enum("cancel_job", "kind") == ["crawl", "run", "batch"]
+    assert enum("search_pages", "mode") == ["content", "selector"]
+    for tool in ("create_project", "keep_crawl_as_project", "update_project"):
+        assert enum(tool, "schedule") == ["manual", "hourly", "daily", "weekly"]
+
+
+def test_each_description_states_the_access_its_hints_declare():
+    # The description and the hints must never disagree: graders mark a
+    # contradiction down to 1, and an assistant told a tool only reads would
+    # call it on a read-only connection and be refused.
+    for name, t in _tools().items():
+        says_read_only = "Works on a read-only connection" in t.description
+        says_write = "Needs write access" in t.description
+        assert says_read_only == (name in READ_ONLY), name
+        assert says_write == (name not in READ_ONLY), name
+
+
+def test_list_projects_passes_on_each_projects_status(monkeypatch):
+    # It asked the API for `health`, which no project has ever carried, so
+    # every row said health: null. The project's state is `status`.
+    class _Projects:
+        @staticmethod
+        def list():
+            return [{"id": "p1", "name": "Docs", "status": "failing", "webhookSecret": "whsec_x"}]
+
+    class _Client:
+        projects = _Projects()
+
+    monkeypatch.setattr(mcp_mod, "_client", lambda: _Client())
+    rows = mcp_mod.list_projects()
+    assert rows[0]["status"] == "failing" and "health" not in rows[0]
+    assert "webhookSecret" not in rows[0]
+
+
+class _Crawl:
+    def __init__(self, status):
+        self.envelope = {"status": status}
+        self.cancelled = False
+
+    def cancel(self):
+        self.cancelled = True
+
+
+class _Cancels:
+    """A client that records what cancel_job asked it to stop."""
+
+    def __init__(self, crawl_status="running", batch_status="running", run_outcome="cancelling"):
+        self.crawl = _Crawl(crawl_status)
+        self._batch_status = batch_status
+        self.stopped_batches = []
+        outcome = run_outcome
+
+        class _Runs:
+            asked = []
+
+            def cancel(self, project_id, run_id):
+                self.asked.append((project_id, run_id))
+                return {"id": run_id, "outcome": outcome}
+
+        self.runs = _Runs()
+
+    def get_crawl(self, crawl_id):
+        return self.crawl
+
+    def batch(self, batch_id, formats="markdown"):
+        self.batch_formats = formats
+        return {"id": batch_id, "status": self._batch_status}
+
+    def cancel_batch(self, batch_id):
+        self.stopped_batches.append(batch_id)
+
+
+def test_cancel_job_stops_a_running_crawl_and_says_how(monkeypatch):
+    c = _Cancels(crawl_status="running")
+    monkeypatch.setattr(mcp_mod, "_client", lambda: c)
+    out = mcp_mod.cancel_job("crawl", "c1")
+    assert c.crawl.cancelled and out["outcome"] == "cancelling" and "nothing is deleted" in out["note"]
+
+
+def test_cancel_job_leaves_a_finished_crawl_alone(monkeypatch):
+    c = _Cancels(crawl_status="done")
+    monkeypatch.setattr(mcp_mod, "_client", lambda: c)
+    out = mcp_mod.cancel_job("crawl", "c1")
+    assert not c.crawl.cancelled and out["outcome"] == "done"
+
+
+def test_cancel_job_stops_a_queued_batch_outright(monkeypatch):
+    c = _Cancels(batch_status="queued")
+    monkeypatch.setattr(mcp_mod, "_client", lambda: c)
+    out = mcp_mod.cancel_job("batch", "b1")
+    assert c.stopped_batches == ["b1"] and out["outcome"] == "cancelled"
+    # The status is read without the pages' bodies.
+    assert c.batch_formats == "none"
+
+
+def test_cancel_job_passes_on_the_runs_outcome(monkeypatch):
+    c = _Cancels(run_outcome="done")
+    monkeypatch.setattr(mcp_mod, "_client", lambda: c)
+    out = mcp_mod.cancel_job("run", "r1", project_id="p1")
+    assert c.runs.asked[-1] == ("p1", "r1") and out["outcome"] == "done"
+
+
+def test_cancel_job_needs_a_runs_project(monkeypatch):
+    c = _Cancels()
+    monkeypatch.setattr(mcp_mod, "_client", lambda: c)
+    assert mcp_mod.cancel_job("run", "r1")["code"] == "validation"
+
+
+def test_list_runs_keeps_what_picks_a_run_and_drops_the_bulk(monkeypatch):
+    asked = []
+
+    class _Runs:
+        def list(self, project_id, limit=25):
+            asked.append((project_id, limit))
+            return [{"id": "r2", "status": "running", "trigger": "manual", "counts": {"ok": 3},
+                     "linkGraph": {"orphans": 9}, "cfg": "v2", "engine": "http"}]
+
+    class _Client:
+        runs = _Runs()
+
+    monkeypatch.setattr(mcp_mod, "_client", lambda: _Client())
+    out = mcp_mod.list_runs("p1", limit=500)
+    assert asked == [("p1", 100)]
+    row = out["runs"][0]
+    assert row["id"] == "r2" and row["status"] == "running" and row["counts"] == {"ok": 3}
+    assert "linkGraph" not in row and "cfg" not in row and "engine" not in row

{mesharc-0.3.2 → mesharc-0.3.4}/tests/test_mcp_http.py

@@ -237,14 +237,14 @@ def test_an_unreachable_issuer_stops_the_server(monkeypatch):
 
 
 def test_get_job_is_offered_alongside_the_rest():
-    """Seventeen declared, and seventeen on the server that was built from
+    """Nineteen declared, and nineteen on the server that was built from
     them. Counting `@server.tool` in the source said nothing about what the
     server ended up carrying."""
     import anyio
 
-    assert len(mcp_mod._TOOLS) == 17, "sixteen verbs plus get_job"
+    assert len(mcp_mod._TOOLS) == 19, "sixteen verbs plus get_job, cancel_job and list_runs"
     served = [t.name for t in anyio.run(mcp_mod.server.list_tools)]
-    assert len(served) == 17
+    assert len(served) == 19
     assert "get_job" in served
     assert callable(mcp_mod.get_job)
 
@@ -426,7 +426,7 @@ def test_the_server_answers_a_real_call_as_the_caller_who_sent_it(served):
     r, listed = _rpc(served, "tools/list", session=sid)
     assert r.status_code == 200, r.text
     names = [t["name"] for t in listed["result"]["tools"]]
-    assert len(names) == 17, names
+    assert len(names) == 19, names
     assert "get_job" in names
 
     r, out = _rpc(served, "tools/call", {"name": "list_projects", "arguments": {}}, session=sid)
@@ -450,8 +450,8 @@ def test_auth_is_attached_through_the_constructor(served):
     assert str(mcp_mod.server.settings.auth.resource_server_url).rstrip("/") == RESOURCE.rstrip("/")
     assert mcp_mod.server.settings.auth.validate_token_resource is True
 
-    # Both servers carry the same seventeen tools, declared once.
-    assert len(mcp_mod._TOOLS) == 17
+    # Both servers carry the same nineteen tools, declared once.
+    assert len(mcp_mod._TOOLS) == 19
     names = {fn.__name__ for fn, _how in mcp_mod._TOOLS}
     assert "get_job" in names
     assert all(how.get("description") for _fn, how in mcp_mod._TOOLS),         "a tool with no description is a verb an assistant cannot choose"

mesharc-0.3.2/tests/test_definitions.py

@@ -1,67 +0,0 @@
-"""What an assistant reads before it calls a tool.
-
-A tool is chosen and filled in from its definition alone: the description, the
-parameters' descriptions and the hints on what it does to the world. Every
-parameter went undescribed until 0.3.2, and directories that grade
-definitions marked the whole server down for it. These keep it from
-drifting back.
-"""
-import asyncio
-
-import pytest
-
-mcp_mod = pytest.importorskip("mesharc.mcp", reason="needs the mcp extra")
-
-# The tools that only read what the workspace has stored. Everything else
-# reaches a site or changes the workspace, and a read-only connection is
-# refused it -- the same nine the read_only answer is about.
-READ_ONLY = {"list_projects", "describe_project_config", "get_project", "list_pages",
-             "get_page", "get_changes", "search_pages", "get_job"}
-
-
-def _tools():
-    return {t.name: t for t in asyncio.run(mcp_mod.server.list_tools())}
-
-
-def test_all_seventeen_are_listed():
-    assert len(_tools()) == 17
-
-
-def test_every_parameter_is_described():
-    for name, t in _tools().items():
-        for param, schema in (t.input_schema.get("properties") or {}).items():
-            assert (schema.get("description") or "").strip(), f"{name}.{param} has no description"
-
-
-def test_every_tool_has_a_title_and_a_description():
-    for name, t in _tools().items():
-        assert t.title and t.title != name and len(t.title) > len(name), name
-        assert len((t.description or "").split()) >= 20, name
-
-
-def test_the_hints_say_which_tools_only_read():
-    for name, t in _tools().items():
-        a = t.annotations
-        assert a is not None, name
-        assert a.read_only_hint is (name in READ_ONLY), name
-        if name in READ_ONLY:
-            assert a.destructive_hint is False and a.open_world_hint is False, name
-
-
-def test_only_update_project_overwrites():
-    destructive = {n for n, t in _tools().items() if t.annotations.destructive_hint}
-    assert destructive == {"update_project"}
-
-
-def test_fixed_choices_are_listed():
-    tools = _tools()
-
-    def enum(tool, param):
-        schema = tools[tool].input_schema["properties"][param]
-        options = [schema] + list(schema.get("anyOf") or [])
-        return next(o["enum"] for o in options if "enum" in o)
-
-    assert enum("get_job", "kind") == ["crawl", "run", "batch"]
-    assert enum("search_pages", "mode") == ["content", "selector"]
-    for tool in ("create_project", "keep_crawl_as_project", "update_project"):
-        assert enum(tool, "schedule") == ["manual", "hourly", "daily", "weekly"]