gi-mcp 0.1.0a9__tar.gz

gi_mcp-0.1.0a9/.dockerignore

@@ -0,0 +1,15 @@
+.venv/
+dist/
+build/
+*.egg-info/
+**/__pycache__/
+.pytest_cache/
+tests/
+scripts/
+_http_smoke.py
+_e2e_*.py
+*.log
+*.md
+!README.md
+Dockerfile
+.dockerignore

gi_mcp-0.1.0a9/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+uv.lock

gi_mcp-0.1.0a9/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to `gi-mcp` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project will adopt
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) once it leaves the
+alpha series. While in the `0.1.0aN` alpha, the tool surface and outputs may
+change between releases without a major-version bump.
+
+## [Unreleased]
+
+_Nothing yet._
+
+## [0.1.0a9]
+
+### Added
+
+- Bundled `annotation_hbb_chr11` demo sequence — a plus-strand HBB locus
+  (`chr11:5,222,472-5,231,670`) that `find_genes` recovers as a single
+  high-confidence transcript centred on the TSS. Completes the "one positive
+  control per task" set, so the no-key `load_demo_sequence` flow can now
+  smoke-test annotation too.
+- `ruff` (lint + format) and `mypy` (typing) gates, wired into CI across
+  Python 3.10–3.12.
+
+### Changed
+
+- Releases now publish to PyPI via a tag-gated OIDC trusted-publish workflow
+  (push a `gi-mcp-v*` tag → build → checks → publish, no long-lived token). See
+  `CONTRIBUTING.md` → Releasing.
+
+## [0.1.0a8]
+
+### Fixed
+
+- `gi://models` resource returned empty per-task model lists. The live
+  `/v1/tasks/{task}/models` response is unwrapped (`{task, default_model,
+  models}`), but the resource dug for a non-existent `data.models` envelope and
+  fell through to `[]`. Now reads the list directly (tolerating a `{data}`
+  wrapper too), so the catalog resource matches the populated `list_models`
+  tool. The test fake was wrapping in `data`, masking the bug; corrected to the
+  real shape with a non-empty assertion guarding regression.
+
+## [0.1.0a7]
+
+### Added
+
+- `fetch_region` acquisition tool: fetch a genomic region by coordinates
+  (`chr8:127,680,000-127,800,000`) and get a handle for `find_genes` / `predict_*`.
+  Accepts the same lenient formats as the Web UI's gene search (commas, en/em
+  dashes, `..`, optional `chr`) and defaults to the plus strand, which the
+  gene-finder expects. This is what makes the documented "find the genes in
+  chr8:…" flow executable over MCP — previously only gene *symbols* could be
+  acquired.
+
+## [0.1.0a6]
+
+Initial alpha — an MCP server exposing the Genomic Intelligence `/v1`
+DNA-analysis API to LLM hosts over stdio, plus a hosted Streamable-HTTP demo.
+
+- **Six inference tasks** — promoter, splice, enhancer, chromatin, expression,
+  and annotation (`find_genes`) — plus the composite
+  `find_genes_and_predict_expression` workflow.
+- **Sequence acquisition** (Ensembl, local FASTA, inline, and bundled demo
+  sequences) via the handle pattern, so large sequences never round-trip through
+  the LLM.
+- **Reference resources** (`gi://models`, `gi://docs/tasks`, `gi://openapi.json`,
+  `gi://sequences`, `gi://cache/{ref}`, `gi://jobs/recent`, `gi://account`) and
+  two slash-command prompts (`gi-promoter-screen`, `gi-expression-screen`).
+- **One execution model** — every tool call blocks until the result is ready and
+  returns the `{data, meta}` envelope; slow tasks stream progress to the host
+  while they run. An explicit detached mode (`wait=False`) instead returns a
+  pollable `job_id`.
+- **Secure-by-default HTTP transport** and a hosted multi-tenant mode
+  (per-request key resolution, per-principal sequence store, `load_local_fasta`
+  disabled remotely).

gi_mcp-0.1.0a9/CLAUDE.md

