catapult-mcp 0.2.0__tar.gz

catapult_mcp-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write  # trusted publishing (OIDC)
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - run: uv venv
+      - run: uv pip install -e ".[dev]"
+      - run: uv run --no-sync pytest
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

catapult_mcp-0.2.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# UV
+uv.lock
+
+# Data
+*.acatome/
+inbox/
+completed/
+errors/

catapult_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to **catapult-mcp** will be documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.1.0] — 2026-03-11
+
+### Added
+
+- Initial release.

catapult_mcp-0.2.0/LICENSE

@@ -0,0 +1,17 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2024-2026 Reto Stamm
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.

catapult_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: catapult-mcp
+Version: 0.2.0
+Summary: MCP server for querying heterogeneous catalysis databases
+Author-email: Reto Stamm <reto@retostamm.com>
+License-Expression: GPL-3.0-or-later
+License-File: LICENSE
+Keywords: catalysis,chemistry,database,materials-science,mcp
+Requires-Python: >=3.11
+Requires-Dist: chemdb-common>=0.1.0
+Requires-Dist: mcp>=1.0
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.0; extra == 'postgres'

catapult_mcp-0.2.0/README.md

@@ -0,0 +1,32 @@
+# catapult-mcp
+
+MCP server for querying heterogeneous catalysis databases. Exposes reaction data, catalysts, and conditions via the Model Context Protocol.
+
+## Features
+
+- **Reaction search** — query by catalyst, reactant, product, or conditions
+- **SQLAlchemy backend** — SQLite (default) or PostgreSQL
+- **MCP protocol** — compatible with any MCP-aware LLM client
+
+## Installation
+
+```bash
+uv pip install -e .
+# With PostgreSQL support:
+uv pip install -e ".[postgres]"
+```
+
+## Usage
+
+```bash
+catapult-mcp   # starts the MCP server
+```
+
+## Dependencies
+
+- **chemdb-common** — shared database models and CLI
+- **mcp** — Model Context Protocol server framework
+
+## License
+
+GPL-3.0-or-later — see [LICENSE](LICENSE).

catapult_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "catapult-mcp"
+version = "0.2.0"
+description = "MCP server for querying heterogeneous catalysis databases"
+requires-python = ">=3.11"
+license = "GPL-3.0-or-later"
+authors = [{name = "Reto Stamm", email = "reto@retostamm.com"}]
+keywords = ["mcp", "catalysis", "chemistry", "materials-science", "database"]
+dependencies = [
+    "chemdb-common>=0.1.0",
+    "mcp>=1.0",
+]
+
+[project.optional-dependencies]
+postgres = [
+    "psycopg[binary]>=3.0",
+]
+dev = [
+    "pytest>=8.0",
+    "black>=24.0",
+    "ruff>=0.5",
+]
+
+[project.scripts]
+catapult-mcp = "catapult.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/catapult"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.black]
+line-length = 88
+
+[tool.ruff]
+line-length = 88
+
+[tool.bumpversion]
+current_version = "0.2.0"
+commit = true
+tag = true
+tag_name = "v{new_version}"
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "src/catapult/__init__.py"
+search = '__version__ = "{current_version}"'
+replace = '__version__ = "{new_version}"'

catapult_mcp-0.2.0/src/catapult/__init__.py

@@ -0,0 +1,3 @@
+"""CataPult — MCP server for heterogeneous catalysis databases."""
+
+__version__ = "0.2.0"

catapult_mcp-0.2.0/src/catapult/db/query.py

