amr-mcp 0.1.0__tar.gz

amr_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,15 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -m "not network"

amr_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,80 @@
+# Publishes to PyPI and the MCP Registry when a version tag (v0.1.0, v0.2.0...) is pushed.
+# No secrets needed: both use GitHub OIDC (PyPI "trusted publishing").
+name: Release
+on:
+  push:
+    tags: ["v*"]
+
+env:
+  MCP_PUBLISHER_VERSION: v1.8.1
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check tag matches pyproject.toml and server.json
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          py=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          srv=$(jq -r .version server.json)
+          pkg=$(jq -r '.packages[0].version' server.json)
+          echo "tag=$tag pyproject=$py server.json=$srv/$pkg"
+          [ "$tag" = "$py" ] && [ "$tag" = "$srv" ] && [ "$tag" = "$pkg" ]
+      - run: pip install -e ".[dev]" build
+      - run: pytest -m "not network"
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  mcp-registry:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+      - uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+      - name: Install mcp-publisher (signature-verified)
+        run: |
+          set -euo pipefail
+          os="$(uname -s | tr '[:upper:]' '[:lower:]')"
+          arch="$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')"
+          archive="mcp-publisher_${os}_${arch}.tar.gz"
+          base_url="https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}"
+          curl --fail --location --silent --show-error --output "$archive" "$base_url/$archive"
+          curl --fail --location --silent --show-error --output "$archive.sigstore.json" "$base_url/$archive.sigstore.json"
+          cosign verify-blob \
+            --bundle "$archive.sigstore.json" \
+            --certificate-identity "https://github.com/modelcontextprotocol/registry/.github/workflows/release.yml@refs/tags/${MCP_PUBLISHER_VERSION}" \
+            --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+            "$archive"
+          tar xzf "$archive" mcp-publisher
+          rm -f "$archive" "$archive.sigstore.json"
+      - run: ./mcp-publisher login github-oidc
+      - name: Publish (retries while PyPI propagates the new release)
+        run: |
+          for i in 1 2 3 4 5; do
+            ./mcp-publisher publish && exit 0
+            sleep 30
+          done
+          exit 1

amr_mcp-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

amr_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pablo Estepa
+
+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.

