@cyanheads/interpro-mcp-server 0.1.2 → 0.2.0

package/AGENTS.md

@@ -1,10 +1,10 @@
 # Developer Protocol
 
 **Server:** @cyanheads/interpro-mcp-server
-**Version:** 0.1.2
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
+**Version:** 0.2.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
+**MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
 **Zod:** ^4.6.7
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
@@ -48,7 +48,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 
 ### Tool
 
-Abridged from `src/mcp-server/tools/definitions/interpro-get-entry.tool.ts`. All six tools share this shape: a service call through `service.begin(ctx)`, `ctx.enrich` for notices, a per-tool `errors` contract, and the shared `formatInterpro` formatter.
+Abridged from `src/mcp-server/tools/definitions/interpro-get-entry.tool.ts`. All nine tools share this shape: a service call through `service.begin(ctx)`, `ctx.enrich` for notices, a per-tool `errors` contract, and the shared `formatInterpro` formatter.
 
 ```ts
 import { tool, z } from '@cyanheads/mcp-ts-core';
@@ -96,7 +96,7 @@ export const interproGetEntry = tool('interpro_get_entry', {
 });
 ```
 
-There are no resources or prompts and no server-specific environment variables: the InterPro API is keyless. Search/member pages clamp positive integer limits to 100, discovery to 50, with default 20 and composed notices. GO filters require the InterPro source; member recovery follows `member_databases` or `integratedInto`. Discovery requests native `extra_fields.is_fragment` on every page, binds only explicit `isFragment` selections to cursor scope, and preserves unknown status. Entry detail alone adds readable `descriptionText` through the `htmlparser2` streaming tokenizer while preserving raw descriptions and annotation flags.
+There are no resources or prompts. The InterPro API is keyless; the one server-specific environment variable, optional `INTERPRO_SCAN_EMAIL` (parsed in `src/config/server-config.ts`), is the contact address the EBI Job Dispatcher requires for InterProScan submissions. Unset, `interpro_scan_sequence` still serves precalculated matches and fails other sequences as `scan_not_configured`; the hosted instance leaves it unset. The scan tools (`interpro_scan_sequence`, `interpro_get_scan_result`) run through `src/services/sequence-scan/`, outside the InterPro pacer, and `interpro_scan_sequence` is the only tool that is not read-only. `interpro_get_structure_domains` lifts each match's nested chain records into top-level `structures[]` joined by `entry` to stay inside the depth-8 parity walker, and its numbering contract (chain `start`/`end` beside author `auth_start`/`auth_end`, UniProt positions) is retained verbatim. Optional `proteomeId` on discovery joins the route after `taxonId` and binds to the cursor scope only when present. Search/member pages clamp positive integer limits to 100, discovery to 50, with default 20 and composed notices. GO filters require the InterPro source and accept either `goTerm` or `goCategory`, never both; member recovery follows `member_databases` or `integratedInto`. Entry `sections` selects named metadata while retaining core and unknown fields; explicit `overlapLimit` enables whole-record paging. Retained descriptions gain readable `descriptionText` through `htmlparser2`, alongside unchanged raw descriptions and annotation flags. Protein maps append requested residue rules after matches and extra features, preserving complete records and old cursor scopes when the new flag is absent/false. Discovery requests native fragment status on every page; optional `architectureId` adds native IDA grouping and explicit entry/taxon detail availability without inventing missing arrays. Bind only explicit selections to cursor scope and preserve unknown upstream values.
 
 ### Server identity and instructions
 
@@ -106,9 +106,13 @@ There are no resources or prompts and no server-specific environment variables:
 await createApp({
   name: 'interpro-mcp-server',
   title: 'interpro-mcp-server',
-  tools: [/* six definitions */],
+  tools: [/* nine definitions */],
   sessionMode: 'stateless',
-  setup() { initInterproService(); },
+  skills: 'skills',
+  setup() {
+    initInterproService();
+    initSequenceScanService(getServerConfig().scanEmail);
+  },
   teardown() { disposeInterproService(); },
   instructions: '…',
 });
