mcp-expose 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -6,6 +6,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [1.1.1] - 2026-09-28
+
+### Added
+
+- `transformResponse` hook for route tools, on every marker and adapter, plus a server-level default. It shapes what
+  the agent sees from a route's response (hide or format fields, add hints) without turning the route into a custom
+  tool. The hook receives the status, headers, body and parsed JSON, the tool arguments and the MCP call context.
+  `ctx.callRoute()` enriches the response with other routes of the app, using the same credentials and the same
+  middleware, guards and validation. Placeholders are URL-encoded, and `.` / `..` segments are rejected.
+- `ResponseTransform`, `ResponseTransformContext` and `RouteToolResponse` types.
+
+### Fixed
+
+- A tool handler or hook that returns plain data with its own `content` array (for example a CMS post) is no longer
+  mistaken for an MCP `ToolResult`; only `content` arrays of MCP content items (`{ type: ... }`) are.
+
 ## [1.1.0] - 2026-09-27
 
 ### Added
@@ -52,6 +68,7 @@ options, default tool naming) now follows Semantic Versioning.
 - Path parameters that are empty, `.` or `..` are rejected, so an agent cannot use them to reach routes
   that were never exposed as tools (for example `/orders/../admin`).
 
-[Unreleased]: https://github.com/NITINKACHHADIYA/Node-MCP/compare/v1.1.0...HEAD
+[Unreleased]: https://github.com/NITINKACHHADIYA/Node-MCP/compare/v1.1.1...HEAD
+[1.1.1]: https://github.com/NITINKACHHADIYA/Node-MCP/releases/tag/v1.1.1
 [1.1.0]: https://github.com/NITINKACHHADIYA/Node-MCP/releases/tag/v1.1.0
 [1.0.0]: https://github.com/NITINKACHHADIYA/Node-MCP/releases/tag/v1.0.0

package/README.md

