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.
- {mesharc-0.3.2 → mesharc-0.3.3}/CHANGELOG.md +14 -0
- {mesharc-0.3.2/mesharc.egg-info → mesharc-0.3.3}/PKG-INFO +1 -1
- {mesharc-0.3.2 → mesharc-0.3.3}/mesharc/__init__.py +1 -1
- {mesharc-0.3.2 → mesharc-0.3.3}/mesharc/mcp.py +208 -120
- {mesharc-0.3.2 → mesharc-0.3.3/mesharc.egg-info}/PKG-INFO +1 -1
- {mesharc-0.3.2 → mesharc-0.3.3}/pyproject.toml +1 -1
- {mesharc-0.3.2 → mesharc-0.3.3}/tests/test_definitions.py +28 -0
- {mesharc-0.3.2 → mesharc-0.3.3}/LICENSE +0 -0
- {mesharc-0.3.2 → mesharc-0.3.3}/MANIFEST.in +0 -0
- {mesharc-0.3.2 → mesharc-0.3.3}/README.md +0 -0
- {mesharc-0.3.2 → mesharc-0.3.3}/SECURITY.md +0 -0
- {mesharc-0.3.2 → mesharc-0.3.3}/mesharc/py.typed +0 -0
- {mesharc-0.3.2 → mesharc-0.3.3}/mesharc.egg-info/SOURCES.txt +0 -0
- {mesharc-0.3.2 → mesharc-0.3.3}/mesharc.egg-info/dependency_links.txt +0 -0
- {mesharc-0.3.2 → mesharc-0.3.3}/mesharc.egg-info/entry_points.txt +0 -0
- {mesharc-0.3.2 → mesharc-0.3.3}/mesharc.egg-info/requires.txt +0 -0
- {mesharc-0.3.2 → mesharc-0.3.3}/mesharc.egg-info/top_level.txt +0 -0
- {mesharc-0.3.2 → mesharc-0.3.3}/setup.cfg +0 -0
- {mesharc-0.3.2 → mesharc-0.3.3}/tests/test_behaviour.py +0 -0
- {mesharc-0.3.2 → mesharc-0.3.3}/tests/test_client.py +0 -0
- {mesharc-0.3.2 → mesharc-0.3.3}/tests/test_mcp_http.py +0 -0
- {mesharc-0.3.2 → mesharc-0.3.3}/tests/test_results.py +0 -0
|
@@ -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
|
|
@@ -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
|
|
595
|
-
"
|
|
596
|
-
"following links
|
|
597
|
-
"
|
|
598
|
-
"
|
|
599
|
-
"
|
|
600
|
-
"
|
|
601
|
-
"
|
|
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
|
-
"
|
|
638
|
-
"
|
|
639
|
-
"for
|
|
640
|
-
"create_project
|
|
641
|
-
"
|
|
642
|
-
"
|
|
643
|
-
"
|
|
644
|
-
"
|
|
645
|
-
"
|
|
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
|
|
662
|
-
"paths, each index file walked to its children
|
|
663
|
-
"first, to see how big a site is and what sections it has, before crawl_site or
|
|
664
|
-
"
|
|
665
|
-
"
|
|
666
|
-
"
|
|
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
|
|
685
|
-
"
|
|
686
|
-
"or section whose page URLs you do not know
|
|
687
|
-
"over time use create_project
|
|
688
|
-
"
|
|
689
|
-
"
|
|
690
|
-
"
|
|
691
|
-
"
|
|
692
|
-
"
|
|
693
|
-
"
|
|
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
|
-
"
|
|
745
|
-
"
|
|
746
|
-
"
|
|
747
|
-
"
|
|
748
|
-
"
|
|
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
|
|
766
|
-
"
|
|
767
|
-
"
|
|
768
|
-
"
|
|
769
|
-
"
|
|
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", "
|
|
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
|
|
825
|
-
"
|
|
826
|
-
"update_project or
|
|
827
|
-
"limit or behaviour
|
|
828
|
-
"
|
|
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
|
|
846
|
-
"
|
|
847
|
-
"
|
|
848
|
-
"
|
|
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
|
|
856
|
-
"compared with the last, recording pages added, modified and removed
|
|
857
|
-
"is to monitor or track a site
|
|
858
|
-
"
|
|
859
|
-
"
|
|
860
|
-
"
|
|
861
|
-
"
|
|
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
|
|
881
|
-
"
|
|
882
|
-
"
|
|
883
|
-
"
|
|
884
|
-
"
|
|
885
|
-
"
|
|
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
|
|
911
|
-
"compared with the last one
|
|
912
|
-
"
|
|
913
|
-
"
|
|
914
|
-
"
|
|
915
|
-
"
|
|
916
|
-
"
|
|
917
|
-
"
|
|
918
|
-
"
|
|
919
|
-
"
|
|
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
|
|
940
|
-
"
|
|
941
|
-
"
|
|
942
|
-
"
|
|
943
|
-
"
|
|
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
|
-
"
|
|
958
|
-
"
|
|
959
|
-
"
|
|
960
|
-
"
|
|
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
|
|
974
|
-
"
|
|
975
|
-
"
|
|
976
|
-
"
|
|
977
|
-
"
|
|
978
|
-
"
|
|
979
|
-
"
|
|
980
|
-
"is
|
|
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
|
|
995
|
-
"
|
|
996
|
-
"it to locate pages by what they say or contain
|
|
997
|
-
"then reads one in full. It
|
|
998
|
-
"
|
|
999
|
-
"
|
|
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
|
-
"
|
|
1016
|
-
"changed without crawling the whole site
|
|
1017
|
-
"reads a page outside any project
|
|
1018
|
-
"
|
|
1019
|
-
"
|
|
1020
|
-
"
|
|
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
|
|
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
|
|
1030
|
-
"recrawl_pages, or a batch from scrape_urls
|
|
1031
|
-
"
|
|
1032
|
-
"
|
|
1033
|
-
"
|
|
1034
|
-
"
|
|
1035
|
-
"
|
|
1036
|
-
"
|
|
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.")],
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "mesharc"
|
|
7
|
-
version = "0.3.
|
|
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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|