world-reference-mcp 0.3.1__tar.gz

world_reference_mcp-0.3.1/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012-2023 Project Maintainers
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

world_reference_mcp-0.3.1/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: world-reference-mcp
+Version: 0.3.1
+Summary: World-reference data (taxonomy, OBO terms, nutrition, observations, Wikidata alignment) MCP server and agent-connector-sdk source adapters
+Author-email: Project Maintainers <maintainers@users.noreply.github.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: agent-connector-sdk[mcp]<1.0.0,>=0.3.13
+Requires-Dist: httpx>=0.28.1
+Provides-Extra: test
+Requires-Dist: pytest-xdist>=3.8.0; extra == "test"
+Requires-Dist: pytest>=9.1.1; extra == "test"
+Requires-Dist: pytest-asyncio>=1.4.0; extra == "test"
+Requires-Dist: pytest-cov>=7.1.0; extra == "test"
+Dynamic: license-file
+
+# world-reference-mcp
+
+*Version: 0.3.1*
+
+World-reference data — organism taxonomy, OBO reference terms, food/nutrition
+composition, organism and weather observations, and Wikidata alignment — as an
+MCP tool surface and, through `agent-connector-sdk`'s declarative `mcp_tool`
+source adapter, as bounded, checkpointed ingestion streams onto the
+epistemic-graph `world_model` ontology (`feat/world-model-ontology`).
+
+## Sources
+
+| Ledger row | Sources | Target class |
+|---|---|---|
+| EH-358 (taxonomy) | NCBI Taxonomy (E-utilities), GBIF backbone | `Taxon` |
+| EH-359 (reference terms) | EBI OLS4 (GO, UBERON, ENVO, PATO, ChEBI, FoodOn) | `BiologicalProcessTerm`, `AnatomyTerm`, `EnvironmentTerm`, `QualityTerm`, `ChemicalEntityTerm`, `FoodTerm` |
+| EH-360 (nutrition) | USDA FoodData Central | `FoodCompositionRecord` |
+| EH-361 (observations) | GBIF occurrences, iNaturalist, Open-Meteo, NOAA GHCND | `OrganismObservation`, `WeatherObservation` |
+| EH-362 (alignment) | Wikidata SPARQL | `wikidataId` / `skos:exactMatch` keys for `Taxon`, `ChemicalEntityTerm`, `Country` |
+
+## Tools
+
+Nine MCP tools, one FastMCP server (`world-reference-mcp` console script):
+`taxonomy_ncbi_search`, `taxonomy_gbif_search`, `reference_term_list`,
+`fdc_food_search`, `gbif_occurrence_search`, `inaturalist_observation_search`,
+`open_meteo_weather_observation`, `noaa_ghcnd_daily`, `wikidata_alignment_search`.
+
+Every tool is keyless except `fdc_food_search` and `noaa_ghcnd_daily`, whose
+credentials are resolved server-side through `agent_connector_sdk.credentials`
+(`WORLD_REFERENCE_FDC_API_KEY`, `WORLD_REFERENCE_NOAA_TOKEN`) — never accepted
+as a tool argument.
+
+See [`AGENTS.md`](AGENTS.md) for architecture, the ontology-mapping
+authority, rate limits, and commands.

world_reference_mcp-0.3.1/README.md

@@ -0,0 +1,34 @@
+# world-reference-mcp
+
+*Version: 0.3.1*
+
+World-reference data — organism taxonomy, OBO reference terms, food/nutrition
+composition, organism and weather observations, and Wikidata alignment — as an
+MCP tool surface and, through `agent-connector-sdk`'s declarative `mcp_tool`
+source adapter, as bounded, checkpointed ingestion streams onto the
+epistemic-graph `world_model` ontology (`feat/world-model-ontology`).
+
+## Sources
+
+| Ledger row | Sources | Target class |
+|---|---|---|
+| EH-358 (taxonomy) | NCBI Taxonomy (E-utilities), GBIF backbone | `Taxon` |
+| EH-359 (reference terms) | EBI OLS4 (GO, UBERON, ENVO, PATO, ChEBI, FoodOn) | `BiologicalProcessTerm`, `AnatomyTerm`, `EnvironmentTerm`, `QualityTerm`, `ChemicalEntityTerm`, `FoodTerm` |
+| EH-360 (nutrition) | USDA FoodData Central | `FoodCompositionRecord` |
+| EH-361 (observations) | GBIF occurrences, iNaturalist, Open-Meteo, NOAA GHCND | `OrganismObservation`, `WeatherObservation` |
+| EH-362 (alignment) | Wikidata SPARQL | `wikidataId` / `skos:exactMatch` keys for `Taxon`, `ChemicalEntityTerm`, `Country` |
+
+## Tools
+
+Nine MCP tools, one FastMCP server (`world-reference-mcp` console script):
+`taxonomy_ncbi_search`, `taxonomy_gbif_search`, `reference_term_list`,
+`fdc_food_search`, `gbif_occurrence_search`, `inaturalist_observation_search`,
+`open_meteo_weather_observation`, `noaa_ghcnd_daily`, `wikidata_alignment_search`.
+
+Every tool is keyless except `fdc_food_search` and `noaa_ghcnd_daily`, whose
+credentials are resolved server-side through `agent_connector_sdk.credentials`
+(`WORLD_REFERENCE_FDC_API_KEY`, `WORLD_REFERENCE_NOAA_TOKEN`) — never accepted
+as a tool argument.
+
+See [`AGENTS.md`](AGENTS.md) for architecture, the ontology-mapping
+authority, rate limits, and commands.