amr_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: amr-mcp
+Version: 0.1.0
+Summary: MCP server for antimicrobial resistance (AMR) data: NCBI Reference Gene Catalog, NCBI E-utilities and UniProt
+Project-URL: Homepage, https://github.com/pabloestepaa/amr-mcp
+Project-URL: Issues, https://github.com/pabloestepaa/amr-mcp/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: amr,antimicrobial-resistance,bioinformatics,mcp,ncbi,uniprot
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# amr-mcp
+
+<!-- mcp-name: io.github.pabloestepaa/amr-mcp -->
+
+[![CI](https://github.com/pabloestepaa/amr-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/pabloestepaa/amr-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/amr-mcp)](https://pypi.org/project/amr-mcp/)
+
+An [MCP](https://modelcontextprotocol.io) server that lets AI assistants (Claude, Codex, Cursor…) query
+**antimicrobial resistance (AMR)** data from public, free sources:
+
+- **NCBI Reference Gene Catalog**, the curated database behind
+  [AMRFinderPlus](https://github.com/ncbi/amr): ~11,500 AMR genes, point mutations, stress and virulence genes
+- **NCBI E-utilities**: protein and nucleotide sequences, PubMed references
+- **UniProtKB**: protein function, keywords and cross-references
+- **AMRFinderPlus** (optional, if installed locally): screen your own genomes
+
+All data sources are public domain or freely accessible; no API keys are required.
+
+## Example questions
+
+> Which carbapenemases are reported in *Klebsiella pneumoniae*, and what is the original paper for KPC-2?
+
+> Give me the protein sequence of mcr-1.1 and its UniProt function annotation.
+
+> Run AMRFinderPlus on `~/data/isolate_17.fasta` as *Escherichia* and explain the hits by drug class.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_amr_genes` | Search by text, drug class, subclass, organism or element type |
+| `get_amr_gene` | Exact record for an allele (`blaKPC-2`) or summary of a family (`blaKPC`) |
+| `list_drug_classes` | Drug classes and how many catalog entries each has |
+| `catalog_info` | Catalog version and size |
+| `fetch_sequence` | Protein or nucleotide FASTA from NCBI by accession |
+| `get_pubmed_references` | Title, journal, authors and DOI for PubMed IDs |
+| `search_uniprot` / `get_uniprot_entry` | UniProtKB search and entry details |
+| `run_amrfinder` | Run a local AMRFinderPlus install on a FASTA file |
+
+## Installation
+
+Run it with [uv](https://docs.astral.sh/uv/) (no install step needed), or `pip install amr-mcp`.
+
+### Claude Code
+
+```bash
+claude mcp add amr -- uvx amr-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "amr": { "command": "uvx", "args": ["amr-mcp"] }
+  }
+}
+```
+
+## Configuration
+
+| Variable | Purpose |
+|---|---|
+| `NCBI_API_KEY` | Optional, free. Raises the NCBI rate limit from 3 to 10 requests/s |
+| `NCBI_EMAIL` | Optional. Contact e-mail NCBI asks tools to send |
+| `AMR_MCP_CACHE_DIR` | Where the catalog is cached (default `~/.cache/amr-mcp`, refreshed every 30 days) |
+
+To enable `run_amrfinder`: `conda install -c bioconda ncbi-amrfinderplus && amrfinder -u`.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest -m "not network"   # offline tests
+.venv/bin/pytest                    # also hits the live NCBI/UniProt APIs
+```
+
+## Data licensing
+
+The NCBI Reference Gene Catalog and NCBI sequence data are US government works in the public domain.
+UniProt data is available under CC BY 4.0. Please cite the original sources when you publish results:
+
+- Feldgarden M, et al. *AMRFinderPlus and the Reference Gene Catalog facilitate examination of the
+  genomic links among antimicrobial resistance, stress response, and virulence.* Sci Rep. 2021.
+- The UniProt Consortium. *UniProt: the Universal Protein Knowledgebase.* Nucleic Acids Res.
+
+## License
+
+MIT
+
+---
+
+Developed with AI assistance (Claude Code); all code reviewed and tested by the author.

amr_mcp-0.1.0/README.md

@@ -0,0 +1,95 @@
+# amr-mcp
+
+<!-- mcp-name: io.github.pabloestepaa/amr-mcp -->
+
+[![CI](https://github.com/pabloestepaa/amr-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/pabloestepaa/amr-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/amr-mcp)](https://pypi.org/project/amr-mcp/)
+
+An [MCP](https://modelcontextprotocol.io) server that lets AI assistants (Claude, Codex, Cursor…) query
+**antimicrobial resistance (AMR)** data from public, free sources:
+
+- **NCBI Reference Gene Catalog**, the curated database behind
+  [AMRFinderPlus](https://github.com/ncbi/amr): ~11,500 AMR genes, point mutations, stress and virulence genes
+- **NCBI E-utilities**: protein and nucleotide sequences, PubMed references
+- **UniProtKB**: protein function, keywords and cross-references
+- **AMRFinderPlus** (optional, if installed locally): screen your own genomes
+
+All data sources are public domain or freely accessible; no API keys are required.
+
+## Example questions
+
+> Which carbapenemases are reported in *Klebsiella pneumoniae*, and what is the original paper for KPC-2?
+
+> Give me the protein sequence of mcr-1.1 and its UniProt function annotation.
+
+> Run AMRFinderPlus on `~/data/isolate_17.fasta` as *Escherichia* and explain the hits by drug class.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_amr_genes` | Search by text, drug class, subclass, organism or element type |
+| `get_amr_gene` | Exact record for an allele (`blaKPC-2`) or summary of a family (`blaKPC`) |
+| `list_drug_classes` | Drug classes and how many catalog entries each has |
+| `catalog_info` | Catalog version and size |
+| `fetch_sequence` | Protein or nucleotide FASTA from NCBI by accession |
+| `get_pubmed_references` | Title, journal, authors and DOI for PubMed IDs |
+| `search_uniprot` / `get_uniprot_entry` | UniProtKB search and entry details |
+| `run_amrfinder` | Run a local AMRFinderPlus install on a FASTA file |
+
+## Installation
+
+Run it with [uv](https://docs.astral.sh/uv/) (no install step needed), or `pip install amr-mcp`.
+
+### Claude Code
+
+```bash
+claude mcp add amr -- uvx amr-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "amr": { "command": "uvx", "args": ["amr-mcp"] }
+  }
+}
+```
+
+## Configuration
+
+| Variable | Purpose |
+|---|---|
+| `NCBI_API_KEY` | Optional, free. Raises the NCBI rate limit from 3 to 10 requests/s |
+| `NCBI_EMAIL` | Optional. Contact e-mail NCBI asks tools to send |
+| `AMR_MCP_CACHE_DIR` | Where the catalog is cached (default `~/.cache/amr-mcp`, refreshed every 30 days) |
+
+To enable `run_amrfinder`: `conda install -c bioconda ncbi-amrfinderplus && amrfinder -u`.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest -m "not network"   # offline tests
+.venv/bin/pytest                    # also hits the live NCBI/UniProt APIs
+```
+
+## Data licensing
+
+The NCBI Reference Gene Catalog and NCBI sequence data are US government works in the public domain.
+UniProt data is available under CC BY 4.0. Please cite the original sources when you publish results:
+
+- Feldgarden M, et al. *AMRFinderPlus and the Reference Gene Catalog facilitate examination of the
+  genomic links among antimicrobial resistance, stress response, and virulence.* Sci Rep. 2021.
+- The UniProt Consortium. *UniProt: the Universal Protein Knowledgebase.* Nucleic Acids Res.
+
+## License
+
+MIT
+
+---
+
+Developed with AI assistance (Claude Code); all code reviewed and tested by the author.

amr_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "amr-mcp"
+version = "0.1.0"
+description = "MCP server for antimicrobial resistance (AMR) data: NCBI Reference Gene Catalog, NCBI E-utilities and UniProt"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["mcp", "bioinformatics", "antimicrobial-resistance", "amr", "ncbi", "uniprot"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Intended Audience :: Science/Research",
+]
+dependencies = ["mcp>=2.0,<3", "httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/pabloestepaa/amr-mcp"
+Issues = "https://github.com/pabloestepaa/amr-mcp/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[project.scripts]
+amr-mcp = "amr_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/amr_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+markers = ["network: hits live NCBI/UniProt APIs (deselect with -m 'not network')"]

amr_mcp-0.1.0/server.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.pabloestepaa/amr-mcp",
+  "title": "AMR (antimicrobial resistance)",
+  "description": "Antimicrobial resistance genes, sequences and literature from NCBI and UniProt",
+  "repository": {
+    "url": "https://github.com/pabloestepaa/amr-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "amr-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "NCBI_API_KEY",
+          "description": "Optional free NCBI API key; raises the rate limit from 3 to 10 requests/s",
+          "isRequired": false,
+          "isSecret": true
+        },
+        {
+          "name": "NCBI_EMAIL",
+          "description": "Optional contact e-mail sent to NCBI with each request",
+          "isRequired": false
+        }
+      ]
+    }
+  ]
+}

amr_mcp-0.1.0/src/amr_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""amr-mcp: MCP server for antimicrobial resistance data from NCBI and UniProt."""
+
+__version__ = "0.1.0"

amr_mcp-0.1.0/src/amr_mcp/amrfinder.py

@@ -0,0 +1,47 @@
+"""Optional wrapper around a locally installed AMRFinderPlus (``amrfinder``) binary."""
+
+from __future__ import annotations
+
+import asyncio
+import csv
+import io
+import shutil
+from pathlib import Path
+
+TIMEOUT_SECONDS = 1800
+
+
+def available() -> bool:
+    return shutil.which("amrfinder") is not None
+
+
+async def run(
+    fasta_path: str, sequence_type: str, organism: str | None, threads: int = 4
+) -> dict:
+    if not available():
+        raise RuntimeError(
+            "AMRFinderPlus is not installed. Install it for free with "
+            "`conda install -c bioconda ncbi-amrfinderplus` and run `amrfinder -u` once."
+        )
+    path = Path(fasta_path).expanduser().resolve()
+    if not path.is_file():
+        raise ValueError(f"FASTA file not found: {path}")
+
+    flag = {"nucleotide": "-n", "protein": "-p"}[sequence_type]
+    args = ["amrfinder", flag, str(path), "--plus", "--threads", str(threads)]
+    if organism:
+        args += ["-O", organism.replace(" ", "_")]
+
+    proc = await asyncio.create_subprocess_exec(
+        *args, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+    )
+    try:
+        stdout, stderr = await asyncio.wait_for(proc.communicate(), TIMEOUT_SECONDS)
+    except TimeoutError:
+        proc.kill()
+        raise RuntimeError(f"amrfinder timed out after {TIMEOUT_SECONDS}s") from None
+    if proc.returncode != 0:
+        raise RuntimeError(f"amrfinder failed: {stderr.decode(errors='replace')[-2000:]}")
+
+    hits = list(csv.DictReader(io.StringIO(stdout.decode()), delimiter="\t"))
+    return {"file": str(path), "organism": organism, "hit_count": len(hits), "hits": hits}

amr_mcp-0.1.0/src/amr_mcp/catalog.py

@@ -0,0 +1,176 @@
+"""NCBI Reference Gene Catalog (the AMRFinderPlus database): download, cache and search.
+
+The catalog is a public-domain TSV published by NCBI. It is downloaded once and
+cached on disk; it is refreshed when older than ``max_age_days``.
+"""
+
+from __future__ import annotations
+
+import csv
+import os
+import time
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+CATALOG_URL = (
+    "https://ftp.ncbi.nlm.nih.gov/pathogen/Antimicrobial_resistance/"
+    "AMRFinderPlus/database/latest/ReferenceGeneCatalog.txt"
+)
+
+# Columns exposed to clients. The raw file has more (coordinates, strands...)
+# that are rarely useful to an LLM and only bloat responses.
+PUBLIC_FIELDS = (
+    "allele",
+    "gene_family",
+    "product_name",
+    "scope",
+    "type",
+    "subtype",
+    "class",
+    "subclass",
+    "whitelisted_taxa",
+    "refseq_protein_accession",
+    "refseq_nucleotide_accession",
+    "genbank_protein_accession",
+    "genbank_nucleotide_accession",
+    "pubmed_reference",
+    "synonyms",
+)
+
+
+def default_cache_dir() -> Path:
+    if env := os.environ.get("AMR_MCP_CACHE_DIR"):
+        return Path(env)
+    return Path.home() / ".cache" / "amr-mcp"
+
+
+@dataclass
+class Catalog:
+    rows: list[dict[str, str]]
+
+    @classmethod
+    def from_file(cls, path: Path) -> Catalog:
+        with path.open(newline="", encoding="utf-8") as fh:
+            rows = [dict(r) for r in csv.DictReader(fh, delimiter="\t")]
+        return cls(rows)
+
+    @property
+    def db_version(self) -> str:
+        return self.rows[0].get("db_version", "unknown") if self.rows else "empty"
+
+    def info(self) -> dict:
+        return {
+            "source": CATALOG_URL,
+            "db_version": self.db_version,
+            "total_entries": len(self.rows),
+            "by_type": dict(Counter(r["type"] for r in self.rows)),
+            "by_scope": dict(Counter(r["scope"] for r in self.rows)),
+        }
+
+    def drug_classes(self) -> list[dict]:
+        counts = Counter(r["class"] for r in self.rows if r["class"])
+        return [{"class": c, "entries": n} for c, n in counts.most_common()]
+
+    def search(
+        self,
+        query: str | None = None,
+        drug_class: str | None = None,
+        subclass: str | None = None,
+        organism: str | None = None,
+        element_type: str | None = None,
+        limit: int = 25,
+    ) -> dict:
+        q = query.lower() if query else None
+        organism_key = organism.replace(" ", "_").lower() if organism else None
+
+        def matches(r: dict[str, str]) -> bool:
+            if q and not any(
+                q in r[f].lower() for f in ("allele", "gene_family", "product_name", "synonyms")
+            ):
+                return False
+            if drug_class and drug_class.lower() not in r["class"].lower():
+                return False
+            if subclass and subclass.lower() not in r["subclass"].lower():
+                return False
+            if element_type and element_type.upper() != r["type"]:
+                return False
+            if organism_key:
+                # Entries with no whitelisted taxa apply to any organism.
+                allowed = _taxa(r["whitelisted_taxa"])
+                if allowed and not any(organism_key.startswith(t) for t in allowed):
+                    return False
+                if any(organism_key.startswith(t) for t in _taxa(r["blacklisted_taxa"])):
+                    return False
+            return True
+
+        hits = [r for r in self.rows if matches(r)]
+        return {
+            "total_matches": len(hits),
+            "returned": min(len(hits), limit),
+            "results": [_public(r) for r in hits[:limit]],
+        }
+
+    def get(self, name: str) -> dict:
+        """Exact lookup by allele (e.g. blaKPC-2) or gene family (e.g. blaKPC)."""
+        key = name.lower()
+        alleles = [r for r in self.rows if r["allele"].lower() == key]
+        if alleles:
+            return {"match": "allele", "entries": [_public(r) for r in alleles]}
+        family = [r for r in self.rows if r["gene_family"].lower() == key]
+        if not family:
+            return {"match": None, "entries": []}
+        named = [r["allele"] for r in family if r["allele"]]
+        return {
+            "match": "gene_family",
+            "gene_family": family[0]["gene_family"],
+            "allele_count": len(named),
+            "alleles": named[:200],
+            "classes": sorted({r["class"] for r in family if r["class"]}),
+            "subclasses": sorted({r["subclass"] for r in family if r["subclass"]}),
+            "example_entry": _public(family[0]),
+        }
+
+
+def _taxa(field: str) -> list[str]:
+    # Taxa are genus or Genus_species names, comma-separated when there are several.
+    return [t.strip().lower() for t in field.split(",") if t.strip()]
+
+
+def _public(row: dict[str, str]) -> dict[str, str]:
+    return {f: row[f] for f in PUBLIC_FIELDS if row.get(f)}
+
+
+async def load_catalog(
+    cache_dir: Path | None = None,
+    max_age_days: float = 30,
+    client: httpx.AsyncClient | None = None,
+) -> Catalog:
+    cache_dir = cache_dir or default_cache_dir()
+    path = cache_dir / "ReferenceGeneCatalog.txt"
+    stale = not path.exists() or (time.time() - path.stat().st_mtime) > max_age_days * 86400
+    if stale:
+        try:
+            await _download(path, client)
+        except httpx.HTTPError:
+            # Offline or NCBI down: fall back to the stale copy if we have one.
+            if not path.exists():
+                raise
+    return Catalog.from_file(path)
+
+
+async def _download(path: Path, client: httpx.AsyncClient | None) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".part")
+    owns_client = client is None
+    client = client or httpx.AsyncClient(timeout=60, follow_redirects=True)
+    try:
+        resp = await client.get(CATALOG_URL)
+        resp.raise_for_status()
+        tmp.write_bytes(resp.content)
+        tmp.replace(path)
+    finally:
+        if owns_client:
+            await client.aclose()

amr_mcp-0.1.0/src/amr_mcp/ncbi.py

@@ -0,0 +1,99 @@
+"""Minimal NCBI E-utilities client (efetch / esummary).
+
+Without an API key NCBI allows 3 requests/second; with one (free, set
+``NCBI_API_KEY``) it allows 10. Requests are spaced accordingly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+import time
+
+import httpx
+
+EUTILS = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"
+TOOL_NAME = "amr-mcp"
+
+# RefSeq / GenBank / WGS accessions, optionally versioned (WP_004199234.1, NG_049253.1, AY034847).
+ACCESSION_RE = re.compile(r"^[A-Z]{1,6}_?[A-Z0-9]*\d+(\.\d+)?$")
+MAX_SEQUENCE_CHARS = 200_000
+
+
+class NCBIClient:
+    def __init__(self, client: httpx.AsyncClient | None = None) -> None:
+        self._client = client or httpx.AsyncClient(timeout=30, follow_redirects=True)
+        self._api_key = os.environ.get("NCBI_API_KEY")
+        self._email = os.environ.get("NCBI_EMAIL")
+        self._min_interval = 0.11 if self._api_key else 0.34
+        self._lock = asyncio.Lock()
+        self._last = 0.0
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def _get(self, endpoint: str, params: dict[str, str]) -> httpx.Response:
+        params = {**params, "tool": TOOL_NAME}
+        if self._api_key:
+            params["api_key"] = self._api_key
+        if self._email:
+            params["email"] = self._email
+        async with self._lock:
+            wait = self._min_interval - (time.monotonic() - self._last)
+            if wait > 0:
+                await asyncio.sleep(wait)
+            self._last = time.monotonic()
+        resp = await self._client.get(f"{EUTILS}/{endpoint}", params=params)
+        resp.raise_for_status()
+        return resp
+
+    async def fetch_fasta(self, accession: str, kind: str) -> dict:
+        accession = accession.strip().upper()
+        if not ACCESSION_RE.match(accession):
+            raise ValueError(f"'{accession}' does not look like an NCBI accession")
+        db = {"protein": "protein", "nucleotide": "nuccore"}[kind]
+        resp = await self._get(
+            "efetch.fcgi", {"db": db, "id": accession, "rettype": "fasta", "retmode": "text"}
+        )
+        fasta = resp.text.strip()
+        if not fasta.startswith(">"):
+            raise ValueError(f"NCBI returned no FASTA for {accession} in db={db}")
+        header, _, body = fasta.partition("\n")
+        seq = body.replace("\n", "")
+        truncated = len(seq) > MAX_SEQUENCE_CHARS
+        return {
+            "accession": accession,
+            "db": db,
+            "header": header[1:],
+            "length": len(seq),
+            "truncated": truncated,
+            "sequence": seq[:MAX_SEQUENCE_CHARS],
+        }
+
+    async def pubmed_summaries(self, pmids: list[str]) -> list[dict]:
+        ids = [p.strip() for p in pmids if p.strip().isdigit()]
+        if not ids:
+            raise ValueError("Provide numeric PubMed IDs")
+        resp = await self._get(
+            "esummary.fcgi", {"db": "pubmed", "id": ",".join(ids[:50]), "retmode": "json"}
+        )
+        result = resp.json().get("result", {})
+        out = []
+        for pmid in result.get("uids", []):
+            doc = result[pmid]
+            out.append(
+                {
+                    "pmid": pmid,
+                    "title": doc.get("title"),
+                    "journal": doc.get("fulljournalname") or doc.get("source"),
+                    "pubdate": doc.get("pubdate"),
+                    "authors": [a["name"] for a in doc.get("authors", [])][:6],
+                    "doi": next(
+                        (i["value"] for i in doc.get("articleids", []) if i["idtype"] == "doi"),
+                        None,
+                    ),
+                    "url": f"https://pubmed.ncbi.nlm.nih.gov/{pmid}/",
+                }
+            )
+        return out

amr_mcp-0.1.0/src/amr_mcp/server.py

@@ -0,0 +1,172 @@
+"""MCP server exposing antimicrobial-resistance data from public NCBI and UniProt sources."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+from typing import Annotated, Any, Literal
+
+import httpx
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp_types import ToolAnnotations
+from pydantic import Field
+
+from . import amrfinder
+from .catalog import Catalog, load_catalog
+from .ncbi import NCBIClient
+from .uniprot import UniProtClient
+
+INSTRUCTIONS = """\
+Tools for antimicrobial resistance (AMR) research backed by public databases:
+the NCBI Reference Gene Catalog (the AMRFinderPlus database), NCBI E-utilities and UniProt.
+Typical flow: search_amr_genes or get_amr_gene -> fetch_sequence with the RefSeq accession
+-> get_pubmed_references with the pubmed_reference IDs. Drug classes are upper-case
+(e.g. BETA-LACTAM, AMINOGLYCOSIDE); call list_drug_classes to see them all.
+"""
+
+READ_ONLY = ToolAnnotations(readOnlyHint=True, openWorldHint=True)
+
+mcp = MCPServer("amr-mcp", instructions=INSTRUCTIONS)
+
+
+class _State:
+    """Lazily created shared clients; the catalog is only downloaded on first use."""
+
+    def __init__(self) -> None:
+        self.catalog: Catalog | None = None
+        self._catalog_lock = asyncio.Lock()
+        self.ncbi = NCBIClient()
+        self.uniprot = UniProtClient()
+
+    async def get_catalog(self) -> Catalog:
+        async with self._catalog_lock:
+            if self.catalog is None:
+                self.catalog = await load_catalog()
+            return self.catalog
+
+
+state = _State()
+
+
+def _user_errors(fn):
+    """Surface expected failures to the model; MCPServer hides plain exceptions' text."""
+
+    @functools.wraps(fn)
+    async def wrapper(*args, **kwargs):
+        try:
+            return await fn(*args, **kwargs)
+        except (ValueError, RuntimeError) as exc:
+            raise ToolError(str(exc)) from exc
+        except httpx.HTTPStatusError as exc:
+            raise ToolError(f"{exc.request.url.host} returned HTTP {exc.response.status_code}") from exc
+        except httpx.HTTPError as exc:
+            raise ToolError(f"Network error talking to {exc.request.url.host}: {exc}") from exc
+
+    return wrapper
+
+
+@mcp.tool(annotations=READ_ONLY)
+@_user_errors
+async def catalog_info() -> dict[str, Any]:
+    """Version and size of the NCBI Reference Gene Catalog in use."""
+    return (await state.get_catalog()).info()
+
+
+@mcp.tool(annotations=READ_ONLY)
+@_user_errors
+async def list_drug_classes() -> dict[str, Any]:
+    """All drug classes in the catalog with the number of entries for each."""
+    return {"drug_classes": (await state.get_catalog()).drug_classes()}
+
+
+@mcp.tool(annotations=READ_ONLY)
+@_user_errors
+async def search_amr_genes(
+    query: Annotated[
+        str | None, Field(description="Text in allele, gene family, product name or synonyms, e.g. 'KPC', 'mcr', 'carbapenemase'")
+    ] = None,
+    drug_class: Annotated[str | None, Field(description="e.g. BETA-LACTAM, COLISTIN, AMINOGLYCOSIDE")] = None,
+    subclass: Annotated[str | None, Field(description="e.g. CARBAPENEM, CEPHALOSPORIN")] = None,
+    organism: Annotated[
+        str | None, Field(description="Restrict to entries valid for this organism, e.g. 'Klebsiella pneumoniae'")
+    ] = None,
+    element_type: Annotated[Literal["AMR", "STRESS", "VIRULENCE"] | None, Field(description="Element type")] = None,
+    limit: Annotated[int, Field(ge=1, le=200)] = 25,
+) -> dict[str, Any]:
+    """Search the NCBI Reference Gene Catalog of AMR, stress and virulence genes and point mutations."""
+    catalog = await state.get_catalog()
+    return catalog.search(query, drug_class, subclass, organism, element_type, limit)
+
+
+@mcp.tool(annotations=READ_ONLY)
+@_user_errors
+async def get_amr_gene(
+    name: Annotated[str, Field(description="Exact allele (e.g. 'blaKPC-2') or gene family (e.g. 'blaKPC')")],
+) -> dict[str, Any]:
+    """Full catalog record for an allele, or a summary of all alleles in a gene family."""
+    result = (await state.get_catalog()).get(name)
+    if result["match"] is None:
+        raise ValueError(f"'{name}' is not in the catalog; try search_amr_genes for a fuzzy match")
+    return result
+
+
+@mcp.tool(annotations=READ_ONLY)
+@_user_errors
+async def fetch_sequence(
+    accession: Annotated[str, Field(description="NCBI accession, e.g. WP_004199234.1 or NG_049253.1")],
+    kind: Literal["protein", "nucleotide"] = "protein",
+) -> dict[str, Any]:
+    """Fetch a protein or nucleotide sequence from NCBI in FASTA form."""
+    return await state.ncbi.fetch_fasta(accession, kind)
+
+
+@mcp.tool(annotations=READ_ONLY)
+@_user_errors
+async def get_pubmed_references(
+    pmids: Annotated[list[str], Field(description="PubMed IDs, e.g. from a catalog entry's pubmed_reference", max_length=50)],
+) -> dict[str, Any]:
+    """Title, journal, date, authors and DOI for PubMed articles."""
+    return {"articles": await state.ncbi.pubmed_summaries(pmids)}
+
+
+@mcp.tool(annotations=READ_ONLY)
+@_user_errors
+async def search_uniprot(
+    query: Annotated[str, Field(description="UniProt query syntax, e.g. 'gene:KPC-2' or 'carbapenemase AND organism_id:573'")],
+    reviewed_only: Annotated[bool, Field(description="Only Swiss-Prot (manually reviewed) entries")] = False,
+    limit: Annotated[int, Field(ge=1, le=100)] = 10,
+) -> dict[str, Any]:
+    """Search UniProtKB proteins."""
+    return await state.uniprot.search(query, reviewed_only, limit)
+
+
+@mcp.tool(annotations=READ_ONLY)
+@_user_errors
+async def get_uniprot_entry(
+    accession: Annotated[str, Field(description="UniProt accession, e.g. Q9F663")],
+) -> dict[str, Any]:
+    """Function, keywords, cross-references and sequence of a UniProtKB entry."""
+    return await state.uniprot.entry(accession)
+
+
+@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=False))
+@_user_errors
+async def run_amrfinder(
+    fasta_path: Annotated[str, Field(description="Absolute path to a local FASTA file")],
+    sequence_type: Literal["nucleotide", "protein"] = "nucleotide",
+    organism: Annotated[
+        str | None, Field(description="Enables point-mutation screening, e.g. 'Escherichia', 'Klebsiella_pneumoniae'")
+    ] = None,
+) -> dict[str, Any]:
+    """Screen a local genome or proteome for AMR genes with AMRFinderPlus (must be installed locally)."""
+    return await amrfinder.run(fasta_path, sequence_type, organism)
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

