@cyanheads/pubmed-mcp-server 2.6.4 → 2.6.6

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Agent Protocol
 
 **Server:** @cyanheads/pubmed-mcp-server
-**Version:** 2.6.4
+**Version:** 2.6.6
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
 
 > **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.
@@ -14,14 +14,14 @@ When the user asks what to do next, what's left, or needs direction, suggest rel
 
 1. **Re-run the `setup` skill** — ensures CLAUDE.md, skills, structure, and metadata are populated and up to date with the current codebase
 2. **Run the `design-mcp-server` skill** — if the tool/resource surface hasn't been mapped yet, work through domain design
-3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-resource`, `add-prompt` skills
+3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt` skills
 4. **Add services** — scaffold domain service integrations using the `add-service` skill
 5. **Add tests** — scaffold tests for existing definitions using the `add-test` skill
 6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points
 7. **Run `devcheck`** — lint, format, typecheck, and security audit
 8. **Run the `security-pass` skill** — audit handlers for MCP-specific security gaps: output injection, scope blast radius, input sinks, tenant isolation
 9. **Run the `polish-docs-meta` skill** — finalize README, CHANGELOG, metadata, and agent protocol for shipping
-10. **Run the `maintenance` skill** — sync skills and dependencies after framework updates
+10. **Run the `maintenance` skill** — investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest`
 
 Tailor suggestions to what's actually missing or stale — don't recite the full list every time.
 
@@ -145,32 +145,60 @@ Handlers receive a unified `ctx` object. Key properties:
 |:---------|:------------|
 | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |
 | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |
+| `ctx.recoveryFor(reason)` | Typed lookup of the contract `recovery` for a declared reason. Returns `{ recovery: { hint } }` for known reasons, `{}` otherwise. Spread into `ctx.fail` data to mirror the contract hint into `content[]`. |
 | `ctx.signal` | `AbortSignal` for cancellation. |
 | `ctx.requestId` | Unique request ID. |
-| `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio. |
+| `ctx.tenantId` | Tenant ID from JWT, `'default'` for stdio or HTTP+`MCP_AUTH_MODE=none`. |
 
 ---
 
 ## Errors
 
-Handlers throw — the framework catches, classifies, and formats. Three escalation levels:
+Handlers throw — the framework catches, classifies, and formats.
+
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required (≥ 5 words, lint-validated) — it's the single source of truth for the recovery hint. Spread `ctx.recoveryFor('reason')` into `data` to mirror the contract recovery onto the wire (the framework mirrors `data.recovery.hint` into `content[]` text); pass an explicit `recovery: { hint: '...' }` when runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
 
 ```ts
-// 1. Plain Error — framework auto-classifies from message patterns
-throw new Error('Item not found');           // → NotFound
-throw new Error('Invalid query format');     // → ValidationError
+errors: [
+  { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
+    when: 'No requested PMID returned data',
+    recovery: 'Try pubmed_search_articles to discover valid PMIDs first.' },
+],
+async handler(input, ctx) {
+  const articles = await ncbi.fetch(input.pmids);
+  if (articles.length === 0) {
+    // Static contract recovery
+    throw ctx.fail('no_match', `None of ${input.pmids.length} PMIDs returned data`, {
+      ...ctx.recoveryFor('no_match'),
+    });
+  }
+  return { articles };
+}
+```
+
+**Fallback (no contract entry fits):** error factories or plain `Error`.
 
