mesharc 0.3.2__tar.gz → 0.3.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -6,6 +6,20 @@ All notable changes to this package are recorded here. The format follows
6
6
 
7
7
  ## Unreleased
8
8
 
9
+ ## 0.3.3 - 2026-10-07
10
+
11
+ ### Changed
12
+
13
+ - **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:
14
+ - **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.
15
+ - **Access:** whether a read-only connection may call it, and that errors come back as `{error, status}`.
16
+ - **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.
17
+ - Apart from the fix below, behaviour is unchanged. Only the text an assistant reads differs.
18
+
19
+ ### Fixed
20
+
21
+ - `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`.
22
+
9
23
  ## 0.3.2 - 2026-10-06
10
24
 
11
25
  ### Changed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: mesharc
3
- Version: 0.3.2
3
+ Version: 0.3.3
4
4
  Summary: Python client for the MeshArc API: a URL in, clean content out, and a record of what changed.
5
5
  License-Expression: MIT
6
6
  Project-URL: Homepage, https://mesharc.dev
@@ -31,7 +31,7 @@ from urllib.parse import parse_qs, urlparse
31
31
 
32
32
  import httpx
33
33
 
34
- __version__ = "0.3.2"
34
+ __version__ = "0.3.3"
35
35
  __all__ = ["MeshArc", "MeshArcError", "MeshArcTimeoutError", "Crawl"]
36
36
 
37
37
  DEFAULT_BASE = "https://api.mesharc.dev"
@@ -591,14 +591,20 @@ def _safe(fn):
591
591
 