@@ -0,0 +1,238 @@
+"""Read-only queries for the catapult_get tool.
+
+All queries are local SQL — no runtime API calls.
+Shape is computed on-the-fly via SQL aggregation.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import func, text
+from sqlalchemy.orm import Session
+
+from chemdb.errors import IdNotFoundError, InvalidRangeError, NoResultsError
+from chemdb.ranges import parse_range
+from chemdb.sort import parse_sort
+
+from catapult.db.schema import Reaction
+
+PAGE_SIZE = 10
+
+SORTABLE_FIELDS = {"energy", "barrier", "catalyst", "facet", "relevance"}
+
+
+def get_by_id(session: Session, id_str: str) -> dict[str, Any]:
+    """Look up reactions by identifier (doi:, pub:, sys:, or bare string)."""
+    scheme, _, ident = id_str.partition(":")
+    if not ident:
+        # Bare string → publication ID search
+        ident = scheme
+        scheme = "pub"
+
+    q = session.query(Reaction)
+    if scheme == "doi":
+        q = q.filter(Reaction.doi == ident)
+    elif scheme == "pub":
+        q = q.filter(Reaction.pub_id.ilike(f"%{ident}%"))
+    elif scheme == "sys":
+        q = q.filter(Reaction.sys_id == ident)
+    else:
+        raise IdNotFoundError(id_str)
+
+    results = q.all()
+    if not results:
+        raise IdNotFoundError(id_str)
+
+    return {
+        "type": "publication",
+        "id": id_str,
+        "total": len(results),
+        "results": [_rxn_to_row(r) for r in results[:PAGE_SIZE]],
+    }
+
+
+def search(
+    session: Session,
+    *,
+    query: str = "",
+    catalyst: str = "",
+    facet: str = "",
+    reactants: str = "",
+    products: str = "",
+    energy: str = "",
+    barrier: str = "",
+    functional: str = "",
+    database: str = "",
+    sort: str = "",
+    page: int = 1,
+) -> dict[str, Any]:
+    """Filter search with shape + paginated results."""
+    q = session.query(Reaction)
+
+    # Catalyst filter (OR logic for comparison)
+    catalysts = []
+    if catalyst:
+        catalysts = [c.strip() for c in catalyst.split(",") if c.strip()]
+        if len(catalysts) == 1:
+            q = q.filter(Reaction.catalyst.ilike(f"%{catalysts[0]}%"))
+        else:
+            from sqlalchemy import or_
+
+            q = q.filter(or_(*[Reaction.catalyst.ilike(f"%{c}%") for c in catalysts]))
+
+    if facet:
+        q = q.filter(Reaction.facet == facet)
+
+    if reactants:
+        q = q.filter(Reaction.reactants.ilike(f"%{reactants}%"))
+
+    if products:
+        q = q.filter(Reaction.products.ilike(f"%{products}%"))
+
+    # Range filters
+    for field_name, raw in [("energy", energy), ("barrier", barrier)]:
+        if raw:
+            try:
+                r = parse_range(raw)
+            except ValueError:
+                raise InvalidRangeError(field_name, raw)
+            clause, params = r.to_sql_clause(field_name)
+            q = q.filter(text(clause).bindparams(**params))
+
+    if functional:
+        q = q.filter(Reaction.functional.ilike(functional))
+
+    if database:
+        q = q.filter(Reaction.database.ilike(database))
+
+    total = q.count()
+    if total == 0:
+        raise NoResultsError()
+
+    # Comparison mode: multiple catalysts
+    is_comparison = len(catalysts) > 1
+
+    # Sort
+    sort_fields = parse_sort(sort, SORTABLE_FIELDS) if sort else []
+    if sort_fields:
+        for sf in sort_fields:
+            if sf.name == "relevance":
+                continue
+            col = getattr(Reaction, sf.name, None)
+            if col is not None:
+                q = q.order_by(col.desc() if sf.descending else col.asc())
+    else:
+        q = q.order_by(Reaction.energy.asc())
+
+    offset = (page - 1) * PAGE_SIZE
+    results = q.offset(offset).limit(PAGE_SIZE).all()
+
+    shape = _compute_shape(session, q) if page == 1 else None
+
+    # For comparison mode, also compute per-catalyst best
+    comparison = None
+    if is_comparison and page == 1:
+        comparison = _compute_comparison(session, q, catalysts)
+
+    return {
+        "total": total,
+        "page": page,
+        "page_size": PAGE_SIZE,
+        "shape": shape,
+        "comparison": comparison,
+        "results": [_rxn_to_row(r) for r in results],
+    }
+
+
+def get_shape(session: Session) -> dict[str, Any]:
+    """Shape of entire database (no-arg call)."""
+    total = session.query(Reaction).count()
+    if total == 0:
+        return {"total": 0}
+
+    shape = _compute_shape(session, session.query(Reaction))
+    shape["total"] = total
+    return shape
+
+
+def _compute_shape(session: Session, q) -> dict[str, Any]:
+    """Compute shape statistics from a query."""
+    stats = session.query(
+        func.count(Reaction.id),
+        func.min(Reaction.energy),
+        func.max(Reaction.energy),
+        func.avg(Reaction.energy),
+        func.min(Reaction.barrier),
+        func.max(Reaction.barrier),
+        func.avg(Reaction.barrier),
+    ).one()
+
+    # Top catalysts
+    cat_counts = (
+        session.query(Reaction.catalyst, func.count(Reaction.id))
+        .group_by(Reaction.catalyst)
+        .order_by(func.count(Reaction.id).desc())
+        .limit(10)
+        .all()
+    )
+
+    # Top facets
+    facet_counts = (
+        session.query(Reaction.facet, func.count(Reaction.id))
+        .filter(Reaction.facet.isnot(None), Reaction.facet != "")
+        .group_by(Reaction.facet)
+        .order_by(func.count(Reaction.id).desc())
+        .limit(10)
+        .all()
+    )
+
+    # Functionals
+    func_counts = (
+        session.query(Reaction.functional, func.count(Reaction.id))
+        .filter(Reaction.functional.isnot(None), Reaction.functional != "")
+        .group_by(Reaction.functional)
+        .order_by(func.count(Reaction.id).desc())
+        .limit(10)
+        .all()
+    )
+
+    return {
+        "energy": {"min": stats[1], "max": stats[2], "avg": stats[3]},
+        "barrier": {"min": stats[4], "max": stats[5], "avg": stats[6]},
+        "catalysts": {cat: count for cat, count in cat_counts},
+        "facets": {f: count for f, count in facet_counts},
+        "functionals": {f: count for f, count in func_counts},
+    }
+
+
+def _compute_comparison(
+    session: Session, q, catalysts: list[str]
+) -> list[dict[str, Any]]:
+    """Best (lowest energy) row per catalyst for comparison table."""
+    rows = []
+    for cat in catalysts:
+        best = (
+            q.filter(Reaction.catalyst.ilike(f"%{cat}%"))
+            .order_by(Reaction.energy.asc())
+            .first()
+        )
+        if best:
+            rows.append(_rxn_to_row(best))
+    return rows
+
+
+def _rxn_to_row(r: Reaction) -> dict[str, Any]:
+    """Summary row for a reaction."""
+    return {
+        "equation": r.equation,
+        "catalyst": r.catalyst,
+        "facet": r.facet,
+        "energy": r.energy,
+        "barrier": r.barrier,
+        "site": r.site,
+        "functional": r.functional,
+        "database": r.database,
+        "doi": r.doi,
+        "pub_id": r.pub_id,
+    }

catapult_mcp-0.2.0/src/catapult/db/schema.py

@@ -0,0 +1,65 @@
+"""SQLAlchemy models for local catalysis reaction data."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import (
+    Column,
+    DateTime,
+    Float,
+    Index,
+    Integer,
+    String,
+    Text,
+)
+from sqlalchemy.orm import DeclarativeBase
+
+SCHEMA = "catapult"
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Reaction(Base):
+    """A DFT-computed catalytic reaction."""
+
+    __tablename__ = "reactions"
+    __table_args__ = {"schema": SCHEMA}
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    equation = Column(Text, nullable=False)
+    catalyst = Column(String(128), nullable=False, index=True)
+    facet = Column(String(64), nullable=True, index=True)
+    reactants = Column(Text, nullable=True)  # comma-separated
+    products = Column(Text, nullable=True)  # comma-separated
+    energy = Column(Float, nullable=True)  # reaction energy ΔE, eV
+    barrier = Column(Float, nullable=True)  # activation barrier Ea, eV
+    site = Column(Text, nullable=True)
+    functional = Column(String(64), nullable=True)
+    dft_code = Column(String(64), nullable=True)
+    database = Column(String(32), nullable=False)  # cathub, mp
+    doi = Column(Text, nullable=True)
+    pub_id = Column(String(128), nullable=True, index=True)
+    sys_id = Column(String(128), nullable=True)
+
+
+class SyncLog(Base):
+    """Sync history."""
+
+    __tablename__ = "sync_log"
+    __table_args__ = {"schema": SCHEMA}
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    source = Column(String(64), nullable=False)
+    synced_at = Column(DateTime, nullable=False, default=datetime.utcnow)
+    row_count = Column(Integer, nullable=False, default=0)
+    duration_s = Column(Float, nullable=True)
+
+
+# Indexes for common queries
+Index("idx_reactions_energy", Reaction.energy)
+Index("idx_reactions_barrier", Reaction.barrier)
+Index("idx_reactions_functional", Reaction.functional)
+Index("idx_reactions_database", Reaction.database)

