gapit 0.2.2__py3-none-any.whl

gapit/hits.py

@@ -0,0 +1,107 @@
+"""Hit processing: the SPEC.md §4 algorithm, in order, nothing more.
+
+No interval merging of any kind — upstream reports overlapping genes at
+different query spans, and so do we. Subject ids decode through
+:mod:`gapit.dbcodec`: legacy ``~~~`` ids parse by the frozen db.py rules,
+``gapit|``-tagged ids by the strict native codec — a malformed native header
+raises DatabaseError ``HEADER_MALFORMED`` (exit 4), never a silent fallback.
+"""
+
+import re
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import BaseModel
+
+from gapit.db import IDSEP
+from gapit.dbcodec import decode_seqid, is_gapit_header
+from gapit.minimap import minimap
+
+# Perl: $product =~ s/^\S+\s+// if $product =~ m/~~~/  — strips the leading
+# makeblastdb id token only when followed by whitespace; a bare ~~~id stays.
+# Native gapit| ids get the same substitution: makeblastdb prefixes stitle
+# with the id, and there the prefix is the whitespace-free tagged seqid.
+_LEADING_TOKEN_RE = re.compile(r"^\S+\s+")
+
+if TYPE_CHECKING:
+    # TYPE_CHECKING-only: blast -> report -> hits would otherwise be a cycle.
+    from gapit.blast import BlastRow
+
+
+class Hit(BaseModel, frozen=True):
+    """One surviving hit — raw semantic values only (display formatting is Phase 3)."""
+
+    sequence: str
+    start: int
+    end: int
+    strand: Literal["+", "-"]
+    gene: str
+    database: str
+    accession: str
+    product: str
+    function: str
+    s_start: int
+    s_end: int
+    s_len: int
+    coverage_map: str
+    gap_openings: int
+    gaps: int
+    identity_pct: float
+    coverage_pct: float
+
+
+def process_rows(rows: Iterable["BlastRow"], *, mincov: float, default_db: str) -> list[Hit]:
+    """Turn BLAST rows into hits, strictly in SPEC.md §4 order:
+
+    1. minus-strand swap (subject coords only), 2. dedup on
+    (qseqid, qstart, qend) — first row wins, key ignores strand, and the key
+    is claimed even if the row is later coverage-filtered, 3. coverage filter
+    on the unrounded float, 4. header decode (native ``gapit|`` codec or
+    legacy ``~~~`` rules), 5. product cleanup.
+    """
+    hits: list[Hit] = []
+    seen: set[tuple[str, int, int]] = set()
+    for row in rows:
+        # 1. minus-strand normalize: swap sstart/send (query coords untouched)
+        if row.sstrand == "minus":
+            s_start, s_end = row.send, row.sstart
+        else:
+            s_start, s_end = row.sstart, row.send
+        # 2. dedup on the query span
+        key = (row.qseqid, row.qstart, row.qend)
+        if key in seen:
+            continue
+        seen.add(key)
+        # 3. coverage filter on the unrounded float
+        coverage_pct = 100.0 * (row.length - row.gaps) / row.slen
+        if coverage_pct < mincov:
+            continue
+        # 4. subject id decode: native gapit| codec, legacy ~~~ delegated
+        header = decode_seqid(row.sseqid, default_db)
+        # 5. product cleanup: n/a fallback, strip ',' and tab, drop leading id token
+        product = row.stitle or "n/a"
+        product = product.replace(",", "").replace("\t", "")
+        if IDSEP in product or is_gapit_header(row.sseqid):
+            product = _LEADING_TOKEN_RE.sub("", product, count=1)
+        hits.append(
+            Hit(
+                sequence=row.qseqid,
+                start=row.qstart,
+                end=row.qend,
+                strand="-" if row.sstrand == "minus" else "+",
+                gene=header.gene,
+                database=header.database,
+                accession=header.accession,
+                function=header.function,
+                product=product,
+                s_start=s_start,
+                s_end=s_end,
+                s_len=row.slen,
+                coverage_map=minimap(s_start, s_end, row.slen, row.gapopen),
+                gap_openings=row.gapopen,
+                gaps=row.gaps,
+                identity_pct=row.pident,
+                coverage_pct=coverage_pct,
+            )
+        )
+    return hits