@@ -0,0 +1,71 @@
+# MCP Server — Claude Context
+
+`gi-mcp`: an MCP (Model Context Protocol) server that exposes the Genomic
+Intelligence `/v1` API to LLM hosts (Claude Desktop/Code, Cursor) over stdio.
+A thin protocol translator over the `/v1` contract.
+
+## What it wraps
+
+The GI GPU service `/v1` contract — same endpoints the Web UI and partners use.
+This server is a **protocol translator**: it owns no inference, it forwards to
+`api.genomicintelligence.ai` (override with `GI_BASE_URL`).
+
+## Stack
+
+- Python 3.10+, `mcp` SDK (FastMCP high-level API), `httpx`
+- `pytest` + `pytest-asyncio` (auto mode) + `pytest-httpx`; build via `hatchling`
+
+## Layout & conventions
+
+- `server.py` builds one `FastMCP` and calls `tools/resources/prompts.register_all`.
+- Each primitive module exposes `register(mcp)`; no global mcp in submodules.
+- Network only through `_client.Client` (GI) and `_ensembl` (Ensembl REST).
+- Shared state is `_state.AppState` (client + `SequenceStore`), a lazy singleton;
+  tests inject a `FakeClient` via `_state.set_client`.
+- Task bounds live in `config.TASKS` — mirror of `gpu_service/core/limits.py`.
+  Keep them in sync if the API's limits change.
+
+## The handle pattern (important)
+
+Large sequences must not round-trip through the LLM. Acquisition tools store the
+sequence in `SequenceStore` and return a short `seq_…` handle; predict tools take
+`sequence` **xor** `sequence_ref`. See `tools/_common.py:resolve_sequence`.
+
+## Primitive map
+
+| Primitive | Where | Notes |
+|---|---|---|
+| Tools | `tools/` | 16 total; 6 acquisition + 6 predict + workflow + jobs + models |
+| Resources | `resources/` | `gi://models`, `gi://docs/tasks`, `gi://openapi.json`, `gi://sequences`, `gi://cache/{ref}`, `gi://jobs/recent`, `gi://account` |
+| Prompts | `prompts/library.py` | 2 slash-command workflows |
+| Roots | `tools/acquisition.py` | `load_local_fasta` gates on `ctx.session.list_roots()` |
+
+## Commands
+
+```bash
+cd mcp-server
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest                          # full suite, no network
+GI_RUN_INTEGRATION=1 GI_API_KEY=gi_... .venv/bin/pytest -m integration  # live
+GI_API_KEY=gi_... .venv/bin/gi-mcp        # run the server (clients normally launch it)
+```
+
+## Gotchas
+
+- Submodules import `config` as a module (`from gi_mcp import config`) so call
+  sites like `config.allow_any_fasta_path()` stay monkeypatchable in tests.
+- Demo FASTAs in `data/sequences/` ship in the wheel via `[tool.hatch.build]
+  artifacts`. `_demos.py` indexes them; `gi://sequences` lists the catalog and
+  `load_demo_sequence(name)` loads one into a handle.
+- `load_local_fasta` needs a request context (`mcp.get_context()`) to read
+  MCP roots; tests that exercise it monkeypatch the context/session.
+
+## Docs
+
+- `README.md` — front door: install, per-client config, handle pattern, full
+  tool/resource/prompt tables, "Try it" examples, environment
+- `CONTRIBUTING.md` — dev setup, conventions, architecture walkthrough, release
+- `CHANGELOG.md` — release history (Keep a Changelog)
+- `../docs/platform/MCP_SERVER.md` — canonical design doc: architecture, primitives,
+  execution model (call→progress→result), and the compressed hosting section
+  (demo key + BYOK, transport/ALB, why hosting is a multi-tenancy refactor)

gi_mcp-0.1.0a9/CONTRIBUTING.md

