@cyanheads/federal-regulations-mcp-server 0.2.1 → 0.2.2

package/dist/services/upstream-failure.js

@@ -1,14 +1,18 @@
 /**
- * @fileoverview Shared helper that stamps the `upstream_unavailable` contract
- * reason onto a transport failure on its way out of a service.
+ * @fileoverview The shared pieces of how a transport failure becomes
+ * `upstream_unavailable` on this surface: `fetchUpstream` raises one from a
+ * request that never produced a response, `rethrowTransportFailure` re-codes the
+ * 5xx statuses the status→code map does not call one, `retryTransportOnly` says
+ * which of them a retry can fix, and `withUpstreamReason` stamps the contract
+ * reason onto whichever transport failure reaches it.
  *
  * Every tool on this surface declares `upstream_unavailable`, but the failure it
- * describes is raised inside the framework's fetch pipeline, below any handler:
- * `fetchWithTimeout` classifies a 5xx, a network error, or a deadline, and
- * `withRetry` exhausts its attempts before the error surfaces. Nothing on that
- * path knows the calling tool's contract, so the answer used to reach the caller
- * with the right code and a null `data.reason` — the one failure an agent most
- * needs to switch on to decide whether to retry.
+ * describes is raised below any handler: the framework's fetch pipeline
+ * classifies a 5xx, a network error, or a deadline, and `withRetry` exhausts its
+ * attempts before the error surfaces. Nothing on that path knows the calling
+ * tool's contract, so the answer used to reach the caller with the right code and
+ * a null `data.reason` — the one failure an agent most needs to switch on to
+ * decide whether to retry.
  *
  * Services carry the reason the way the framework prescribes for code that has
  * no `ctx.fail`: put `reason` in the thrown error's `data`, and spread
@@ -18,6 +22,47 @@
  * @module services/upstream-failure
  */
 import { JsonRpcErrorCode, McpError, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+/**
+ * Perform an upstream request, raising a classified `ServiceUnavailable` when it
+ * never produced a response.
+ *
+ * `fetchWithTimeout` already does this for the services that route through it,
+ * but a service that has to branch on `response.status` calls `fetch` directly
+ * and gets no such classification — `fetch` rejects with whatever the runtime
+ * throws, which is not an `McpError`, so it reaches the caller as an
+ * unclassified `InternalError` with no reason. That is the gap this closes.
+ *
+ * **Classified by position, not by message.** A rejection here means no
+ * `Response` was ever produced — DNS failure, refused connection, TLS failure, a
+ * socket dropped before headers — which is exactly the condition
+ * `upstream_unavailable` names. Matching the message text instead would be a rule
+ * per runtime: Bun answers both a refused connection and an unresolvable host
+ * with the one message "Unable to connect. Is the computer able to access the
+ * url?" and no `cause` at all, while Node says "fetch failed" and keeps the
+ * syscall detail one level below that. Neither puts `ECONNREFUSED`/`ENOTFOUND`
+ * where the framework's patterns for them look, so those never match. Reaching
+ * this catch is itself the evidence.
+ *
+ * An abort is the exception and re-throws untouched: the caller ending its own
+ * request is not an upstream failure, and the framework already classifies it.
+ *
+ * This wrapper adds no deadline of its own — the request is bounded only by
+ * `init.signal`, unlike the `fetchWithTimeout` legs.
+ */
+export async function fetchUpstream(url, init, { service, operation }) {
+    try {
+        return await fetch(url, init);
+    }
+    catch (error) {
+        if (init.signal?.aborted || (error instanceof Error && error.name === 'AbortError')) {
+            throw error;
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw serviceUnavailable(`${service} could not be reached: ${detail}`, { operation }, {
+            cause: error,
+        });
+    }
+}
 /**
  * Codes that mean the upstream never produced a usable response. Kept to these
  * two on purpose: a 404, a 400, a 401, or a 429 is an answer, and each already
@@ -28,6 +73,53 @@ const TRANSPORT_CODES = new Set([
     JsonRpcErrorCode.ServiceUnavailable,
     JsonRpcErrorCode.Timeout,
 ]);
+/**
+ * Re-raise an upstream failure, re-coding a 5xx the status→code map does not
+ * already call a transport failure.
+ *
+ * Both HTTP helpers map 500 and 501 to `InternalError` and everything else in
+ * the range to `ServiceUnavailable`. That split is right for a status→code map —
+ * "the server has a bug" is not "the server is down" — but every definition here
+ * declares `upstream_unavailable` for a 5xx, and a 500 is the commonest one an
+ * upstream serves. Left alone it reached the caller as `InternalError` with no
+ * reason and no hint, and `withRetry` did not retry it, while the 502 beside it
+ * was retried and answered `upstream_unavailable`.
+ *
+ * **Keyed on the status, not the code or the message.** `data.status` is set only
+ * by the two helpers that read a real `Response`, so a caller abort (an
+ * `InternalError` carrying `errorSource: 'FetchAborted'` and no status) and a
+ * programmer error (no `data` at all) cannot reach this branch — which is the
+ * point, since both are `InternalError` too and neither is an unreachable
+ * upstream. An error already carrying a transport code is left alone rather than
+ * re-wrapped to the same code: a 504's `Timeout` then reaches
+ * {@link withUpstreamReason} as itself, and the 502/503 that need nothing done
+ * to them keep their own object and a `cause` chain one link shorter.
+ */
+export function rethrowTransportFailure(error) {
+    if (error instanceof McpError && !TRANSPORT_CODES.has(error.code)) {
+        const status = error.data?.status;
+        if (typeof status === 'number' && status >= 500) {
+            throw serviceUnavailable(error.message, { ...error.data }, { cause: error });
+        }
+    }
+    throw error;
+}
+/**
+ * Retry predicate for a service that raises a non-retryable failure with a
+ * retryable code.
+ *
+ * `withRetry`'s default treats every `RateLimited` as transient unless the throw
+ * carries `data.retryable: false`. That flag is also the client's own backoff
+ * hint, so opting out through it tells the caller not to retry a failure the
+ * tools declare as retryable. Deciding it here keeps the wire honest: a transport
+ * failure is retried, an answer with a status is not, and an unclassified throw
+ * (a parse failure mid-pipeline) stays transient the way the default has it.
+ */
+export function retryTransportOnly(error) {
+    if (!(error instanceof McpError))
+        return true;
+    return TRANSPORT_CODES.has(error.code);
+}
 /**
  * Run upstream work, stamping `upstream_unavailable` on a transport failure.
  *

package/dist/services/upstream-failure.js.map

@@ -1 +1 @@
-{"version":3,"file":"upstream-failure.js","sourceRoot":"","sources":["../../src/services/upstream-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAE/F;;;;;GAKG;AACH,MAAM,eAAe,GAAG,IAAI,GAAG,CAAmB;IAChD,gBAAgB,CAAC,kBAAkB;IACnC,gBAAgB,CAAC,OAAO;CACzB,CAAC,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAI,IAAgB,EAAE,GAAY;IAClE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACjC,IAAI,CAAC,CAAC,GAAG,YAAY,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,MAAM,GAAG,CAAC;QAC5E,MAAM,kBAAkB,CACtB,GAAG,CAAC,OAAO,EACX,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,sBAAsB,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,sBAAsB,CAAC,EAAE,EAC3F,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"upstream-failure.js","sourceRoot":"","sources":["../../src/services/upstream-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAU/F;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAW,EACX,IAAiB,EACjB,EAAE,OAAO,EAAE,SAAS,EAA0B;IAE9C,IAAI,CAAC;QACH,OAAO,MAAM,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,EAAE,CAAC;YACpF,MAAM,KAAK,CAAC;QACd,CAAC;QACD,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,MAAM,kBAAkB,CACtB,GAAG,OAAO,0BAA0B,MAAM,EAAE,EAC5C,EAAE,SAAS,EAAE,EACb;YACE,KAAK,EAAE,KAAK;SACb,CACF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,eAAe,GAAG,IAAI,GAAG,CAAmB;IAChD,gBAAgB,CAAC,kBAAkB;IACnC,gBAAgB,CAAC,OAAO;CACzB,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,IAAI,KAAK,YAAY,QAAQ,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAClE,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC;QAClC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;YAChD,MAAM,kBAAkB,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;IACD,MAAM,KAAK,CAAC;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,OAAO,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAI,IAAgB,EAAE,GAAY;IAClE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACjC,IAAI,CAAC,CAAC,GAAG,YAAY,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,MAAM,GAAG,CAAC;QAC5E,MAAM,kBAAkB,CACtB,GAAG,CAAC,OAAO,EACX,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,sBAAsB,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,sBAAsB,CAAC,EAAE,EAC3F,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/federal-regulations-mcp-server",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "mcpName": "io.github.cyanheads/federal-regulations-mcp-server",
   "description": "Search and trace US federal rules across the Federal Register (proposed/final rules and notices), the eCFR (codified, point-in-time CFR full text, locally mirrored), and Regulations.gov (rulemaking dockets and public comments) via MCP. STDIO or Streamable HTTP.",
   "type": "module",

package/server.json

@@ -6,7 +6,7 @@
     "url": "https://github.com/cyanheads/federal-regulations-mcp-server",
     "source": "github"
   },
-  "version": "0.2.1",
+  "version": "0.2.2",
   "remotes": [
     {
       "type": "streamable-http",
@@ -19,7 +19,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/federal-regulations-mcp-server",
       "runtimeHint": "node",
-      "version": "0.2.1",
+      "version": "0.2.2",
       "packageArguments": [
         {
           "type": "positional",
@@ -55,7 +55,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/federal-regulations-mcp-server",
       "runtimeHint": "node",
-      "version": "0.2.1",
+      "version": "0.2.2",
       "packageArguments": [
         {
           "type": "positional",