gapit/mcp.py

@@ -0,0 +1,158 @@
+r"""Minimal MCP stdio server: gapit as a tool provider for agents.
+
+Hand-rolled on purpose (AGENTS.md §2 keeps the dependency list deliberately
+short): no `mcp` SDK — just the essential MCP stdio behavior, JSON-RPC 2.0,
+one message per line on stdin and one response line on stdout. Limitations:
+single messages only (no batch arrays); non-JSON lines are ignored silently
+(robustness over -32700); JSON lines that fail frame validation get a
+-32600/-32602 error when they carry a request id, so no client ever hangs.
+This module is the PROTOCOL only — frames,
+dispatch, and the serve loop; the tool implementations live in
+:mod:`gapit.mcp_tools` and the tools/list declarations (inputSchemas) in
+:mod:`gapit.mcp_schemas` (screen, summary, schema, db_list, db_fetch,
+db_build, db_search, db_outdated). Tool failures return isError=true with
+the gapit.error/1 envelope as text; stdout is protocol-only.
+"""
+
+import json
+import sys
+from collections.abc import Iterable
+from typing import Any, TextIO, TypeGuard
+
+import typer
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from gapit import __version__
+from gapit.errors import render_error
+from gapit.mcp_schemas import TOOLS
+from gapit.mcp_tools import TOOL_HANDLERS
+
+# Parsed JSON-RPC values are the one sanctioned Any boundary (card.py
+# precedent): frame/argument containers stay dict[str, Any] until the
+# per-field checks in mcp_tools pin concrete types.
+JsonRpcId = str | int | float | None
+
+PROTOCOL_VERSION = "2025-06-18"
+
+
+class _Frame(BaseModel, frozen=True):
+    """One stdin frame (request or notification); ``id`` presence in
+    model_fields_set distinguishes requests, per JSON-RPC 2.0."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    method: str | None = None
+    params: dict[str, Any] | None = None
+    id: JsonRpcId = None
+
+
+class _ToolCall(BaseModel, frozen=True):
+    """tools/call params: the tool ``name`` and its ``arguments`` object."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    name: str = ""
+    arguments: dict[str, Any] | None = None
+
+
+def _result(id_value: JsonRpcId, result: dict[str, object]) -> dict[str, object]:
+    return {"jsonrpc": "2.0", "id": id_value, "result": result}
+
+
+def _error(id_value: JsonRpcId, code: int, message: str) -> dict[str, object]:
+    return {"jsonrpc": "2.0", "id": id_value, "error": {"code": code, "message": message}}
+
+
+def _text(text: str, *, is_error: bool) -> dict[str, object]:
+    return {"content": [{"type": "text", "text": text}], "isError": is_error}
+
+
+def _initialize(params: dict[str, Any] | None) -> dict[str, object]:
+    version = (params or {}).get("protocolVersion", "")
+    requested = version if isinstance(version, str) else ""
+    return {
+        "protocolVersion": requested or PROTOCOL_VERSION,
+        "capabilities": {"tools": {}},
+        "serverInfo": {"name": "gapit", "version": __version__},
+    }
+
+
+def _tools_call(id_value: JsonRpcId, params: dict[str, Any] | None) -> dict[str, object]:
+    try:
+        call = _ToolCall.model_validate(params or {})
+    except ValidationError:
+        return _error(id_value, -32602, "invalid tools/call params")
+    tool = TOOL_HANDLERS.get(call.name)
+    if tool is None:
+        return _error(id_value, -32602, f"unknown tool: {call.name or '(none)'}")
+    try:
+        text = tool(call.arguments or {})
+    except Exception as exc:  # gapit.dispatch semantics: envelope, not a crash
+        return _result(id_value, _text(render_error(exc), is_error=True))
+    return _result(id_value, _text(text, is_error=False))
+
+
+def _is_json_object(value: Any) -> TypeGuard[dict[str, Any]]:
+    """Narrow a parsed JSON value to the sanctioned dict[str, Any] boundary
+    (plain isinstance would surface dict[Unknown, Unknown])."""
+    return isinstance(value, dict)
+
+
+def _reject(value: Any) -> dict[str, object] | None:
+    """A line that parsed as JSON but failed _Frame validation: answer the
+    request id with -32600 (missing/non-string method) or -32602 (params not
+    an object); id-less messages stay ignored like notifications."""
+    if not _is_json_object(value):
+        return None
+    id_value = value.get("id")
+    if id_value is None:
+        return None
+    if not isinstance(value.get("method"), str):
+        return _error(id_value, -32600, "invalid request: method must be a string")
+    return _error(id_value, -32602, "invalid request: params must be an object")
+
+
+def _handle(frame: _Frame) -> dict[str, object] | None:
+    """One parsed frame -> one response object; None = no response."""
+    if "id" not in frame.model_fields_set:
+        return None  # notifications never get responses
+    if frame.method is None:
+        return _error(frame.id, -32600, "invalid request: method is required")
+    id_value = frame.id
+    if frame.method == "initialize":
+        return _result(id_value, _initialize(frame.params))
+    if frame.method == "tools/list":
+        return _result(id_value, {"tools": list(TOOLS)})
+    if frame.method == "tools/call":
+        return _tools_call(id_value, frame.params)
+    return _error(id_value, -32601, f"method not found: {frame.method}")
+
+
+def serve(stdin: Iterable[str], stdout: TextIO) -> None:
+    """Serve newline-delimited JSON-RPC 2.0 until EOF; non-JSON lines and
+    id-less invalid messages are ignored, requests that fail frame
+    validation get a -32600/-32602 error instead of silence."""
+    for line in stdin:
+        try:
+            value: object = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        try:
+            frame = _Frame.model_validate(value)
+        except ValidationError:
+            response = _reject(value)
+        else:
+            response = _handle(frame)
+        if response is not None:
+            stdout.write(json.dumps(response, separators=(",", ":")) + "\n")
+            stdout.flush()
+
+
+def register_mcp_command(app: typer.Typer) -> None:
+    """Attach the `mcp` subcommand (cli.py stays import + registration only)."""
+    app.command("mcp")(main)
+
+
+def main() -> None:
+    """`gapit-mcp` console script; also backs the `gapit mcp` subcommand."""
+    serve(sys.stdin, sys.stdout)