catapult_mcp-0.2.0/src/catapult/db/sync.py

@@ -0,0 +1,202 @@
+"""Sync upstream catalysis databases to local storage.
+
+Fetches data from Catalysis-Hub GraphQL and (optionally) Materials Project,
+then upserts into the local DB (Postgres schema or SQLite file).
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from datetime import datetime
+
+from chemdb.config import ChemdbConfig
+from chemdb.db import ensure_schema, make_engine, make_session
+from catapult.db.schema import SCHEMA, Base, Reaction, SyncLog
+
+log = logging.getLogger(__name__)
+
+CATHUB_GRAPHQL = "https://api.catalysis-hub.org/graphql"
+CATHUB_PAGE_SIZE = 200
+
+
+class CatapultSyncer:
+    """Downloads catalysis data from upstream sources into local DB."""
+
+    def __init__(self, config: ChemdbConfig):
+        self.config = config
+        self.engine = make_engine(config, SCHEMA)
+        self.Session = make_session(self.engine)
+
+    def run(self, *, force: bool = False):
+        """Run the full sync."""
+        ensure_schema(self.engine, SCHEMA)
+
+        if force:
+            Base.metadata.drop_all(self.engine)
+
+        Base.metadata.create_all(self.engine)
+
+        t0 = time.time()
+
+        count = self._sync_cathub()
+        if self.config.mp_api_key:
+            count += self._sync_mp()
+
+        duration = time.time() - t0
+        self._log_sync("all", count, duration)
+        log.info("Sync complete: %d rows in %.1fs", count, duration)
+
+    def _sync_cathub(self) -> int:
+        """Fetch reactions from Catalysis-Hub GraphQL API.
+
+        Uses keyset pagination: id > last_id, ordered by id.
+        """
+        import base64
+        import httpx
+
+        log.info("Syncing from Catalysis-Hub...")
+        count = 0
+        last_id = 0
+
+        with self.Session() as session:
+            while True:
+                query = _cathub_query(last_id, CATHUB_PAGE_SIZE)
+                try:
+                    resp = httpx.post(
+                        CATHUB_GRAPHQL,
+                        json={"query": query},
+                        timeout=60,
+                    )
+                    resp.raise_for_status()
+                except Exception as exc:
+                    log.error("Catalysis-Hub fetch failed: %s", exc)
+                    break
+
+                data = resp.json()
+                reactions = data.get("data", {}).get("reactions")
+                if reactions is None:
+                    errors = data.get("errors", [])
+                    log.error("GraphQL error: %s", errors)
+                    break
+
+                edges = reactions.get("edges", [])
+                if not edges:
+                    break
+
+                for edge in edges:
+                    node = edge.get("node", {})
+                    # Extract numeric id from base64 "Reaction:NNN"
+                    raw_id = node.get("id", "")
+                    try:
+                        decoded = base64.b64decode(raw_id).decode()
+                        last_id = int(decoded.split(":", 1)[1])
+                    except Exception:
+                        pass
+
+                    rxn = self._cathub_to_model(node)
+                    if rxn:
+                        session.add(rxn)
+                        count += 1
+
+                session.flush()
+                if count % 5000 < CATHUB_PAGE_SIZE:
+                    session.commit()
+                    log.info("  %d reactions (last_id=%d)...", count, last_id)
+
+                if len(edges) < CATHUB_PAGE_SIZE:
+                    break
+
+            session.commit()
+
+        return count
+
+    def _sync_mp(self) -> int:
+        """Fetch bulk properties from Materials Project."""
+        log.info("MP sync: not yet implemented (needs mp-api client)")
+        return 0
+
+    def _cathub_to_model(self, node: dict) -> Reaction | None:
+        """Convert a Catalysis-Hub GraphQL node to a Reaction model."""
+        equation = node.get("Equation", "")
+        if not equation:
+            return None
+
+        # Parse reactants/products from equation
+        reactants = ""
+        products = ""
+        if " -> " in equation:
+            parts = equation.split(" -> ", 1)
+            reactants = parts[0].strip()
+            products = parts[1].strip()
+
+        # Prefer JSON reactants/products fields if available, else parse equation
+        raw_reactants = node.get("reactants") or ""
+        raw_products = node.get("products") or ""
+        if raw_reactants and isinstance(raw_reactants, str) and raw_reactants != "{}":
+            reactants = raw_reactants
+        if raw_products and isinstance(raw_products, str) and raw_products != "{}":
+            products = raw_products
+
+        return Reaction(
+            equation=equation,
+            catalyst=node.get("chemicalComposition", ""),
+            facet=node.get("facet", ""),
+            reactants=reactants,
+            products=products,
+            energy=_float(node.get("reactionEnergy")),
+            barrier=_float(node.get("activationEnergy")),
+            site=node.get("sites", ""),
+            functional=node.get("dftFunctional", ""),
+            dft_code=node.get("dftCode", ""),
+            database="cathub",
+            pub_id=node.get("pubId"),
+        )
+
+    def _log_sync(self, source: str, count: int, duration: float):
+        with self.Session() as session:
+            session.add(
+                SyncLog(
+                    source=source,
+                    synced_at=datetime.utcnow(),
+                    row_count=count,
+                    duration_s=duration,
+                )
+            )
+            session.commit()
+
+
+def _cathub_query(last_id: int, page_size: int) -> str:
+    """Build a Catalysis-Hub GraphQL query with keyset pagination."""
+    id_filter = f', id: {last_id}, op: ">"' if last_id > 0 else ""
+    return f"""{{
+  reactions(first: {page_size}, order: "id"{id_filter}) {{
+    totalCount
+    edges {{
+      node {{
+        id
+        Equation
+        reactionEnergy
+        activationEnergy
+        chemicalComposition
+        surfaceComposition
+        facet
+        sites
+        reactants
+        products
+        pubId
+        dftCode
+        dftFunctional
+      }}
+    }}
+  }}
+}}"""
+
+
+def _float(v) -> float | None:
+    if v is None:
+        return None
+    try:
+        return float(v)
+    except (ValueError, TypeError):
+        return None

catapult_mcp-0.2.0/src/catapult/server.py

@@ -0,0 +1,73 @@
+"""MCP server for CataPult — one tool: catapult_get.
+
+Queries heterogeneous catalysis databases (Catalysis-Hub, Materials Project).
+All data is local (Postgres or SQLite). Run ``chemdb sync catapult`` first.
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from catapult import tool
+
+mcp = FastMCP("catapult")
+
+
+@mcp.tool()
+def catapult_get(
+    id: str = "",
+    query: str = "",
+    catalyst: str = "",
+    facet: str = "",
+    reactants: str = "",
+    products: str = "",
+    energy: str = "",
+    barrier: str = "",
+    functional: str = "",
+    database: str = "",
+    sort: str = "",
+    page: int = 1,
+) -> str:
+    """Query heterogeneous catalysis databases.
+
+    id: identifier — "doi:10.1021/...", "pub:xyz", "sys:abc"
+    query: FTS5 full-text search (always AND with filters)
+    catalyst: composition, OR/comparison logic ("Pd", "Pd,Pt,Cu" = compare)
+    facet: Miller index ("111", "100")
+    reactants: reactant formula ("CO", "H2O")
+    products: product formula
+    energy: reaction energy range, eV ("-1.5..0", "<-0.5")
+    barrier: activation barrier range, eV ("<1.0")
+    functional: DFT method filter ("BEEF-vdW", "PBE")
+    database: source filter ("cathub", "mp")
+    sort: sort order ("energy", "!barrier", "energy,catalyst")
+    page: page number (10 results/page)
+
+    No args → shape of entire database (catalyst counts, energy ranges, top facets).
+    id provided → all reactions from that publication.
+    Any filter → search with results + shape on page 1.
+    Multi-catalyst → comparison table (best per catalyst).
+    """
+    return tool.catapult_get(
+        id=id,
+        query=query,
+        catalyst=catalyst,
+        facet=facet,
+        reactants=reactants,
+        products=products,
+        energy=energy,
+        barrier=barrier,
+        functional=functional,
+        database=database,
+        sort=sort,
+        page=page,
+    )
+
+
+def main():
+    """Run the MCP server (stdio transport)."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

catapult_mcp-0.2.0/src/catapult/tool.py

@@ -0,0 +1,279 @@
+"""catapult_get implementation — formats query results as markdown strings."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from chemdb.cite import format_citation
+from chemdb.config import ChemdbConfig, load_config
+from chemdb.db import make_engine, make_session
+from chemdb.errors import ChemdbError
+
+from catapult.db.query import PAGE_SIZE, get_by_id, get_shape, search
+from catapult.db.schema import SCHEMA
+
+_config: ChemdbConfig | None = None
+_SessionFactory = None
+
+
+def _get_session():
+    global _config, _SessionFactory
+    if _SessionFactory is None:
+        _config = load_config()
+        engine = make_engine(_config, SCHEMA)
+        _SessionFactory = make_session(engine)
+    return _SessionFactory()
+
+
+def catapult_get(
+    id: str = "",
+    query: str = "",
+    catalyst: str = "",
+    facet: str = "",
+    reactants: str = "",
+    products: str = "",
+    energy: str = "",
+    barrier: str = "",
+    functional: str = "",
+    database: str = "",
+    sort: str = "",
+    page: int = 1,
+) -> str:
+    """Query heterogeneous catalysis databases.
+
+    Returns formatted markdown with results, shape, and hints.
+    """
+    try:
+        session = _get_session()
+
+        # ID lookup mode
+        if id:
+            data = get_by_id(session, id)
+            return _format_publication(data)
+
+        # No args → shape of entire database
+        has_filters = any(
+            [
+                query,
+                catalyst,
+                facet,
+                reactants,
+                products,
+                energy,
+                barrier,
+                functional,
+                database,
+                sort,
+            ]
+        )
+        if not has_filters and page == 1:
+            data = get_shape(session)
+            return _format_shape(data)
+
+        # Filter search
+        data = search(
+            session,
+            query=query,
+            catalyst=catalyst,
+            facet=facet,
+            reactants=reactants,
+            products=products,
+            energy=energy,
+            barrier=barrier,
+            functional=functional,
+            database=database,
+            sort=sort,
+            page=page,
+        )
+        return _format_search(data, catalyst=catalyst)
+
+    except ChemdbError as exc:
+        return exc.to_markdown()
+    except Exception as exc:
+        return f"⚠ Internal error: {exc}"
+
+
+# ── Formatters ──────────────────────────────────────────────────────
+
+
+def _format_publication(data: dict[str, Any]) -> str:
+    """Format publication/ID lookup results."""
+    total = data["total"]
+    results = data["results"]
+
+    lines = [f"## {total} reactions for {data['id']}"]
+    lines.append("")
+
+    for i, r in enumerate(results, 1):
+        lines.append(_format_rxn_line(i, r))
+
+    if total > PAGE_SIZE:
+        lines.append("")
+        lines.append(f'→ catapult_get(id="{data["id"]}", page=2) for next {PAGE_SIZE}')
+
+    return "\n".join(lines)
+
+
+def _format_shape(data: dict[str, Any]) -> str:
+    """Format full database shape (no-arg call)."""
+    total = data.get("total", 0)
+
+    lines = [f"## CataPult — ~{total:,} reactions"]
+    lines.append("")
+
+    cats = data.get("catalysts", {})
+    if cats:
+        lines.append("### Top catalysts (by reaction count)")
+        parts = [f"{cat} {count:,}" for cat, count in list(cats.items())[:8]]
+        lines.append(" | ".join(parts))
+
+    facets = data.get("facets", {})
+    if facets:
+        lines.append("")
+        lines.append("### Facets")
+        parts = [f"{f} {count:,}" for f, count in list(facets.items())[:8]]
+        lines.append(" | ".join(parts))
+
+    e = data.get("energy", {})
+    b = data.get("barrier", {})
+    if e.get("min") is not None:
+        lines.append("")
+        lines.append("### Energy ranges")
+        lines.append("| Property | Min | Avg | Max | Unit |")
+        lines.append("|----------|-----|-----|-----|------|")
+        if e.get("min") is not None:
+            lines.append(
+                f"| ΔE (reaction) | {e['min']:.1f} | {e['avg']:.1f} | {e['max']:.1f} | eV |"
+            )
+        if b.get("min") is not None:
+            lines.append(
+                f"| Ea (barrier) | {b['min']:.1f} | {b['avg']:.1f} | {b['max']:.1f} | eV |"
+            )
+
+    funcs = data.get("functionals", {})
+    if funcs:
+        lines.append("")
+        lines.append("### Functionals")
+        parts = [f"{f} {count:,}" for f, count in list(funcs.items())[:6]]
+        lines.append(" | ".join(parts))
+
+    lines.append("")
+    lines.append("### Sortable fields")
+    lines.append("energy, barrier, catalyst, facet")
+    lines.append("")
+    lines.append('→ catapult_get(catalyst="Pd") to browse palladium reactions')
+    lines.append(
+        '→ catapult_get(reactants="CO", catalyst="Pd,Pt,Cu", facet="111") to compare metals'
+    )
+    lines.append('→ catapult_get(query="oxygen evolution") for free-text search')
+
+    return "\n".join(lines)
+
+
+def _format_search(data: dict[str, Any], catalyst: str = "") -> str:
+    """Format search results with shape + hints."""
+    total = data["total"]
+    page = data["page"]
+    start = (page - 1) * PAGE_SIZE + 1
+    end = min(start + PAGE_SIZE - 1, total)
+    comparison = data.get("comparison")
+
+    # Comparison mode
+    if comparison:
+        return _format_comparison(data, catalyst)
+
+    lines = [f"## {total} reactions (showing {start}–{end})"]
+    lines.append("")
+
+    # Shape on page 1
+    shape = data.get("shape")
+    if shape:
+        lines.append("### Shape")
+        e = shape.get("energy", {})
+        b = shape.get("barrier", {})
+        if e.get("min") is not None:
+            lines.append(
+                f"  ΔE  {e['min']:.1f} to {e['max']:.1f} eV  (mean {e['avg']:.2f})"
+            )
+        if b.get("min") is not None:
+            lines.append(
+                f"  Ea  {b['min']:.1f}–{b['max']:.1f} eV  (mean {b['avg']:.2f})"
+            )
+        facets = shape.get("facets", {})
+        if facets:
+            parts = [f"{f} ×{count}" for f, count in list(facets.items())[:5]]
+            lines.append(f"  Facets: {' | '.join(parts)}")
+        funcs = shape.get("functionals", {})
+        if funcs:
+            parts = [f"{f} {count}" for f, count in list(funcs.items())[:4]]
+            lines.append(f"  Functionals: {' | '.join(parts)}")
+        lines.append("")
+
+    for i, r in enumerate(data["results"], start):
+        lines.append(_format_rxn_line(i, r))
+
+    # Hints
+    lines.append("")
+    if end < total:
+        lines.append(f"→ catapult_get(..., page={page + 1}) for next {PAGE_SIZE}")
+    if data["results"] and data["results"][0].get("doi"):
+        doi = data["results"][0]["doi"]
+        lines.append(f'→ catapult_get(id="doi:{doi}") for full pub details')
+
+    return "\n".join(lines)
+
+
+def _format_comparison(data: dict[str, Any], catalyst: str) -> str:
+    """Format multi-catalyst comparison table."""
+    comparison = data["comparison"]
+    total = data["total"]
+
+    lines = [f"## Comparison — {len(comparison)} catalysts ({total} total reactions)"]
+    lines.append("")
+    lines.append("| Surface | ΔE (eV) | Ea (eV) | Site | Functional | Source |")
+    lines.append("|---------|---------|---------|------|------------|--------|")
+
+    for r in comparison:
+        cat_facet = r.get("catalyst", "?")
+        if r.get("facet"):
+            cat_facet += f"({r['facet']})"
+        energy_s = f"{r['energy']:.2f}" if r.get("energy") is not None else "?"
+        barrier_s = f"{r['barrier']:.2f}" if r.get("barrier") is not None else "?"
+        cite = r.get("doi", "")
+        if cite:
+            cite = f"[@{cite}]"
+        lines.append(
+            f"| {cat_facet} | {energy_s} | {barrier_s} | {r.get('site', '')} | {r.get('functional', '')} | {cite} |"
+        )
+
+    lines.append("")
+    cats = catalyst.split(",")
+    if cats:
+        lines.append(
+            f'→ catapult_get(catalyst="{cats[0].strip()}") for all {cats[0].strip()} reactions'
+        )
+
+    return "\n".join(lines)
+
+
+def _format_rxn_line(i: int, r: dict[str, Any]) -> str:
+    """Format a single reaction result line."""
+    cat_facet = r.get("catalyst", "?")
+    if r.get("facet"):
+        cat_facet += f"({r['facet']})"
+
+    parts = [f"{cat_facet} — {r.get('equation', '?')}"]
+    if r.get("energy") is not None:
+        parts.append(f"ΔE {r['energy']:.2f} eV")
+    if r.get("barrier") is not None:
+        parts.append(f"Ea {r['barrier']:.2f} eV")
+    if r.get("functional"):
+        parts.append(r["functional"])
+
+    line = f"{i:>2}. {parts[0]}    {'  |  '.join(parts[1:])}"
+
+    if r.get("doi"):
+        cite = format_citation(r["doi"])
+        line += f"\n    {cite}"
+
+    return line