@@ -182,12 +186,15 @@ See framework CLAUDE.md and the `api-errors` skill for the full auto-classificat
 ```text
 src/
   index.ts                              # createApp() entry point
+  config/
+    server-config.ts                    # INTERPRO_SCAN_EMAIL parsing (lazy, validated at startup)
   services/
     interpro/
       interpro-service.ts               # Paced, cancellable request boundary (init/accessor pattern)
-      http-adapter.ts                   # node:https HTTP/1.1 transport with 204 handling
+      http-adapter.ts                   # node:https HTTP/1.1 transport with 204 handling; also carries the scan tools' Matches API and Job Dispatcher calls
       routing.ts                        # Accession → database routing, fixed-origin URL building
       schemas.ts                        # Wire and output Zod schemas
+      structure-schemas.ts              # PDB ID and chain validation, structure and chain-record schemas
       cursors.ts                        # Opaque cursor envelopes
       budget.ts                         # 100,000-byte response budget and whole-item fitting
       relationships.ts                  # Clan relationship-graph slicing
@@ -195,9 +202,14 @@ src/
       format.ts                         # Shared content[] formatter
       description-text.ts               # Readable HTML fragment projection for entry detail
       upstream-errors.ts                # Shared upstream error contract rows
+    sequence-scan/
+      sequence.ts                       # Sequence parsing and the UniParc MD5 digest
+      scan-schemas.ts                   # Matches API, Job Dispatcher, and match-record schemas
+      sequence-scan-service.ts          # Precalculated lookup, job submission and polling, in-flight cap
+      scan-output.ts                    # Shared scan output schema and match segmentation
   mcp-server/
     tools/definitions/
-      interpro-[name].tool.ts           # Six tool definitions
+      interpro-[name].tool.ts           # Nine tool definitions
 tests/
   services/                             # Service, adapter, and budget tests
   tools/                                # Tool contract tests
@@ -218,9 +230,18 @@ tests/
 
 ## Skills
 
-Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
+Two skill trees live at the project root, written for different readers:
+
+| Tree | For | Written by |
+|:-----|:----|:-----------|
+| `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |
+| `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | You, deliberately, with the `add-skill` skill. Absent by default; usually none is needed |
+
+Development skills are modular instructions. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. Their directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand them to every agent that installs it.
+
+A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree. This server publishes one, `skills/interpro-guide/SKILL.md` (identifier chains, gates, and chain/author/UniProt numbering), served with `skills: 'skills'`.
 
-**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
+**Agent skill directory:** Copy `framework-skills/` into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
 
 Available skills:
 
@@ -232,6 +253,7 @@ Available skills:
 | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
 | `add-resource` | Scaffold a new resource definition |
 | `add-prompt` | Scaffold a new prompt definition |
+| `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -279,7 +301,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
 | `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
 | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
-| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
+| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity, `.mcpbignore` coverage, plugin manifests, the published `skills/` tree (run by devcheck) |
 | `bun run list-skills` | Print the skill registry |
 | `bun run tree` | Generate directory structure doc |
 | `bun run format` | Auto-fix formatting (safe fixes only) |
@@ -295,7 +317,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
 | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
-**Waived `devcheck` warnings.** `bun run devcheck` emits six `format-parity-depth-limit` warnings, for the `…fragments[].start`, `…fragments[].end`, and `…fragments[].dc-status` output fields of `interpro_find_proteins_by_domain` and `interpro_get_protein_domains`. The schema is finite but deeper than the framework's depth-8 parity walker, and tests prove both surfaces render those fields. The owner waived exactly these six, pending [cyanheads/mcp-ts-core#531](https://github.com/cyanheads/mcp-ts-core/issues/531). Don't flatten or weaken the schema, and don't add suppressions to clear them. Any other warning, or a seventh of this kind, still blocks shipping.
+**Waived `devcheck` warnings.** The owner waived `format-parity-depth-limit` for the `…fragments[].start`, `…fragments[].end`, and `…fragments[].dc-status` output fields of `interpro_find_proteins_by_domain` and `interpro_get_protein_domains`, plus discovery's containing path `proteins[].entries[].entry_protein_locations[].fragments[]`. The architecture union moves discovery's three diagnostics to that array, so the current schema emits four warnings. These finite nested records exceed the framework's depth-8 parity walker; tests prove both surfaces retain them, pending [cyanheads/mcp-ts-core#531](https://github.com/cyanheads/mcp-ts-core/issues/531). Don't flatten or weaken the schema or add suppressions. Any warning outside these exact paths still blocks shipping.
 
 **CI is one file.** `.github/workflows/codeql.yml` (scaffolded) is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
 
@@ -303,7 +325,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ## Bundling
 
-`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
+`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `mcpb pack` reads `.mcpbignore`, not `.gitignore`, so every root path the bundle must not ship — source, tests, docs, caches, logs, agent docs, plugin manifests, gitignored local files — needs a root-anchored line there (`/docs/`, never `docs/`, which also strips `node_modules/*/docs/`); `lint:packaging` names each missing or unanchored line. Root `skills/` ships on purpose. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips four classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`); platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on; node-gyp build output beside a `binding.gyp` (`config.gypi`, Makefiles, `obj.target/`, `.deps/`, object files and debug symbols), which records the packing machine's paths — compiled `*.node` addons stay; and build-only package files — the framework's `changelog/`, `scripts/`, `templates/`, `CLAUDE.md`, `AGENTS.md`, and config bases (`biome.json`, `vitest.config.base.mjs`, `config/tsconfig.base.json`), and `better-sqlite3`'s `deps/` and `src/` C sources. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
 
 **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
 
@@ -370,7 +392,10 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
+- [ ] `plugin.json` + `mcp.json` (Agent Plugins 1.0.0 — read by Codex, Cursor, GitHub Copilot, VS Code, Kiro) populated — `plugin.json` `name` = the unscoped repo name (lowercase `a-z`, `0-9`, `-`, `.` only); `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords` from `package.json`; no other top-level field, `extensions` included. `mcp.json` holds one `"type": "stdio"` entry keyed by the unscoped name, `npx -y <full package name>`, and the same fixed `env` as `.codex-plugin/mcp.json`. Neither file carries a user-supplied variable (no `""`, no `${…}` besides `${PLUGIN_ROOT}`/`${PLUGIN_DATA}`): keys reach Codex through `.codex-plugin/mcp.json` `env_vars`, which works only while `.codex-plugin/plugin.json` keeps `"mcpServers": "./.codex-plugin/mcp.json"`
 - [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
 - [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
 - [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
+- [ ] Any new root dev path has a root-anchored line in `.mcpbignore`; `bun run bundle` and `lint:packaging` pass
+- [ ] If the server publishes a skill in root `skills/`: `lint:packaging` passes, and `field-test` verified every gate and identifier claim in it against live tool behavior
 - [ ] `npm run devcheck` passes

package/CLAUDE.md

@@ -1,10 +1,10 @@
 # Developer Protocol
 
 **Server:** @cyanheads/interpro-mcp-server
-**Version:** 0.1.2
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`
+**Version:** 0.2.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
+**MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
 **Zod:** ^4.6.7
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
@@ -48,7 +48,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 
 ### Tool
 
-Abridged from `src/mcp-server/tools/definitions/interpro-get-entry.tool.ts`. All six tools share this shape: a service call through `service.begin(ctx)`, `ctx.enrich` for notices, a per-tool `errors` contract, and the shared `formatInterpro` formatter.
+Abridged from `src/mcp-server/tools/definitions/interpro-get-entry.tool.ts`. All nine tools share this shape: a service call through `service.begin(ctx)`, `ctx.enrich` for notices, a per-tool `errors` contract, and the shared `formatInterpro` formatter.
 
 ```ts
 import { tool, z } from '@cyanheads/mcp-ts-core';
@@ -96,7 +96,7 @@ export const interproGetEntry = tool('interpro_get_entry', {
 });
 ```
 
-There are no resources or prompts and no server-specific environment variables: the InterPro API is keyless. Search/member pages clamp positive integer limits to 100, discovery to 50, with default 20 and composed notices. GO filters require the InterPro source; member recovery follows `member_databases` or `integratedInto`. Discovery requests native `extra_fields.is_fragment` on every page, binds only explicit `isFragment` selections to cursor scope, and preserves unknown status. Entry detail alone adds readable `descriptionText` through the `htmlparser2` streaming tokenizer while preserving raw descriptions and annotation flags.
+There are no resources or prompts. The InterPro API is keyless; the one server-specific environment variable, optional `INTERPRO_SCAN_EMAIL` (parsed in `src/config/server-config.ts`), is the contact address the EBI Job Dispatcher requires for InterProScan submissions. Unset, `interpro_scan_sequence` still serves precalculated matches and fails other sequences as `scan_not_configured`; the hosted instance leaves it unset. The scan tools (`interpro_scan_sequence`, `interpro_get_scan_result`) run through `src/services/sequence-scan/`, outside the InterPro pacer, and `interpro_scan_sequence` is the only tool that is not read-only. `interpro_get_structure_domains` lifts each match's nested chain records into top-level `structures[]` joined by `entry` to stay inside the depth-8 parity walker, and its numbering contract (chain `start`/`end` beside author `auth_start`/`auth_end`, UniProt positions) is retained verbatim. Optional `proteomeId` on discovery joins the route after `taxonId` and binds to the cursor scope only when present. Search/member pages clamp positive integer limits to 100, discovery to 50, with default 20 and composed notices. GO filters require the InterPro source and accept either `goTerm` or `goCategory`, never both; member recovery follows `member_databases` or `integratedInto`. Entry `sections` selects named metadata while retaining core and unknown fields; explicit `overlapLimit` enables whole-record paging. Retained descriptions gain readable `descriptionText` through `htmlparser2`, alongside unchanged raw descriptions and annotation flags. Protein maps append requested residue rules after matches and extra features, preserving complete records and old cursor scopes when the new flag is absent/false. Discovery requests native fragment status on every page; optional `architectureId` adds native IDA grouping and explicit entry/taxon detail availability without inventing missing arrays. Bind only explicit selections to cursor scope and preserve unknown upstream values.
 
 ### Server identity and instructions
 
@@ -106,9 +106,13 @@ There are no resources or prompts and no server-specific environment variables:
 await createApp({
   name: 'interpro-mcp-server',
   title: 'interpro-mcp-server',
-  tools: [/* six definitions */],
+  tools: [/* nine definitions */],
   sessionMode: 'stateless',