gapit/mcp_schemas.py

@@ -0,0 +1,123 @@
+"""MCP tools/list declarations: names, descriptions, inputSchemas (protocol: gapit.mcp).
+
+Pure data — the roster mirrors the handler map in :mod:`gapit.mcp_tools`.
+Descriptions are wire-visible wording; treat any edit like a schema change
+(AGENTS.md §5).
+"""
+
+from gapit.db_query_ops import DEFAULT_LIMIT, DEFAULT_STALE_DAYS, SearchField
+from gapit.formats.schemas import SCHEMA_MODELS
+from gapit.reads import ReadTypeEnum
+
+_FILES: dict[str, object] = {"type": "array", "items": {"type": "string"}}
+_FLAG: dict[str, object] = {"type": "boolean", "default": False}
+_STR: dict[str, object] = {"type": "string"}
+_DAYS: dict[str, object] = {"type": "integer", "minimum": 0, "default": DEFAULT_STALE_DAYS}
+_SEARCH_FIELDS: list[str] = [field.value for field in SearchField]
+_READ_TYPES: list[str] = [preset.value for preset in ReadTypeEnum]
+
+
+def _tool_entry(
+    name: str,
+    description: str,
+    properties: dict[str, object] | None = None,
+    required: list[str] | None = None,
+) -> dict[str, object]:
+    schema = {"type": "object", "properties": properties or {}, "required": required or []}
+    return {"name": name, "description": description, "inputSchema": schema}
+
+
+TOOLS: list[dict[str, object]] = [
+    _tool_entry(
+        "screen",
+        "Screen contig files for AMR/virulence genes (json = gapit.report/1;"
+        " aligner minimap2 = fast assembly survey emitting gapit.reads/1).",
+        dict(
+            files=_FILES,
+            db={"type": "string", "default": "ncbi"},
+            minid={"type": "number"},
+            mincov={"type": "number"},
+            format={"type": "string", "enum": ["json", "tsv", "md"], "default": "json"},
+            aligner={"type": "string", "enum": ["blastn", "minimap2"], "default": "blastn"},
+            min_breadth={"type": "number", "minimum": 0, "maximum": 100, "default": 90},
+            min_identity={"type": "number", "minimum": 0, "maximum": 100, "default": 0},
+            min_mapq={"type": "integer", "minimum": 0, "default": 0},
+            datadir=_STR,
+        ),
+        ["files"],
+    ),
+    _tool_entry(
+        "screen_reads",
+        "Screen FASTQ reads for genes via minimap2 (json = gapit.reads/1;"
+        " min_identity/min_mapq > 0 emits gapit.reads/2). Returns the rendered"
+        " document.",
+        dict(
+            r1=_FILES,
+            r2=_FILES,
+            read_type={"type": "string", "enum": _READ_TYPES, "default": "sr"},
+            min_breadth={"type": "number", "minimum": 0, "maximum": 100, "default": 90},
+            min_identity={"type": "number", "minimum": 0, "maximum": 100, "default": 0},
+            min_mapq={"type": "integer", "minimum": 0, "default": 0},
+            format={"type": "string", "enum": ["json", "md"], "default": "json"},
+            db={"type": "string", "default": "ncbi"},
+            datadir=_STR,
+        ),
+        ["r1"],
+    ),
+    _tool_entry(
+        "summary",
+        "Summarize report tables into a gapit.summary/1 matrix.",
+        dict(files=_FILES, identity={"type": "boolean"}, nopath={"type": "boolean"}),
+        ["files"],
+    ),
+    _tool_entry(
+        "schema",
+        "Print the JSON Schema of a gapit output document.",
+        dict(name={"type": "string", "enum": sorted(SCHEMA_MODELS)}),
+        ["name"],
+    ),
+    _tool_entry("db_list", "List database providers and their installed state (gapit.dblist/1)."),
+    _tool_entry(
+        "db_fetch",
+        "Fetch provider database(s) into the datadir (name omitted: card+vfdb from bundled"
+        " snapshots; network installs can take minutes). One JSON receipt line per database"
+        " (db, records, dbtype, destination).",
+        dict(name=_STR, datadir=_STR, force=_FLAG),
+    ),
+    _tool_entry(
+        "db_build",
+        "Build a custom database from a LOCAL FASTA filesystem path (plain, abricate ~~~, or"
+        " gapit| headers; .gz/.bz2 accepted). Returns a JSON receipt (db, records, dbtype,"
+        " destination).",
+        dict(
+            name=_STR,
+            fasta=_STR,
+            tsv=_STR,
+            dbtype={"type": "string", "enum": ["nucl", "prot"]},
+            description=_STR,
+            datadir=_STR,
+            force=_FLAG,
+        ),
+        ["name", "fasta"],
+    ),
+    _tool_entry(
+        "db_search",
+        "Search installed databases for a term (case-insensitive substring, or exact"
+        " full-field equality). Hit rows are TSV: DB, GENE, ACCESSION, FUNCTION, PRODUCT, LENGTH.",
+        dict(
+            term=_STR,
+            db=_STR,
+            field={"type": "string", "enum": _SEARCH_FIELDS, "default": "any"},
+            exact=_FLAG,
+            limit={"type": "integer", "minimum": 0, "default": DEFAULT_LIMIT},
+            datadir=_STR,
+        ),
+        ["term"],
+    ),
+    _tool_entry(
+        "db_outdated",
+        "Report installed database ages against the staleness threshold (days) and newer"
+        " bundled snapshots. Rows are TSV with columns NAME, FETCHED_AT, AGE_DAYS, STATUS.",
+        dict(days=_DAYS, datadir=_STR),
+    ),
+]