amr_mcp-0.1.0/src/amr_mcp/uniprot.py

@@ -0,0 +1,76 @@
+"""Minimal UniProtKB REST client."""
+
+from __future__ import annotations
+
+import httpx
+
+UNIPROT = "https://rest.uniprot.org/uniprotkb"
+SEARCH_FIELDS = "accession,id,protein_name,gene_names,organism_name,length,reviewed"
+
+
+class UniProtClient:
+    def __init__(self, client: httpx.AsyncClient | None = None) -> None:
+        self._client = client or httpx.AsyncClient(timeout=30, follow_redirects=True)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def search(self, query: str, reviewed_only: bool = False, limit: int = 10) -> dict:
+        q = f"({query}) AND (reviewed:true)" if reviewed_only else query
+        resp = await self._client.get(
+            f"{UNIPROT}/search",
+            params={"query": q, "fields": SEARCH_FIELDS, "format": "json", "size": str(limit)},
+        )
+        resp.raise_for_status()
+        results = [_summarize(e) for e in resp.json().get("results", [])]
+        return {
+            "query": q,
+            "total_matches": int(resp.headers.get("x-total-results", len(results))),
+            "results": results,
+        }
+
+    async def entry(self, accession: str) -> dict:
+        resp = await self._client.get(f"{UNIPROT}/{accession.strip()}", params={"format": "json"})
+        if resp.status_code in (400, 404):
+            raise ValueError(f"UniProt entry '{accession}' not found")
+        resp.raise_for_status()
+        e = resp.json()
+        comments = {
+            c["commentType"]: " ".join(t["value"] for t in c.get("texts", []))
+            for c in e.get("comments", [])
+            if c.get("texts")
+        }
+        return {
+            **_summarize(e),
+            "function": comments.get("FUNCTION"),
+            "catalytic_activity": comments.get("CATALYTIC ACTIVITY"),
+            "keywords": [k["name"] for k in e.get("keywords", [])],
+            "cross_references": _xrefs(e, {"RefSeq", "EMBL", "PDB", "Pfam", "InterPro", "CARD"}),
+            "sequence": e.get("sequence", {}).get("value"),
+            "url": f"https://www.uniprot.org/uniprotkb/{e['primaryAccession']}",
+        }
+
+
+def _summarize(e: dict) -> dict:
+    desc = e.get("proteinDescription", {})
+    name = (
+        desc.get("recommendedName", {}).get("fullName", {}).get("value")
+        or next(iter(desc.get("submissionNames", [])), {}).get("fullName", {}).get("value")
+    )
+    return {
+        "accession": e.get("primaryAccession"),
+        "entry_name": e.get("uniProtkbId"),
+        "protein_name": name,
+        "genes": [g["geneName"]["value"] for g in e.get("genes", []) if "geneName" in g],
+        "organism": e.get("organism", {}).get("scientificName"),
+        "length": e.get("sequence", {}).get("length"),
+        "reviewed": e.get("entryType", "").startswith("UniProtKB reviewed"),
+    }
+
+
+def _xrefs(e: dict, dbs: set[str]) -> dict[str, list[str]]:
+    out: dict[str, list[str]] = {}
+    for x in e.get("uniProtKBCrossReferences", []):
+        if x["database"] in dbs:
+            out.setdefault(x["database"], []).append(x["id"])
+    return {k: v[:20] for k, v in out.items()}