@@ -47,13 +47,14 @@ router.get('/orders/:id', [OrdersController, 'show']).use(middleware.auth()).mcp
 6. [Connect an AI client](#connect-an-ai-client)
 7. [OAuth: sign in from AI clients](#oauth-sign-in-from-ai-clients)
 8. [Defining tool inputs (schemas)](#defining-tool-inputs-schemas)
-9. [Configuration reference](#configuration-reference)
-10. [Custom (non-HTTP) tools](#custom-non-http-tools)
-11. [Security checklist](#security-checklist)
-12. [Writing tools agents use well](#writing-tools-agents-use-well)
-13. [Limitations and roadmap](#limitations-and-roadmap)
-14. [Development](#development)
-15. [Versioning and support](#versioning-and-support)
+9. [Shaping and enriching responses](#shaping-and-enriching-responses)
+10. [Configuration reference](#configuration-reference)
+11. [Custom (non-HTTP) tools](#custom-non-http-tools)
+12. [Security checklist](#security-checklist)
+13. [Writing tools agents use well](#writing-tools-agents-use-well)
+14. [Limitations and roadmap](#limitations-and-roadmap)
+15. [Development](#development)
+16. [Versioning and support](#versioning-and-support)
 
 ---
 
@@ -648,30 +649,88 @@ Sources, from highest to lowest precedence:
 
 Your app's own validation always runs as well. The schema tells the agent what to send, and your API decides what it accepts.
 
+## Shaping and enriching responses
+
+By default the agent gets the route's response as it is. Add `transformResponse` to a route tool to change
+what the agent sees: hide internal fields, format values, add hints, or pull in related data from other
+routes. The route stays a route tool; there is no need to rewrite it as a custom tool.
+
+```ts
+@Get(':id')
+@McpTool({
+  name: 'get_order',
+  transformResponse: async (res, ctx) => {
+    if (!res.ok) return undefined; // keep the default error result
+    const { internalNotes, ...order } = res.json as Order;
+    // Another route of this app, with the same user's credentials, guards and pipes:
+    const customer = await ctx.callRoute({ path: '/api/customers/:id', params: { id: order.customerId } });
+    return { ...order, total: formatMoney(order.total), customer: customer.ok ? customer.json : null };
+  },
+})
+findOne(@Param('id') id: string) { ... }
+```
+
+It works the same with every marker: `mcpTool({ transformResponse })`, `config: { mcp: { transformResponse } }`,
+`.mcp({ transformResponse })`, and `toolsFromOpenApi(doc, dispatch, { transformResponse })`.
+
+**What the hook receives**
+
+- `res`: `status`, `headers`, the raw `body`, the parsed `json` (for JSON responses) and `ok` (status below 400).
+- `ctx.args`: the tool arguments. `ctx.request`: the internal request (method, path, query, body).
+- `ctx.toolContext`: the MCP request's headers, client IP and, with [OAuth](#oauth-sign-in-from-ai-clients), `auth`.
+- `ctx.defaultResult()`: the result mcp-expose would return without the hook.
+- `ctx.callRoute({ method, path, params, query, body, headers })`: calls another route of the same app.
+  - It forwards the same credentials (`Authorization`, cookies) and runs through the same middleware, guards and validation.
+  - `path` is the full path as your server sees it, including any global prefix or router mount path. Fill `:id` / `{id}`
+    placeholders from `params`: values are URL-encoded, and `.` or `..` are rejected, so agent input can't redirect the call.
+
+**What it returns**
+
+| Return value               | Result                                                                                              |
+| -------------------------- | --------------------------------------------------------------------------------------------------- |
+| a string or any JSON value | Sent to the agent (objects also as `structuredContent`). Still an error result if the route failed. |
+| a full `ToolResult`        | Used as is, so you control `isError` (e.g. `{ ...ctx.defaultResult(), content: [...] }`).           |
+| `undefined`                | The default result.                                                                                 |
+| a thrown error             | An error result with the message, which the agent sees.                                             |
+
+`maxResponseChars` still applies to whatever the hook returns.
+
+**For every tool at once**, set `transformResponse` in the server options, e.g. to strip fields everywhere:
+
+```ts
+mountMcp(app, {
+  name: 'shop-api',
+  transformResponse: (res) => (res.ok ? omitDeep(res.json, ['internalNotes', 'passwordHash']) : undefined),
+});
+```
+
+A tool's own `transformResponse` replaces the server-level one.
+
 ## Configuration reference
 
 ### Server options (all adapters)
 
-| Option             | Type                  | Default                                                    | Description                                                                                                                        |
-| ------------------ | --------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `name`             | `string`              | required                                                   | Server name shown to clients.                                                                                                      |
-| `version`          | `string`              | `'1.0.0'`                                                  | Server version.                                                                                                                    |
-| `instructions`     | `string`              | none                                                       | Guidance for the model on how to use the tools together.                                                                           |
-| `path`             | `string`              | `'/mcp'`                                                   | Endpoint path.                                                                                                                     |
-| `allowedOrigins`   | `string[] \| '*'`     | `[]`                                                       | Browser origins allowed to call the endpoint. Requests without `Origin` (CLIs, IDEs, servers) are always allowed.                  |
-| `forwardHeaders`   | `string[]`            | `['authorization','cookie','x-api-key','accept-language']` | Headers copied from the MCP request to the internal API call.                                                                      |
-| `maxResponseChars` | `number`              | `100000`                                                   | Longer API responses are truncated before reaching the model.                                                                      |
-| `oauth`            | `OAuthOptions`        | none                                                       | Protect the endpoint with OAuth 2.1. See [OAuth](#oauth-sign-in-from-ai-clients).                                                  |
-| `tools`            | `McpToolDefinition[]` | `[]`                                                       | Extra hand-written tools.                                                                                                          |
-| `baseUrl`          | `string`              | loopback                                                   | _Express/Koa/Nest/Adonis._ Where internal calls go. Set it for HTTPS with self-signed certs, unix sockets, or a separate API host. |
-| `routes`           | `{method,path,...}[]` | `[]`                                                       | _Express/Koa/Hono._ Expose routes without editing them.                                                                            |
-| `routers`          | see guide             | none                                                       | _Express:_ `{ '/prefix': router }`. _Koa:_ `[router]`.                                                                             |
-| `middleware`       | `Middleware[]`        | `[]`                                                       | _Express._ Middleware in front of `/mcp`, such as auth.                                                                            |
-| `guards`           | `CanActivate[]`       | `[]`                                                       | _NestJS._ Guards on the MCP controller.                                                                                            |
-| `decorators`       | `ClassDecorator[]`    | `[]`                                                       | _NestJS._ Extra decorators on the MCP controller, e.g. `[Public()]` for global guards.                                             |
-| `pathPrefix`       | `string`              | none                                                       | _NestJS._ Extra prefix for tool routes. Global prefix and URI versioning are automatic.                                            |
-| `routeOptions`     | `object`              | none                                                       | _Fastify._ Extra route options for `/mcp`, such as `onRequest` hooks.                                                              |
-| `configureRoute`   | `(route) => void`     | none                                                       | _AdonisJS._ Configure the MCP route, e.g. add middleware.                                                                          |
+| Option              | Type                  | Default                                                    | Description                                                                                                                        |
+| ------------------- | --------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `name`              | `string`              | required                                                   | Server name shown to clients.                                                                                                      |
+| `version`           | `string`              | `'1.0.0'`                                                  | Server version.                                                                                                                    |
+| `instructions`      | `string`              | none                                                       | Guidance for the model on how to use the tools together.                                                                           |
+| `path`              | `string`              | `'/mcp'`                                                   | Endpoint path.                                                                                                                     |
+| `allowedOrigins`    | `string[] \| '*'`     | `[]`                                                       | Browser origins allowed to call the endpoint. Requests without `Origin` (CLIs, IDEs, servers) are always allowed.                  |
+| `forwardHeaders`    | `string[]`            | `['authorization','cookie','x-api-key','accept-language']` | Headers copied from the MCP request to the internal API call.                                                                      |
+| `maxResponseChars`  | `number`              | `100000`                                                   | Longer API responses are truncated before reaching the model.                                                                      |
+| `oauth`             | `OAuthOptions`        | none                                                       | Protect the endpoint with OAuth 2.1. See [OAuth](#oauth-sign-in-from-ai-clients).                                                  |
+| `transformResponse` | `ResponseTransform`   | none                                                       | Default response hook for route tools without their own. See [Shaping responses](#shaping-and-enriching-responses).                |
+| `tools`             | `McpToolDefinition[]` | `[]`                                                       | Extra hand-written tools.                                                                                                          |
+| `baseUrl`           | `string`              | loopback                                                   | _Express/Koa/Nest/Adonis._ Where internal calls go. Set it for HTTPS with self-signed certs, unix sockets, or a separate API host. |
+| `routes`            | `{method,path,...}[]` | `[]`                                                       | _Express/Koa/Hono._ Expose routes without editing them.                                                                            |
+| `routers`           | see guide             | none                                                       | _Express:_ `{ '/prefix': router }`. _Koa:_ `[router]`.                                                                             |
+| `middleware`        | `Middleware[]`        | `[]`                                                       | _Express._ Middleware in front of `/mcp`, such as auth.                                                                            |
+| `guards`            | `CanActivate[]`       | `[]`                                                       | _NestJS._ Guards on the MCP controller.                                                                                            |
+| `decorators`        | `ClassDecorator[]`    | `[]`                                                       | _NestJS._ Extra decorators on the MCP controller, e.g. `[Public()]` for global guards.                                             |
+| `pathPrefix`        | `string`              | none                                                       | _NestJS._ Extra prefix for tool routes. Global prefix and URI versioning are automatic.                                            |
+| `routeOptions`      | `object`              | none                                                       | _Fastify._ Extra route options for `/mcp`, such as `onRequest` hooks.                                                              |
+| `configureRoute`    | `(route) => void`     | none                                                       | _AdonisJS._ Configure the MCP route, e.g. add middleware.                                                                          |
 
 ### Tool options (`@McpTool()`, `mcpTool()`, `config.mcp`, `.mcp()`)
 
@@ -684,6 +743,7 @@ Your app's own validation always runs as well. The schema tells the agent what t
 | `annotations`                         | MCP hints: `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. Defaults come from the HTTP method (GET → read-only, DELETE → destructive).        |
 | `headers`                             | Static headers added to the internal request.                                                                                                                       |
 | `scopes`                              | OAuth scopes the token needs to call this tool (with the `oauth` option). Missing scopes answer `403 insufficient_scope`.                                           |
+| `transformResponse`                   | Shape or enrich what the agent sees from this route's response. See [Shaping and enriching responses](#shaping-and-enriching-responses).                            |
 
 Each internal request also carries `X-Mcp-Tool: <tool name>`, so you can log or meter agent traffic separately.
 
@@ -740,7 +800,7 @@ Planned (non-breaking, 1.x minor releases):
 
 - Per-user tool lists (hide tools the token's scopes can't call)
 - Next.js route handlers, Hapi and Elysia adapters
-- Structured output schemas, and binary/file responses
+- Structured output schemas (`outputSchema`), and binary/file responses
 - Streaming long-running responses over SSE
 - CLI to preview generated tools (`npx mcp-expose inspect`)
 - Resources from GET routes, and prompts

package/dist/adonisjs/index.cjs

@@ -98,6 +98,38 @@ function loopbackBaseUrl(req) {
 }
 __name(loopbackBaseUrl, "loopbackBaseUrl");
 
+// src/core/result.ts
+function isToolResult(value) {
+  const content = value?.content;
+  return !!value && typeof value === "object" && Array.isArray(content) && content.length > 0 && content.every((c) => !!c && typeof c === "object" && typeof c.type === "string");
+}
+__name(isToolResult, "isToolResult");
+function toToolResult(value) {
+  if (isToolResult(value)) return value;
+  if (typeof value === "string") return {
+    content: [
+      {
+        type: "text",
+        text: value
+      }
+    ]
+  };
+  const text = JSON.stringify(value ?? null);
+  const result = {
+    content: [
+      {
+        type: "text",
+        text
+      }
+    ]
+  };
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    result.structuredContent = value;
+  }
+  return result;
+}
+__name(toToolResult, "toToolResult");
+
 // src/core/schema.ts
 function isStandard(s) {
   return typeof s === "object" && s !== null && "~standard" in s;
@@ -318,9 +350,7 @@ function splitArgs(args, mapping) {
 }
 __name(splitArgs, "splitArgs");
 function responseToResult(res, maxChars) {
-  let text = res.body;
-  if (text.length > maxChars) text = `${text.slice(0, maxChars)}
-\u2026[truncated ${text.length - maxChars} chars]`;
+  const text = truncate(res.body, maxChars);
   const isError = res.status >= 400;
   const result = {
     content: [
@@ -345,6 +375,58 @@ ${text}` : text || `HTTP ${res.status}`
   return result;
 }
 __name(responseToResult, "responseToResult");
+function safeDecode(segment) {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+__name(safeDecode, "safeDecode");
+function truncate(text, maxChars) {
+  return text.length > maxChars ? `${text.slice(0, maxChars)}
+\u2026[truncated ${text.length - maxChars} chars]` : text;
+}
+__name(truncate, "truncate");
+function toRouteToolResponse(res) {
+  let json;
+  if ((res.headers["content-type"] ?? "").includes("json") && res.body) {
+    try {
+      json = JSON.parse(res.body);
+    } catch {
+    }
+  }
+  return {
+    ...res,
+    json,
+    ok: res.status < 400
+  };
+}
+__name(toRouteToolResponse, "toRouteToolResponse");
+function transformedResult(value, res, maxChars) {
+  const explicit = isToolResult(value);
+  const result = toToolResult(value);
+  if (!explicit && !res.ok) {
+    result.isError = true;
+    delete result.structuredContent;
+  }
+  let truncated = false;
+  const content = result.content.map((c) => {
+    if (c.type !== "text" || c.text.length <= maxChars) return c;
+    truncated = true;
+    return {
+      ...c,
+      text: truncate(c.text, maxChars)
+    };
+  });
+  if (!truncated) return result;
+  const { structuredContent: _dropped, ...rest } = result;
+  return {
+    ...rest,
+    content
+  };
+}
+__name(transformedResult, "transformedResult");
 function pickForwardHeaders(ctx, names) {
   const out = {};
   for (const name of names) {
@@ -360,6 +442,7 @@ function createRouteTool(route, opts, dispatch, serverOpts = {}) {
   const { schema, mapping } = buildInputSchema(route, opts);
   const forward = serverOpts.forwardHeaders ?? DEFAULT_FORWARD_HEADERS;
   const maxChars = serverOpts.maxResponseChars ?? 1e5;
+  const transform = opts.transformResponse ?? serverOpts.transformResponse;
   return {
     name,
     title: opts.title,
@@ -405,14 +488,53 @@ function createRouteTool(route, opts, dispatch, serverOpts = {}) {
           ]
         };
       }
-      const res = await dispatch({
+      const request = {
         method,
         path,
         query,
         body,
         headers
-      }, ctx);
-      return responseToResult(res, maxChars);
+      };
+      const res = await dispatch(request, ctx);
+      if (!transform) return responseToResult(res, maxChars);
+      const { "content-type": _ct, ...baseHeaders } = headers;
+      const hookCtx = {
+        tool: name,
+        args,
+        request,
+        toolContext: ctx,
+        defaultResult: /* @__PURE__ */ __name(() => responseToResult(res, maxChars), "defaultResult"),
+        async callRoute(r) {
+          if (!r.path.startsWith("/")) {
+            throw new Error(`callRoute: path must start with "/", got ${JSON.stringify(r.path)}`);
+          }
+          const params = r.params ?? {};
+          const missing2 = pathParams(r.path).filter((p) => params[p] === void 0 && !r.path.includes(`:${p}?`));
+          if (missing2.length) throw new Error(`callRoute: missing params for ${r.path}: ${missing2.join(", ")}`);
+          const subPath = interpolatePath(r.path, params);
+          if (subPath.split("/").some((seg) => [
+            ".",
+            ".."
+          ].includes(safeDecode(seg)))) {
+            throw new Error(`callRoute: path must not contain "." or ".." segments: ${JSON.stringify(subPath)}`);
+          }
+          const sub = {
+            method: (r.method ?? "GET").toUpperCase(),
+            path: subPath,
+            query: r.query ?? {},
+            body: r.body,
+            headers: {
+              ...baseHeaders,
+              ...r.headers
+            }
+          };
+          if (sub.body !== void 0) sub.headers["content-type"] = "application/json";
+          return toRouteToolResponse(await dispatch(sub, ctx));
+        }
+      };
+      const response = toRouteToolResponse(res);
+      const value = await transform(response, hookCtx);
+      return value === void 0 ? responseToResult(res, maxChars) : transformedResult(value, response, maxChars);
     }
   };
 }