592
592
  @tool(title="Scrape a list of URLs",
593
593
  annotations=_acts(idempotent=True),
594
- description="Fetch known URLs (1 to 500) once and return each page's content, markdown by default; no project "
595
- "is created. For one page with every format or browser steps use extract_url; to find pages by "
596
- "following links use crawl_site; to list a site's URLs without fetching them use map_site. "
597
- "Each page costs the credits of the engine that read it (1 plain fetch, 4 browser render), and a "
598
- "page the site refuses is free. A single URL answers in the same request; a list waits for the "
599
- "batch, and a large one comes back as an index with excerpts inside 60,000 characters. Hosted, a "
600
- "batch still going after the time budget comes back as a job for get_job, and repeating the same "
601
- "call returns that job instead of starting another.")
594
+ description="Fetch known URLs (1 to 500) once and return each page's content. No project is created.\n"
595
+ "Use extract_url for one page with browser steps or structured fields, crawl_site to discover "
596
+ "pages by following links, and map_site to list a site's URLs without fetching them.\n"
597
+ "Inputs: `formats` only picks which stored bodies come back (e.g. 'markdown,text'); how a page is "
598
+ "fetched and extracted is `config`. A PDF, Word or spreadsheet URL is read as text unless "
599
+ "parse_documents is false.\n"
600
+ "Cost: the credits of the engine that read each page (1 plain fetch, 4 browser render). A page "
601
+ "the site refuses is free.\n"
602
+ "Returns: one URL answers in the same request. A list waits for the batch, and a large batch is "
603
+ "an index plus excerpts inside 60,000 characters. Hosted, a batch still going after the time "
604
+ "budget comes back as a job for get_job. Repeating the same call returns that job instead of "
605
+ "starting another.\n"
606
+ "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
607
+ "{error, status}.")
602
608
  def scrape_urls(urls: Annotated[list[str], Field(
603
609
  description="The pages to fetch: 1 to 500 absolute http(s) URLs.")],
604
610
  config: FetchConfig = None,
@@ -633,16 +639,21 @@ def scrape_urls(urls: Annotated[list[str], Field(
633
639
 
634
640
  @tool(title="Extract one page in full",
635
641
  annotations=_acts(),
636
- description="Fetch one URL exactly as a project with the given settings would, and return the whole page: "
637
- "the bodies config's formats ask for plus the raw html (each capped at 12,000 characters), head "
638
- "and extracted fields, its images, and which engine read it -- without its link list. Use it "
639
- "for a single page that needs browser steps, structured fields or a settings trial before "
640
- "create_project; for plain content of one or many known URLs use scrape_urls, and get_page "
641
- "reads a page a project already stored without fetching. It climbs the fetch ladder -- plain "
642
- "http first, a browser only when the page needs one or render_js is 'always' -- and costs the "
643
- "credits of the rung that read it (1 to 4 for most pages, +1 when formats ask for a "
644
- "screenshot). Browser `actions` in config (click, type, select, press, wait, scroll; repeat "
645
- "'until_gone' for Load-more buttons; `each` to act on every match) run before the page is read.")
642
+ description="Fetch one URL exactly as a project with the given settings would, and return the whole page: the "
643
+ "bodies config's formats ask for plus the raw html (each capped at 12,000 characters), head and "
644
+ "extracted fields, its images, and which engine read it. The link list is left out.\n"
645
+ "Use it for one page that needs browser steps, structured fields, or a settings trial before "
646
+ "create_project. For plain content of known URLs use scrape_urls. To read a page a project "
647
+ "already stored, without fetching, use get_page.\n"
648
+ "Inputs: browser `actions` in config (click, type, select, press, wait, scroll; repeat "
649
+ "'until_gone' for Load-more buttons; `each` to act on every match) run before the page is read. A "
650
+ "parse_documents key in config wins over the parse_documents argument.\n"
651
+ "Behaviour: it climbs the fetch ladder, plain http first and a browser only when the page needs "
652
+ "one or render_js is 'always'. It costs the credits of the rung that read it (1 to 4 for most "
653
+ "pages, +1 when formats ask for a screenshot). A page the site refuses comes back marked blocked, "
654
+ "at no cost, rather than as an error.\n"
655
+ "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
656
+ "{error, status}.")
646
657
  def extract_url(url: Annotated[str, Field(description="The absolute http(s) URL of the page to read.")],
647
658
  config: FetchConfig = None,
648
659
  parse_documents: ParseDocuments = True) -> dict:
@@ -658,12 +669,18 @@ def extract_url(url: Annotated[str, Field(description="The absolute http(s) URL
658
669
 
659
670
  @tool(title="Map a site's declared URLs",
660
671
  annotations=_acts(),
661
- description="List every URL a site declares in its sitemaps -- found through robots.txt and the well-known "
662
- "paths, each index file walked to its children -- without fetching any of the pages. Use it "
663
- "first, to see how big a site is and what sections it has, before crawl_site or create_project; "
664
- "it cannot read page content (scrape_urls or crawl_site do) and misses pages a site links to but "
665
- "does not declare. Costs 1 credit per sitemap file read, usually 1 in total, never per URL. "
666
- "Returns the discovery method, totals, up to `limit` URLs and the section names.")
672
+ description="List every URL a site declares in its sitemaps (found through robots.txt and the well-known "
673
+ "paths, each index file walked to its children) without fetching any of the pages.\n"
674
+ "Use it first, to see how big a site is and what sections it has, before crawl_site or "
675
+ "create_project. It cannot read page content (scrape_urls or crawl_site do), and it misses pages "
676
+ "a site links to but does not declare.\n"
677
+ "Inputs: `url` can be any page of the site, since discovery starts at the site's root. `search` "
678
+ "is a case-insensitive substring of the full URL, with no wildcards, applied before `limit`. "
679
+ "`totals` still count every declared URL.\n"
680
+ "Cost: 1 credit per sitemap file read (usually 1 in total), never per URL.\n"
681
+ "Returns: the discovery method, totals, up to `limit` URLs and the section names.\n"
682
+ "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
683
+ "{error, status}.")
667
684
  def map_site(url: Annotated[str, Field(description="Any URL on the site, usually its home page.")],
668
685
  search: Annotated[str | None, Field(
669
686
  description="Keep only URLs containing this text, e.g. '/blog/'; omit for all.")] = None,
@@ -681,16 +698,22 @@ def map_site(url: Annotated[str, Field(description="Any URL on the site, usually
681
698
 
682
699
  @tool(title="Crawl a whole site once",
683
700
  annotations=_acts(idempotent=True),
684
- description="Crawl a site once from a start URL -- following its links and reading its sitemap, up to "
685
- "`limit` pages -- and return what it found, without setting up a project. Use it to read a site "
686
- "or section whose page URLs you do not know; for known URLs use scrape_urls, and to watch a site "
687
- "over time use create_project (or keep_crawl_as_project on this crawl afterwards). Each page "
688
- "costs the credits of the engine that read it (usually 1 to 4) and refused pages are free. It "
689
- "waits for the crawl, minutes for a large limit; hosted, a crawl still going after the time "
690
- "budget comes back as a job for get_job, and repeating the call returns the same crawl. The "
691
- "answer is an index of the pages read plus excerpts inside 60,000 characters; get_job with "
692
- "`url` reads one page in full and with `cursor` the next window. The crawl is kept for a day; "
693
- "pass the result's crawl_id to keep_crawl_as_project to keep it for good.")
701
+ description="Crawl a site once from a start URL, following its links and reading its sitemap up to `limit` "
702
+ "pages, and return what it found. No project is set up.\n"
703
+ "Use it to read a site or section whose page URLs you do not know. For known URLs use "
704
+ "scrape_urls. To watch a site over time use create_project, or keep_crawl_as_project on this "
705
+ "crawl afterwards.\n"
706
+ "Inputs: include_paths and exclude_paths match the URL path only, never the host, and pages they "
707
+ "leave out do not count toward `limit`. '/blog/*' takes the blog index and everything under it. "
708
+ "`max_depth` counts link hops from the start URL (0 = that page only).\n"
709
+ "Cost: the credits of the engine that read each page (usually 1 to 4). Refused pages are free.\n"
710
+ "Behaviour: it waits for the crawl, minutes for a large limit. Hosted, a crawl still going after "
711
+ "the time budget comes back as a job for get_job, and repeating the call returns the same crawl.\n"
712
+ "Returns: an index of the pages read plus excerpts inside 60,000 characters. get_job with `url` "
713
+ "reads one page in full, and with `cursor` the next window. The crawl is kept for a day; pass its "
714
+ "crawl_id to keep_crawl_as_project to keep it for good.\n"
715
+ "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
716
+ "{error, status}.")
694
717
  def crawl_site(url: Annotated[str, Field(description="The absolute http(s) URL to start from, e.g. the home page.")],
695
718
  limit: Annotated[int, Field(
696
719
  description="The most pages to read, 1 to 5,000 (default 50); the plan's page cap also applies.")]
@@ -740,12 +763,19 @@ def crawl_site(url: Annotated[str, Field(description="The absolute http(s) URL t
740
763
 
741
764
  @tool(title="Keep a crawl as a project",
742
765
  annotations=_acts(open_world=False),
743
- description="Turn a crawl_site crawl into a project, so the site is watched over time and each later run "
744
- "is compared against this one. Nothing is fetched again and it costs no credits: the crawl's "
745
- "pages become the project's first run. Use it after crawl_site when the site is worth watching; "
746
- "to start a watched site from scratch use create_project. Without it a crawl and its pages "
747
- "expire after a day. It counts toward the plan's project limit (refused with plan_limit when "
748
- "full). Returns the new project, whose id the other project tools take.")
766
+ description="Turn a crawl_site crawl into a project, so the site is watched over time and each later run is "
767
+ "compared with this one.\n"
768
+ "Use it after crawl_site when the site is worth watching. To start a watched site from scratch "
769
+ "use create_project.\n"
770
+ "Inputs: `crawl_id` must be a crawl this workspace started, kept within a day. After that the "
771
+ "crawl and its pages have expired and the call answers 404. A `schedule` other than 'manual' "
772
+ "starts runs on its own, and each run spends credits.\n"
773
+ "Behaviour: nothing is fetched again and it costs no credits; the crawl's pages become the "
774
+ "project's first run. It counts toward the plan's project limit and is refused with plan_limit "
775
+ "when that is full.\n"
776
+ "Returns: the new project, whose id the other project tools take.\n"
777
+ "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
778
+ "{error, status}.")
749
779
  def keep_crawl_as_project(crawl_id: Annotated[str, Field(
750
780
  description="The crawl_id a crawl_site answer (or get_job on a crawl) returned.")],
751
781
  name: Annotated[str | None, Field(
@@ -762,13 +792,17 @@ def keep_crawl_as_project(crawl_id: Annotated[str, Field(
762
792
 
763
793
  @tool(title="List all projects",
764
794
  annotations=READS_STORED,
765
- description="List every project in the workspace -- the sites it watches over time -- with each one's id, "
766
- "name, seed URL, host, schedule, page count, coverage, last run and health. Call it first to "
767
- "find a project_id for the other project tools, or to check whether a site is already watched "
768
- "before create_project; get_project gives one project's full settings. Reads only what is "
769
- "stored: free, and it fetches nothing. A key limited to some projects sees only those.")
795
+ description="List every project in the workspace (the sites it watches over time) with each one's id, name, "
796
+ "seed URL, host, schedule, page count, coverage, last run and status (draft, crawling, healthy or "
797
+ "failing).\n"
798
+ "Call it first to find a project_id for the other project tools, or to check whether a site is "
799
+ "already watched before create_project. get_project gives one project's full settings.\n"
800
+ "Returns: all projects in one answer, oldest first, with no paging. A key limited to some "
801
+ "projects sees only those.\n"
802
+ "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
803
+ "{error, status}.")
770
804
  def list_projects() -> list | dict:
771
- return _safe(lambda: [{k: p.get(k) for k in ("id", "name", "seed", "host", "schedule", "pages", "coverage", "lastRun", "health")}
805
+ return _safe(lambda: [{k: p.get(k) for k in ("id", "name", "seed", "host", "schedule", "pages", "coverage", "lastRun", "status")}
772
806
  for p in _client().projects.list()])
773
807
 
774
808
 
@@ -821,11 +855,16 @@ CONFIG_GUIDE = {
821
855
 
822
856
  @tool(title="Describe project settings",
823
857
  annotations=READS_STORED,
824
- description="List the project settings an assistant can set -- each key with its meaning and its default "
825
- "-- plus the valid schedules and how path globs work. Read it before create_project, "
826
- "update_project or a `config` argument whenever the request names a section, schedule, format, "
827
- "limit or behaviour: keys are exact and guessed names are refused. It describes settings in "
828
- "general; get_project shows the values one project has. Free, and it fetches nothing.")
858
+ description="List the project settings an assistant can set, each with its meaning and default, plus the "
859
+ "valid schedules and how path globs work.\n"
860
+ "Read it before create_project, update_project or any `config` argument whenever the request "
861
+ "names a section, schedule, format, limit or behaviour. Keys are exact, and guessed names are "
862
+ "refused.\n"
863
+ "It describes settings in general. get_project shows the values one project has.\n"
864
+ "Returns: `settings` as [{key, meaning, default}], `other_keys` (accepted but rarely needed), "
865
+ "`schedules`, and a `note` on path globs.\n"
866
+ "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
867
+ "{error, status}.")
829
868
  def describe_project_config() -> dict:
830
869
  def go():
831
870
  with _client() as s:
@@ -841,24 +880,34 @@ def describe_project_config() -> dict:
841
880
 
842
881
  @tool(title="Get one project",
843
882
  annotations=READS_STORED,
844
- description="Read one project in full: its settings (config), schedule, retention, coverage and last run. "
845
- "Read it before update_project, to see the values you are about to change; list_projects is "
846
- "the lighter way to find projects, and list_pages or get_changes read what its runs found. "
847
- "Free, fetches nothing; an unknown or hidden project answers 404. The webhook signing secret "
848
- "is withheld from the answer.")
883
+ description="Read one project in full: its settings (config), schedule, retention, coverage and last run.\n"
884
+ "Read it before update_project, to see the values you are about to change. list_projects is the "
885
+ "lighter way to find projects. list_pages and get_changes read what its runs found.\n"
886
+ "Inputs: `project_id` is the 32-character hex id that list_projects shows, not the project's name "
887
+ "or URL. An unknown id, or a project the key cannot see, answers 404.\n"
888
+ "Returns: the project's id, name, seed, host, schedule, config, retention, pages, coverage, "
889
+ "status, lastRun, nextRunAt and changeSummary. The webhook signing secret is withheld.\n"
890
+ "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
891
+ "{error, status}.")
849
892
  def get_project(project_id: ProjectId) -> dict:
850
893
  return _safe(lambda: _client().projects.get(project_id))
851
894
 
852
895
 
853
896
  @tool(title="Create a watched project",
854
897
  annotations=_acts(),
855
- description="Create a project that watches a site over time: it is crawled on its schedule and each run is "
856
- "compared with the last, recording pages added, modified and removed. Use it when the request "
857
- "is to monitor or track a site; for a one-off read use crawl_site (keep_crawl_as_project can "
858
- "turn that into a project later), and check list_projects first so the site is not added "
859
- "twice. Creating it reads the site's robots.txt and sitemaps but fetches no pages; every run "
860
- "then spends credits per page. Refused when the plan's project limit is reached. Returns the "
861
- "project, whose id start_run takes to crawl it now.")
898
+ description="Create a project that watches a site over time. It is crawled on its schedule and each run is "
899
+ "compared with the last, recording pages added, modified and removed.\n"
900
+ "Use it when the request is to monitor or track a site. For a one-off read use crawl_site (and "
901
+ "keep_crawl_as_project later if it is worth keeping). Check list_projects first so the site is "
902
+ "not added twice.\n"
903
+ "Inputs: `seed` fixes the project's host for good; no later update can move it to another site. A "
904
+ "`schedule` other than 'manual' starts runs on its own. Unknown `config` keys are refused, and "
905
+ "values above the plan's caps (such as max_pages) are lowered to them.\n"
906
+ "Behaviour: creating it reads the site's robots.txt and sitemaps but fetches no pages. Every run "
907
+ "then spends credits per page. It is refused when the plan's project limit is reached.\n"
908
+ "Returns: the new project, in get_project's shape; start_run takes its id to crawl it now.\n"
909
+ "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
910
+ "{error, status}.")
862
911
  def create_project(seed: Annotated[str, Field(
863
912
  description="Where the crawl starts: a public site's URL or bare domain, e.g. "
864
913
  "'https://example.com/blog/' or 'example.com'. The project covers that host.")],
@@ -877,12 +926,16 @@ def create_project(seed: Annotated[str, Field(
877
926
 
878
927
  @tool(title="Update a project's settings",
879
928
  annotations=_acts(destructive=True, idempotent=True, open_world=False),
880
- description="Change an existing project's name, schedule or settings. Only what you pass changes: in "
881
- "`config` only the keys given are replaced, the rest stay; a replaced value is not kept. Call "
882
- "get_project first to see the current values, and describe_project_config for valid keys; to "
883
- "start a different site use create_project instead. Nothing is fetched and no credits are "
884
- "spent now; the next run uses the new settings, and a settings change that alters how pages "
885
- "are read starts a fresh comparison baseline. Returns the updated project.")
929
+ description="Change an existing project's name, schedule or settings.\n"
930
+ "Call get_project first to see the current values, and describe_project_config for valid keys. To "
931
+ "watch a different site use create_project instead.\n"
932
+ "Inputs: only what you pass changes. In `config` only the keys given are replaced and the rest "
933
+ "stay. A replaced value is gone, not versioned.\n"
934
+ "Behaviour: nothing is fetched and no credits are spent now. The next run uses the new settings. "
935
+ "A change that alters how pages are read starts a fresh comparison baseline.\n"
936
+ "Returns: the updated project, in get_project's shape.\n"
937
+ "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
938
+ "{error, status}.")
886
939
  def update_project(project_id: ProjectId,
887
940
  name: Annotated[str | None, Field(description="A new name; omit to leave it.")] = None,
888
941
  schedule: Annotated[Schedule | None, Field(
@@ -907,16 +960,19 @@ def update_project(project_id: ProjectId,
907
960
 
908
961
  @tool(title="Start a project run now",
909
962
  annotations=_acts(),
910
- description="Crawl a project's site now with its saved settings, outside its schedule; the run is then "
911
- "compared with the last one. Use it after create_project or update_project, or when fresh "
912
- "results are wanted; to re-read only a few pages use recrawl_pages, and for a site with no "
913
- "project use crawl_site. Every page read costs credits (usually 1 to 4) and a run stops when "
914
- "the credit budget runs out, keeping what it read; it is refused with 409 while a run of the "
915
- "project is already queued or running, and 402 when no credits are left. Without wait it "
916
- "returns the queued run at once; with wait it returns the finished run, except hosted, where "
917
- "a run still going after "
918
- "the time budget comes back as a job for get_job. Results are read with list_pages and "
919
- "get_changes.")
963
+ description="Crawl a project's site now with its saved settings, outside its schedule. The run is then "
964
+ "compared with the last one.\n"
965
+ "Use it after create_project or update_project, or when fresh results are wanted. To re-read only "
966
+ "a few pages use recrawl_pages. For a site with no project use crawl_site.\n"
967
+ "Cost: every page read costs credits (usually 1 to 4). A run stops when the credit budget runs "
968
+ "out and keeps what it read.\n"
969
+ "Refusals: 409 while a run of the project is already queued or running, and 402 when no credits "
970
+ "are left.\n"
971
+ "Returns: without wait, the queued run at once. With wait, the finished run, except hosted, where "
972
+ "a run still going after the time budget comes back as a job for get_job. Read the results with "
973
+ "list_pages and get_changes.\n"
974
+ "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
975
+ "{error, status}.")
920
976
  def start_run(project_id: ProjectId,
921
977
  wait: Annotated[bool, Field(
922
978
  description="true waits for the run to finish (minutes for a large site); false (default) "
@@ -936,12 +992,16 @@ def start_run(project_id: ProjectId,
936
992
 
937
993
  @tool(title="List a run's pages",
938
994
  annotations=READS_STORED,
939
- description="List the pages one project run stored -- the last finished run unless run_id is given -- "
940
- "with each page's url, status, depth, word count and when it last changed, up to 500 rows, "
941
- "plus the runId. Use it to see what a crawl covered or to pick a URL; get_page reads one of "
942
- "them in full, search_pages finds pages by their text, and get_changes lists only what "
943
- "changed. Free and reads only what is stored: it never fetches the site. A project with no "
944
- "finished run answers with no pages.")
995
+ description="List the pages one project run stored, with each page's url, status, depth, word count and when "
996
+ "it last changed, plus the run's link-graph summary and its runId.\n"
997
+ "Use it to see what a crawl covered or to pick a URL. get_page reads one page in full, "
998
+ "search_pages finds pages by their text, and get_changes lists only what changed.\n"
999
+ "Inputs: `run_id` is a run's id, not a number or a date. Leave it empty for the latest finished "
1000
+ "run; a project with no finished run answers with no pages.\n"
1001
+ "Returns: up to 500 rows, shallowest pages first. A larger run is cut at 500, so use search_pages "
1002
+ "to find pages beyond that.\n"
1003
+ "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
1004
+ "{error, status}.")
945
1005
  def list_pages(project_id: ProjectId, run_id: RunId = None) -> dict:
946
1006
  def go():
947
1007
  r = _client().pages(project_id, run_id)
@@ -953,11 +1013,16 @@ def list_pages(project_id: ProjectId, run_id: RunId = None) -> dict:
953
1013
  @tool(title="Get one stored page",
954
1014
  annotations=READS_STORED,
955
1015
  description="Read one page a project run stored, in full: its markdown and other bodies (each capped at "
956
- "12,000 characters), head fields (title, description, canonical, h1), extracted fields, and "
957
- "its versions across runs. Use it when you know the page's URL; list_pages or search_pages "
958
- "finds the URL first, and for a page from a crawl_site crawl use get_job with url instead. "
959
- "Free and reads only what is stored, so it never fetches the site -- use extract_url for a "
960
- "live copy. A URL the run did not store answers 404.")
1016
+ "12,000 characters), head fields (title, description, canonical, h1), extracted fields, and its "
1017
+ "versions across runs.\n"
1018
+ "Use it when you know the page's URL; list_pages or search_pages finds it first. For a page from "
1019
+ "a crawl_site crawl use get_job with url instead. For a live copy use extract_url.\n"
1020
+ "Inputs: `url` is an address, not a search term. The scheme and a trailing slash may differ, but "
1021
+ "the rest of the URL, query string included, must match exactly. `run_id` pins that run's copy; "
1022
+ "without it, the newest copy across the project's last 50 runs.\n"
1023
+ "A URL the run did not store answers 404.\n"
1024
+ "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
1025
+ "{error, status}.")
961
1026
  def get_page(project_id: ProjectId,
962
1027
  url: Annotated[str, Field(
963
1028
  description="The page's full URL as list_pages or search_pages shows it; the other scheme or "
@@ -970,14 +1035,18 @@ def get_page(project_id: ProjectId,
970
1035
 
971
1036
  @tool(title="Get what changed in a run",
972
1037
  annotations=READS_STORED,
973
- description="Report what changed in a project run against the run before it -- the last finished run "
974
- "unless run_id is given: pages added, modified and removed, head-field changes (title, "
975
- "description, canonical...), and the run's coverage, with up to 200 entries per list plus the "
976
- "runs a record exists for. Use it to answer 'what changed on the site'; list_pages shows every "
977
- "page whatever changed, and get_page shows one page's text and versions. Removals are withheld "
978
- "when the crawl reached under 90% of the site, so a blocked crawl never reports the site as "
979
- "gone. A project's first run is a baseline with nothing to compare. Free and reads only what "
980
- "is stored.")
1038
+ description="Report what changed in a project run against the run before it: pages added, modified and "
1039
+ "removed, head-field changes (title, description, canonical), and the run's coverage.\n"
1040
+ "Use it to answer 'what changed on the site'. list_pages shows every page whatever changed, and "
1041
+ "get_page shows one page's text and versions.\n"
1042
+ "Inputs: `run_id` picks the run whose record to read, and that run is always compared with the "
1043
+ "run just before it. Leave it empty for the latest finished run. A run still going answers 409.\n"
1044
+ "Behaviour: removals are withheld when the crawl reached under 90% of the site, so a blocked "
1045
+ "crawl never reports the site as gone. A project's first run is a baseline with nothing to "
1046
+ "compare.\n"
1047
+ "Returns: up to 200 entries per list, plus the runs a record exists for.\n"
1048
+ "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
1049
+ "{error, status}.")
981
1050
  def get_changes(project_id: ProjectId, run_id: RunId = None) -> dict:
982
1051
  def go():
983
1052
  r = _client().changes(project_id, run_id)
@@ -991,12 +1060,18 @@ def get_changes(project_id: ProjectId, run_id: RunId = None) -> dict:
991
1060
 
992
1061
  @tool(title="Search a run's stored pages",
993
1062
  annotations=READS_STORED,
994
- description="Find which pages of a project run contain some text or an element -- the last finished run "
995
- "unless run_id is given -- returning the matching URLs with how many pages were scanned. Use "
996
- "it to locate pages by what they say or contain; list_pages lists every page and get_page "
997
- "then reads one in full. It scans the stored copies and never fetches the site, so it is free "
998
- "and as fresh as the run. A selector search needs the run to have kept html (the rawHtml "
999
- "format); when none was kept the answer says so rather than reporting no matches.")
1063
+ description="Find which pages of a project run contain some text or an element, and return the matching URLs "
1064
+ "with how many pages were scanned.\n"
1065
+ "Use it to locate pages by what they say or contain. list_pages lists every page, and get_page "
1066
+ "then reads one in full. It cannot search a crawl_site crawl or the live site: use get_job or "
1067
+ "extract_url for those.\n"
1068
+ "Inputs: a selector search needs the run to have kept html (the rawHtml format). When none was "
1069
+ "kept, the answer says so rather than reporting no matches. Leave run_id empty for the latest "
1070
+ "finished run.\n"
1071
+ "Returns: up to 500 hits, each {url, count, snippet}, with `scanned`, `noBody` and `truncated` "
1072
+ "(true when more pages matched). It is as fresh as the run.\n"
1073
+ "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
1074
+ "{error, status}.")
1000
1075
  def search_pages(project_id: ProjectId,
1001
1076
  q: Annotated[str, Field(
1002
1077
  description="What to look for, 1 to 200 characters. In content mode every word must "
@@ -1011,29 +1086,42 @@ def search_pages(project_id: ProjectId,
1011
1086
 
1012
1087
  @tool(title="Re-crawl chosen pages",
1013
1088
  annotations=_acts(),
1014
- description="Fetch specific pages of a project again now, as a small run of their own whose record "
1015
- "compares just those pages with the last full run. Use it to check a few pages you expect "
1016
- "changed without crawling the whole site; start_run re-crawls everything, and extract_url "
1017
- "reads a page outside any project. Each page costs credits (usually 1 to 4). The URLs must be "
1018
- "on the project's site; refused with 409 while another run of the project is queued or "
1019
- "running. Returns the queued run; follow it with get_job (kind 'run') and read results with "
1020
- "get_changes.")
1089
+ description="Fetch specific pages of a project again now, as a small run of their own whose record compares "
1090
+ "just those pages with the last full run.\n"
1091
+ "Use it to check a few pages you expect changed without crawling the whole site. start_run "
1092
+ "re-crawls everything, and extract_url reads a page outside any project.\n"
1093
+ "Inputs: a path such as '/pricing' is resolved against the project's site. A URL on another site "
1094
+ "is refused with 400 naming it, before anything runs.\n"
1095
+ "Cost: each page costs credits (usually 1 to 4). A page that fails is recorded in the run with "
1096
+ "its status, not dropped.\n"
1097
+ "Refusals: 409 while another run of the project is queued or running.\n"
1098
+ "Returns: the queued run. Follow it with get_job (kind 'run') and read the results with "
1099
+ "get_changes.\n"
1100
+ "Needs write access; a read-only connection is refused with code 'read_only'. Errors return "
1101
+ "{error, status}.")
1021
1102
  def recrawl_pages(project_id: ProjectId,
1022
1103
  urls: Annotated[list[str], Field(
1023
- description="1 to 500 full URLs on the project's site to fetch again.")]) -> dict:
1104
+ description="1 to 500 pages on the project's site to fetch again: full URLs, or paths "
1105
+ "such as '/pricing'.")]) -> dict:
1024
1106
  return _safe(lambda: _client().recrawl(project_id, urls))
1025
1107
 
1026
1108
 
1027
1109
  @tool(title="Follow a long-running job",
1028
1110
  annotations=READS_STORED,
1029
- description="Check on a job a long tool handed back -- a crawl from crawl_site, a run from start_run or "
1030
- "recrawl_pages, or a batch from scrape_urls -- and, once it has finished, return the same "
1031
- "result the original tool would have given; while it is still going, its status and counts. "
1032
- "Call it when a tool answered with status 'running' and a job; calling the original tool "
1033
- "again is not needed and would not start a second job. For a crawl it is also how to read "
1034
- "further: `url` returns one page in full (even mid-crawl) and `cursor` the next window of "
1035
- "pages. For a project's stored pages use get_page instead. Free: it only reads stored "
1036
- "results and never fetches.")
1111
+ description="Check on a job a long tool handed back (a crawl from crawl_site, a run from start_run or "
1112
+ "recrawl_pages, or a batch from scrape_urls) and return its result once it has finished.\n"
1113
+ "Call it when a tool answered with status 'running' and a job. Calling the original tool again is "
1114
+ "not needed and would not start a second job. For a project's stored pages use get_page instead.\n"
1115
+ "Inputs: for a crawl, `url` returns one page in full (even mid-crawl) and `cursor` the next "
1116
+ "window of pages.\n"
1117
+ "Returns: while it runs, {status: 'running', job, counts}. Once finished, a crawl gives "
1118
+ "crawl_site's answer (crawl_id, status, pages, index, counts, stop, note, and cursor when there "
1119
+ "is more), a batch gives scrape_urls' answer, and a run gives the run record (id, status, "
1120
+ "counts).\n"
1121
+ "Behaviour: a crawl expires a day after it started unless it was kept, and then the call answers "
1122
+ "404.\n"
1123
+ "Works on a read-only connection. Free: it reads stored data and never fetches. Errors return "
1124
+ "{error, status}.")
1037
1125
  def get_job(kind: Annotated[Literal["crawl", "run", "batch"], Field(
1038
1126
  description="What the job is: 'crawl' (crawl_site), 'run' (start_run, recrawl_pages) or "
1039
1127
  "'batch' (scrape_urls); the 'job' object a tool returned names it.")],
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: mesharc
3
- Version: 0.3.2
3
+ Version: 0.3.3
4
4
  Summary: Python client for the MeshArc API: a URL in, clean content out, and a record of what changed.
5
5
  License-Expression: MIT
6
6
  Project-URL: Homepage, https://mesharc.dev
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "mesharc"
7
- version = "0.3.2"
7
+ version = "0.3.3"
8
8
  description = "Python client for the MeshArc API: a URL in, clean content out, and a record of what changed."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -65,3 +65,31 @@ def test_fixed_choices_are_listed():
65
65
  assert enum("search_pages", "mode") == ["content", "selector"]
66
66
  for tool in ("create_project", "keep_crawl_as_project", "update_project"):
67
67
  assert enum(tool, "schedule") == ["manual", "hourly", "daily", "weekly"]
68
+
69
+
70
+ def test_each_description_states_the_access_its_hints_declare():
71
+ # The description and the hints must never disagree: graders mark a
72
+ # contradiction down to 1, and an assistant told a tool only reads would
73
+ # call it on a read-only connection and be refused.
74
+ for name, t in _tools().items():
75
+ says_read_only = "Works on a read-only connection" in t.description
76
+ says_write = "Needs write access" in t.description
77
+ assert says_read_only == (name in READ_ONLY), name
78
+ assert says_write == (name not in READ_ONLY), name
79
+
80
+
81
+ def test_list_projects_passes_on_each_projects_status(monkeypatch):
82
+ # It asked the API for `health`, which no project has ever carried, so
83
+ # every row said health: null. The project's state is `status`.
84
+ class _Projects:
85
+ @staticmethod
86
+ def list():
87
+ return [{"id": "p1", "name": "Docs", "status": "failing", "webhookSecret": "whsec_x"}]
88
+
89
+ class _Client:
90
+ projects = _Projects()
91
+
92
+ monkeypatch.setattr(mcp_mod, "_client", lambda: _Client())
93
+ rows = mcp_mod.list_projects()
94
+ assert rows[0]["status"] == "failing" and "health" not in rows[0]
95
+ assert "webhookSecret" not in rows[0]
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes