@cyanheads/pubchem-mcp-server 0.6.2 → 0.6.4

package/README.md

@@ -7,13 +7,13 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.6.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/pubchem-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/pubchem-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pubchem-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-^1.4.0-f472b6.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.6.4-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/pubchem-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/pubchem-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pubchem-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-^1.4.0-f472b6.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
 <div align="center">
 
-[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/pubchem-mcp-server/releases/latest/download/pubchem-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=pubchem-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvcHViY2hlbS1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22pubchem-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads/pubchem-mcp-server%22%5D%7D)
+[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/pubchem-mcp-server/releases/latest/download/pubchem-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=pubchem-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvcHViY2hlbS1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22pubchem-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fpubchem-mcp-server%22%5D%7D)
 
 [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
 
@@ -27,12 +27,14 @@
 
 ---
 
-## Tools
+## Overview
 
-Ten tools for querying PubChem's chemical information database:
+Chemical compound and bioassay data from PubChem's PUG REST and PUG View APIs. Search compounds by identifier, formula, or structure; fetch physicochemical properties, safety data, bioactivity, interactions, cross-references, and 3D structures; find bioassays by biological target. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
 
-| Tool Name | Description |
-|:----------|:------------|
+### Tools
+
+| Tool | Description |
+|:---|:---|
 | `pubchem_search_compounds` | Search for compounds by name, SMILES, InChIKey, formula, substructure, superstructure, or 2D similarity. |
 | `pubchem_get_compound_details` | Get physicochemical properties, descriptions, synonyms, drug-likeness, and classification for compounds by CID. |
 | `pubchem_get_compound_image` | Fetch a 2D structure diagram (PNG) for a compound by CID. |
@@ -44,104 +46,174 @@ Ten tools for querying PubChem's chemical information database:
 | `pubchem_search_assays` | Find bioassays by biological target (gene symbol, protein, Gene ID, UniProt accession). |
 | `pubchem_get_summary` | Get summaries for PubChem entities: assays, genes, proteins, taxonomy. |
 
-### `pubchem_search_compounds`
+### Resources
+
+Compound and assay records are also exposed as URI-templated resources, backed by the same client methods as the tools; many MCP clients are tool-only and never surface resources.
+
+| Resource | Description |
+|:---|:---|
+| `pubchem://compound/{cid}` | Core physicochemical properties (JSON). |
+| `pubchem://compound/{cid}/safety` | GHS hazard classification (JSON). |
+| `pubchem://compound/{cid}/image` | 2D structure diagram (PNG). |
+| `pubchem://compound/{cid}/xrefs` | External cross-references (JSON). |
+| `pubchem://compound/{cid}/bioactivity` | Bioassay activity profile (JSON). |
+| `pubchem://assay/{aid}` | BioAssay summary (JSON). |
+
+## Capability reference
+
+### `pubchem_search_compounds` <sub>tool</sub>
+
+- Five search strategies: identifier (name/SMILES/InChIKey, batched 1-25), formula (Hill notation, optional `allowOtherElements`), substructure/superstructure containment, or 2D Tanimoto similarity (threshold 70-100, default 90)
+- Each strategy needs its own fields — identifier: `identifierType` + `identifiers`; formula: `formula`; substructure/superstructure/similarity: `query` + `queryType` — and a missing or blank one is rejected before the upstream call
+- Caps at 200 CIDs per page (default 20); `offset` pages to a ceiling of 10,000 — identifier lookups resolve every match up front so paging is free, while formula/structure/similarity searches cost more upstream per deep page
+- Optional `properties` hydration avoids a follow-up `pubchem_get_compound_details` call
+- Identifier mode reports `unresolvedIdentifiers` for inputs that resolved to no CID, plus notices when multiple inputs collide on one CID
+- Reports an exact `totalFound` when the full match set was observed, or a `totalFoundAtLeast` floor when a bounded upstream search saturated
+
+---
+
+### `pubchem_get_compound_details` <sub>tool</sub>
+
+- Up to 100 CIDs per call; 27 available properties, defaulting to a core set of 14 (formula, weight, IUPAC name, SMILES forms, InChIKey, XLogP, TPSA, H-bond/rotatable-bond counts, heavy atom count, charge, complexity)
+- Optional textual descriptions, paged via `descriptionOffset`/`maxDescriptions` (default 3, up to 20) — fetched only for the first 10 CIDs in the batch, remaining CIDs listed in `skippedCids`
+- Optional synonyms for every found CID, paged via `synonymOffset`/`maxSynonyms` (default 20, up to 100)
+- Optional drug-likeness assessment (Lipinski Rule of Five + Veber rules), computed from the returned properties at no extra latency
+- Optional pharmacological classification (FDA classes/mechanisms, MeSH classes, ATC codes) — same 10-CID fan-out cap as descriptions
+- Per-CID `found: false` distinguishes a nonexistent CID from a real compound PubChem simply has no data for
+
+---
+
+### `pubchem_get_compound_image` <sub>tool</sub>
+
+- Single CID; `size` is `"small"` (100x100) or `"large"` (300x300, default)
+- Returns base64-encoded PNG plus width/height
+- Typed `cid_not_found` error when PubChem has no record for the CID
+
+---
 
-Search PubChem for chemical compounds across five search modes.
+### `pubchem_get_compound_3d_structure` <sub>tool</sub>
 
-- **Identifier lookup** — resolve compound names, SMILES, or InChIKeys to CIDs (batch up to 25)
-- **Formula search** — find compounds by molecular formula in Hill notation
-- **Substructure/superstructure** — find compounds containing or contained within a query structure
-- **2D similarity** — find structurally similar compounds by Tanimoto similarity (configurable threshold)
-- Caps at 200 CIDs per page; `offset` pages further, to a ceiling of 10,000. Identifier lookups page over the set already resolved; formula and structure searches widen their bounded upstream request to reach a page, so deep pages cost more upstream
-- Optionally hydrate results with properties to avoid a follow-up details call
+- Single CID; `format="json"` (default) returns parsed atoms (element + x/y/z) and bonds, `format="sdf"` returns the raw V2000 SDF text
+- `maxAtoms`/`maxBonds` cap the JSON preview (default 200 each); `atomCount`/`bondCount` always report the full totals, with any capping disclosed via enrichment
+- `includeRawSdf` bypasses the default 500-line cap on the raw SDF text
+- Optional `includeAlternateConformerIds` lists conformer IDs beyond the default
+- Typed `no_3d_structure` error when PubChem has no computed 3D coordinates (large molecules, mixtures, some salts)
 
 ---
 
-### `pubchem_get_compound_details`
+### `pubchem_get_compound_xrefs` <sub>tool</sub>
 
-Get detailed compound information by CID.
+- Single CID; one or more `xrefTypes` — string IDs (`RegistryID`, `RN` for CAS numbers, `PatentID`) and numeric IDs (`PubMedID`, `GeneID`, `ProteinGI`, `TaxonomyID`)
+- Paged per type: `maxPerType` up to 500 (default 50), with the same `offset` applied across every requested type
+- Each type reports its own `totalAvailable` and `truncated` flag
+- Empty-result notice distinguishes "this compound has none of the requested types" from a possibly-mistyped CID
 
-- Batches up to 100 CIDs in a single request
-- 27 available properties: molecular weight, SMILES, InChIKey, XLogP, TPSA, complexity, stereo counts, and more
-- Optionally includes textual descriptions (pharmacology, mechanism, therapeutic use) from PUG View — fetched for the first 10 CIDs of a batch, with the skipped CIDs named in the response
-- Optionally includes known synonyms (trade names, systematic names, registry numbers)
-- Synonyms and descriptions are paged: `synonymOffset` and `descriptionOffset` window every compound in the batch at the same position, reaching the entries past a page
-- Optionally computes drug-likeness assessment (Lipinski Rule of Five + Veber rules) from fetched properties
-- Optionally fetches pharmacological classification (FDA classes, mechanisms of action, MeSH classes, ATC codes)
+---
+
+### `pubchem_get_compound_safety` <sub>tool</sub>
+
+- Batch of 1-25 CIDs
+- Returns GHS signal word, pictograms, hazard statements (H-codes), and precautionary statements (P-codes), with source attribution
+- Per-CID `status`: `ok`, `no_ghs_data` (compound exists, no deposited classification), or `cid_not_found` (no PubChem record at all) — kept distinct so a bad CID never reads as "no hazards on file"
+- Precautionary statements carry a `decoded` flag — false for codes needing label-specific fill text or outside the decoder table; the code itself is still authoritative
 
 ---
 
-### `pubchem_get_bioactivity`
+### `pubchem_get_bioactivity` <sub>tool</sub>
+
+- Single CID; filter by `outcomeFilter` (`active`/`inactive`/`all`, default `all`) and/or `targetGeneId`/`targetAccession`
+- Caps at 100 results per page (default 20); `offset` reaches the rest
+- Reports `totalAssays`/`activeCount`/`inactiveCount` for the whole compound, plus `filteredCount`/`returnedCount` for the current page
+- Notices distinguish "no bioactivity data at all" from "the filter excluded everything" from "offset past the end"
+
+---
 
-Get a compound's bioactivity profile from PubChem BioAssay.
+### `pubchem_get_compound_interactions` <sub>tool</sub>
 
-- Returns assay outcomes (Active/Inactive/Inconclusive), target info (protein accessions, NCBI Gene IDs), and quantitative values (IC50, EC50, Ki)
-- Filter by outcome and/or a specific molecular target (NCBI Gene ID or protein accession)
-- Caps at 100 results per page; `offset` reaches the rest (well-studied compounds may have thousands)
+- Single CID; one or more `kinds` — `drug-drug` (DrugBank), `drug-food`, `target` (binding/activity from BindingDB, ChEMBL, and others); default `["drug-drug"]`
+- `maxEntries` per kind per page (1-50, default 10); `offset` counts source records rather than returned entries, capped at 2,147,483,646
+- Each kind pages independently — `paging[]` reports per-kind `totalRecords`/`nextOffset`/`truncated`; the top-level `nextOffset` is populated only when exactly one requested kind still has records left
+- A kind that fails to retrieve is named in `failedKinds` without failing the kinds that succeeded
 
 ---
 
-### `pubchem_get_summary`
+### `pubchem_search_assays` <sub>tool</sub>
 
-Get descriptive summaries for four PubChem entity types.
+- Search by `targetType`: `genesymbol`/`proteinname` (text), `geneid` (NCBI Gene ID), `proteinaccession` (UniProt)
+- Caps at 200 AIDs per page (default 50); `offset` pages to the total found
+- Rejects a blank `targetQuery` and a non-numeric `geneid` query before the upstream call
+- Reports `totalFound` across all pages and distinguishes "no match" from "offset past the end"
 
-- Assays (AID), genes (Gene ID), proteins (UniProt accession), taxonomy (Tax ID)
-- Up to 10 entities per call
-- Type-specific field extraction for clean, structured output
+---
+
+### `pubchem_get_summary` <sub>tool</sub>
+
+- `entityType`: `assay` (AID), `gene` (NCBI Gene ID), `protein` (UniProt accession), or `taxonomy` (Tax ID); up to 10 identifiers per call
+- Per-identifier `found` flag; populated fields depend on `entityType` (taxonomy includes an ordered `lineage`, gene includes `symbol`/`taxonomy`)
+- Notice reports how many identifiers were not found and which ID type `entityType` expects
 
 ---
 
-### `pubchem_get_compound_interactions`
+### `pubchem://compound/{cid}` <sub>resource</sub>
+
+- Core physicochemical properties (the same default 14-property set as `pubchem_get_compound_details`), as `application/json`
+- Throws a typed not-found when the CID doesn't exist in PubChem
+- Use `pubchem_get_compound_details` to select specific properties or add descriptions, synonyms, drug-likeness, and classification
+
+---
 
-Get a compound's interaction data by CID.
+### `pubchem://compound/{cid}/safety` <sub>resource</sub>
 
-- Drug-drug interactions (DrugBank), drug-food interactions, and chemical-target binding/activity (BindingDB, ChEMBL, and others)
-- Select which interaction kinds to fetch and cap entries per kind
-- Paged per kind: each reports its source-record total and its own `nextOffset`, and `offset` reaches the records past a page
-- Each entry carries its originating source — coverage is richest for approved drugs
+- GHS hazard classification as `application/json`
+- `status` (`ok`/`no_ghs_data`/`cid_not_found`) is the only signal distinguishing a bad CID from a compound with no deposited classification — a resource read has no notice surface
 
 ---
 
-### `pubchem_get_compound_3d_structure`
+### `pubchem://compound/{cid}/image` <sub>resource</sub>
 
-Get a compound's default 3D conformer by CID.
+- 2D structure diagram, 300x300 PNG, returned as a base64 blob
+- Use `pubchem_get_compound_image` for the 100x100 size option
 
-- `format="json"` returns parsed atoms (element + x/y/z) and bonds for direct reasoning; `format="sdf"` returns raw V2000 SDF for passthrough to docking or rendering
-- `maxAtoms`/`maxBonds` bound the atom/bond preview and `includeRawSdf` opts into a large raw SDF past the safe line cap; `atomCount`/`bondCount` always report the totals and any capping is disclosed
-- Optionally lists alternate conformer IDs
-- Returns a typed not-found when PubChem has no computed 3D coordinates (large molecules, mixtures, some salts)
+---
 
-## Resources
+### `pubchem://compound/{cid}/xrefs` <sub>resource</sub>
 
-Compound and assay records are also exposed as URI-templated MCP resources, backed by the same client methods as the tools:
+- Focused default set — `RN` (CAS), `RegistryID`, `PubMedID` — up to 25 IDs per type, as `application/json`
+- Use `pubchem_get_compound_xrefs` for the full set of xref types, a higher per-type cap, and offset paging
 
-| URI Template | Returns |
-|:-------------|:--------|
-| `pubchem://compound/{cid}` | Core physicochemical properties (JSON). |
-| `pubchem://compound/{cid}/safety` | GHS hazard classification (JSON). |
-| `pubchem://compound/{cid}/image` | 2D structure diagram (PNG). |
-| `pubchem://compound/{cid}/xrefs` | External cross-references (JSON). |
-| `pubchem://compound/{cid}/bioactivity` | Bioassay activity profile (JSON). |
-| `pubchem://assay/{aid}` | BioAssay summary (JSON). |
+---
 
-## Features
+### `pubchem://compound/{cid}/bioactivity` <sub>resource</sub>
+
+- Up to 25 assays as `application/json`, plus `totalAssays`/`activeCount` for the whole compound
+- Use `pubchem_get_bioactivity` to filter by outcome or target, raise the cap, or page with offset
 
-Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):
+---
+
+### `pubchem://assay/{aid}` <sub>resource</sub>
+
+- BioAssay summary as `application/json` — name, description, source, protocol, substance counts
+- Throws a typed not-found when the AID doesn't exist
 
-- Declarative tool definitions — single file per tool, framework handles registration and validation
-- Unified error handling across all tools
-- Pluggable auth (`none`, `jwt`, `oauth`)
-- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`
-- Structured logging with optional OpenTelemetry tracing
-- Runs locally (stdio/HTTP) or containerized via Docker
+## Features
+
+Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
 
 PubChem-specific:
 
-- Rate-limited client for PUG REST and PUG View APIs (5 req/s with automatic queuing)
-- Retry with exponential backoff on 5xx errors and network failures
-- All tools are read-only and idempotent — no API keys required
+- Covers both PUG REST (search, properties, cross-references, safety, bioactivity, interactions) and PUG View (textual descriptions, pharmacological classification) endpoints
+- Rate-limited client (5 req/s) with automatic request queuing, and retry with exponential backoff on 5xx errors and network failures
+- Hand-rolled V2000 SDF parser for 3D conformer atoms and bonds; drug-likeness (Lipinski/Veber) computed from already-fetched properties, adding no extra latency
+- All tools are read-only and idempotent — no API keys required, PubChem's API is freely accessible
+
+Agent-friendly output:
 
-## Getting Started
+- Discriminated output contracts — per-CID `status` (`ok` / `no_ghs_data` / `cid_not_found`) and `found` flags let callers branch on data instead of matching an error string
+- Graceful partial failure — batch tools return per-item results alongside `unresolvedIdentifiers`, `skippedCids`, and `failedKinds` rather than failing the whole call
+- Response shaping — truncation disclosure (`truncated`, `shown`/`cap`, `nextOffset`) on every capped list, plus a `totalFoundAtLeast` floor in place of a count when an upstream search saturates
+- Typed error reasons — validation and not-found failures declare a `reason` (e.g. `cid_not_found`, `missing_identifier_args`, `invalid_cid_query`) with actionable recovery text, not generic messages
+
+## Getting started
 
 ### Public Hosted Instance
 
@@ -160,7 +232,7 @@ A public instance is available at `https://pubchem.caseyjhand.com/mcp` — no in
 
 ### Self-Hosted / Local
 
-Add to your MCP client config (e.g., `claude_desktop_config.json`):
+Add the following to your MCP client configuration file.
 
 ```json
 {
@@ -177,9 +249,48 @@ Add to your MCP client config (e.g., `claude_desktop_config.json`):
 }
 ```
 
+Or with npx (no Bun required):
+
+```json
+{
+  "mcpServers": {
+    "pubchem-mcp-server": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@cyanheads/pubchem-mcp-server@latest"],
+      "env": {
+        "MCP_TRANSPORT_TYPE": "stdio"
+      }
+    }
+  }
+}
+```
+
+Or with Docker:
+
+```json
+{
+  "mcpServers": {
+    "pubchem-mcp-server": {
+      "type": "stdio",
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/pubchem-mcp-server:latest"]
+    }
+  }
+}
+```
+
+For Streamable HTTP, set the transport and start the server:
+
+```sh
+MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
+# Server listens at http://localhost:3010/mcp
+```
+
 ### Prerequisites
 
-- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+)
+- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
+- No API keys required — PubChem's API is freely accessible.
 
 ### Installation
 
@@ -189,73 +300,92 @@ Add to your MCP client config (e.g., `claude_desktop_config.json`):
 git clone https://github.com/cyanheads/pubchem-mcp-server.git
 ```
 
-1. **Navigate into the directory:**
+2. **Navigate into the directory:**
 
 ```sh
 cd pubchem-mcp-server
 ```
 
-1. **Install dependencies:**
+3. **Install dependencies:**
 
 ```sh
 bun install
 ```
 
-## Configuration
+4. **Configure environment (optional):**
 
-No API keys are required — PubChem's API is freely accessible.
+```sh
+cp .env.example .env
+# edit .env to override transport, session mode, storage, or logging defaults
+```
+
+## Configuration
 
 | Variable | Description | Default |
 |:---------|:------------|:--------|
 | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
-| `MCP_HTTP_PORT` | Port for HTTP server. | `3000` (`3010` in Docker) |
-| `MCP_SESSION_MODE` | `stateless`, `stateful`, or `auto`. The example and Docker use `stateless`; no multi-round-trip input is needed. | `auto` (resolves to `stateful`) |
-| `MCP_HTTP_HOST` | Host for HTTP server. | `localhost` |
+| `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |
+| `MCP_HTTP_HOST` | Host for HTTP server. | `127.0.0.1` |
+| `MCP_SESSION_MODE` | `stateless`, `stateful`, or `auto`. PubChem needs no multi-round-trip input, so the server declares `stateless`; the example and Docker set it to match. | `stateless` |
 | `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
 | `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |
 | `STORAGE_PROVIDER_TYPE` | Storage backend. | `in-memory` |
 | `OTEL_ENABLED` | Enable OpenTelemetry. | `false` |
 
-## Running the Server
+See [`.env.example`](./.env.example) for the full list of optional overrides.
+
+## Running the server
 
-### Local Development
+### Local development
 
 - **Build and run:**
 
   ```sh
+  # One-time build
   bun run rebuild
-  bun run start:stdio   # or start:http
+
+  # Run the built server
+  bun run start:stdio
+  # or
+  bun run start:http
   ```
 
 - **Run checks and tests:**
 
   ```sh
-  bun run devcheck     # Lints, formats, type-checks
-  bun run test         # Runs test suite
+  bun run devcheck   # Lint, format, typecheck, security
+  bun run test       # Vitest test suite
+  bun run lint:mcp   # Validate MCP definitions against spec
   ```
 
 ### Docker
 
 ```sh
 docker build -t pubchem-mcp-server .
-docker run -p 3010:3010 pubchem-mcp-server
+docker run --rm -p 3010:3010 pubchem-mcp-server
 ```
 
-## Project Structure
+The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/pubchem-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.
+
+## Project structure
 
 | Directory | Purpose |
 |:----------|:--------|
+| `src/index.ts` | `createApp()` entry point — registers tools/resources and inits the PubChem client. |
 | `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`). |
-| `src/services/pubchem/` | PubChem API client with rate limiting and response parsing. |
+| `src/mcp-server/resources/definitions/` | Resource definitions (`*.resource.ts`). |
+| `src/services/pubchem/` | PubChem API client — rate limiting, retry, and response/SDF parsing. |
 | `scripts/` | Build, clean, devcheck, and tree generation scripts. |
+| `tests/` | Unit and integration tests. |
 
-## Development Guide
+## Development guide
 
 See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
 
 - Handlers throw, framework catches — no `try/catch` in tool logic
-- Use `ctx.log` for domain-specific logging
-- Register new tools in the `index.ts` barrel file
+- Use `ctx.log` for request-scoped logging
+- Wrap external API calls: validate the raw PubChem response → normalize to a domain type → return the output schema; never fabricate missing fields
+- Register new tools and resources in the `index.ts` barrel files
 
 ## Contributing
 

package/changelog/0.1.x/0.1.21.md

@@ -0,0 +1,23 @@
+---
+summary: "mcp-ts-core ^0.9.6 → ^0.9.13: HTTP body cap, session-init gate, quieter 4xx logs, GET /mcp keywords; httpErrorFromResponse adoption; keyword additions"
+breaking: false
+security: false
+---
+
+# 0.1.21 — 2026-05-28
+
+## Changed
+
+- **`@cyanheads/mcp-ts-core`** `^0.9.6 → ^0.9.13` — adopted across seven patch releases:
+  - **`MCP_HTTP_MAX_BODY_BYTES`** (0.9.13) — configurable inbound body cap; oversized requests rejected with 413 before the SDK parses the body. Default 1 MiB; set to `0` to disable.
+  - **HTTP session-init gate** (0.9.10) — stateful HTTP mode now rejects non-`initialize` requests without an `Mcp-Session-Id` header with HTTP 400.
+  - **`httpErrorHandler` log-level split** (0.9.10) — 401, 403, 400, 404 responses downgraded to `warning`; stack traces removed from expected client errors.
+  - **`GET /mcp` keywords** (0.9.12) — `package.json` `keywords` now surfaced on the HTTP status endpoint alongside name/version/description.
+  - 0.9.7–0.9.9, 0.9.11 — skill refreshes, `git-wrapup` skill, fuzz pre-parse fixes, `code-simplifier` skill, `biome` lint adjustment.
+- **`pubchem-client.ts`** — `httpStatusToErrorCode` + manual `McpError` construction replaced with `httpErrorFromResponse` (framework util that classifies by status and body). Both `fetchJson` and `fetchBinary` error paths updated; fault message passed as `data.fault` alongside `data.url`.
+- **`package.json` keywords** — added `typescript`, `bun`, `stdio`, `streamable-http` (surfaces on `GET /mcp` endpoint via 0.9.12 framework support).
+- **`@biomejs/biome`** `^2.4.15 → ^2.4.16`.
+
+## Skills
+
+- **Skills synced** from `@cyanheads/mcp-ts-core@0.9.13` — refreshed `api-canvas`, `api-config`, `design-mcp-server`, `polish-docs-meta`, `release-and-publish`, `report-issue-framework`; added `code-simplifier`, `git-wrapup`; removed `migrate-mcp-ts-template`.

package/changelog/0.1.x/0.1.22.md

@@ -0,0 +1,14 @@
+---
+summary: "Enrichment adoption: search_compounds and search_assays surface search-type/target echoes, true upstream totals, and empty-result guidance via a typed enrichment block"
+breaking: false
+security: false
+---
+
+# 0.1.22 — 2026-05-30
+
+## Changed
+
+- **`pubchem_search_compounds`** — `searchType` and `totalFound` moved from `output` to a typed `enrichment` block; `output` now contains only `results`. Both fields reach `structuredContent` and `content[]` automatically via `ctx.enrich()`; an empty-result `notice` is appended when no compounds match.
+- **`pubchem_search_assays`** — `targetType`, `targetQuery`, and `totalFound` moved from `output` to `enrichment`; `output` now contains only `aids`. An empty-result `notice` is appended when no assays match, suggesting alternative `targetType` values or `pubchem_get_summary` for entity lookups.
+- **`@cyanheads/mcp-ts-core`** `^0.9.13 → ^0.9.16` — skill refreshes, `enrichment` contract support, and associated framework patches.
+- **Skills synced** from `@cyanheads/mcp-ts-core@0.9.16`.

package/changelog/0.1.x/0.1.23.md

@@ -0,0 +1,18 @@
+---
+summary: "Typed cid_not_found error on get_compound_image; enrichment for get_bioactivity, get_compound_safety, and get_summary"
+breaking: false
+security: false
+---
+
+# 0.1.23 — 2026-06-01
+
+## Added
+
+- **`pubchem_get_compound_image`** — a 404 for a missing CID now returns a typed `cid_not_found` (`NotFound`) error carrying `data.reason: 'cid_not_found'` and a recovery hint, instead of a bare not-found with a null reason. The other six CID tools surface absence as a structured success response and need no error contract. ([#17](https://github.com/cyanheads/pubchem-mcp-server/issues/17))
+- **`pubchem_get_bioactivity`** — enrichment block with `outcomeFilter` echo, `filteredCount` (matching the filter) and `returnedCount` (after the `maxResults` cap), plus a notice distinguishing no-data from filter-excluded results. ([#19](https://github.com/cyanheads/pubchem-mcp-server/issues/19))
+- **`pubchem_get_compound_safety`** — enrichment notice pointing to `pubchem_get_compound_details` when no GHS data is on file. ([#19](https://github.com/cyanheads/pubchem-mcp-server/issues/19))
+- **`pubchem_get_summary`** — enrichment with `requestedCount`, `foundCount`, and a per-miss notice. ([#19](https://github.com/cyanheads/pubchem-mcp-server/issues/19))
+
+## Changed
+
+- **`vitest`** `^4.1.7 → ^4.1.8`.

package/changelog/0.2.x/0.2.0.md

@@ -0,0 +1,24 @@
+---
+summary: "interactions and 3D structure tools, URI-templated resources, target filter for bioactivity, batch safety"
+breaking: true
+security: false
+---
+
+# 0.2.0 — 2026-06-01
+
+## Added
+
+- **`pubchem_get_compound_interactions`** — drug-drug, drug-food, and chemical-target interactions with per-entry source attribution ([#12](https://github.com/cyanheads/pubchem-mcp-server/issues/12)). Drug-drug and target interactions fetched from PubChem's SDQ external tables (`drugbankddi`, `consolidatedcompoundtarget`); drug-food interactions from PUG-View inline. `severity` is not normalized across sources — reported faithfully from source prose.
+- **`pubchem_get_compound_3d_structure`** — 3D conformer as parsed JSON atoms/bonds (`format: 'json'`, default) or raw SDF text (`format: 'sdf'`), with optional alternate conformer IDs ([#15](https://github.com/cyanheads/pubchem-mcp-server/issues/15)). Returns `notFound` for compounds without computed 3D coordinates.
+- **URI-templated MCP resources** — six resources backed by existing `PubChemClient` methods, no new API calls ([#14](https://github.com/cyanheads/pubchem-mcp-server/issues/14)):
+  - `pubchem://compound/{cid}` — compound properties
+  - `pubchem://compound/{cid}/safety` — GHS classification
+  - `pubchem://compound/{cid}/image` — 2D structure diagram (PNG)
+  - `pubchem://compound/{cid}/xrefs` — external database cross-references
+  - `pubchem://compound/{cid}/bioactivity` — assay activity
+  - `pubchem://assay/{aid}` — assay entity summary
+- **`targetGeneId` / `targetAccession` filters** on `pubchem_get_bioactivity` input — pure client-side filter on existing `BioactivityRow` fields; both echoed in enrichment when set ([#9](https://github.com/cyanheads/pubchem-mcp-server/issues/9)).
+
+## Changed
+
+- **`pubchem_get_compound_safety` input is now `cids` (array, 1–25)** — replaces the single `cid: number` parameter; output is now `results[]` with one entry per CID ([#13](https://github.com/cyanheads/pubchem-mcp-server/issues/13)). **Breaking:** callers must update to pass an array.

package/changelog/0.2.x/0.2.1.md

@@ -0,0 +1,14 @@
+---
+summary: "interactions target source, per-kind isolation, fetch resilience for image and 3D structure"
+breaking: false
+security: false
+---
+
+# 0.2.1 — 2026-06-02
+
+## Fixed
+
+- **`pubchem_get_compound_interactions` (`target` kind)** — now returns chemical–target binding and activity for the requested compound, sourced from PubChem's CID-keyed `bioactivity` collection (BindingDB, ChEMBL, and others). Previously queried a gene-indexed collection whose compound filter was silently ignored, causing every compound to return the same unrelated compound's records ([#20](https://github.com/cyanheads/pubchem-mcp-server/issues/20)).
+- **`pubchem_get_compound_interactions` (per-kind isolation)** — a failure in one requested interaction kind no longer discards the kinds that succeeded. Successful kinds are returned and unavailable kinds are reported via a `failedKinds` notice (`Promise.allSettled` per-kind isolation) ([#21](https://github.com/cyanheads/pubchem-mcp-server/issues/21)).
+- **`pubchem_get_compound_image` and `pubchem_get_compound_3d_structure`** — image and 3D-structure fetches now retry once on transient upstream 5xx errors and surface a clear `PubChem request timed out (30s)` message on timeout instead of a raw abort error, matching the JSON fetch path ([#16](https://github.com/cyanheads/pubchem-mcp-server/issues/16)).
+- **SDQ-backed interaction fetches** — PubChem's occasional malformed JSON now returns a contextful error instead of an opaque `Failed to parse JSON`.

package/changelog/0.2.x/0.2.2.md

@@ -0,0 +1,17 @@
+---
+summary: "adopt @cyanheads/mcp-ts-core 0.9.21 — per-request log context fix, secret scrubbing in fetch errors, fail-fast retries"
+breaking: false
+security: false
+---
+
+# 0.2.2 — 2026-06-02
+
+## Changed
+
+- **`@cyanheads/mcp-ts-core`** `^0.9.16 → ^0.9.21` — adopts three framework fixes: per-request logs and traces now carry fresh request/trace/span IDs instead of the frozen boot context (HTTP transport); `fetchWithTimeout` strips query-string secrets (e.g. `?api_key=`) from error messages and logs; `withRetry` fails fast on non-retryable errors and `ctx.fail` auto-populates the `retryable` flag.
+- **`release:github` script** — new `scripts/release-github.ts` added to `package.json`; creates a GitHub Release from the annotated tag with correct title formatting.
+- **`devcheck`** — adds Open-Indexed Interfaces and Skill Versions checks from framework 0.9.21 skill sync.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` `^0.9.16 → ^0.9.21`

package/changelog/0.2.x/0.2.3.md

@@ -0,0 +1,27 @@
+---
+summary: "adopt @cyanheads/mcp-ts-core ^0.10.6 — truncation disclosure on capped searches, explicit createApp identity, MCPB bundle-content hardening"
+breaking: false
+security: false
+---
+
+# 0.2.3 — 2026-06-12
+
+## Added
+
+- **Truncation disclosure** — `pubchem_search_compounds`, `pubchem_search_assays`, and `pubchem_get_bioactivity` now emit `truncated`/`shown`/`cap` via `ctx.enrich.truncated()` when results are capped at `maxResults`, so callers know more matches exist beyond what was returned.
+- **`scripts/clean-mcpb.ts`** — post-pack bundle cleaner wired into the `bundle` script: runs `mcpb clean`, then strips dependency-shipped agent-doc entries (`skills/`, `.claude/`, `.agents/`, `SKILL.md`) nested under `node_modules/` that root-anchored `.mcpbignore` patterns cannot reach.
+- **Dockerfile `HEALTHCHECK`** — bun-native `fetch` against `/healthz` (slim image ships no curl/wget), plus an `org.opencontainers.image.version` OCI label sourced from the `APP_VERSION` build arg.
+
+## Changed
+
+- **`createApp()`** — sets explicit `name` and `title` to `pubchem-mcp-server`, pinning the served identity to the repo name on every surface instead of relying on the scoped-package fallback.
+- **`scripts/lint-packaging.ts`** — adds bundle-content and identity guards: `.mcpbignore` dev-dir exclusion and anchoring (unanchored patterns also strip `node_modules/…/skills/`), critical-runtime-path protection, a post-bundle `node_modules` agent-doc scan, and a `createApp()`/manifest `display_name` identity check against the unscoped package name.
+- **`scripts/check-framework-antipatterns.ts`** — adds rule 4 flagging `z.coerce.boolean()` on env flags (`Boolean("false")` is `true`, so the flag can't be disabled via env — use `z.stringbool()`); comment-line matches are now skipped so JSDoc naming an antipattern no longer false-positives.
+- **`.mcpbignore`** — root dev-dir patterns anchored with a leading `/` so they no longer match nested runtime paths under `node_modules/`.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` `^0.9.21 → ^0.10.6`
+- `@biomejs/biome` `^2.4.16 → ^2.5.0`
+- `@types/node` `^25.9.1 → ^25.9.3`
+- `packageManager` `bun@1.3.2 → bun@1.3.11`

package/changelog/0.2.x/0.2.4.md

@@ -0,0 +1,27 @@
+---
+summary: "adopt @cyanheads/mcp-ts-core ^0.10.9 — check-dependency-specifiers devcheck step, plugin-manifest packaging lint, fresh-scaffold devcheck guards, vendored skill re-sync"
+breaking: false
+security: false
+---
+
+# 0.2.4 — 2026-06-20
+
+## Added
+
+- **`scripts/check-dependency-specifiers.ts`** — new devcheck step (`Dependency Specifiers`, `--no-dep-specifiers`) rejecting floating specifiers (`latest`, `*`, pre-release dist-tags) in `package.json`'s dependency sections and `bun.lock`'s `workspaces` map, catching the case where `bun update --latest` writes a literal `latest` dist-tag into the lock and lets a later `bun install` re-resolve past an intentional version hold. ([cyanheads/mcp-ts-core#246](https://github.com/cyanheads/mcp-ts-core/issues/246))
+- **Plugin marketplace manifest checks in `scripts/lint-packaging.ts`** — check 10 validates `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, and `.codex-plugin/mcp.json`: non-empty descriptions, display fields carry the unscoped machine name, and the `npx -y` install arg carries the full scoped package name. Gated by the new `devcheck.config.json` `packaging.pluginManifests` flag (default on). ([cyanheads/mcp-ts-core#240](https://github.com/cyanheads/mcp-ts-core/issues/240))
+
+## Changed
+
+- **Fresh-scaffold devcheck guards** — `scripts/build-changelog.ts`, `scripts/devcheck.ts`, and `scripts/check-framework-antipatterns.ts` skip git-dependent checks when `.git` is absent; `scripts/check-skill-versions.ts` guards against a `SKILL.md` deleted from the worktree. ([cyanheads/mcp-ts-core#237](https://github.com/cyanheads/mcp-ts-core/issues/237), [#242](https://github.com/cyanheads/mcp-ts-core/issues/242), [#243](https://github.com/cyanheads/mcp-ts-core/issues/243))
+- **Vendored skills re-synced** to mcp-ts-core 0.10.7–0.10.9 — `metadata.version` bumps across `api-auth`, `api-errors`, `api-services`, `api-telemetry`, `field-test`, `report-issue-local`, `tool-defs-analysis`, plus body updates to `git-wrapup`, `orchestrations`, `api-context`, and others. ([cyanheads/mcp-ts-core#238](https://github.com/cyanheads/mcp-ts-core/issues/238))
+
+## Removed
+
+- **`skills/references/{formatting,parsing,security}.md`** — stray framework reference docs vendored in error; removed.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` `^0.10.6 → ^0.10.9`
+- `@types/node` `^25.9.3 → ^26.0.0`
+- `vitest` `^4.1.8 → ^4.1.9`