gapit/mcp_tools.py

@@ -0,0 +1,289 @@
+"""MCP tool implementations (protocol: gapit.mcp; declarations: gapit.mcp_schemas).
+
+Every tool mirrors its CLI twin by calling the SAME shared callables —
+never a reimplementation. Failures raise typed errors; the protocol layer
+renders them as isError envelopes.
+"""
+
+import json
+from collections.abc import Callable
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from gapit import config
+from gapit.db_build_ops import perform_build
+from gapit.db_ops import db_list_json, perform_fetch
+from gapit.db_query_ops import (
+    DEFAULT_LIMIT,
+    DEFAULT_STALE_DAYS,
+    SearchField,
+    outdated_tsv_lines,
+    perform_outdated,
+    perform_search,
+)
+from gapit.errors import usage_fail
+from gapit.formats.schemas import SCHEMA_MODELS
+from gapit.formats.summary import render_summary_json
+from gapit.reads import ReadTypeEnum
+from gapit.screening import AlignerEnum, OutputFormat, run_screen
+from gapit.screening_reads import run_screen_assemblies, run_screen_reads
+from gapit.summary import SummaryParams, build_summary
+
+# Parsed JSON-RPC argument containers stay dict[str, Any] until the
+# per-field isinstance checks in the helpers below pin concrete types (the
+# sanctioned Any boundary, card.py precedent).
+
+
+def _paths(arguments: dict[str, Any], key: str) -> list[Path]:
+    value: Any = arguments.get(key, [])
+    # items stays unnarrowed Any: iterating the isinstance-narrowed value
+    # would leak Unknown into basedpyright strict; value proves list-ness.
+    items: Any = arguments.get(key, [])
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in items):
+        usage_fail(f"{key} must be an array of file path strings")
+    return [Path(item) for item in items]
+
+
+def _string(arguments: dict[str, Any], key: str, default: str) -> str:
+    value = arguments.get(key, default)
+    if not isinstance(value, str):
+        usage_fail(f"{key} must be a string")
+    return value
+
+
+def _optional_string(arguments: dict[str, Any], key: str) -> str | None:
+    value = arguments.get(key)
+    if value is not None and not isinstance(value, str):
+        usage_fail(f"{key} must be a string")
+    return value
+
+
+def _required_string(arguments: dict[str, Any], key: str) -> str:
+    value = arguments.get(key)
+    if not isinstance(value, str) or not value:
+        usage_fail(f"{key} must be a non-empty string")
+    return value
+
+
+def _optional_path(arguments: dict[str, Any], key: str) -> Path | None:
+    value = _optional_string(arguments, key)
+    return None if value is None else Path(value)
+
+
+def _integer(arguments: dict[str, Any], key: str, default: int) -> int:
+    value = arguments.get(key, default)
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        usage_fail(f"{key} must be a non-negative integer")
+    return value
+
+
+def _number(arguments: dict[str, Any], key: str, default: float) -> float:
+    value = arguments.get(key, default)
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        usage_fail(f"{key} must be a number")
+    return float(value)
+
+
+def _flag(arguments: dict[str, Any], key: str) -> bool:
+    value = arguments.get(key, False)
+    if not isinstance(value, bool):
+        usage_fail(f"{key} must be a boolean")
+    return value
+
+
+def _optional_output_format(name: str) -> OutputFormat | None:
+    """Map an already-validated format name onto the reads use-case's
+    OutputFormat|None (None = the json default, SPEC.md §10)."""
+    return None if name == "json" else OutputFormat(name)
+
+
+def _tool_screen(arguments: dict[str, Any]) -> str:
+    files = _paths(arguments, "files")
+    if not files:
+        usage_fail("no input files given (files is required)")
+    db_name = _string(arguments, "db", "ncbi")
+    datadir = _optional_path(arguments, "datadir")
+    minid = _number(arguments, "minid", 80.0)
+    mincov = _number(arguments, "mincov", 80.0)
+    output_format = _string(arguments, "format", "json")
+    if output_format not in ("json", "tsv", "md"):
+        usage_fail(f"format must be one of json, tsv, md: got {output_format}")
+    aligner_name = _string(arguments, "aligner", "blastn")
+    try:
+        aligner = AlignerEnum(aligner_name)
+    except ValueError:
+        usage_fail(f"aligner must be blastn or minimap2: got {aligner_name}")
+    min_breadth = _number(arguments, "min_breadth", 90.0)
+    min_identity = _number(arguments, "min_identity", 0.0)
+    min_mapq = _integer(arguments, "min_mapq", 0)
+    if aligner is AlignerEnum.minimap2:
+        # tsv is rejected by the use-case itself (reads-mode format rule);
+        # non-default minid/mincov too (blastn-only thresholds).
+        return run_screen_assemblies(
+            files,
+            None,
+            db_name,
+            datadir,
+            None,
+            min_breadth,
+            min_identity,
+            min_mapq,
+            threads=1,
+            jobs=1,
+            noheader=False,
+            nopath=False,
+            output_format=_optional_output_format(output_format),
+            quiet=True,
+            minid=minid,
+            mincov=mincov,
+        )
+    if (min_breadth, min_identity, min_mapq) != (90.0, 0.0, 0):
+        usage_fail("reads-mode parameters require aligner minimap2")
+    return run_screen(
+        files=files,
+        db_name=db_name,
+        datadir=datadir,
+        minid=minid,
+        mincov=mincov,
+        threads=1,
+        jobs=1,
+        fofn=None,
+        quiet=True,
+        noheader=False,
+        nopath=False,
+        debug=False,
+        output_format=OutputFormat(output_format),
+    )
+
+
+def _reads_paths(arguments: dict[str, Any], key: str) -> list[Path]:
+    """Reads path array -> the native list the use-case consumes (no
+    join/split round trip, so commas in filenames survive). Empty elements
+    are usage errors: an empty string would silently become the cwd."""
+    _paths(arguments, key)
+    # list[str] proven by the _paths isinstance checks above
+    raw: list[str] = arguments.get(key, [])
+    if any(item == "" for item in raw):
+        usage_fail(f"{key} contains an empty element")
+    return [Path(item) for item in raw]
+
+
+def _tool_screen_reads(arguments: dict[str, Any]) -> str:
+    r1 = _reads_paths(arguments, "r1")
+    if not r1:
+        usage_fail("no reads files given (r1 is required)")
+    r2 = _reads_paths(arguments, "r2") or None
+    read_type_name = _string(arguments, "read_type", ReadTypeEnum.sr.value)
+    try:
+        read_type = ReadTypeEnum(read_type_name)
+    except ValueError:
+        usage_fail(f"read_type must be one of {', '.join(t.value for t in ReadTypeEnum)}")
+    output_format = _string(arguments, "format", "json")
+    if output_format not in ("json", "md"):
+        usage_fail(f"format must be one of json, md: got {output_format}")
+    min_breadth = _number(arguments, "min_breadth", 90.0)
+    if not 0.0 <= min_breadth <= 100.0:
+        usage_fail(f"min_breadth must be in [0, 100]: got {min_breadth}")
+    min_identity = _number(arguments, "min_identity", 0.0)
+    if not 0.0 <= min_identity <= 100.0:
+        usage_fail(f"min_identity must be in [0, 100]: got {min_identity}")
+    min_mapq = _integer(arguments, "min_mapq", 0)
+    # lane pairing is validated by the use-case (frozen CLI message)
+    return run_screen_reads(
+        r1,
+        r2,
+        _string(arguments, "db", "ncbi"),
+        _optional_path(arguments, "datadir"),
+        read_type,
+        min_breadth,
+        min_identity,
+        min_mapq,
+        threads=1,
+        output_format=_optional_output_format(output_format),
+        quiet=True,
+    )
+
+
+def _tool_summary(arguments: dict[str, Any]) -> str:
+    files = _paths(arguments, "files")
+    if not files:
+        usage_fail("summary needs >= 1 report file(s)")
+    params = SummaryParams(identity=_flag(arguments, "identity"), nopath=_flag(arguments, "nopath"))
+    # The CLI warns about duplicate inputs on stderr; MCP reserves stderr for
+    # protocol-internal errors, so those warnings are dropped here.
+    matrix = build_summary(files, params, warn=lambda message: None)
+    return render_summary_json(matrix, now=datetime.now(UTC))
+
+
+def _tool_schema(arguments: dict[str, Any]) -> str:
+    name = _string(arguments, "name", "")
+    model = SCHEMA_MODELS.get(name)
+    if model is None:
+        usage_fail(f"unknown schema name: {name} (choose from: {', '.join(SCHEMA_MODELS)})")
+    return json.dumps(model.model_json_schema(by_alias=True), indent=2)
+
+
+def _tool_db_list(arguments: dict[str, Any]) -> str:
+    return db_list_json(config.resolve_datadir(None))
+
+
+def _tool_db_fetch(arguments: dict[str, Any]) -> str:
+    receipts = perform_fetch(
+        _optional_string(arguments, "name"),
+        _optional_path(arguments, "datadir"),
+        force=_flag(arguments, "force"),
+    )
+    return "\n".join(receipt.model_dump_json() for receipt in receipts)
+
+
+def _tool_db_build(arguments: dict[str, Any]) -> str:
+    dbtype = _optional_string(arguments, "dbtype")
+    if dbtype is not None and dbtype not in ("nucl", "prot"):
+        usage_fail(f"dbtype must be nucl or prot: got {dbtype}")
+    receipt = perform_build(
+        _required_string(arguments, "name"),
+        Path(_required_string(arguments, "fasta")),
+        _optional_path(arguments, "tsv"),
+        dbtype,
+        _string(arguments, "description", ""),
+        _optional_path(arguments, "datadir"),
+        _flag(arguments, "force"),
+        warn=lambda message: None,
+    )
+    return receipt.model_dump_json()
+
+
+def _tool_db_search(arguments: dict[str, Any]) -> str:
+    try:
+        field = SearchField(_string(arguments, "field", "any"))
+    except ValueError:
+        usage_fail(f"field must be one of {', '.join(f.value for f in SearchField)}")
+    hits, _total = perform_search(
+        _required_string(arguments, "term"),
+        _optional_path(arguments, "datadir"),
+        db=_optional_string(arguments, "db"),
+        field=field,
+        exact=_flag(arguments, "exact"),
+        limit=_integer(arguments, "limit", DEFAULT_LIMIT),
+    )
+    return "\n".join(hits)
+
+
+def _tool_db_outdated(arguments: dict[str, Any]) -> str:
+    days = _integer(arguments, "days", DEFAULT_STALE_DAYS)
+    lines = outdated_tsv_lines(perform_outdated(_optional_path(arguments, "datadir"), days=days))
+    return "\n".join(lines)
+
+
+TOOL_HANDLERS: dict[str, Callable[[dict[str, Any]], str]] = {
+    "screen": _tool_screen,
+    "screen_reads": _tool_screen_reads,
+    "summary": _tool_summary,
+    "schema": _tool_schema,
+    "db_list": _tool_db_list,
+    "db_fetch": _tool_db_fetch,
+    "db_build": _tool_db_build,
+    "db_search": _tool_db_search,
+    "db_outdated": _tool_db_outdated,
+}