amr_mcp-0.1.0/tests/fixtures/catalog_sample.tsv

@@ -0,0 +1,10 @@
+allele	gene_family	whitelisted_taxa	product_name	scope	type	subtype	class	subclass	refseq_protein_accession	refseq_nucleotide_accession	curated_refseq_start	genbank_protein_accession	genbank_nucleotide_accession	genbank_strand	genbank_start	genbank_stop	refseq_strand	refseq_start	refseq_stop	pubmed_reference	blacklisted_taxa	synonyms	hierarchy_node	db_version
+blaKPC-2	blaKPC		carbapenem-hydrolyzing class A beta-lactamase KPC-2	core	AMR	AMR	BETA-LACTAM	CARBAPENEM	WP_004199234.1	NG_049253.1	No	AAK70220.1	AY034847.1	+	6	887	+	6	887	12615876,37255469		blaKPC-1	blaKPC-2	2026-10-29.1
+blaKPC-20	blaKPC		carbapenem-hydrolyzing class A beta-lactamase KPC-20	core	AMR	AMR	BETA-LACTAM	CARBAPENEM	WP_436452774.1	NG_245797.1	No	MGK4321900.1	JBPQFE010000002.1	+	33852	34733	+	101	982				blaKPC-20	2026-10-29.1
+blaKPC-3	blaKPC		carbapenem-hydrolyzing class A beta-lactamase KPC-3	core	AMR	AMR	BETA-LACTAM	CARBAPENEM	WP_004152396.1	NG_049257.1	No	AAL05630.1	AF395881.1	+	1	882	+	1	882	15561858,19015357,37255469			blaKPC-3	2026-10-29.1
+mcr-1.1	mcr-1		phosphoethanolamine--lipid A transferase MCR-1.1	core	AMR	AMR	COLISTIN	COLISTIN	WP_049589868.1	NG_050417.1	No	AKF16168.1	KP347127.1	+	22413	24038	+	101	1726	26603172			mcr-1.1	2026-10-29.1
+adeL_G27R	adeL	Acinetobacter_baumannii	multidrug efflux transcriptional repressor AdeL	core	AMR	POINT	TETRACYCLINE	TIGECYCLINE	WP_002000718.1	NZ_CP091335.1	No	UMO35973.1	CP091335.1	+	73589	74620	+	73589	74620	35704614				2026-10-29.1
+	arsB		arsenite efflux transporter membrane subunit ArsB	plus	STRESS	METAL	ARSENIC	ARSENITE	WP_004152098.1		No	BAA24823.1	AB004659.1	+	3095	4384					Escherichia		arsB_pKW301	2026-10-29.1
+	kdeA		multidrug efflux MFS transporter KdeA	plus	AMR	AMR	EFFLUX	EFFLUX	WP_004141972.1		No	ABR76310.1	CP000647.1	+	980459	981691				17917272	Klebsiella_pneumoniae		kdeA	2026-10-29.1
+	aafA		aggregative adherence fimbria II major subunit AafA	plus	VIRULENCE	VIRULENCE			WP_077767014.1		No	BAJ79293.1	AB571091.1	+	34	516							aafA	2026-10-29.1
+16S_A523C	16S	Escherichia	16S ribosomal RNA	core	AMR	POINT	AMINOGLYCOSIDE	STREPTOMYCIN		NC_000913.3			U00096.3	+	4166659	4168201	+	4166659	4168201	3054810				2026-10-29.1

