@ttoss/http-server-mcp 0.28.1 → 0.29.0

package/README.md

@@ -127,6 +127,31 @@ const data = await apiCall('GET', 'https://partner.api.com/data', {
 
 `apiCall` throws with a clear message when called with a relative path and no `apiBaseUrl` is configured in the context.
 
+### Errors
+
+A non-2xx response throws, with the message read off the error body — `{ error: 'text' }` and `{ error: { code, message } }` both work, the latter as `code: message`. A body naming neither falls back to `HTTP <status>`.
+
+```typescript
+// { "error": { "code": "plan_limit_reached", "message": "Upgrade to add more." } }
+// → Error: plan_limit_reached: Upgrade to add more.
+```
+
+Inside a tool handler the thrown message is what the MCP SDK returns to the client, so it is the whole answer the calling model acts on.
+
+### Using your own HTTP client
+
+A handler that does not use `apiCall` can still reuse its two request-scoped pieces: `getApiHeaders()` returns the headers `getApiHeaders` produced for the current MCP request, and `errorBodyMessage(body)` renders an error body exactly as `apiCall` does.
+
+```typescript
+import { errorBodyMessage, getApiHeaders } from '@ttoss/http-server-mcp';
+
+const response = await fetch(url, { headers: getApiHeaders() });
+if (!response.ok) {
+  const body = await response.json().catch(() => undefined);
+  throw new Error(errorBodyMessage(body) ?? `HTTP ${response.status}`);
+}
+```
+
 ## Authentication
 
 `createMcpRouter` supports OAuth 2.0 Bearer token authentication via the `auth` option. Incoming MCP requests must include a valid `Authorization: Bearer <token>` header — invalid or missing tokens receive a `401 Unauthorized` response. The MCP lifecycle methods `initialize` and `tools/list` are exempt by default so clients can discover the server before authenticating (see [Public methods and discovery](#public-methods-and-discovery)).
@@ -593,6 +618,20 @@ Generic HTTP helper for use inside MCP tool handlers.
 
 **Returns:** `Promise<unknown>` — Parsed JSON response body
 
+**Throws:** `Error` on a non-2xx response, carrying the error body's message (see [Errors](#errors))
+
+### `getApiHeaders()`
+
+Returns a copy of the headers `createMcpRouter`'s `getApiHeaders` option produced for the current MCP request — the same headers `apiCall` injects.
+
+**Returns:** `Record<string, string>` — `{}` outside a request or when `getApiHeaders` is not configured
+
+### `errorBodyMessage(body)`
+
+Reads the message off a REST error body — `{ error: 'text' }` or `{ error: { code?, message? } }` (rendered `code: message`).
+
+**Returns:** `string | undefined` — `undefined` when the body carries no message
+
 ### `getIdentity<T>()`
 
 Returns the verified JWT payload for the current MCP request. Only available inside a tool handler when `auth` is configured. Returns `undefined` when called outside an authenticated context.

package/dist/index.cjs

@@ -24,6 +24,19 @@ var requestContextStore = new node_async_hooks.AsyncLocalStorage();
 var getIdentity = () => {
   return requestContextStore.getStore()?.identity;
 };
+/**
+* Returns the headers `getApiHeaders` produced for the current MCP request —
+* the same headers `apiCall` injects. Use it inside a tool handler that runs
+* its own HTTP client instead of `apiCall`, so caller credentials still reach
+* the upstream API.
+*
+* Returns `{}` outside a request, or when `getApiHeaders` is not configured.
+*/
+var getApiHeaders = () => {
+  return {
+    ...(requestContextStore.getStore()?.apiHeaders ?? {})
+  };
+};
 
 //#endregion
 //#region src/serveMcpRequest.ts
@@ -588,6 +601,43 @@ var buildVerifyToken = auth => {
     return payload;
   };
 };
+var isRecord = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+var readText = value => {
+  return typeof value === "string" && value !== "" ? value : void 0;
+};
+/**
+* The message an error body carries, across the two shapes REST APIs answer
+* with: `{ error: 'text' }` and `{ error: { code?, message? } }`.
+*
+* The structured one is why this is read rather than taken: an object handed
+* to `new Error()` renders as `[object Object]`, and inside a tool handler
+* that string is the whole answer the calling model acts on.
+*
+* Exported so a tool handler with its own HTTP client renders error bodies
+* exactly as `apiCall` does. Returns `undefined` when the body carries no
+* message.
+*
+* @example
+* ```typescript
+* if (!response.ok) {
+*   const body = await response.json().catch(() => undefined);
+*   throw new Error(errorBodyMessage(body) ?? `HTTP ${response.status}`);
+* }
+* ```
+*/
+var errorBodyMessage = body => {
+  if (!isRecord(body)) return;
+  const {
+    error
+  } = body;
+  if (!isRecord(error)) return readText(error);
+  const code = readText(error.code);
+  const message = readText(error.message);
+  if (message === void 0) return code;
+  return code === void 0 ? message : `${code}: ${message}`;
+};
 /**
 * Generic HTTP helper for use inside MCP tool handlers.
 *
@@ -663,12 +713,12 @@ var apiCall = async (method, url, options) => {
     body: hasBody ? JSON.stringify(options.body) : void 0
   });
   if (!response.ok) {
-    const err = await response.json().catch(() => {
+    const errorBody = await response.json().catch(() => {
       return {
         error: response.statusText
       };
     });
-    throw new Error(err.error || `HTTP ${response.status}`);
+    throw new Error(errorBodyMessage(errorBody) ?? `HTTP ${response.status}`);
   }
   if (response.status === 204 || response.status === 205) return;
   if (response.headers.get("content-type")?.includes("application/json")) return response.json();
@@ -860,6 +910,8 @@ exports.apiCall = apiCall;
 exports.checkScopes = checkScopes;
 exports.createGatedToolRegistrar = createGatedToolRegistrar;
 exports.createMcpRouter = createMcpRouter;
+exports.errorBodyMessage = errorBodyMessage;
+exports.getApiHeaders = getApiHeaders;
 exports.getIdentity = getIdentity;
 exports.registerAppResource = registerAppResource;
 exports.registerToolFromSchema = registerToolFromSchema;

package/dist/index.d.cts

@@ -674,6 +674,15 @@ declare namespace Application {
  * Omitting the type parameter keeps the return type as `unknown | undefined`.
  */
 declare const getIdentity: <T = unknown>() => T | undefined;
+/**
+ * Returns the headers `getApiHeaders` produced for the current MCP request —
+ * the same headers `apiCall` injects. Use it inside a tool handler that runs
+ * its own HTTP client instead of `apiCall`, so caller credentials still reach
+ * the upstream API.
+ *
+ * Returns `{}` outside a request, or when `getApiHeaders` is not configured.
+ */
+declare const getApiHeaders: () => Record<string, string>;
 //#endregion
 //#region src/registerAppResource.d.ts
 /**
@@ -1191,6 +1200,27 @@ interface McpAuthOptions {
    */
   resourceIndicator?: string | string[];
 }
+/**
+ * The message an error body carries, across the two shapes REST APIs answer
+ * with: `{ error: 'text' }` and `{ error: { code?, message? } }`.
+ *
+ * The structured one is why this is read rather than taken: an object handed
+ * to `new Error()` renders as `[object Object]`, and inside a tool handler
+ * that string is the whole answer the calling model acts on.
+ *
+ * Exported so a tool handler with its own HTTP client renders error bodies
+ * exactly as `apiCall` does. Returns `undefined` when the body carries no
+ * message.
+ *
+ * @example
+ * ```typescript
+ * if (!response.ok) {
+ *   const body = await response.json().catch(() => undefined);
+ *   throw new Error(errorBodyMessage(body) ?? `HTTP ${response.status}`);
+ * }
+ * ```
+ */
+declare const errorBodyMessage: (body: unknown) => string | undefined;
 /**
  * Options for a single `apiCall` request.
  */
@@ -1444,4 +1474,4 @@ interface McpRouterOptions {
  */
 declare const createMcpRouter: (server: McpServer$1, options?: McpRouterOptions) => Router<Application.DefaultState, Application.DefaultContext>;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolFromSchemaParams, type RegisteredAppResource, type ToolCallContext, type ToolIdentity, type ToolMetaParams, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerAppResource, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolFromSchemaParams, type RegisteredAppResource, type ToolCallContext, type ToolIdentity, type ToolMetaParams, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, errorBodyMessage, getApiHeaders, getIdentity, registerAppResource, registerToolFromSchema, z };

package/dist/index.d.mts

@@ -675,6 +675,15 @@ declare namespace Application {
  * Omitting the type parameter keeps the return type as `unknown | undefined`.
  */
 declare const getIdentity: <T = unknown>() => T | undefined;
+/**
+ * Returns the headers `getApiHeaders` produced for the current MCP request —
+ * the same headers `apiCall` injects. Use it inside a tool handler that runs
+ * its own HTTP client instead of `apiCall`, so caller credentials still reach
+ * the upstream API.
+ *
+ * Returns `{}` outside a request, or when `getApiHeaders` is not configured.
+ */
+declare const getApiHeaders: () => Record<string, string>;
 //#endregion
 //#region src/registerAppResource.d.ts
 /**
@@ -1192,6 +1201,27 @@ interface McpAuthOptions {
    */
   resourceIndicator?: string | string[];
 }
+/**
+ * The message an error body carries, across the two shapes REST APIs answer
+ * with: `{ error: 'text' }` and `{ error: { code?, message? } }`.
+ *
+ * The structured one is why this is read rather than taken: an object handed
+ * to `new Error()` renders as `[object Object]`, and inside a tool handler
+ * that string is the whole answer the calling model acts on.
+ *
+ * Exported so a tool handler with its own HTTP client renders error bodies
+ * exactly as `apiCall` does. Returns `undefined` when the body carries no
+ * message.
+ *
+ * @example
+ * ```typescript
+ * if (!response.ok) {
+ *   const body = await response.json().catch(() => undefined);
+ *   throw new Error(errorBodyMessage(body) ?? `HTTP ${response.status}`);
+ * }
+ * ```
+ */
+declare const errorBodyMessage: (body: unknown) => string | undefined;
 /**
  * Options for a single `apiCall` request.
  */
@@ -1445,4 +1475,4 @@ interface McpRouterOptions {
  */
 declare const createMcpRouter: (server: McpServer$1, options?: McpRouterOptions) => Router<Application.DefaultState, Application.DefaultContext>;
 //#endregion
-export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolFromSchemaParams, type RegisteredAppResource, type ToolCallContext, type ToolIdentity, type ToolMetaParams, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerAppResource, registerToolFromSchema, z };
+export { ApiCallOptions, CognitoUserPoolConfig, type CreateGatedToolRegistrarOptions, type GatedToolDef, type JsonObjectSchema, McpAuthOptions, McpRouterOptions, McpServer, type RegisterAppResourceParams, type RegisterToolFromSchemaParams, type RegisteredAppResource, type ToolCallContext, type ToolIdentity, type ToolMetaParams, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, type UiResourceCsp, type UiResourceMeta, type UiResourcePermissions, type UiToolVisibility, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, errorBodyMessage, getApiHeaders, getIdentity, registerAppResource, registerToolFromSchema, z };

package/dist/index.mjs

@@ -21,6 +21,19 @@ var requestContextStore = new AsyncLocalStorage();
 var getIdentity = () => {
   return requestContextStore.getStore()?.identity;
 };
+/**
+* Returns the headers `getApiHeaders` produced for the current MCP request —
+* the same headers `apiCall` injects. Use it inside a tool handler that runs
+* its own HTTP client instead of `apiCall`, so caller credentials still reach
+* the upstream API.
+*
+* Returns `{}` outside a request, or when `getApiHeaders` is not configured.
+*/
+var getApiHeaders = () => {
+  return {
+    ...(requestContextStore.getStore()?.apiHeaders ?? {})
+  };
+};
 
 //#endregion
 //#region src/serveMcpRequest.ts
@@ -585,6 +598,43 @@ var buildVerifyToken = auth => {
     return payload;
   };
 };
+var isRecord = value => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+var readText = value => {
+  return typeof value === "string" && value !== "" ? value : void 0;
+};
+/**
+* The message an error body carries, across the two shapes REST APIs answer
+* with: `{ error: 'text' }` and `{ error: { code?, message? } }`.
+*
+* The structured one is why this is read rather than taken: an object handed
+* to `new Error()` renders as `[object Object]`, and inside a tool handler
+* that string is the whole answer the calling model acts on.
+*
+* Exported so a tool handler with its own HTTP client renders error bodies
+* exactly as `apiCall` does. Returns `undefined` when the body carries no
+* message.
+*
+* @example
+* ```typescript
+* if (!response.ok) {
+*   const body = await response.json().catch(() => undefined);
+*   throw new Error(errorBodyMessage(body) ?? `HTTP ${response.status}`);
+* }
+* ```
+*/
+var errorBodyMessage = body => {
+  if (!isRecord(body)) return;
+  const {
+    error
+  } = body;
+  if (!isRecord(error)) return readText(error);
+  const code = readText(error.code);
+  const message = readText(error.message);
+  if (message === void 0) return code;
+  return code === void 0 ? message : `${code}: ${message}`;
+};
 /**
 * Generic HTTP helper for use inside MCP tool handlers.
 *
@@ -660,12 +710,12 @@ var apiCall = async (method, url, options) => {
     body: hasBody ? JSON.stringify(options.body) : void 0
   });
   if (!response.ok) {
-    const err = await response.json().catch(() => {
+    const errorBody = await response.json().catch(() => {
       return {
         error: response.statusText
       };
     });
-    throw new Error(err.error || `HTTP ${response.status}`);
+    throw new Error(errorBodyMessage(errorBody) ?? `HTTP ${response.status}`);
   }
   if (response.status === 204 || response.status === 205) return;
   if (response.headers.get("content-type")?.includes("application/json")) return response.json();
@@ -845,4 +895,4 @@ var createMcpRouter = (server, options = {}) => {
 };
 
 //#endregion
-export { McpServer, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, getIdentity, registerAppResource, registerToolFromSchema, z };
+export { McpServer, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, errorBodyMessage, getApiHeaders, getIdentity, registerAppResource, registerToolFromSchema, z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",