catapult_mcp-0.2.0/tests/conftest.py

@@ -0,0 +1,114 @@
+"""Shared fixtures for catapult tests."""
+
+from __future__ import annotations
+
+import pytest
+from sqlalchemy import create_engine, event
+from sqlalchemy.orm import sessionmaker
+
+from catapult.db.schema import Base, Reaction
+
+
+@pytest.fixture
+def engine():
+    """In-memory SQLite engine with schema tables."""
+    eng = create_engine(
+        "sqlite:///:memory:",
+        execution_options={"schema_translate_map": {"catapult": None}},
+    )
+
+    @event.listens_for(eng, "connect")
+    def _set_pragma(dbapi_conn, connection_record):
+        cursor = dbapi_conn.cursor()
+        cursor.execute("PRAGMA journal_mode=WAL")
+        cursor.close()
+
+    Base.metadata.create_all(eng)
+    return eng
+
+
+@pytest.fixture
+def session(engine):
+    """Session with sample reaction data."""
+    Session = sessionmaker(bind=engine)
+    s = Session()
+
+    reactions = [
+        Reaction(
+            equation="CO* -> CO2",
+            catalyst="Pd",
+            facet="111",
+            reactants="CO",
+            products="CO2",
+            energy=-0.72,
+            barrier=0.89,
+            site="fcc",
+            functional="BEEF-vdW",
+            database="cathub",
+            doi="10.1021/acscatal.7b02335",
+            pub_id="MedfordEtAl2017",
+            sys_id="rxn_001",
+        ),
+        Reaction(
+            equation="CO* -> CO2",
+            catalyst="Pd",
+            facet="100",
+            reactants="CO",
+            products="CO2",
+            energy=-0.58,
+            barrier=1.02,
+            site="bridge",
+            functional="BEEF-vdW",
+            database="cathub",
+            doi="10.1021/acscatal.7b02335",
+            pub_id="MedfordEtAl2017",
+            sys_id="rxn_002",
+        ),
+        Reaction(
+            equation="CO* -> CO2",
+            catalyst="Pt",
+            facet="111",
+            reactants="CO",
+            products="CO2",
+            energy=-0.91,
+            barrier=0.78,
+            site="atop",
+            functional="BEEF-vdW",
+            database="cathub",
+            doi="10.1021/acscatal.7b02335",
+            pub_id="MedfordEtAl2017",
+            sys_id="rxn_003",
+        ),
+        Reaction(
+            equation="H2O* -> OH* + H*",
+            catalyst="Cu",
+            facet="111",
+            reactants="H2O",
+            products="OH,H",
+            energy=-0.33,
+            barrier=1.35,
+            site="fcc",
+            functional="PBE",
+            database="cathub",
+            doi="10.1021/ja5088237",
+            pub_id="NorskovEtAl2014",
+            sys_id="rxn_004",
+        ),
+        Reaction(
+            equation="O2* -> 2O*",
+            catalyst="Pt",
+            facet="111",
+            reactants="O2",
+            products="O",
+            energy=-1.45,
+            barrier=0.52,
+            site="bridge",
+            functional="RPBE",
+            database="cathub",
+            sys_id="rxn_005",
+        ),
+    ]
+    s.add_all(reactions)
+    s.commit()
+    yield s
+    s.close()

catapult_mcp-0.2.0/tests/test_query.py

@@ -0,0 +1,84 @@
+"""Tests for catapult.db.query."""
+
+from __future__ import annotations
+
+import pytest
+
+from chemdb.errors import IdNotFoundError, NoResultsError
+from catapult.db.query import get_by_id, get_shape, search
+
+
+class TestGetById:
+    def test_doi_prefix(self, session):
+        result = get_by_id(session, "doi:10.1021/acscatal.7b02335")
+        assert result["type"] == "publication"
+        assert result["total"] == 3  # 3 reactions from Medford
+
+    def test_pub_prefix(self, session):
+        result = get_by_id(session, "pub:MedfordEtAl2017")
+        assert result["total"] == 3
+
+    def test_sys_prefix(self, session):
+        result = get_by_id(session, "sys:rxn_001")
+        assert result["total"] == 1
+
+    def test_bare_string_as_pub(self, session):
+        result = get_by_id(session, "MedfordEtAl2017")
+        assert result["total"] == 3
+
+    def test_not_found(self, session):
+        with pytest.raises(IdNotFoundError):
+            get_by_id(session, "doi:10.9999/nonexistent")
+
+
+class TestSearch:
+    def test_catalyst_single(self, session):
+        result = search(session, catalyst="Pd")
+        assert result["total"] == 2
+
+    def test_catalyst_multi_comparison(self, session):
+        result = search(session, catalyst="Pd,Pt")
+        assert result["total"] == 4  # 2 Pd + 2 Pt
+        assert result["comparison"] is not None
+
+    def test_facet_filter(self, session):
+        result = search(session, facet="111")
+        assert result["total"] == 4
+
+    def test_reactants_filter(self, session):
+        result = search(session, reactants="CO")
+        assert result["total"] == 3
+
+    def test_energy_range(self, session):
+        result = search(session, energy="-1..0")
+        assert result["total"] == 4  # all except O2 dissociation at -1.45
+
+    def test_barrier_range(self, session):
+        result = search(session, barrier="<1.0")
+        assert result["total"] == 3  # Pd(111) 0.89, Pt(111) 0.78, Pt(111) 0.52
+
+    def test_functional_filter(self, session):
+        result = search(session, functional="PBE")
+        assert result["total"] == 1  # Cu only
+
+    def test_database_filter(self, session):
+        result = search(session, database="cathub")
+        assert result["total"] == 5
+
+    def test_no_results(self, session):
+        with pytest.raises(NoResultsError):
+            search(session, catalyst="Au")
+
+    def test_shape_on_page_1(self, session):
+        result = search(session, catalyst="Pd")
+        assert result["shape"] is not None
+        assert "energy" in result["shape"]
+
+
+class TestGetShape:
+    def test_full_shape(self, session):
+        shape = get_shape(session)
+        assert shape["total"] == 5
+        assert "catalysts" in shape
+        assert "facets" in shape
+        assert "energy" in shape

catapult_mcp-0.2.0/tests/test_tool.py

@@ -0,0 +1,38 @@
+"""Tests for catapult.tool — formatted output."""
+
+from __future__ import annotations
+
+from catapult.db.query import get_by_id, get_shape, search
+from catapult.tool import _format_publication, _format_search, _format_shape
+
+
+class TestFormatPublication:
+    def test_pub_output(self, session):
+        data = get_by_id(session, "doi:10.1021/acscatal.7b02335")
+        text = _format_publication(data)
+        assert "reactions" in text
+        assert "CO" in text
+
+
+class TestFormatShape:
+    def test_shape_output(self, session):
+        data = get_shape(session)
+        text = _format_shape(data)
+        assert "CataPult" in text
+        assert "Top catalysts" in text
+        assert "Sortable fields" in text
+        assert "→ catapult_get" in text
+
+
+class TestFormatSearch:
+    def test_search_output(self, session):
+        data = search(session, catalyst="Pd")
+        text = _format_search(data, catalyst="Pd")
+        assert "reactions" in text
+        assert "Shape" in text
+
+    def test_comparison_output(self, session):
+        data = search(session, catalyst="Pd,Pt", facet="111")
+        text = _format_search(data, catalyst="Pd,Pt")
+        assert "Comparison" in text
+        assert "Surface" in text