amr_mcp-0.1.0/tests/test_catalog.py

@@ -0,0 +1,79 @@
+from pathlib import Path
+
+import pytest
+
+from amr_mcp.catalog import Catalog
+
+FIXTURE = Path(__file__).parent / "fixtures" / "catalog_sample.tsv"
+
+
+@pytest.fixture
+def catalog() -> Catalog:
+    return Catalog.from_file(FIXTURE)
+
+
+def test_info(catalog):
+    info = catalog.info()
+    assert info["total_entries"] == 9
+    assert info["by_type"]["AMR"] == 7
+    assert info["db_version"] != "unknown"
+
+
+def test_drug_classes_sorted_by_count(catalog):
+    classes = catalog.drug_classes()
+    assert classes[0] == {"class": "BETA-LACTAM", "entries": 3}
+
+
+def test_search_by_text_is_case_insensitive(catalog):
+    result = catalog.search(query="kpc")
+    assert result["total_matches"] == 3
+    assert {r["allele"] for r in result["results"]} == {"blaKPC-2", "blaKPC-3", "blaKPC-20"}
+
+
+def test_search_limit(catalog):
+    result = catalog.search(query="kpc", limit=1)
+    assert result["total_matches"] == 3
+    assert result["returned"] == 1
+
+
+def test_search_by_class_and_type(catalog):
+    assert catalog.search(drug_class="colistin")["results"][0]["allele"] == "mcr-1.1"
+    assert catalog.search(element_type="VIRULENCE")["total_matches"] == 1
+
+
+def test_organism_whitelist(catalog):
+    # Acinetobacter-only point mutation is excluded for E. coli but included for A. baumannii.
+    assert "adeL_G27R" not in _alleles(catalog.search(organism="Escherichia coli", limit=100))
+    assert "adeL_G27R" in _alleles(catalog.search(organism="Acinetobacter baumannii", limit=100))
+    # Genus-level whitelist matches a species of that genus.
+    assert "16S_A523C" in _alleles(catalog.search(organism="Escherichia coli", limit=100))
+
+
+def test_organism_blacklist(catalog):
+    families = {r["gene_family"] for r in catalog.search(organism="Escherichia coli", limit=100)["results"]}
+    assert "arsB" not in families
+    assert "arsB" in {r["gene_family"] for r in catalog.search(organism="Salmonella enterica", limit=100)["results"]}
+
+
+def test_get_allele(catalog):
+    result = catalog.get("BLAKPC-2")
+    assert result["match"] == "allele"
+    entry = result["entries"][0]
+    assert entry["refseq_protein_accession"].startswith("WP_")
+    # Empty columns are dropped to keep responses small.
+    assert "whitelisted_taxa" not in entry
+
+
+def test_get_gene_family(catalog):
+    result = catalog.get("blaKPC")
+    assert result["match"] == "gene_family"
+    assert result["allele_count"] == 3
+    assert result["subclasses"] == ["CARBAPENEM"]
+
+
+def test_get_unknown(catalog):
+    assert catalog.get("notagene")["match"] is None
+
+
+def _alleles(result: dict) -> set[str]:
+    return {r.get("allele") for r in result["results"]}

amr_mcp-0.1.0/tests/test_live.py

@@ -0,0 +1,47 @@
+"""Smoke tests against the real NCBI and UniProt APIs. Skip with: pytest -m 'not network'."""
+
+import pytest
+
+from amr_mcp.catalog import load_catalog
+from amr_mcp.ncbi import NCBIClient
+from amr_mcp.uniprot import UniProtClient
+
+pytestmark = pytest.mark.network
+
+
+async def test_download_full_catalog(tmp_path):
+    catalog = await load_catalog(cache_dir=tmp_path)
+    assert len(catalog.rows) > 5000
+    assert catalog.get("blaKPC-2")["match"] == "allele"
+
+
+async def test_fetch_kpc2_protein():
+    ncbi = NCBIClient()
+    try:
+        seq = await ncbi.fetch_fasta("WP_004199234.1", "protein")
+    finally:
+        await ncbi.aclose()
+    assert "KPC" in seq["header"]
+    assert 280 <= seq["length"] <= 300
+
+
+async def test_pubmed_summary():
+    ncbi = NCBIClient()
+    try:
+        refs = await ncbi.pubmed_summaries(["12615876"])
+    finally:
+        await ncbi.aclose()
+    assert refs[0]["pmid"] == "12615876"
+    assert refs[0]["title"]
+
+
+async def test_uniprot_search_and_entry():
+    uniprot = UniProtClient()
+    try:
+        found = await uniprot.search("gene:KPC-2", reviewed_only=True, limit=3)
+        assert found["results"]
+        entry = await uniprot.entry(found["results"][0]["accession"])
+    finally:
+        await uniprot.aclose()
+    assert entry["sequence"]
+    assert entry["reviewed"] is True

amr_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,55 @@
+"""End-to-end tests through an in-process MCP client."""
+
+from pathlib import Path
+
+import pytest
+from mcp import Client
+
+from amr_mcp import server
+from amr_mcp.catalog import Catalog
+
+FIXTURE = Path(__file__).parent / "fixtures" / "catalog_sample.tsv"
+
+EXPECTED_TOOLS = {
+    "catalog_info",
+    "list_drug_classes",
+    "search_amr_genes",
+    "get_amr_gene",
+    "fetch_sequence",
+    "get_pubmed_references",
+    "search_uniprot",
+    "get_uniprot_entry",
+    "run_amrfinder",
+}
+
+
+@pytest.fixture(autouse=True)
+def offline_catalog(monkeypatch):
+    monkeypatch.setattr(server.state, "catalog", Catalog.from_file(FIXTURE))
+
+
+async def test_lists_all_tools():
+    async with Client(server.mcp) as client:
+        tools = {t.name for t in (await client.list_tools()).tools}
+    assert tools == EXPECTED_TOOLS
+
+
+async def test_search_tool_returns_structured_content():
+    async with Client(server.mcp) as client:
+        result = await client.call_tool("search_amr_genes", {"query": "KPC", "limit": 2})
+    assert not result.is_error
+    assert result.structured_content["total_matches"] == 3
+    assert len(result.structured_content["results"]) == 2
+
+
+async def test_unknown_gene_is_a_tool_error():
+    async with Client(server.mcp) as client:
+        result = await client.call_tool("get_amr_gene", {"name": "notagene"})
+    assert result.is_error
+    assert "search_amr_genes" in result.content[0].text
+
+
+async def test_bad_accession_is_rejected_before_any_request():
+    async with Client(server.mcp) as client:
+        result = await client.call_tool("fetch_sequence", {"accession": "rm -rf /"})
+    assert result.is_error