-  setup() { initInterproService(); },
+  skills: 'skills',
+  setup() {
+    initInterproService();
+    initSequenceScanService(getServerConfig().scanEmail);
+  },
   teardown() { disposeInterproService(); },
   instructions: '…',
 });
@@ -182,12 +186,15 @@ See framework CLAUDE.md and the `api-errors` skill for the full auto-classificat
 ```text
 src/
   index.ts                              # createApp() entry point
+  config/
+    server-config.ts                    # INTERPRO_SCAN_EMAIL parsing (lazy, validated at startup)
   services/
     interpro/
       interpro-service.ts               # Paced, cancellable request boundary (init/accessor pattern)
-      http-adapter.ts                   # node:https HTTP/1.1 transport with 204 handling
+      http-adapter.ts                   # node:https HTTP/1.1 transport with 204 handling; also carries the scan tools' Matches API and Job Dispatcher calls
       routing.ts                        # Accession → database routing, fixed-origin URL building
       schemas.ts                        # Wire and output Zod schemas
+      structure-schemas.ts              # PDB ID and chain validation, structure and chain-record schemas
       cursors.ts                        # Opaque cursor envelopes
       budget.ts                         # 100,000-byte response budget and whole-item fitting
       relationships.ts                  # Clan relationship-graph slicing
@@ -195,9 +202,14 @@ src/
       format.ts                         # Shared content[] formatter
       description-text.ts               # Readable HTML fragment projection for entry detail
       upstream-errors.ts                # Shared upstream error contract rows
+    sequence-scan/
+      sequence.ts                       # Sequence parsing and the UniParc MD5 digest
+      scan-schemas.ts                   # Matches API, Job Dispatcher, and match-record schemas
+      sequence-scan-service.ts          # Precalculated lookup, job submission and polling, in-flight cap
+      scan-output.ts                    # Shared scan output schema and match segmentation
   mcp-server/
     tools/definitions/
-      interpro-[name].tool.ts           # Six tool definitions
+      interpro-[name].tool.ts           # Nine tool definitions
 tests/
   services/                             # Service, adapter, and budget tests
   tools/                                # Tool contract tests
@@ -218,9 +230,18 @@ tests/
 
 ## Skills
 
-Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
+Two skill trees live at the project root, written for different readers:
+
+| Tree | For | Written by |
+|:-----|:----|:-----------|
+| `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |
+| `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | You, deliberately, with the `add-skill` skill. Absent by default; usually none is needed |
+
+Development skills are modular instructions. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. Their directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand them to every agent that installs it.
+
+A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree. This server publishes one, `skills/interpro-guide/SKILL.md` (identifier chains, gates, and chain/author/UniProt numbering), served with `skills: 'skills'`.
 
-**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
+**Agent skill directory:** Copy `framework-skills/` into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
 
 Available skills:
 
@@ -232,6 +253,7 @@ Available skills:
 | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
 | `add-resource` | Scaffold a new resource definition |
 | `add-prompt` | Scaffold a new prompt definition |
+| `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -279,7 +301,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
 | `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
 | `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
-| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |
+| `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity, `.mcpbignore` coverage, plugin manifests, the published `skills/` tree (run by devcheck) |
 | `bun run list-skills` | Print the skill registry |
 | `bun run tree` | Generate directory structure doc |
 | `bun run format` | Auto-fix formatting (safe fixes only) |
@@ -295,7 +317,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
 | `bun run bundle` | Build, pack, and clean a `.mcpb` for one-click Claude Desktop install |
 
-**Waived `devcheck` warnings.** `bun run devcheck` emits six `format-parity-depth-limit` warnings, for the `…fragments[].start`, `…fragments[].end`, and `…fragments[].dc-status` output fields of `interpro_find_proteins_by_domain` and `interpro_get_protein_domains`. The schema is finite but deeper than the framework's depth-8 parity walker, and tests prove both surfaces render those fields. The owner waived exactly these six, pending [cyanheads/mcp-ts-core#531](https://github.com/cyanheads/mcp-ts-core/issues/531). Don't flatten or weaken the schema, and don't add suppressions to clear them. Any other warning, or a seventh of this kind, still blocks shipping.
+**Waived `devcheck` warnings.** The owner waived `format-parity-depth-limit` for the `…fragments[].start`, `…fragments[].end`, and `…fragments[].dc-status` output fields of `interpro_find_proteins_by_domain` and `interpro_get_protein_domains`, plus discovery's containing path `proteins[].entries[].entry_protein_locations[].fragments[]`. The architecture union moves discovery's three diagnostics to that array, so the current schema emits four warnings. These finite nested records exceed the framework's depth-8 parity walker; tests prove both surfaces retain them, pending [cyanheads/mcp-ts-core#531](https://github.com/cyanheads/mcp-ts-core/issues/531). Don't flatten or weaken the schema or add suppressions. Any warning outside these exact paths still blocks shipping.
 
 **CI is one file.** `.github/workflows/codeql.yml` (scaffolded) is the only GitHub Actions workflow: CodeQL is GitHub-owned end to end, and the file runs only while the repo's CodeQL *default setup* is turned off. Verification — `devcheck`, tests, the release gates — runs locally; don't add a workflow that re-runs it.
 
@@ -303,7 +325,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ## Bundling
 
-`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
+`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `mcpb pack` reads `.mcpbignore`, not `.gitignore`, so every root path the bundle must not ship — source, tests, docs, caches, logs, agent docs, plugin manifests, gitignored local files — needs a root-anchored line there (`/docs/`, never `docs/`, which also strips `node_modules/*/docs/`); `lint:packaging` names each missing or unanchored line. Root `skills/` ships on purpose. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips four classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`); platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on; node-gyp build output beside a `binding.gyp` (`config.gypi`, Makefiles, `obj.target/`, `.deps/`, object files and debug symbols), which records the packing machine's paths — compiled `*.node` addons stay; and build-only package files — the framework's `changelog/`, `scripts/`, `templates/`, `CLAUDE.md`, `AGENTS.md`, and config bases (`biome.json`, `vitest.config.base.mjs`, `config/tsconfig.base.json`), and `better-sqlite3`'s `deps/` and `src/` C sources. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
 
 **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
 
@@ -370,7 +392,10 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
+- [ ] `plugin.json` + `mcp.json` (Agent Plugins 1.0.0 — read by Codex, Cursor, GitHub Copilot, VS Code, Kiro) populated — `plugin.json` `name` = the unscoped repo name (lowercase `a-z`, `0-9`, `-`, `.` only); `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords` from `package.json`; no other top-level field, `extensions` included. `mcp.json` holds one `"type": "stdio"` entry keyed by the unscoped name, `npx -y <full package name>`, and the same fixed `env` as `.codex-plugin/mcp.json`. Neither file carries a user-supplied variable (no `""`, no `${…}` besides `${PLUGIN_ROOT}`/`${PLUGIN_DATA}`): keys reach Codex through `.codex-plugin/mcp.json` `env_vars`, which works only while `.codex-plugin/plugin.json` keeps `"mcpServers": "./.codex-plugin/mcp.json"`
 - [ ] `.codex-plugin/plugin.json` populated — `name`, `version`, `description`, `repository`, `license` from `package.json`; `interface.displayName` = the unscoped repo name (never the npm scope — `lint:packaging` enforces this); `interface.shortDescription` from `package.json` description
 - [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable (API key, contact email, instance URL) is listed in `env_vars` so Codex forwards it from the user's environment. Never write `"KEY": ""` into `env` — an empty value replaces the user's exported key and is read as unset
 - [ ] `.claude-plugin/plugin.json` populated — `name`, `version`, `description`, `author`, `repository`, `license`, `keywords` from `package.json`; inline `mcpServers` entry keyed by the unscoped repo name. Every user-supplied variable is declared under `userConfig` (`type`, `title`, `description`; `sensitive: true` for keys and tokens; `required: true` or `default: ""`) and referenced from `env` as `"KEY": "${user_config.<option>}"` — mirror the `user_config` block in `manifest.json`. Never write `"KEY": ""` into `env`
+- [ ] Any new root dev path has a root-anchored line in `.mcpbignore`; `bun run bundle` and `lint:packaging` pass
+- [ ] If the server publishes a skill in root `skills/`: `lint:packaging` passes, and `field-test` verified every gate and identifier claim in it against live tool behavior
 - [ ] `npm run devcheck` passes

package/Dockerfile

@@ -29,6 +29,11 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
 # Copy the rest of the source code
 COPY . .
 
+# The skills a server publishes (`createApp({ skills: 'skills' })`) are read at
+# runtime from the application root. Created when the project has none, so the
+# production stage's copy below holds with or without one.
+RUN mkdir -p skills
+
 # Build the application
 RUN bun run build
 
@@ -124,7 +129,7 @@ ENV NODE_ENV=production
 # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
 ARG APP_VERSION
 LABEL org.opencontainers.image.title="interpro-mcp-server"
-LABEL org.opencontainers.image.description="Search InterPro entries, map protein domains and functional sites, and find proteins by domain via MCP. STDIO or Streamable HTTP."
+LABEL org.opencontainers.image.description="Search InterPro entries, map domains and functional sites onto UniProt proteins and PDB structures, find proteins by domain, and scan raw protein sequences via MCP. STDIO or Streamable HTTP."
 LABEL org.opencontainers.image.licenses="Apache-2.0"
 LABEL org.opencontainers.image.version="${APP_VERSION}"
 LABEL org.opencontainers.image.source="https://github.com/cyanheads/interpro-mcp-server"
@@ -136,6 +141,7 @@ COPY --from=deps /usr/src/app/node_modules ./node_modules
 
 # Copy the compiled application code from the build stage
 COPY --from=build /usr/src/app/dist ./dist
+COPY --from=build /usr/src/app/skills ./skills
 
 # Mirror CLI (MirrorService adopters only — Tier 3, opt-in):
 # Copy your mirror lifecycle scripts and emit a runtime tsconfig so Bun resolves
@@ -175,6 +181,8 @@ ENV MCP_TRANSPORT_TYPE="http"
 ENV MCP_SESSION_MODE="stateless"
 ENV MCP_LOG_LEVEL="info"
 ENV LOGS_DIR="/var/log/interpro-mcp-server"
+# Optional, no default: set INTERPRO_SCAN_EMAIL at run time (docker run -e) to let
+# interpro_scan_sequence submit InterProScan jobs; unset, it serves precalculated matches only.
 
 # Expose the port the server listens on
 EXPOSE ${MCP_HTTP_PORT}