Merge pull request #873 from zereight/fix/structured-content-array-guard

fix: drop non-object structuredContent after a jmespath filter

Author: zereight

CHANGELOG.md

@@ -31,6 +31,7 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
 ##### Fixed
 
+- A `jmespath` filter that turns `structuredContent` into an array, a scalar, or `null` (for example `items[].title`) now drops `structuredContent` instead of returning a value the MCP SDK rejects. The filtered JSON is still in the text content. No tool sets `structuredContent` today ([#873](https://github.com/zereight/gitlab-mcp/pull/873))
 - Tool calls that cannot reach GitLab now name the reason (for example `ECONNREFUSED`, `ENOTFOUND`, or a TLS certificate code) and a hint, instead of only `fetch failed` ([#856](https://github.com/zereight/gitlab-mcp/pull/856))
 - Values interpolated into GitLab URL paths (project/group ids, file paths, branch and tag names, keys, slugs) are now fully percent-decoded and rejected when they contain a `.`/`..` segment, a leading `/`, an empty path segment, or a control character such as NUL ([#760](https://github.com/zereight/gitlab-mcp/pull/760)). Because values are decoded before encoding, a name that literally contains a percent escape (for example a tag named `release%2F1.0`) now resolves to the decoded name (`release/1.0`), and a value mixing a valid escape with a stray `%` is rejected
 - `execute_graphql` in `GITLAB_PERMISSION_MODE=modify` now rejects destructive GraphQL mutations whose top-level field names use teardown verbs (for example `environmentStop`, `pipelineCancel`, and `jobUnschedule`), not only delete-style names ([#755](https://github.com/zereight/gitlab-mcp/pull/755))

test/utils/jmespath-tool-result.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import { describe, test } from "node:test";
+import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
 import {
   applyJmespathFilter,
   applyJmespathToToolResult,
@@ -123,6 +124,42 @@ describe("jmespath tool result helpers", () => {
     assert.deepEqual(applyJmespathToToolResult(original, "starts_with(title, `a`)"), original);
   });
 
+  test("applyJmespathToToolResult keeps structuredContent when the filter returns an object", () => {
+    const result = applyJmespathToToolResult(
+      {
+        content: [{ type: "text", text: JSON.stringify({ items: [{ title: "a" }], total: 1 }) }],
+        structuredContent: { items: [{ title: "a" }], total: 1 },
+      },
+      "{total: total}"
+    );
+    assert.deepEqual(result.structuredContent, { total: 1 });
+    assert.equal(CallToolResultSchema.safeParse(result).success, true);
+  });
+
+  test("applyJmespathToToolResult drops structuredContent the filter turns into a non-object", () => {
+    const items = [{ title: "a" }, { title: "b" }];
+    for (const [expression, filtered] of [
+      ["items[].title", ["a", "b"]],
+      ["missing", null],
+      ["length(items)", 2],
+    ] as const) {
+      const result = applyJmespathToToolResult(
+        {
+          content: [{ type: "text", text: JSON.stringify({ items }) }],
+          structuredContent: { items },
+        },
+        expression
+      );
+      assert.equal("structuredContent" in result, false, expression);
+      assert.deepEqual(
+        JSON.parse((result.content as { text: string }[])[0].text),
+        filtered,
+        expression
+      );
+      assert.equal(CallToolResultSchema.safeParse(result).success, true, expression);
+    }
+  });
+
   test("getJmespathSyntaxError rejects invalid expressions before execution", () => {
     assert.match(getJmespathSyntaxError("[[[") ?? "", /Invalid jmespath expression/);
     assert.equal(getJmespathSyntaxError("[].title"), undefined);

utils/jmespath-tool-result.ts

@@ -56,6 +56,10 @@ function isContentBlock(value: unknown): value is { type?: unknown; text?: unkno
   return Boolean(value && typeof value === "object");
 }
 
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function prepareDataForJmespath(data: unknown, maskValue?: (value: unknown) => unknown): unknown {
   return maskValue ? maskValue(data) : data;
 }
@@ -102,9 +106,13 @@ export function applyJmespathToToolResult<T extends ToolResultLike>(
           return parsed.ok ? { ...block, text: JSON.stringify(filter(parsed.value)) } : block;
         })
       : result.content;
-    return result.structuredContent === undefined
-      ? { ...result, content }
-      : { ...result, content, structuredContent: filter(result.structuredContent) };
+    if (result.structuredContent === undefined) return { ...result, content };
+    // MCP structuredContent must be a JSON object, and the SDK rejects the whole tools/call
+    // result otherwise. "items[].title" or a missing path is not one, so drop it; the text keeps it.
+    const structuredContent = filter(result.structuredContent);
+    if (isJsonObject(structuredContent)) return { ...result, content, structuredContent };
+    const { structuredContent: _dropped, ...rest } = result;
+    return { ...rest, content } as T;
   } catch {
     return result;
   }