world_reference_mcp-0.3.1/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["setuptools>=80.9.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "world-reference-mcp"
+version = "0.3.1"
+description = "World-reference data (taxonomy, OBO terms, nutrition, observations, Wikidata alignment) MCP server and agent-connector-sdk source adapters"
+readme = "README.md"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Environment :: Console",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+]
+requires-python = ">=3.12, <3.15"
+dependencies = [
+    "agent-connector-sdk[mcp]>=0.3.13,<1.0.0",
+    "httpx>=0.28.1",
+]
+
+[[project.authors]]
+name = "Project Maintainers"
+email = "maintainers@users.noreply.github.com"
+
+[project.license]
+text = "MIT"
+
+[project.optional-dependencies]
+test = ["pytest-xdist>=3.8.0", "pytest>=9.1.1", "pytest-asyncio>=1.4.0", "pytest-cov>=7.1.0"]
+
+[project.scripts]
+world-reference-mcp = "world_reference_mcp.mcp_server:mcp_server"
+
+[project.entry-points."agent_connector_sdk.skill_providers"]
+world-reference-mcp = "world_reference_mcp.skills"
+
+[project.entry-points."agent_connector_sdk.ontology_providers"]
+world-reference-mcp = "world_reference_mcp.ontology"
+
+[project.entry-points."agent_connector_sdk.prompt_providers"]
+world-reference-mcp = "world_reference_mcp.prompts"
+
+[project.entry-points."agent_connector_sdk.source_connector_providers"]
+world-reference-mcp = "world_reference_mcp.connectors"
+
+[tool.uv.workspace]
+members = ["."]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.mypy]
+python_version = "3.12"
+ignore_missing_imports = true
+check_untyped_defs = true
+
+[dependency-groups]
+dev = ["pytest-timeout>=2.4.0", "mypy>=1.20.2", "ruff>=0.16.0"]
+
+[tool.setuptools.package-data]
+world_reference_mcp = ["mcp_config.json", "prompts/**", "skills/**", "ontology/**", "connectors/**"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E402", "E501", "B008"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+
+
+[tool.pipelines_hooks]
+packages = ["world_reference_mcp"]
+
+[tool.pipelines_hooks.stdout_writes]
+served_paths = ["world_reference_mcp"]
+
+[tool.pipelines_hooks.ste]
+exempt = ["specs/*", "specs/**/*"]

world_reference_mcp-0.3.1/scripts/compute_tool_fingerprints.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Regenerate ``connectors/tool_schema_fingerprints.json`` from the live tool surface.
+
+Connects an in-process FastMCP client to a plain server carrying this
+package's nine tools (no auth/network/fleet-registration wiring — those are
+concerns of ``agent_connector_sdk.mcp.server.create_mcp_server``, irrelevant
+to a tool's client-visible schema) and fingerprints exactly what a real
+client's ``tools/list`` would see, via
+``agent_connector_sdk.certify.fingerprints.tool_fingerprint`` — the same
+function ``discover()`` verifies against at extraction time.
+
+Run after changing any tool's signature or docstring-derived schema:
+
+    uv run --frozen python scripts/compute_tool_fingerprints.py --apply
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+from pathlib import Path
+
+from agent_connector_sdk.certify.fingerprints import tool_fingerprint
+from fastmcp import Client, FastMCP
+
+from world_reference_mcp.mcp.clients import Clients
+from world_reference_mcp.mcp.tools_nutrition import register_nutrition_tools
+from world_reference_mcp.mcp.tools_observations import register_observation_tools
+from world_reference_mcp.mcp.tools_taxonomy import register_taxonomy_tools
+from world_reference_mcp.mcp.tools_terms import register_term_tools
+from world_reference_mcp.mcp.tools_wikidata import register_wikidata_tools
+
+_OUTPUT = Path(__file__).resolve().parent.parent / (
+    "world_reference_mcp/connectors/tool_schema_fingerprints.json"
+)
+
+
+def _bare_server() -> FastMCP:
+    mcp: FastMCP = FastMCP("world-reference-mcp")
+    clients = Clients()
+    register_taxonomy_tools(mcp, clients)
+    register_term_tools(mcp, clients)
+    register_nutrition_tools(mcp, clients)
+    register_observation_tools(mcp, clients)
+    register_wikidata_tools(mcp, clients)
+    return mcp
+
+
+async def _fingerprints() -> dict[str, str]:
+    mcp = _bare_server()
+    async with Client(mcp) as client:
+        tools = await client.list_tools()
+    return {tool.name: tool_fingerprint(tool) for tool in tools}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--apply", action="store_true", help="write the output file")
+    args = parser.parse_args()
+    fingerprints = asyncio.run(_fingerprints())
+    document = {
+        "_comment": (
+            "Generated by scripts/compute_tool_fingerprints.py from the live "
+            "tools/list schema. Never hand-edit."
+        ),
+        "tools": dict(sorted(fingerprints.items())),
+    }
+    text = json.dumps(document, indent=2, sort_keys=False) + "\n"
+    if args.apply:
+        _OUTPUT.write_text(text)
+        print(f"wrote {_OUTPUT}")
+    else:
+        print(text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

world_reference_mcp-0.3.1/scripts/security_sanitizer.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+MAX_SCAN_BYTES = 8 * 1024 * 1024
+
+# Config
+# llms.txt is the deliberate root-level AI entry index (llms-txt convention,
+# like robots.txt) shipped by the docs/day-0 work — not garbage.
+# overrides.txt is the sanctioned uv dependency-override file (UV_OVERRIDE in
+# docker/Dockerfile, mirroring [tool.uv] override-dependencies) shipped by the
+# pydantic-ai v2 migration — a canonical packaging input, not scratch.
+# .security-audit-allow.txt is the OSV dependency-audit risk-acceptance ledger
+# (scripts/audit_dependencies.py, wired into the dependency-audit pre-commit hook)
+# — a committed, actively-read governance input, not scratch/garbage.
+ALLOWED_TXT_NAMES = {
+    "requirements.txt",
+    "requirements-dev.txt",
+    "llms.txt",
+    "overrides.txt",
+    ".security-audit-allow.txt",
+}
+TRANSIENT_PY_PATTERNS = [
+    re.compile(r"^test_.*\.py$"),
+    re.compile(r"^fix_.*\.py$"),
+    re.compile(r"^debug_.*\.py$"),
+    re.compile(r"^scratch_.*\.py$"),
+    re.compile(r"^temp_.*\.py$"),
+]
+
+SECRET_PATTERNS = [
+    ("GitHub PAT", re.compile(r"ghp_[A-Za-z0-9_]{36,255}")),
+    ("GitHub Fine-grained PAT", re.compile(r"github_pat_[A-Za-z0-9_]{82,255}")),
+    ("GitLab PAT", re.compile(r"glpat-[A-Za-z0-9\-]{20,255}")),
+    ("Private key", re.compile(r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----")),
+    ("AWS access key", re.compile(r"\b(?:AKIA|ASIA)[A-Z0-9]{16}\b")),
+    ("Slack token", re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{20,}\b")),
+    ("Langfuse secret", re.compile(r"\bsk-lf-[A-Za-z0-9_-]{16,}\b")),
+    (
+        "Generic Secret Assignment",
+        re.compile(
+            r"secret[A-Za-z0-9_]*\s*[:=]\s*['\"][A-Za-z0-9_\-\.\~\*]{16,255}['\"]",
+            re.IGNORECASE,
+        ),
+    ),
+    (
+        "Generic Token Assignment",
+        re.compile(
+            r"token\s*[:=]\s*['\"][A-Za-z0-9_\-\.\~\*]{16,255}['\"]", re.IGNORECASE
+        ),
+    ),
+]
+
+EXCLUDED_DIRS = {
+    ".git",
+    ".venv",
+    "venv",
+    "node_modules",
+    "build",
+    "dist",
+    "__pycache__",
+    ".tox",
+    ".specify",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".cache",
+}
+EXCLUDED_EXTENSIONS = {
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".ico",
+    ".pyc",
+    ".db",
+    ".kuzu",
+    ".sqlite",
+    ".sqlite3",
+    ".zip",
+    ".tar.gz",
+    ".tgz",
+    ".bz2",
+    ".xz",
+    ".pdf",
+    ".bin",
+    ".exe",
+    ".dll",
+    ".so",
+    ".dylib",
+    ".woff",
+    ".woff2",
+    ".eot",
+    ".ttf",
+    ".mp4",
+    ".mp3",
+    ".wav",
+    ".lock",
+    ".svg",
+}
+
+# Placeholder / Mock indicators
+PLACEHOLDER_VALUES = {
+    "1234567890",
+    "abcdef12345",
+    "abc123youandme",
+    "askdfalskdvjas",
+    "test_token",
+    "test_secret",
+    "glpat-askdfalskdvjas",
+    "github_pat_12345",
+    "glpat-abc123youandme",
+    "github_pat_...",
+    "glpat-*************",
+    "ghp_*************",
+    "github_pat_*************",
+    "token_*************",
+    "secret_*************",
+    "glpat-abc",
+    "ghp_abc",
+    "github_pat_abc",
+    "${env:",
+}
+PLACEHOLDER_PREFIXES = ("your_", "your-", "dummy", "example", "mock")
+
+
+def is_placeholder(match_str: str) -> bool:
+    # Generic assignment patterns include the variable name. Judge only the
+    # quoted value so names such as ``secret_example`` cannot suppress a real
+    # credential finding.
+    assignment = re.search(r"['\"]([^'\"]+)['\"]\s*$", match_str)
+    candidate = assignment.group(1) if assignment else match_str
+    candidate_lower = candidate.strip().lower()
+    if candidate_lower in PLACEHOLDER_VALUES or candidate_lower.startswith(
+        PLACEHOLDER_PREFIXES
+    ):
+        return True
+
+    # Check if match is mostly asterisks or single repeated char
+    cleaned = candidate.replace("'", "").replace('"', "").strip()
+    if not cleaned:
+        return True
+
+    # Check if there are sequences of asterisks indicating masked values
+    if "*" in cleaned:
+        # e.g., glpat-*************
+        return True
+
+    compact = re.sub(r"[^A-Za-z0-9]", "", cleaned).lower()
+    if len(compact) >= 8 and len(set(compact)) == 1:
+        return True
+
+    return False
+
+
+def _is_excluded_relative_path(relative: Path) -> bool:
+    if relative.is_absolute() or ".." in relative.parts:
+        raise ValueError("unsafe source inventory path")
+    return any(part in EXCLUDED_DIRS for part in relative.parts)
+
+
+def _git_tracked_files(repo_path: Path):
+    result = subprocess.run(
+        ["git", "ls-files", "--cached", "--others", "--exclude-standard"],
+        cwd=str(repo_path),
+        capture_output=True,
+        text=True,
+        check=True,
+        timeout=30,
+    )
+    files = []
+    for line in result.stdout.splitlines():
+        if not line.strip():
+            continue
+        relative = Path(line.strip())
+        # Avoid files inside excluded directories
+        if not _is_excluded_relative_path(relative):
+            files.append(repo_path / relative)
+    return files
+
+
+def _walk_tracked_files(repo_path: Path):
+    # Fallback to manual recursive scan
+    files = []
+    for root, dirs, walk_files in os.walk(str(repo_path)):
+        # Hidden source/config directories (for example ``.github``) can
+        # contain credentials and must not disappear merely because Git
+        # inventory was unavailable. Exclude only known generated trees.
+        dirs[:] = [d for d in dirs if d not in EXCLUDED_DIRS]
+        for file in walk_files:
+            files.append(Path(root) / file)
+    return files
+
+
+def get_repo_files(repo_path: Path):
+    try:
+        return _git_tracked_files(repo_path)
+    except (OSError, subprocess.SubprocessError, ValueError):
+        return _walk_tracked_files(repo_path)
+
+
+def _root_naming_violations(file_path: Path):
+    violations = []
+    if file_path.suffix == ".txt":
+        if file_path.name.lower() not in ALLOWED_TXT_NAMES:
+            violations.append(
+                "Non-standard root-level text file detected: "
+                f"'{file_path.name}'. Only {sorted(ALLOWED_TXT_NAMES)} "
+                "are allowed."
+            )
+    elif file_path.suffix == ".py":
+        for pattern in TRANSIENT_PY_PATTERNS:
+            if pattern.match(file_path.name):
+                violations.append(
+                    "Transient/temporary script detected in root: "
+                    f"'{file_path.name}'. Please move it to a subfolder "
+                    "or delete it."
+                )
+                break
+    return violations
+
+
+def _should_secret_scan(file_path: Path) -> bool:
+    if file_path.suffix.lower() in EXCLUDED_EXTENSIONS:
+        return False
+    if file_path.name == "security_sanitizer.py":
+        return False
+    return True
+
+
+def _secret_violations_in_line(line: str, rel_path: Path, idx: int):
+    violations = []
+    for label, pattern in SECRET_PATTERNS:
+        for match in pattern.findall(line):
+            match_str = match[0] if isinstance(match, tuple) else match
+            if not is_placeholder(match_str):
+                violations.append(
+                    f"Potential unmasked secret ({label}) detected in "
+                    f"{rel_path}:{idx}"
+                )
+    return violations
+
+
+def _secret_scan_violations(file_path: Path, repo_path: Path):
+    rel_path = file_path.relative_to(repo_path)
+    if file_path.stat().st_size > MAX_SCAN_BYTES:
+        return [
+            f"Source file exceeds security scan boundary: '{rel_path}'",
+        ]
+
+    # Decode strictly. Silently discarding invalid bytes can splice a
+    # credential around the discarded byte and make a fail-open scan.
+    content = file_path.read_text(encoding="utf-8")
+    violations = []
+    for idx, line in enumerate(content.splitlines(), 1):
+        violations.extend(_secret_violations_in_line(line, rel_path, idx))
+    return violations
+
+
+def _scan_one_file(file_path: Path, repo_path: Path):
+    violations = []
+
+    # 1. Check root level naming constraints
+    if file_path.parent == repo_path:
+        violations.extend(_root_naming_violations(file_path))
+
+    # 2. Check for secrets
+    if not _should_secret_scan(file_path):
+        return violations
+
+    try:
+        violations.extend(_secret_scan_violations(file_path, repo_path))
+    except (OSError, UnicodeError):
+        violations.append(
+            f"Source file could not be inspected: "
+            f"'{file_path.relative_to(repo_path)}'"
+        )
+    return violations
+
+
+def scan_repository(repo_path: Path):
+    violations = []
+
+    for file_path in get_repo_files(repo_path):
+        if not file_path.is_file():
+            continue
+        if file_path.is_symlink():
+            # Git tracks the link target text, not the target contents. Never
+            # follow a repository symlink into machine-local material.
+            continue
+        violations.extend(_scan_one_file(file_path, repo_path))
+
+    return violations
+
+
+def main():
+    repo_path = Path.cwd()
+
+    print("🔒 Running Security and Garbage Sanitizer...")
+    violations = scan_repository(repo_path)
+
+    if violations:
+        print("\n❌ SECURITY AND GARBAGE VALIDATION FAILED!")
+        print("Please correct the following issues before committing:")
+        for idx, violation in enumerate(violations, 1):
+            print(f"\n[{idx}] {violation}")
+        sys.exit(1)
+
+    print("✅ All checks passed! No root garbage or unmasked secrets detected.")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

world_reference_mcp-0.3.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

world_reference_mcp-0.3.1/tests/conftest.py

@@ -0,0 +1,34 @@
+"""Shared test fixtures. No live network: every HTTP call is mocked."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+
+import httpx
+import pytest
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+def load_fixture(name: str) -> dict:
+    """Read one recorded or synthetic fixture JSON file by name."""
+    return json.loads((FIXTURES / name).read_text())
+
+
+def mock_client(
+    base_url: str, handler: Callable[[httpx.Request], httpx.Response]
+) -> httpx.AsyncClient:
+    """An ``httpx.AsyncClient`` whose transport is a synchronous fixture handler."""
+    return httpx.AsyncClient(base_url=base_url, transport=httpx.MockTransport(handler))
+
+
+def json_response(payload: dict) -> httpx.Response:
+    """A 200 JSON response carrying ``payload``."""
+    return httpx.Response(200, json=payload)
+
+
+@pytest.fixture
+def fixture() -> Callable[[str], dict]:
+    return load_fixture