@ttoss/http-server-mcp 0.29.1 → 0.30.0

package/README.md

@@ -503,6 +503,25 @@ register({
 
 **`buildContext`** injects request-scoped values (DB clients, tenant IDs) into every handler call without threading them through each individual tool. It receives the full `ToolCallContext` so context can vary by identity or by call args.
 
+### Localized refusals and errors
+
+Pass `i18n` to render a [`LocalizedError`](https://ttoss.dev/docs/modules/packages/i18n-core/) thrown by a **gate** or by the **handler** as an `isError` result `{ "error": "<message>", "code": "<CODE>" }` in the caller's locale. Gates run outside the handler, so the registrar is the one place that covers both.
+
+```ts
+const { register } = createGatedToolRegistrar({
+  server,
+  gates: [subscriptionGate],
+  i18n: {
+    catalog,
+    // Default: the MCP request's Accept-Language (`getRequestLocale()`).
+    // Pin the agent contract to one language instead:
+    getLocale: () => 'en',
+  },
+});
+```
+
+`onError` still runs for a handler error before it is rendered. Errors that are not localized behave exactly as without the option.
+
 ## MCP Apps (interactive UIs)
 
 The [`io.modelcontextprotocol/ui`](https://github.com/modelcontextprotocol/ext-apps) extension lets a tool result render as an interactive view instead of text. The view is a `ui://` resource holding an HTML document, which the host loads into a sandboxed iframe and talks to over `postMessage`; the tool points at it through its `_meta`.

package/dist/index.cjs

@@ -37,6 +37,14 @@ var getApiHeaders = () => {
     ...(requestContextStore.getStore()?.apiHeaders ?? {})
   };
 };
+/**
+* The `Accept-Language` header of the current MCP request, or `undefined`
+* outside a request or when the client sent none. The default locale source
+* for `createGatedToolRegistrar`'s `i18n` option.
+*/
+var getRequestLocale = () => {
+  return requestContextStore.getStore()?.acceptLanguage;
+};
 
 //#endregion
 //#region src/serveMcpRequest.ts
@@ -431,18 +439,44 @@ var registerToolFromSchema = (server, params) => {
 
 //#endregion
 //#region src/createGatedToolRegistrar.ts
-var toolError = message => {
+var toolError = (message, code) => {
   return {
     content: [{
       type: "text",
-      text: JSON.stringify({
+      text: JSON.stringify(code === void 0 ? {
         error: message
+      } : {
+        error: message,
+        code
       })
     }],
     isError: true
   };
 };
 /**
+* The localized `isError` result for `error`, or `undefined` when it is not
+* a `LocalizedError` or rendering fails — the caller then keeps its usual path.
+*/
+var localizedToolError = async ({
+  error,
+  ctx,
+  i18n
+}) => {
+  try {
+    const requested = i18n.getLocale ? await i18n.getLocale(ctx) : getRequestLocale();
+    const {
+      renderLocalizedError
+    } = await import("@ttoss/i18n-core");
+    const rendered = renderLocalizedError({
+      error,
+      i18n: await i18n.catalog.getI18n(requested)
+    });
+    return rendered ? toolError(rendered.message, rendered.code) : void 0;
+  } catch {
+    return;
+  }
+};
+/**
 * Factory that returns a `register` helper for MCP tools that require
 * authentication and a specific OAuth scope.
 *
@@ -461,6 +495,8 @@ var toolError = message => {
 * 4. Merges `buildContext` output into the handler args.
 * 5. Wraps `null`/`undefined` results in a configurable "Not found" error result.
 * 6. Calls `onError` on handler throw before rethrowing.
+* 7. With `i18n`, renders a `LocalizedError` from a gate or the handler as an
+*    `isError` result in the caller's locale instead of rethrowing it.
 *
 * @example
 * ```typescript
@@ -502,8 +538,37 @@ var createGatedToolRegistrar = ({
   enforceScope = true,
   onError,
   buildContext,
-  notFoundMessage = "Not found"
+  notFoundMessage = "Not found",
+  i18n
 }) => {
+  const renderOrRethrow = async (error, ctx) => {
+    const localized = i18n ? await localizedToolError({
+      error,
+      ctx,
+      i18n
+    }) : void 0;
+    if (localized) return localized;
+    throw error;
+  };
+  const runMethod = async (def, ctx) => {
+    const extra = buildContext ? buildContext(ctx) : {};
+    try {
+      const result = await def.method({
+        ...ctx.args,
+        ...extra
+      });
+      if (result == null) return toolError(notFoundMessage);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(result)
+        }]
+      };
+    } catch (error) {
+      if (onError) await onError(error, ctx);
+      return renderOrRethrow(error, ctx);
+    }
+  };
   const register = def => {
     const handler = async args => {
       const identity = resolveIdentity();
@@ -517,24 +582,12 @@ var createGatedToolRegistrar = ({
         const scopeError = checkScope(identity, def.requiredScope);
         if (scopeError) return scopeError;
       }
-      await runGates([...gates, ...(def.gates ?? [])], ctx);
-      const extra = buildContext ? buildContext(ctx) : {};
       try {
-        const result = await def.method({
-          ...args,
-          ...extra
-        });
-        if (result == null) return toolError(notFoundMessage);
-        return {
-          content: [{
-            type: "text",
-            text: JSON.stringify(result)
-          }]
-        };
+        await runGates([...gates, ...(def.gates ?? [])], ctx);
       } catch (error) {
-        if (onError) await onError(error, ctx);
-        throw error;
+        return renderOrRethrow(error, ctx);
       }
+      return runMethod(def, ctx);
     };
     server.registerTool(def.name, {
       description: def.description,
@@ -856,10 +909,12 @@ var createMcpRouter = (server, options = {}) => {
       await serveRequest(ctx, body);
       ctx.respond = false;
     };
-    if (needsContext) await requestContextStore.run({
+    const acceptLanguage = ctx.get("Accept-Language") || void 0;
+    if (needsContext || acceptLanguage) await requestContextStore.run({
       apiBaseUrl,
       apiHeaders,
-      identity
+      identity,
+      acceptLanguage
     }, runRequest);else await runRequest();
   };
   const postHandler = async ctx => {
@@ -913,6 +968,7 @@ exports.createMcpRouter = createMcpRouter;
 exports.errorBodyMessage = errorBodyMessage;
 exports.getApiHeaders = getApiHeaders;
 exports.getIdentity = getIdentity;
+exports.getRequestLocale = getRequestLocale;
 exports.registerAppResource = registerAppResource;
 exports.registerToolFromSchema = registerToolFromSchema;
 Object.defineProperty(exports, 'z', {

package/dist/index.d.cts

@@ -16,6 +16,7 @@ import compose from "koa-compose";
 import { ListenOptions, Socket } from "net";
 import { ParsedUrlQuery } from "querystring";
 import * as url from "url";
+import { Catalog } from "@ttoss/i18n-core";
 import { z } from "zod";
 
 //#region ../../node_modules/.pnpm/@types+koa@3.0.3/node_modules/@types/koa/index.d.ts
@@ -683,6 +684,12 @@ declare const getIdentity: <T = unknown>() => T | undefined;
  * Returns `{}` outside a request, or when `getApiHeaders` is not configured.
  */
 declare const getApiHeaders: () => Record<string, string>;
+/**
+ * The `Accept-Language` header of the current MCP request, or `undefined`
+ * outside a request or when the client sent none. The default locale source
+ * for `createGatedToolRegistrar`'s `i18n` option.
+ */
+declare const getRequestLocale: () => string | undefined;
 //#endregion
 //#region src/registerAppResource.d.ts
 /**
@@ -1062,6 +1069,22 @@ type CreateGatedToolRegistrarOptions = {
    * `null` or `undefined`. Defaults to `"Not found"`.
    */
   notFoundMessage?: string;
+  /**
+   * Renders a `LocalizedError` — thrown by a gate or by the handler — as an
+   * `isError` result `{ error: <message>, code }` in the caller's locale,
+   * instead of letting the SDK surface its source-language message. Gates run
+   * outside the handler, so this is the one place both are covered.
+   *
+   * `getLocale` defaults to the MCP request's `Accept-Language`
+   * (`getRequestLocale()`); return a fixed locale to pin the agent contract to
+   * one language. `onError` still runs for a handler error before it is
+   * rendered. Errors that are not localized behave exactly as without this
+   * option.
+   */
+  i18n?: {
+    catalog: Pick<Catalog, 'getI18n'>;
+    getLocale?: (ctx: ToolCallContext) => string | string[] | null | undefined | Promise<string | string[] | null | undefined>;
+  };
 };
 declare const createGatedToolRegistrar: ({
   server,
@@ -1070,7 +1093,8 @@ declare const createGatedToolRegistrar: ({
   enforceScope,
   onError,
   buildContext,
-  notFoundMessage
+  notFoundMessage,
+  i18n
 }: CreateGatedToolRegistrarOptions) => {
   register: (def: GatedToolDef) => void;
 };
@@ -1474,4 +1498,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, errorBodyMessage, getApiHeaders, 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, getRequestLocale, registerAppResource, registerToolFromSchema, z };

package/dist/index.d.mts

@@ -18,6 +18,7 @@ import compose from "koa-compose";
 import { ListenOptions, Socket } from "net";
 import { ParsedUrlQuery } from "querystring";
 import * as url from "url";
+import { Catalog } from "@ttoss/i18n-core";
 
 //#region ../../node_modules/.pnpm/@types+koa@3.0.3/node_modules/@types/koa/index.d.ts
 declare interface ContextDelegatedRequest {
@@ -684,6 +685,12 @@ declare const getIdentity: <T = unknown>() => T | undefined;
  * Returns `{}` outside a request, or when `getApiHeaders` is not configured.
  */
 declare const getApiHeaders: () => Record<string, string>;
+/**
+ * The `Accept-Language` header of the current MCP request, or `undefined`
+ * outside a request or when the client sent none. The default locale source
+ * for `createGatedToolRegistrar`'s `i18n` option.
+ */
+declare const getRequestLocale: () => string | undefined;
 //#endregion
 //#region src/registerAppResource.d.ts
 /**
@@ -1063,6 +1070,22 @@ type CreateGatedToolRegistrarOptions = {
    * `null` or `undefined`. Defaults to `"Not found"`.
    */
   notFoundMessage?: string;
+  /**
+   * Renders a `LocalizedError` — thrown by a gate or by the handler — as an
+   * `isError` result `{ error: <message>, code }` in the caller's locale,
+   * instead of letting the SDK surface its source-language message. Gates run
+   * outside the handler, so this is the one place both are covered.
+   *
+   * `getLocale` defaults to the MCP request's `Accept-Language`
+   * (`getRequestLocale()`); return a fixed locale to pin the agent contract to
+   * one language. `onError` still runs for a handler error before it is
+   * rendered. Errors that are not localized behave exactly as without this
+   * option.
+   */
+  i18n?: {
+    catalog: Pick<Catalog, 'getI18n'>;
+    getLocale?: (ctx: ToolCallContext) => string | string[] | null | undefined | Promise<string | string[] | null | undefined>;
+  };
 };
 declare const createGatedToolRegistrar: ({
   server,
@@ -1071,7 +1094,8 @@ declare const createGatedToolRegistrar: ({
   enforceScope,
   onError,
   buildContext,
-  notFoundMessage
+  notFoundMessage,
+  i18n
 }: CreateGatedToolRegistrarOptions) => {
   register: (def: GatedToolDef) => void;
 };
@@ -1475,4 +1499,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, errorBodyMessage, getApiHeaders, 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, getRequestLocale, registerAppResource, registerToolFromSchema, z };

package/dist/index.mjs

@@ -34,6 +34,14 @@ var getApiHeaders = () => {
     ...(requestContextStore.getStore()?.apiHeaders ?? {})
   };
 };
+/**
+* The `Accept-Language` header of the current MCP request, or `undefined`
+* outside a request or when the client sent none. The default locale source
+* for `createGatedToolRegistrar`'s `i18n` option.
+*/
+var getRequestLocale = () => {
+  return requestContextStore.getStore()?.acceptLanguage;
+};
 
 //#endregion
 //#region src/serveMcpRequest.ts
@@ -428,18 +436,44 @@ var registerToolFromSchema = (server, params) => {
 
 //#endregion
 //#region src/createGatedToolRegistrar.ts
-var toolError = message => {
+var toolError = (message, code) => {
   return {
     content: [{
       type: "text",
-      text: JSON.stringify({
+      text: JSON.stringify(code === void 0 ? {
         error: message
+      } : {
+        error: message,
+        code
       })
     }],
     isError: true
   };
 };
 /**
+* The localized `isError` result for `error`, or `undefined` when it is not
+* a `LocalizedError` or rendering fails — the caller then keeps its usual path.
+*/
+var localizedToolError = async ({
+  error,
+  ctx,
+  i18n
+}) => {
+  try {
+    const requested = i18n.getLocale ? await i18n.getLocale(ctx) : getRequestLocale();
+    const {
+      renderLocalizedError
+    } = await import("@ttoss/i18n-core");
+    const rendered = renderLocalizedError({
+      error,
+      i18n: await i18n.catalog.getI18n(requested)
+    });
+    return rendered ? toolError(rendered.message, rendered.code) : void 0;
+  } catch {
+    return;
+  }
+};
+/**
 * Factory that returns a `register` helper for MCP tools that require
 * authentication and a specific OAuth scope.
 *
@@ -458,6 +492,8 @@ var toolError = message => {
 * 4. Merges `buildContext` output into the handler args.
 * 5. Wraps `null`/`undefined` results in a configurable "Not found" error result.
 * 6. Calls `onError` on handler throw before rethrowing.
+* 7. With `i18n`, renders a `LocalizedError` from a gate or the handler as an
+*    `isError` result in the caller's locale instead of rethrowing it.
 *
 * @example
 * ```typescript
@@ -499,8 +535,37 @@ var createGatedToolRegistrar = ({
   enforceScope = true,
   onError,
   buildContext,
-  notFoundMessage = "Not found"
+  notFoundMessage = "Not found",
+  i18n
 }) => {
+  const renderOrRethrow = async (error, ctx) => {
+    const localized = i18n ? await localizedToolError({
+      error,
+      ctx,
+      i18n
+    }) : void 0;
+    if (localized) return localized;
+    throw error;
+  };
+  const runMethod = async (def, ctx) => {
+    const extra = buildContext ? buildContext(ctx) : {};
+    try {
+      const result = await def.method({
+        ...ctx.args,
+        ...extra
+      });
+      if (result == null) return toolError(notFoundMessage);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(result)
+        }]
+      };
+    } catch (error) {
+      if (onError) await onError(error, ctx);
+      return renderOrRethrow(error, ctx);
+    }
+  };
   const register = def => {
     const handler = async args => {
       const identity = resolveIdentity();
@@ -514,24 +579,12 @@ var createGatedToolRegistrar = ({
         const scopeError = checkScope(identity, def.requiredScope);
         if (scopeError) return scopeError;
       }
-      await runGates([...gates, ...(def.gates ?? [])], ctx);
-      const extra = buildContext ? buildContext(ctx) : {};
       try {
-        const result = await def.method({
-          ...args,
-          ...extra
-        });
-        if (result == null) return toolError(notFoundMessage);
-        return {
-          content: [{
-            type: "text",
-            text: JSON.stringify(result)
-          }]
-        };
+        await runGates([...gates, ...(def.gates ?? [])], ctx);
       } catch (error) {
-        if (onError) await onError(error, ctx);
-        throw error;
+        return renderOrRethrow(error, ctx);
       }
+      return runMethod(def, ctx);
     };
     server.registerTool(def.name, {
       description: def.description,
@@ -853,10 +906,12 @@ var createMcpRouter = (server, options = {}) => {
       await serveRequest(ctx, body);
       ctx.respond = false;
     };
-    if (needsContext) await requestContextStore.run({
+    const acceptLanguage = ctx.get("Accept-Language") || void 0;
+    if (needsContext || acceptLanguage) await requestContextStore.run({
       apiBaseUrl,
       apiHeaders,
-      identity
+      identity,
+      acceptLanguage
     }, runRequest);else await runRequest();
   };
   const postHandler = async ctx => {
@@ -895,4 +950,4 @@ var createMcpRouter = (server, options = {}) => {
 };
 
 //#endregion
-export { McpServer, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, errorBodyMessage, getApiHeaders, getIdentity, registerAppResource, registerToolFromSchema, z };
+export { McpServer, UI_EXTENSION_ID, UI_RESOURCE_MIME_TYPE, apiCall, checkScopes, createGatedToolRegistrar, createMcpRouter, errorBodyMessage, getApiHeaders, getIdentity, getRequestLocale, registerAppResource, registerToolFromSchema, z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.29.1",
+  "version": "0.30.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -37,9 +37,10 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "zod": "^4.4.3",
-    "@ttoss/http-server": "^0.9.0",
-    "@ttoss/http-server-auth": "^0.7.0",
-    "@ttoss/auth-core": "^0.15.0"
+    "@ttoss/auth-core": "^0.15.0",
+    "@ttoss/http-server": "^0.10.0",
+    "@ttoss/http-server-auth": "^0.7.1",
+    "@ttoss/i18n-core": "^0.2.0"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.0.0",