-// 2. Error factories — explicit code, concise
-import { notFound, validationError, forbidden, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+```ts
+// Error factories — explicit code, concise
+import { notFound, serializationError, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
 throw notFound('Item not found', { itemId });
 throw serviceUnavailable('API unavailable', { url }, { cause: err });
+throw serializationError('Invalid XML response', { endpoint });
+
+// Plain Error — framework auto-classifies from message patterns
+throw new Error('Item not found');           // → NotFound
+throw new Error('Invalid query format');     // → ValidationError
 
-// 3. McpError — full control over code and data
+// McpError — full control when the code is dynamic
 import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });
 ```
 
-Plain `Error` is fine for most cases. Use factories when the error code matters. See framework CLAUDE.md for the full auto-classification table and all available factories.
+For HTTP responses, prefer `httpErrorFromResponse(response, { service, data })` from `/utils` over hand-rolled status ladders — covers the full 4xx/5xx → `JsonRpcErrorCode` table and captures body + `Retry-After`.
+
+**Service-layer:** services don't have `ctx.fail`. To carry a contract `reason` from a service throw, pass `data: { reason: 'X' }` to the factory — the auto-classifier preserves `data` on the wire so clients see the same `error.data.reason` they'd see from `ctx.fail`.
+
+See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all factories, and the contract reference.
 
 ---
 
@@ -231,7 +259,7 @@ Available skills:
 | `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
-| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills after `bun update --latest` |
+| `maintenance` | Investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest` |
 | `release-and-publish` | Ship a release: verification gate, push commits+tags, publish to npm / MCP Registry / GHCR |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
 | `api-config` | AppConfig, parseConfig, env vars |
@@ -261,8 +289,6 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run format` | Auto-fix formatting |
 | `bun run test` | Run tests |
 | `bun run lint:mcp` | Validate MCP definitions against spec |
-| `bun run dev:stdio` | Dev mode (stdio) |
-| `bun run dev:http` | Dev mode (HTTP) |
 | `bun run start:stdio` | Production mode (stdio) |
 | `bun run start:http` | Production mode (HTTP) |
 

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![npm](https://img.shields.io/npm/v/@cyanheads/pubmed-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pubmed-mcp-server) [![Version](https://img.shields.io/badge/Version-2.6.4-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) 
+[![npm](https://img.shields.io/npm/v/@cyanheads/pubmed-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pubmed-mcp-server) [![Version](https://img.shields.io/badge/Version-2.6.6-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) 
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 

package/dist/mcp-server/prompts/definitions/research-plan.prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"research-plan.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/research-plan.prompt.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAU,CAAC,EAAE,MAAM,wBAAwB,CAAC;AA8InD,eAAO,MAAM,kBAAkB;;;;;;;;;kBA6B7B,CAAC"}
+{"version":3,"file":"research-plan.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/research-plan.prompt.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAU,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAgJnD,eAAO,MAAM,kBAAkB;;;;;;;;;kBA6B7B,CAAC"}

package/dist/mcp-server/prompts/definitions/research-plan.prompt.js

@@ -13,7 +13,7 @@ const ArgsSchema = z.object({
     includeAgentPrompts: z
         .enum(['true', 'false'])
         .default('false')
-        .describe('Include detailed prompts for consuming LLM ("true" or "false")'),
+        .describe('Include inline guidance blocks under each phase with execution-time hints ("true" or "false")'),
 });
 function agentBlock(text, include) {
     return include ? `\n> **Agent guidance:** ${text}\n` : '';

package/dist/mcp-server/prompts/definitions/research-plan.prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"research-plan.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/research-plan.prompt.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"research-plan.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/research-plan.prompt.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC;IAC3C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;IAClD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;IACpE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IAC3D,mBAAmB,EAAE,CAAC;SACnB,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SACvB,OAAO,CAAC,OAAO,CAAC;SAChB,QAAQ,CACP,+FAA+F,CAChG;CACJ,CAAC,CAAC;AAEH,SAAS,UAAU,CAAC,IAAY,EAAE,OAAgB;IAChD,OAAO,OAAO,CAAC,CAAC,CAAC,2BAA2B,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;AAC5D,CAAC;AAED,SAAS,SAAS,CAAC,IAAgC;IACjD,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ;SACrB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CAAC;IACnB,MAAM,MAAM,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,eAAe,CAAC;IAC7C,MAAM,EAAE,GAAG,IAAI,CAAC,mBAAmB,KAAK,MAAM,CAAC;IAE/C,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,oBAAoB,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACrC,KAAK,CAAC,IAAI,CAAC,iBAAiB,MAAM,EAAE,CAAC,CAAC;IACtC,KAAK,CAAC,IAAI,CAAC,iBAAiB,GAAG,EAAE,CAAC,CAAC;IACnC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,UAAU;IACV,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,KAAK,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;IAChD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;IACrD,KAAK,CAAC,IAAI,CAAC,yDAAyD,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;IAClF,KAAK,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAC;IACxE,KAAK,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;IAChE,KAAK,CAAC,IAAI,CACR,UAAU,CACR,8FAA8F,EAC9F,EAAE,CACH,CACF,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACxC,KAAK,CAAC,IAAI,CAAC,iDAAiD,MAAM,EAAE,CAAC,CAAC;IACtE,KAAK,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;IAClD,KAAK,CAAC,IAAI,CAAC,qEAAqE,CAAC,CAAC;IAClF,KAAK,CAAC,IAAI,CAAC,2EAA2E,CAAC,CAAC;IACxF,KAAK,CAAC,IAAI,CACR,UAAU,CACR,qGAAqG,EACrG,EAAE,CACH,CACF,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;IAC1C,KAAK,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;IAC5D,KAAK,CAAC,IAAI,CAAC,iEAAiE,CAAC,CAAC;IAC9E,KAAK,CAAC,IAAI,CAAC,yEAAyE,CAAC,CAAC;IACtF,KAAK,CAAC,IAAI,CAAC,kEAAkE,CAAC,CAAC;IAC/E,KAAK,CAAC,IAAI,CAAC,kEAAkE,CAAC,CAAC;IAC/E,KAAK,CAAC,IAAI,CACR,UAAU,CAAC,6EAA6E,EAAE,EAAE,CAAC,CAC9F,CAAC;IAEF,UAAU;IACV,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,KAAK,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;IACvD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IACtC,KAAK,CAAC,IAAI,CAAC,uDAAuD,CAAC,CAAC;IACpE,KAAK,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;IAC7E,KAAK,CAAC,IAAI,CAAC,qDAAqD,CAAC,CAAC;IAClE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,6DAA6D,EAAE,EAAE,CAAC,CAAC,CAAC;IAC1F,KAAK,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;IACtD,KAAK,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;IAC5D,KAAK,CAAC,IAAI,CAAC,4DAA4D,CAAC,CAAC;IACzE,KAAK,CAAC,IAAI,CAAC,wEAAwE,CAAC,CAAC;IACrF,KAAK,CAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;IACrE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,8DAA8D,EAAE,EAAE,CAAC,CAAC,CAAC;IAE3F,UAAU;IACV,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,KAAK,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;IACpD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;IAC3D,KAAK,CAAC,IAAI,CAAC,2EAA2E,CAAC,CAAC;IACxF,KAAK,CAAC,IAAI,CAAC,uDAAuD,CAAC,CAAC;IACpE,KAAK,CAAC,IAAI,CAAC,oEAAoE,CAAC,CAAC;IACjF,KAAK,CAAC,IAAI,CAAC,qDAAqD,CAAC,CAAC;IAClE,KAAK,CAAC,IAAI,CACR,UAAU,CACR,yFAAyF,EACzF,EAAE,CACH,CACF,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;IACzD,KAAK,CAAC,IAAI,CAAC,oDAAoD,CAAC,CAAC;IACjE,KAAK,CAAC,IAAI,CAAC,4EAA4E,CAAC,CAAC;IACzF,KAAK,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAC;IACxE,KAAK,CAAC,IAAI,CAAC,8DAA8D,CAAC,CAAC;IAC3E,KAAK,CAAC,IAAI,CACR,UAAU,CACR,uFAAuF,EACvF,EAAE,CACH,CACF,CAAC;IAEF,UAAU;IACV,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,KAAK,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACxC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;IACnD,KAAK,CAAC,IAAI,CAAC,sEAAsE,CAAC,CAAC;IACnF,KAAK,CAAC,IAAI,CAAC,oFAAoF,CAAC,CAAC;IACjG,KAAK,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAC;IACxE,KAAK,CAAC,IAAI,CACR,UAAU,CACR,oFAAoF,EACpF,EAAE,CACH,CACF,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;IACtD,KAAK,CAAC,IAAI,CAAC,8DAA8D,CAAC,CAAC;IAC3E,KAAK,CAAC,IAAI,CAAC,4DAA4D,CAAC,CAAC;IACzE,KAAK,CAAC,IAAI,CAAC,qDAAqD,CAAC,CAAC;IAClE,KAAK,CAAC,IAAI,CAAC,+DAA+D,CAAC,CAAC;IAC5E,KAAK,CAAC,IAAI,CACR,UAAU,CACR,uFAAuF,EACvF,EAAE,CACH,CACF,CAAC;IAEF,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,eAAe,EAAE;IACxD,WAAW,EAAE,gFAAgF;IAC7F,IAAI,EAAE,UAAU;IAEhB,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE;QACjB,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAE7B,OAAO;YACL;gBACE,IAAI,EAAE,WAAoB;gBAC1B,OAAO,EAAE;oBACP,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE;wBACJ,mDAAmD;wBACnD,8EAA8E;wBAC9E,+FAA+F;wBAC/F,4FAA4F;qBAC7F,CAAC,IAAI,CAAC,GAAG,CAAC;iBACZ;aACF;YACD;gBACE,IAAI,EAAE,MAAe;gBACrB,OAAO,EAAE;oBACP,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI;iBACX;aACF;SACF,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/resources/definitions/database-info.resource.d.ts

@@ -14,5 +14,5 @@ export declare const databaseInfoResource: import("@cyanheads/mcp-ts-core").Reso
         fullName: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
-}, z.core.$strip>>;
+}, z.core.$strip>, undefined>;
 //# sourceMappingURL=database-info.resource.d.ts.map

package/dist/mcp-server/resources/definitions/database-info.resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database-info.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/database-info.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAoBrD,eAAO,MAAM,oBAAoB;;;;;;;;;;kBA+C/B,CAAC"}
+{"version":3,"file":"database-info.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/database-info.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAoBrD,eAAO,MAAM,oBAAoB;;;;;;;;;;6BA+C/B,CAAC"}

package/dist/mcp-server/tools/definitions/_error-contracts.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Shared `errors[]` contract entries for tool definitions.
+ *
+ * The NCBI service layer (queue, retry loop, deadline) throws three failure
+ * modes that any NCBI-consuming tool can surface. They're collected here so
+ * tool definitions can spread them into their own `errors[]` without
+ * duplicating the contract — keeping the public failure surface consistent
+ * and machine-readable across the whole server.
+ *
+ * Service-layer throws stamp `data.reason` to match these entries (see
+ * `src/services/ncbi/request-queue.ts` and `src/services/ncbi/ncbi-service.ts`)
+ * so wire payloads carry the same `error.data.reason` clients see from
+ * `ctx.fail` in tool handlers.
+ *
+ * @module src/mcp-server/tools/definitions/_error-contracts
+ */
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+/**
+ * Cross-tool error reasons shared by every tool that calls the NCBI service.
+ * Spread these into a tool's `errors[]` alongside any tool-specific entries.
+ */
+export declare const NCBI_SERVICE_ERRORS: readonly [{
+    readonly reason: "queue_full";
+    readonly code: JsonRpcErrorCode.RateLimited;
+    readonly when: "Local NCBI request queue is at capacity.";
+    readonly recovery: "Retry after 1-2 seconds; the request queue hit the NCBI rate limit.";
+    readonly retryable: true;
+}, {
+    readonly reason: "ncbi_unreachable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "NCBI E-utilities is unreachable after all retry attempts.";
+    readonly recovery: "Retry after a brief delay; NCBI was unreachable across all retry attempts.";
+    readonly retryable: true;
+}, {
+    readonly reason: "ncbi_deadline_exceeded";
+    readonly code: JsonRpcErrorCode.Timeout;
+    readonly when: "Total request deadline expired before NCBI returned a response.";
+    readonly recovery: "Reduce batch size or retry; NCBI may be under temporary load.";
+    readonly retryable: true;
+}];
+//# sourceMappingURL=_error-contracts.d.ts.map

package/dist/mcp-server/tools/definitions/_error-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_error-contracts.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_error-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;EAsBtB,CAAC"}

package/dist/mcp-server/tools/definitions/_error-contracts.js

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Shared `errors[]` contract entries for tool definitions.
+ *
+ * The NCBI service layer (queue, retry loop, deadline) throws three failure
+ * modes that any NCBI-consuming tool can surface. They're collected here so
+ * tool definitions can spread them into their own `errors[]` without
+ * duplicating the contract — keeping the public failure surface consistent
+ * and machine-readable across the whole server.
+ *
+ * Service-layer throws stamp `data.reason` to match these entries (see
+ * `src/services/ncbi/request-queue.ts` and `src/services/ncbi/ncbi-service.ts`)
+ * so wire payloads carry the same `error.data.reason` clients see from
+ * `ctx.fail` in tool handlers.
+ *
+ * @module src/mcp-server/tools/definitions/_error-contracts
+ */
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+/**
+ * Cross-tool error reasons shared by every tool that calls the NCBI service.
+ * Spread these into a tool's `errors[]` alongside any tool-specific entries.
+ */
+export const NCBI_SERVICE_ERRORS = [
+    {
+        reason: 'queue_full',
+        code: JsonRpcErrorCode.RateLimited,
+        when: 'Local NCBI request queue is at capacity.',
+        recovery: 'Retry after 1-2 seconds; the request queue hit the NCBI rate limit.',
+        retryable: true,
+    },
+    {
+        reason: 'ncbi_unreachable',
+        code: JsonRpcErrorCode.ServiceUnavailable,
+        when: 'NCBI E-utilities is unreachable after all retry attempts.',
+        recovery: 'Retry after a brief delay; NCBI was unreachable across all retry attempts.',
+        retryable: true,
+    },
+    {
+        reason: 'ncbi_deadline_exceeded',
+        code: JsonRpcErrorCode.Timeout,
+        when: 'Total request deadline expired before NCBI returned a response.',
+        recovery: 'Reduce batch size or retry; NCBI may be under temporary load.',
+        retryable: true,
+    },
+];
+//# sourceMappingURL=_error-contracts.js.map

package/dist/mcp-server/tools/definitions/_error-contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_error-contracts.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_error-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEjE;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC;QACE,MAAM,EAAE,YAAY;QACpB,IAAI,EAAE,gBAAgB,CAAC,WAAW;QAClC,IAAI,EAAE,0CAA0C;QAChD,QAAQ,EAAE,qEAAqE;QAC/E,SAAS,EAAE,IAAI;KAChB;IACD;QACE,MAAM,EAAE,kBAAkB;QAC1B,IAAI,EAAE,gBAAgB,CAAC,kBAAkB;QACzC,IAAI,EAAE,2DAA2D;QACjE,QAAQ,EAAE,4EAA4E;QACtF,SAAS,EAAE,IAAI;KAChB;IACD;QACE,MAAM,EAAE,wBAAwB;QAChC,IAAI,EAAE,gBAAgB,CAAC,OAAO;QAC9B,IAAI,EAAE,iEAAiE;QACvE,QAAQ,EAAE,+DAA+D;QACzE,SAAS,EAAE,IAAI;KAChB;CACO,CAAC"}

package/dist/mcp-server/tools/definitions/convert-ids.tool.d.ts

@@ -6,7 +6,7 @@
 import { z } from '@cyanheads/mcp-ts-core';
 export declare const convertIdsTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
     ids: z.ZodArray<z.ZodString>;
-    idtype: z.ZodEnum<{
+    idType: z.ZodEnum<{
         pmcid: "pmcid";
         pmid: "pmid";
         doi: "doi";
@@ -21,5 +21,5 @@ export declare const convertIdsTool: import("@cyanheads/mcp-ts-core").ToolDefini
     }, z.core.$strip>>;
     totalConverted: z.ZodNumber;
     totalSubmitted: z.ZodNumber;
-}, z.core.$strip>>;
+}, z.core.$strip>, undefined>;
 //# sourceMappingURL=convert-ids.tool.d.ts.map

package/dist/mcp-server/tools/definitions/convert-ids.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convert-ids.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/convert-ids.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAajD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;kBAyGzB,CAAC"}
+{"version":3,"file":"convert-ids.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/convert-ids.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAajD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;6BAyGzB,CAAC"}

package/dist/mcp-server/tools/definitions/convert-ids.tool.js

@@ -24,7 +24,7 @@ export const convertIdsTool = tool('pubmed_convert_ids', {
             .min(1)
             .max(50)
             .describe('Article identifiers to convert. All IDs must be the same type. DOIs: "10.1093/nar/gks1195", PMIDs: "23193287", PMCIDs: "PMC3531190".'),
-        idtype: z
+        idType: z
             .enum(['pmcid', 'pmid', 'doi'])
             .describe('The type of IDs being submitted. Required so the API can unambiguously resolve them.'),
     }),
@@ -55,9 +55,9 @@ export const convertIdsTool = tool('pubmed_convert_ids', {
     async handler(input, ctx) {
         ctx.log.info('Executing pubmed_convert_ids', {
             count: input.ids.length,
-            idtype: input.idtype,
+            idType: input.idType,
         });
-        const raw = await getNcbiService().idConvert(input.ids, input.idtype, { signal: ctx.signal });
+        const raw = await getNcbiService().idConvert(input.ids, input.idType, { signal: ctx.signal });
         // NCBI returns pmid as a number in JSON — coerce all ID fields to strings
         const records = raw.map((r) => {
             const requestedId = String(r['requested-id']);

package/dist/mcp-server/tools/definitions/fetch-articles.tool.d.ts

@@ -4,6 +4,7 @@
  * @module src/mcp-server/tools/definitions/fetch-articles.tool
  */
 import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 export declare const fetchArticlesTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
     pmids: z.ZodArray<z.ZodString>;
     includeMesh: z.ZodDefault<z.ZodBoolean>;
@@ -68,5 +69,28 @@ export declare const fetchArticlesTool: import("@cyanheads/mcp-ts-core").ToolDef
     }, z.core.$strip>>;
     totalReturned: z.ZodNumber;
     unavailablePmids: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "queue_full";
+    readonly code: JsonRpcErrorCode.RateLimited;
+    readonly when: "Local NCBI request queue is at capacity.";
+    readonly recovery: "Retry after 1-2 seconds; the request queue hit the NCBI rate limit.";
+    readonly retryable: true;
+}, {
+    readonly reason: "ncbi_unreachable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "NCBI E-utilities is unreachable after all retry attempts.";
+    readonly recovery: "Retry after a brief delay; NCBI was unreachable across all retry attempts.";
+    readonly retryable: true;
+}, {
+    readonly reason: "ncbi_deadline_exceeded";
+    readonly code: JsonRpcErrorCode.Timeout;
+    readonly when: "Total request deadline expired before NCBI returned a response.";
+    readonly recovery: "Reduce batch size or retry; NCBI may be under temporary load.";
+    readonly retryable: true;
+}, {
+    readonly reason: "invalid_efetch_response";
+    readonly code: JsonRpcErrorCode.SerializationError;
+    readonly when: "NCBI EFetch returned a payload missing the PubmedArticleSet wrapper.";
+    readonly recovery: "Retry once; if it persists, NCBI returned malformed data — try fewer PMIDs at once.";
+}]>;
 //# sourceMappingURL=fetch-articles.tool.d.ts.map

package/dist/mcp-server/tools/definitions/fetch-articles.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-articles.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fetch-articles.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAwGjD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA2J5B,CAAC"}
+{"version":3,"file":"fetch-articles.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fetch-articles.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAyGjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0K5B,CAAC"}

package/dist/mcp-server/tools/definitions/fetch-articles.tool.js

@@ -4,10 +4,12 @@
  * @module src/mcp-server/tools/definitions/fetch-articles.tool
  */
 import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { getNcbiService } from '../../../services/ncbi/ncbi-service.js';
 import { parseFullArticle } from '../../../services/ncbi/parsing/article-parser.js';
 import { ensureArray } from '../../../services/ncbi/parsing/xml-helpers.js';
 import { conceptMeta, EDAM_DATA_RETRIEVAL, EDAM_PUBMED_ID, SCHEMA_SCHOLARLY_ARTICLE, } from './_concepts.js';
+import { NCBI_SERVICE_ERRORS } from './_error-contracts.js';
 import { pmidStringSchema } from './_schemas.js';
 const AuthorSchema = z
     .object({
@@ -97,6 +99,15 @@ export const fetchArticlesTool = tool('pubmed_fetch_articles', {
     annotations: { readOnlyHint: true, openWorldHint: true },
     _meta: conceptMeta([SCHEMA_SCHOLARLY_ARTICLE, EDAM_DATA_RETRIEVAL, EDAM_PUBMED_ID]),
     sourceUrl: 'https://github.com/cyanheads/pubmed-mcp-server/blob/main/src/mcp-server/tools/definitions/fetch-articles.tool.ts',
+    errors: [
+        ...NCBI_SERVICE_ERRORS,
+        {
+            reason: 'invalid_efetch_response',
+            code: JsonRpcErrorCode.SerializationError,
+            when: 'NCBI EFetch returned a payload missing the PubmedArticleSet wrapper.',
+            recovery: 'Retry once; if it persists, NCBI returned malformed data — try fewer PMIDs at once.',
+        },
+    ],
     input: z.object({
         pmids: z.array(pmidStringSchema).min(1).max(200).describe('PubMed IDs to fetch'),
         includeMesh: z.boolean().default(true).describe('Include MeSH terms'),
@@ -114,7 +125,7 @@ export const fetchArticlesTool = tool('pubmed_fetch_articles', {
         ctx.log.info('Executing pubmed_fetch', { pmidCount: input.pmids.length });
         const xmlData = await getNcbiService().eFetch({ db: 'pubmed', id: input.pmids.join(','), retmode: 'xml' }, { retmode: 'xml', usePost: input.pmids.length >= 100, signal: ctx.signal });
         if (!xmlData || !('PubmedArticleSet' in xmlData)) {
-            throw new Error('Invalid EFetch response from NCBI: missing PubmedArticleSet');
+            throw ctx.fail('invalid_efetch_response', 'Invalid EFetch response from NCBI: missing PubmedArticleSet', { requestedPmids: input.pmids.length, ...ctx.recoveryFor('invalid_efetch_response') });
         }
         const rawArticles = xmlData.PubmedArticleSet?.PubmedArticle;
         const xmlArticles = rawArticles ? ensureArray(rawArticles) : [];

package/dist/mcp-server/tools/definitions/fetch-articles.tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-articles.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fetch-articles.tool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fetch-articles.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fetch-articles.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,wCAAwC,CAAC;AAErE,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,cAAc,EACd,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,MAAM,YAAY,GAAG,CAAC;KACnB,MAAM,CAAC;IACN,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;IACrD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAC7D,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IAC3D,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;IAC9E,kBAAkB,EAAE,CAAC;SAClB,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,QAAQ,EAAE;SACV,QAAQ,CAAC,+CAA+C,CAAC;IAC5D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;CAC1D,CAAC;KACD,QAAQ,CAAC,eAAe,CAAC,CAAC;AAE7B,MAAM,4BAA4B,GAAG,CAAC;KACnC,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IACxD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC;IAC1D,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IACtD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;CAC7F,CAAC;KACD,QAAQ,CAAC,0BAA0B,CAAC,CAAC;AAExC,MAAM,iBAAiB,GAAG,CAAC;KACxB,MAAM,CAAC;IACN,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IAC3D,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;IAC3E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC;IAClD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IACxD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC;IACvD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;IACrD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;IAClE,eAAe,EAAE,4BAA4B,CAAC,QAAQ,EAAE;CACzD,CAAC;KACD,QAAQ,CAAC,qBAAqB,CAAC,CAAC;AAEnC,MAAM,mBAAmB,GAAG,CAAC;KAC1B,MAAM,CAAC;IACN,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;IAC/D,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qBAAqB,CAAC;IAClE,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,yCAAyC,CAAC;CAC9E,CAAC;KACD,QAAQ,CAAC,2BAA2B,CAAC,CAAC;AAEzC,MAAM,cAAc,GAAG,CAAC;KACrB,MAAM,CAAC;IACN,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC;IACtE,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;IACzE,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;IAClF,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;CAC5F,CAAC;KACD,QAAQ,CAAC,sBAAsB,CAAC,CAAC;AAEpC,MAAM,WAAW,GAAG,CAAC;KAClB,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IAC3D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC;IACxD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IACxD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC;CAC1D,CAAC;KACD,QAAQ,CAAC,cAAc,CAAC,CAAC;AAE5B,MAAM,iBAAiB,GAAG,CAAC;KACxB,MAAM,CAAC;IACN,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;IACrD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC5C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC;IAC9C,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC;CAC3C,CAAC;KACD,QAAQ,CAAC,qBAAqB,CAAC,CAAC;AAEnC,MAAM,oBAAoB,GAAG,CAAC;KAC3B,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;IACjD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC;IACtD,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC;IAC7D,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;IACzF,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,aAAa,CAAC;IACjE,WAAW,EAAE,iBAAiB,CAAC,QAAQ,EAAE;IACzC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC;IAC1C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAC/C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IAC/D,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC;IAC3D,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC;IAC9E,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC;IAC7D,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC;IACpE,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC;IACxE,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC;CAC9E,CAAC;KACD,QAAQ,CAAC,uBAAuB,CAAC,CAAC;AAErC,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,uBAAuB,EAAE;IAC7D,WAAW,EACT,mIAAmI;IACrI,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;IACxD,KAAK,EAAE,WAAW,CAAC,CAAC,wBAAwB,EAAE,mBAAmB,EAAE,cAAc,CAAC,CAAC;IACnF,SAAS,EACP,kHAAkH;IAEpH,MAAM,EAAE;QACN,GAAG,mBAAmB;QACtB;YACE,MAAM,EAAE,yBAAyB;YACjC,IAAI,EAAE,gBAAgB,CAAC,kBAAkB;YACzC,IAAI,EAAE,sEAAsE;YAC5E,QAAQ,EACN,qFAAqF;SACxF;KACO;IAEV,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,qBAAqB,CAAC;QAChF,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,oBAAoB,CAAC;QACrE,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,2BAA2B,CAAC;KAChF,CAAC;IAEF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC;QACnE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;QACjE,gBAAgB,EAAE,CAAC;aAChB,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;aACjB,QAAQ,EAAE;aACV,QAAQ,CAAC,qCAAqC,CAAC;KACnD,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,wBAAwB,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAE1E,MAAM,OAAO,GAAG,MAAM,cAAc,EAAE,CAAC,MAAM,CAC3C,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAC3D,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,IAAI,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAC3E,CAAC;QAEF,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,kBAAkB,IAAI,OAAO,CAAC,EAAE,CAAC;YACjD,MAAM,GAAG,CAAC,IAAI,CACZ,yBAAyB,EACzB,6DAA6D,EAC7D,EAAE,cAAc,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,yBAAyB,CAAC,EAAE,CACtF,CAAC;QACJ,CAAC;QAED,MAAM,WAAW,GAAG,OAAO,CAAC,gBAAgB,EAAE,aAAa,CAAC;QAC5D,MAAM,WAAW,GAAG,WAAW,CAAC,CAAC,CAAE,WAAW,CAAC,WAAW,CAAwB,CAAC,CAAC,CAAC,EAAE,CAAC;QACxF,MAAM,QAAQ,GAAG,WAAW;aACzB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,eAAe,CAAC;aACjC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACT,MAAM,MAAM,GAAG,gBAAgB,CAAC,CAAC,EAAE;gBACjC,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,aAAa,EAAE,KAAK,CAAC,aAAa;aACnC,CAAC,CAAC;YACH,OAAO;gBACL,GAAG,MAAM;gBACT,SAAS,EAAE,mCAAmC,MAAM,CAAC,IAAI,GAAG;gBAC5D,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI;oBAClB,MAAM,EAAE,6CAA6C,MAAM,CAAC,KAAK,GAAG;iBACrE,CAAC;aACH,CAAC;QACJ,CAAC,CAAC,CAAC;QAEL,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3E,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAEvE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,wBAAwB,EAAE;YACrC,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM;YAC7B,QAAQ,EAAE,QAAQ,CAAC,MAAM;SAC1B,CAAC,CAAC;QACH,OAAO;YACL,QAAQ;YACR,aAAa,EAAE,QAAQ,CAAC,MAAM;YAC9B,GAAG,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,gBAAgB,EAAE,WAAW,EAAE,CAAC;SACjE,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;QACjB,MAAM,KAAK,GAAG,CAAC,oBAAoB,EAAE,0BAA0B,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC;QACvF,IAAI,MAAM,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;YACpC,KAAK,CAAC,IAAI,CAAC,0BAA0B,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC7E,CAAC;QACD,IAAI,MAAM,CAAC,aAAa,KAAK,CAAC,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CACR,+IAA+I,CAChJ,CAAC;QACJ,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YAChC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,IAAI,SAAS,EAAE,CAAC,CAAC;YAEtD,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;gBACtB,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,OAAO,CAAC,MAAM,MAAM,CAAC,CAAC;gBACnD,KAAK,MAAM,EAAE,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;oBAC3B,KAAK,CAAC,IAAI,CAAC,KAAK,YAAY,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;gBACtC,CAAC;YACH,CAAC;YAED,IAAI,CAAC,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;gBAC3B,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;gBAClC,KAAK,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC;oBAChD,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;gBAChC,CAAC;YACH,CAAC;YAED,MAAM,EAAE,GAAG,CAAC,CAAC,WAAW,CAAC;YACzB,IAAI,EAAE,EAAE,CAAC;gBACP,MAAM,KAAK,GAAa,EAAE,CAAC;gBAC3B,IAAI,EAAE,CAAC,KAAK;oBAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;gBACnC,IAAI,EAAE,CAAC,eAAe,IAAI,EAAE,CAAC,eAAe,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC;oBAC1D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,eAAe,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC;gBACxE,CAAC;gBACD,MAAM,UAAU,GAAG,qBAAqB,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC;gBAC7D,IAAI,UAAU;oBAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;gBACvC,IAAI,EAAE,CAAC,MAAM;oBAAE,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,MAAM,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAChF,IAAI,EAAE,CAAC,KAAK;oBAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;gBACnC,IAAI,EAAE,CAAC,IAAI;oBAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;gBAC3C,IAAI,EAAE,CAAC,KAAK;oBAAE,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC;gBAC9C,IAAI,KAAK,CAAC,MAAM;oBAAE,KAAK,CAAC,IAAI,CAAC,kBAAkB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACrE,CAAC;YAED,IAAI,CAAC,CAAC,gBAAgB,EAAE,MAAM;gBAAE,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACzF,IAAI,CAAC,CAAC,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YAC9C,IAAI,CAAC,CAAC,GAAG;gBAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;YAC3C,IAAI,CAAC,CAAC,KAAK;gBAAE,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;YACjD,IAAI,CAAC,CAAC,SAAS;gBAAE,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;YAC1D,IAAI,CAAC,CAAC,MAAM;gBAAE,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;YAEjD,IAAI,CAAC,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;gBAC3B,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACvF,CAAC;YAED,IAAI,CAAC,CAAC,YAAY;gBAAE,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;YACrE,IAAI,CAAC,CAAC,QAAQ,EAAE,MAAM;gBAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC/E,IAAI,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;gBACxB,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;gBAChC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;oBAC5B,MAAM,UAAU,GAAG,CAAC,CAAC,YAAY;wBAC/B,CAAC,CAAC,GAAG,CAAC,CAAC,cAAc,KAAK,CAAC,CAAC,YAAY,GAAG;wBAC3C,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC;oBACrB,MAAM,KAAK,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC/C,MAAM,UAAU,GAAG,CAAC,CAAC,UAAU,EAAE,MAAM;wBACrC,CAAC,CAAC,KAAK,CAAC,CAAC,UAAU;6BACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;4BACT,MAAM,IAAI,GAAG,CAAC,CAAC,WAAW;gCACxB,CAAC,CAAC,GAAG,CAAC,CAAC,aAAa,KAAK,CAAC,CAAC,WAAW,GAAG;gCACzC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;4BACpB,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;wBACtD,CAAC,CAAC;6BACD,IAAI,CAAC,IAAI,CAAC,GAAG;wBAClB,CAAC,CAAC,EAAE,CAAC;oBACP,KAAK,CAAC,IAAI,CAAC,KAAK,UAAU,GAAG,KAAK,GAAG,UAAU,EAAE,CAAC,CAAC;gBACrD,CAAC;YACH,CAAC;YACD,IAAI,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;gBACxB,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;gBAC5B,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;oBAC5B,MAAM,OAAO,GACX,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;oBAC1F,MAAM,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;oBAC7D,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBACvC,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;CACF,CAAC,CAAC;AAWH,SAAS,YAAY,CAAC,EAAmB;IACvC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,EAAE,CAAC,cAAc;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,cAAc,eAAe,CAAC,CAAC;IAEvE,MAAM,IAAI,GAAG,CAAC,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnE,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SACtB,IAAI,EAAE,CAAC,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC9C,IAAI,EAAE,CAAC,QAAQ,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,QAAQ,GAAG,CAAC,CAAC;IAExD,IAAI,EAAE,CAAC,kBAAkB,EAAE,MAAM,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,EAAE,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC;IAChD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC;AACtC,CAAC;AASD,SAAS,qBAAqB,CAAC,EAAgC;IAC7D,IAAI,CAAC,EAAE;QAAE,OAAO;IAChB,MAAM,GAAG,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClE,IAAI,EAAE,CAAC,WAAW,IAAI,GAAG;QAAE,OAAO,GAAG,EAAE,CAAC,WAAW,KAAK,GAAG,GAAG,CAAC;IAC/D,OAAO,EAAE,CAAC,WAAW,IAAI,GAAG,IAAI,SAAS,CAAC;AAC5C,CAAC;AASD,SAAS,iBAAiB,CAAC,EAAwB;IACjD,MAAM,QAAQ,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvE,OAAO,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC/D,CAAC"}

package/dist/mcp-server/tools/definitions/fetch-fulltext.tool.d.ts

@@ -7,6 +7,7 @@
  * @module src/mcp-server/tools/definitions/fetch-fulltext.tool
  */
 import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 export declare const fetchFulltextTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
     pmcids: z.ZodOptional<z.ZodArray<z.ZodString>>;
     pmids: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -90,5 +91,28 @@ export declare const fetchFulltextTool: import("@cyanheads/mcp-ts-core").ToolDef
         detail: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     unavailablePmcIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "queue_full";
+    readonly code: JsonRpcErrorCode.RateLimited;
+    readonly when: "Local NCBI request queue is at capacity.";
+    readonly recovery: "Retry after 1-2 seconds; the request queue hit the NCBI rate limit.";
+    readonly retryable: true;
+}, {
+    readonly reason: "ncbi_unreachable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "NCBI E-utilities is unreachable after all retry attempts.";
+    readonly recovery: "Retry after a brief delay; NCBI was unreachable across all retry attempts.";
+    readonly retryable: true;
+}, {
+    readonly reason: "ncbi_deadline_exceeded";
+    readonly code: JsonRpcErrorCode.Timeout;
+    readonly when: "Total request deadline expired before NCBI returned a response.";
+    readonly recovery: "Reduce batch size or retry; NCBI may be under temporary load.";
+    readonly retryable: true;
+}, {
+    readonly reason: "invalid_pmc_efetch_response";
+    readonly code: JsonRpcErrorCode.SerializationError;
+    readonly when: "PMC EFetch returned a payload missing the pmc-articleset wrapper.";
+    readonly recovery: "Retry once; if it persists, NCBI returned malformed data — try fewer PMC IDs at once.";
+}]>;
 //# sourceMappingURL=fetch-fulltext.tool.d.ts.map

package/dist/mcp-server/tools/definitions/fetch-fulltext.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-fulltext.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fetch-fulltext.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAsB,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAgL/D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAoO5B,CAAC"}
+{"version":3,"file":"fetch-fulltext.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/fetch-fulltext.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAsB,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAiLjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuP5B,CAAC"}

package/dist/mcp-server/tools/definitions/fetch-fulltext.tool.js

@@ -7,6 +7,7 @@
  * @module src/mcp-server/tools/definitions/fetch-fulltext.tool
  */
 import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { htmlExtractor, pdfParser } from '@cyanheads/mcp-ts-core/utils';
 import { getNcbiService } from '../../../services/ncbi/ncbi-service.js';
 import { extractDoi, extractPmid } from '../../../services/ncbi/parsing/article-parser.js';
@@ -15,6 +16,7 @@ import { findAll, findOne } from '../../../services/ncbi/parsing/pmc-xml-helpers
 import { ensureArray } from '../../../services/ncbi/parsing/xml-helpers.js';
 import { getUnpaywallService } from '../../../services/unpaywall/unpaywall-service.js';
 import { conceptMeta, EDAM_DATA_RETRIEVAL, SCHEMA_SCHOLARLY_ARTICLE } from './_concepts.js';
+import { NCBI_SERVICE_ERRORS } from './_error-contracts.js';
 import { pmidStringSchema } from './_schemas.js';
 function normalizePmcId(id) {
     return id.replace(/^PMC/i, '');
@@ -148,6 +150,15 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
     annotations: { readOnlyHint: true, openWorldHint: true },
     _meta: conceptMeta([SCHEMA_SCHOLARLY_ARTICLE, EDAM_DATA_RETRIEVAL]),
     sourceUrl: 'https://github.com/cyanheads/pubmed-mcp-server/blob/main/src/mcp-server/tools/definitions/fetch-fulltext.tool.ts',
+    errors: [
+        ...NCBI_SERVICE_ERRORS,
+        {
+            reason: 'invalid_pmc_efetch_response',
+            code: JsonRpcErrorCode.SerializationError,
+            when: 'PMC EFetch returned a payload missing the pmc-articleset wrapper.',
+            recovery: 'Retry once; if it persists, NCBI returned malformed data — try fewer PMC IDs at once.',
+        },
+    ],
     input: z
         .object({
         pmcids: z
@@ -238,7 +249,10 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             });
             const articleSet = findOne(xmlData, 'pmc-articleset');
             if (!articleSet)
-                throw new Error('Invalid PMC EFetch response: missing pmc-articleset');
+                throw ctx.fail('invalid_pmc_efetch_response', 'Invalid PMC EFetch response: missing pmc-articleset', {
+                    requestedPmcIdCount: pmcIds.length,
+                    ...ctx.recoveryFor('invalid_pmc_efetch_response'),
+                });
             let parsed = findAll(articleSet, 'article').map(parsePmcArticle);
             if (input.sections?.length) {
                 const sectionFilter = input.sections;