@@ -0,0 +1,161 @@
+# Contributing to gi-mcp
+
+`gi-mcp` is the MCP server that exposes the Genomic Intelligence `/v1`
+DNA-analysis API to LLM hosts. It's a thin protocol translator: it owns no
+inference and forwards to `api.genomicintelligence.ai`. Contributions that keep
+the surface tight, honest, and well-tested are very welcome.
+
+## Development setup
+
+```bash
+cd mcp-server
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+```
+
+Run the server locally (your MCP client normally launches it for you):
+
+```bash
+GI_API_KEY=gi_... .venv/bin/gi-mcp
+```
+
+## Tests
+
+```bash
+.venv/bin/pytest                 # full suite — mocked, no network
+.venv/bin/pytest -q tests/test_predict.py
+
+# Live tests against the real API (consume quota):
+GI_RUN_INTEGRATION=1 GI_API_KEY=gi_... .venv/bin/pytest -m integration
+```
+
+The suite is network-free by default: tools run through the real FastMCP
+dispatch with a `FakeClient` injected via `_state.set_client` (see
+`tests/conftest.py`), and HTTP behaviour is exercised with `pytest-httpx`.
+CI runs this on Python 3.10–3.12; please keep it green and add a test with any
+behaviour change.
+
+## Conventions
+
+- **One source of truth for the version:** `src/gi_mcp/__init__.py:__version__`.
+  `pyproject.toml` reads it dynamically (Hatch); the doc status banners are
+  pinned to it by `tests/test_version_consistency.py`. Don't hand-edit the
+  version anywhere else.
+- **Task bounds** live in `config.TASKS`, mirroring `gpu_service/core/limits.py`.
+  `tests/test_limits_parity.py` fails if they drift (in a monorepo checkout).
+- Each primitive module exposes `register(mcp)`; there is no global `mcp` in
+  submodules. All network access goes through `_client.Client` (GI `/v1`) and
+  `_ensembl` (Ensembl REST) — never call `httpx` directly elsewhere.
+- Tools return the GI `{data, meta}` envelope on success and
+  `{error: {code, message, ...}}` on failure — the same shape the API uses.
+  Map new failure modes into that envelope; never let a raw traceback reach the
+  host.
+- Tool/argument docstrings are the LLM-facing contract. Keep them accurate and
+  specific — they steer tool selection.
+
+## Architecture
+
+`server.py` builds one `FastMCP` instance and calls
+`tools/resources/prompts.register_all(mcp)`. Each primitive module exposes
+`register(mcp)`; there is no global `mcp` in submodules.
+
+```
+MCP client (Claude Desktop / Code / Cursor)
+        │  stdio (JSON-RPC)
+        ▼
+server.py — one FastMCP; registers tools · resources · prompts
+        │
+   ┌────┴───────────────┬────────────────────┐
+   ▼                    ▼                     ▼
+_state.py            _store.py            _client.py
+AppState         →   SequenceStore        Client → /v1 (httpx, envelopes)
+(client+store)       handle ↔ sequence         │ HTTPS + Bearer
+   │  _ensembl.py (REST)  _fasta.py (parse+roots)  _demos.py (bundled FASTAs)
+   ▼                                          api.genomicintelligence.ai
+config.py — task registry, limits, env
+```
+
+Everything that touches the network lives behind two clients: `_client.Client`
+(GI `/v1`) and `_ensembl` (Ensembl REST).
+
+### Source layout
+
+```
+src/gi_mcp/
+├── server.py            assemble FastMCP, register primitives, stdio entry
+├── config.py            TaskSpec registry, length bounds, env resolution
+├── _client.py           GI /v1 client: predict, async submit/poll, workflow, jobs
+├── _ensembl.py          symbol → locus → sequence; TSS-centred window
+├── _fasta.py            FASTA parse + roots path-containment
+├── _store.py            SequenceStore: handles, dedupe, TTL, size cap
+├── _state.py            AppState (stdio singleton / hosted per-request); test seams
+├── _demos.py            bundled demo FASTA index (catalog + name → sequence)
+├── tools/               acquisition · predict (×6) · workflow · jobs · models
+├── resources/           catalog · contract · sequences · jobs · account
+├── prompts/library.py   the two prompt workflows
+└── data/sequences/      bundled demo FASTAs
+```
+
+### The four MCP primitives
+
+- **Tools** (`@mcp.tool()`) — the verbs. Return the GI `{data, meta}` envelope
+  on success, `{error: {code, message, ...}}` on failure. Core design choice:
+  **acquisition vs prediction separation** — acquisition tools return a `seq_…`
+  handle via the `SequenceStore`; predict tools accept `sequence` (inline) **xor**
+  `sequence_ref` (handle), resolved by `tools/_common.py:resolve_sequence`.
+  Length is validated locally (`config.TaskSpec.validate_length`) before any
+  request leaves the machine. Slow tasks (`find_genes`,
+  `find_genes_and_predict_expression`, which always submits async) block and
+  stream progress via `tools/_common.py:block_and_poll`, returning the result in
+  one call; the response shape never flips on a timer. Exceeding the
+  `GI_ASYNC_TIMEOUT` ceiling returns a clean `{error: timeout}`, and the explicit
+  detached mode (`wait=False`) is the only path that returns a `job_id` to poll
+  with `get_job`. See [`docs/platform/MCP_SERVER.md`](../docs/platform/MCP_SERVER.md) §5.
+- **Resources** (`@mcp.resource(uri)`) — the nouns: an index the host reads on
+  demand, static (`gi://models`) or templated (`gi://cache/{ref}`). Nothing loads
+  until asked, so even a 500 kb cached sequence is safe to expose.
+- **Roots** — `load_local_fasta` calls `ctx.session.list_roots()` and refuses any
+  path outside the granted roots (`realpath` defeats `..`). Not registered when
+  `GI_MCP_HOSTED=1` (host file-read is unsafe on a shared server).
+- **Prompts** (`@mcp.prompt()`) — instruction text naming this server's tools, so
+  one slash-command drives a multi-step recipe.
+
+### State & lifecycle
+
+`AppState` is lazily built in `_state.py`, so importing the package needs no
+`GI_API_KEY` (tests rely on this). The store is in-memory, TTL- and size-bounded,
+keyed by a content hash so identical fetches dedupe. In hosted mode the client is
+resolved per request (BYOK header, else the demo key) and the store is keyed per
+principal. Restarting clears everything — no persistence, by design.
+
+For the full server design — architecture, execution model, and the hosted HTTP
+deployment (transport, ALB, multi-tenancy) — see
+[`docs/platform/MCP_SERVER.md`](../docs/platform/MCP_SERVER.md).
+
+## Changelog
+
+Add a bullet under `## [Unreleased]` in `CHANGELOG.md`
+([Keep a Changelog](https://keepachangelog.com/) style: Added / Changed /
+Fixed / Removed / Security). While in the `0.1.0aN` alpha series the surface may
+change between releases without a major bump.
+
+## Releasing (maintainers)
+
+The package is not yet on PyPI. Release is automated by the
+`.github/workflows/mcp-publish.yml` workflow, which publishes via PyPI **OIDC
+trusted publishing** — no API token is stored. One-time setup: register this
+repo + workflow as a Trusted Publisher for the `gi-mcp` project on PyPI and
+create a GitHub Environment named `pypi`.
+
+To cut a release:
+
+1. Bump `__version__` in `src/gi_mcp/__init__.py`; move the `[Unreleased]`
+   CHANGELOG section under the new version. Commit and merge to `main`.
+2. Locally, sanity-check the artifact: `pip install build twine && python -m
+   build && twine check dist/*` (CI gates this too).
+3. Optionally publish to **TestPyPI** first and `pip install` into a fresh venv
+   to smoke-test `gi-mcp --help` and a stdio handshake.
+4. Tag the commit `gi-mcp-v<version>` (e.g. `gi-mcp-v0.1.0a9`) and push the tag.
+   The workflow asserts the tag matches `__version__`, builds, runs
+   `twine check`, and publishes to **PyPI** — after which `uvx gi-mcp` works
+   without a checkout. The tag is namespaced (`gi-mcp-v*`) because this is a
+   monorepo with multiple deployables.

gi_mcp-0.1.0a9/Dockerfile

@@ -0,0 +1,30 @@
+# gi-mcp hosted (Streamable HTTP) image.
+#
+# Build context is mcp-server/ ONLY — no other monorepo code (gpu_service,
+# web-ui, deploy, AWS configs, .env*) is present in the context, so it cannot
+# leak into the image. The runtime stage installs only the gi-mcp wheel
+# (gi_mcp package + mcp + httpx + bundled demo FASTAs). The demo key is
+# injected at runtime via GI_MCP_DEMO_KEY — never baked into a layer.
+
+FROM python:3.12-slim AS build
+WORKDIR /build
+RUN pip install --no-cache-dir build
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN python -m build --wheel
+
+FROM python:3.12-slim AS runtime
+RUN useradd --create-home --uid 10001 appuser
+COPY --from=build /build/dist/*.whl /tmp/
+RUN pip install --no-cache-dir /tmp/*.whl && rm -f /tmp/*.whl
+USER appuser
+
+# Hosted HTTP defaults; GI_MCP_DEMO_KEY is supplied at runtime (Secrets Manager).
+ENV MCP_TRANSPORT=http \
+    GI_MCP_HOSTED=1 \
+    MCP_HTTP_HOST=0.0.0.0 \
+    MCP_HTTP_PORT=8000
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/healthz',timeout=2).read()==b'ok' else 1)"
+CMD ["gi-mcp"]

gi_mcp-0.1.0a9/LICENSE

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

gi_mcp-0.1.0a9/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: gi-mcp
+Version: 0.1.0a9
+Summary: MCP server for the Genomic Intelligence DNA-analysis API: promoter, splice, enhancer, chromatin, expression, annotation + a composite annotation→expression workflow, over MCP stdio.
+Project-URL: Homepage, https://genomicintelligence.ai
+Project-URL: Documentation, https://docs.genomicintelligence.ai
+Project-URL: Get an API key, https://genomicintelligence.ai/contact
+Author-email: Genomic Intelligence <hello@genomicintelligence.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bioinformatics,claude,dna,ensembl,genomics,llm,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: mcp<2,>=1.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gi-mcp
+
+> **Status: ALPHA (`0.1.0a9`).** Provided for development, testing, and
+> internal use. The task set, outputs, and tool surface may change without
+> notice, and availability and results are not guaranteed. Not for production
+> systems or clinical/diagnostic decisions.
+
+An MCP server for the [Genomic Intelligence](https://genomicintelligence.ai)
+DNA-analysis API. It exposes the six inference tasks (promoter, splice,
+enhancer, chromatin, expression, annotation), a composite
+annotation→expression workflow, sequence acquisition (Ensembl + local FASTA),
+reference resources, and ready-made prompt workflows — all over MCP stdio.
+
+It runs locally as a thin protocol translator: it owns no inference and stores
+no key, forwarding each request to your Genomic Intelligence backend under
+**your** API key.
+
+## Install
+
+`gi-mcp` runs with [`uv`](https://docs.astral.sh/uv/) (`uvx` fetches and runs it
+with no manual install or virtualenv):
+
+```bash
+uvx gi-mcp                # recommended (once published to PyPI)
+pip install gi-mcp        # alternative
+```
+
+Install `uv` with `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS/Linux)
+or see the [uv docs](https://docs.astral.sh/uv/). For local development from this
+monorepo:
+
+```bash
+cd mcp-server
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+```
+
+## Configure your MCP client
+
+Request a partner key from <https://genomicintelligence.ai/contact>, then add a
+server block. In every client the pattern is the same: run `uvx gi-mcp` with
+`GI_API_KEY` in the environment.
+
+**Claude Desktop** — edit `claude_desktop_config.json` (macOS:
+`~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`), then
+fully quit and reopen:
+
+```json
+{
+  "mcpServers": {
+    "genomic-intelligence": {
+      "command": "uvx",
+      "args": ["gi-mcp"],
+      "env": { "GI_API_KEY": "gi_..." }
+    }
+  }
+}
+```
+
+**Claude Code (CLI):**
+
+```bash
+claude mcp add genomic-intelligence --env GI_API_KEY=gi_... -- uvx gi-mcp
+```
+
+**Cursor / Windsurf / Zed** use the same JSON shape as Claude Desktop in their
+own MCP config files. **Your own agent:** point any MCP-capable client at the
+stdio command `uvx gi-mcp` with `GI_API_KEY` set — it speaks standard MCP.
+
+From a **local checkout**, point `command` at the venv entry point instead of
+`uvx`:
+
+```json
+{ "command": "/abs/path/to/mcp-server/.venv/bin/gi-mcp", "env": { "GI_API_KEY": "gi_..." } }
+```
+
+Notes:
+
+- **Verify:** your client should list the **genomic-intelligence** server with
+  16 tools. Ask *"List the available promoter models"* → runs `list_models`.
+- **Your key, your quota:** calls count against your partner key's rate /
+  concurrency caps. The server stores no key and owns no inference.
+- **Updating / pinning:** `uvx --refresh gi-mcp` picks up new releases; pin with
+  `"args": ["gi-mcp@0.1.0a9"]`.
+
+## The handle pattern (why large sequences don't bloat your context)
+
+Genomic sequences are big — the expression model alone wants 9,198 bp, and
+promoter accepts up to 500,000. Round-tripping those through the LLM twice
+(once as a tool result, once as the next tool's argument) is wasteful and
+blows the context window.
+
+So acquisition and prediction are split:
+
+1. An **acquisition** tool fetches/loads a sequence, stores it server-side, and
+   returns a short **handle** (`seq_ab12cd34`) plus light metadata — never the
+   bases.
+2. A **prediction** tool takes that `sequence_ref`. The server resolves the
+   bases internally.
+
+```
+fetch_ensembl_sequence(gene="TP53")
+  → { ref: "seq_ab12cd34", name: "TP53", length: 19148, preview: "CACC…GGTG" }
+
+predict_promoter(sequence_ref="seq_ab12cd34")
+  → { data: { regions: [...] }, meta: {...} }     # 19 kb never hit the LLM
+```
+
+Small sequences can still be passed inline via `sequence`. Every predict tool
+accepts `sequence` **xor** `sequence_ref`. The handle lives server-side, so a
+remote client (e.g. ChatGPT) that opens a fresh session per tool call still
+resolves the fetched sequence across the fetch→predict steps.
+
+## Try it
+
+Copy-paste these natural-language prompts into a freshly-connected client to
+smoke-test the live connection end-to-end — one per inference task plus the
+composite workflow, ordered from simplest (no inference) to full fetch→predict
+chains.
+
+| # | Task | Prompt | Expected behavior |
+|---|------|--------|-------------------|
+| 0 | warm-up (no inference) | "What Genomic Intelligence models are available for the expression task?" | Calls `list_models`; returns the model registry. No inference. |
+| 1 | promoter | "Fetch human TP53 from Ensembl and scan it for promoter regions — show me the strongest hits." | Fetch → `predict_promoter`; ranked promoter windows. |
+| 2 | expression | "Fetch HBB prepared for expression and predict its expression in K562 cells." | `fetch_gene_for_expression` → `predict_expression`. Cell-type-specific — omit the cell type and it returns `invalid_input` asking for it. |
+| 3 | splice | "Fetch the human HBB gene sequence and predict its splice sites." | Fetch → `predict_splice`; donor/acceptor sites. |
+| 4 | enhancer | "Fetch human GATA1 and predict enhancer regions." | Fetch → `predict_enhancer`. |
+| 5 | chromatin | "Fetch human SOX2 and predict chromatin accessibility." | Fetch → `predict_chromatin`. |
+| 6 | annotation | "Find the genes in chr8:127,680,000–127,800,000." | `fetch_region` → `find_genes`; transcript intervals (plus-strand). |
+| 7 | composite | "Find the genes in chr8:127,680,000–127,800,000 and predict each one's expression in K562." | `find_genes_and_predict_expression` — annotation→expression in one call. |
+
+No API key handy? *"List the bundled demo sequences, then load the K562
+expression one and predict its expression"* runs `load_demo_sequence` → no
+Ensembl fetch, no personal quota. The server ships one curated positive control
+per task (including `annotation_hbb_chr11`, a plus-strand HBB locus the
+gene-finder recovers centred on the TSS), so every task above is smoke-testable
+this way.
+
+**Going further** — the server also works as an analytical assistant that chains
+tools and reasons over results:
+
+- *"Compare the regulatory landscape of HBB versus HBA1 — which has stronger promoter signal and higher predicted expression in K562?"*
+- *"Run promoter prediction on TP53 with every available model and give me a diff table of where they disagree."*  (`list_models` + multi-model fan-out)
+- *"Annotate chr8:127,680,000–127,800,000 — if it's slow, hand me a job ID and I'll check back."*  (async `find_genes` → `get_job`)
+- *"Characterize GATA1: run every applicable task and assemble a one-page report for a wet-lab audience."*
+
+## What's exposed
+
+### Tools
+
+| Group | Tools |
+|---|---|
+| Acquisition | `fetch_ensembl_sequence`, `fetch_region`, `fetch_gene_for_expression`, `load_local_fasta`, `store_inline_sequence`, `load_demo_sequence` |
+| Prediction (sync) | `predict_promoter`, `predict_splice`, `predict_enhancer`, `predict_chromatin`, `predict_expression` |
+| Prediction (async) | `find_genes` |
+| Workflow | `find_genes_and_predict_expression` |
+| Jobs | `get_job`, `list_jobs` |
+| Catalog | `list_models` |
+
+### Resources
+
+| URI | Contents |
+|---|---|
+| `gi://models` | Full model catalog across all six tasks |
+| `gi://models/{model_id}` | Bio spec for one model |
+| `gi://docs/tasks` | What each task does, sync/async, length bounds |
+| `gi://openapi.json` | Live `/v1` OpenAPI contract |
+| `gi://sequences` | Bundled demo references — one positive control per task; load one with `load_demo_sequence` |
+| `gi://cache/{ref}` | Inspect a stored sequence handle |
+| `gi://jobs/recent` | The caller's recent async jobs |
+| `gi://account` | Configured backend + health + exposed tasks |
+
+### Prompts (slash-command workflows)
+
+| Prompt | What it does |
+|---|---|
+| `gi-promoter-screen <gene>` | Fetch a gene → scan for promoters → report strong hits |
+| `gi-expression-screen <gene>` | TSS window → predict expression → summarise across tissues |
+
+### Roots
+
+`load_local_fasta` only reads files inside directories the user granted via MCP
+roots. Set `GI_FASTA_ALLOW_ANY=1` to bypass on hosts that don't implement roots.
+
+## Environment
+
+| Var | Default | Purpose |
+|---|---|---|
+| `GI_API_KEY` | — (required) | Partner bearer key (`gi_…`) |
+| `GI_BASE_URL` | `https://api.genomicintelligence.ai` | Override for staging / local backend |
+| `GI_ENSEMBL_URL` | `https://rest.ensembl.org` | Ensembl REST base |
+| `GI_FASTA_ALLOW_ANY` | unset | `1` to skip roots gating for local FASTA |
+| `GI_ASYNC_TIMEOUT` | `240` | Ceiling (s) a `wait=True` slow task blocks while streaming progress before returning a `timeout` error (never a job_id) |
+| `GI_ASYNC_POLL_INTERVAL` | `2` | Poll cadence (s) for the block-and-stream loop |
+| `GI_HTTP_TIMEOUT` | `300` | Per-request read timeout (s) for `/v1` calls |
+
+## Development & contributing
+
+Setup, conventions, the architecture walkthrough, and the release process live
+in [`CONTRIBUTING.md`](CONTRIBUTING.md). Quick start:
+
+```bash
+.venv/bin/pytest                 # full suite (mocked; no network)
+```
+
+Release history is in [`CHANGELOG.md`](CHANGELOG.md).