Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

Read an MCP tool answer that arrived as a resource link (#638)

kevin1b203a6f4528
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c459fd61..c18f77b8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,16 @@ Newest first. `Unreleased` is what is on `main` and not yet tagged.
## Unreleased
+### An MCP tool that answers with a resource link is no longer read as an empty name
+
+A tool that points at a file or a page often returns a `resource_link`: a URI, a name, and a
+sentence of what it is, rather than the contents themselves. That part was named `[resource_link]`
+and the URI was dropped, so the model was told a link arrived and never shown where it went. A
+search that answered with pages produced no page it could open. The URI, name and description are
+now read, each on its own labelled line. The URI leads and the name and description are bounded, so
+a long name cannot push the pointer past the result cap; a server's `title` is shown over its `name`
+when it gives one. A part that already carried text is unchanged.
+
### Dictate messages and talk to a coworker in a live voice call
Deployments can configure transcription separately from their Bots' models, with a waveform composer
diff --git a/server/src/plugins/mcp.ts b/server/src/plugins/mcp.ts
index ba76e6ce..5906a535 100644
--- a/server/src/plugins/mcp.ts
+++ b/server/src/plugins/mcp.ts
@@ -44,6 +44,52 @@ export const MAX_RESULT_CHARS = 20_000;
* from memory. For a knowledge connector that is precisely the failure the whole slice exists to
* prevent — an answer with nothing behind it. So nothing is stated, in words.
*/
+/**
+ * How much of a resource link's title, name or description a model is shown.
+ *
+ * Long enough for a heading and a sentence, short enough that a link's own metadata cannot spend
+ * the result cap its pointer has to fit in.
+ */
+const LINK_FIELD_CHARS = 400;
+
+/**
+ * A resource_link as the lines a model reads: the pointer first, then bounded metadata.
+ *
+ * The URI is the link's identity; the title or name and the description are metadata. The URI
+ * therefore leads, whole, and the other two are cut, so that a server's long name cannot push its
+ * own pointer past {@link MAX_RESULT_CHARS} below and leave the model holding a link with nowhere
+ * to go. Truncation may lose what a resource was called, never where it is. Each line is labelled,
+ * so the fields are told apart by name rather than by position.
+ *
+ * The spec's `title` is the name meant for people, `name` the one meant for programs; the title is
+ * shown when a server gives one. Null when the link names nothing, so the caller names its type.
+ */
+function resourceLinkText(item: {
+ uri?: unknown;
+ name?: unknown;
+ title?: unknown;
+ description?: unknown;
+}): string | null {
+ const field = (value: unknown) =>
+ typeof value === "string" && value.trim() !== "" ? value : null;
+ const bounded = (value: string) =>
+ value.length > LINK_FIELD_CHARS
+ ? `${value.slice(0, LINK_FIELD_CHARS)}…`
+ : value;
+ const lines: string[] = [];
+ const uri = field(item.uri);
+ if (uri !== null) lines.push(`uri: ${uri}`);
+ const title = field(item.title);
+ const name = field(item.name);
+ if (title !== null) lines.push(`title: ${bounded(title)}`);
+ else if (name !== null) lines.push(`name: ${bounded(name)}`);
+ const description = field(item.description);
+ if (description !== null) {
+ lines.push(`description: ${bounded(description)}`);
+ }
+ return lines.length > 0 ? lines.join("\n") : null;
+}
+
export function resultText(
content: unknown,
structuredContent?: unknown,
@@ -58,6 +104,10 @@ export function resultText(
const item = part as {
type?: string;
text?: string;
+ uri?: unknown;
+ name?: unknown;
+ title?: unknown;
+ description?: unknown;
resource?: { text?: unknown } | null;
};
if (item.type === "text" && typeof item.text === "string") {
@@ -69,6 +119,14 @@ export function resultText(
if (item.type === "resource" && typeof item.resource?.text === "string") {
return item.resource.text;
}
+ // A resource_link is a pointer, not the file: a URI, a name, sometimes a title, and often a
+ // sentence of what it is. Named as "[resource_link]", the model was told a link arrived and
+ // never shown where it went, so a search that answered with pages produced no page it could
+ // open.
+ if (item.type === "resource_link") {
+ const shown = resourceLinkText(item);
+ if (shown !== null) return shown;
+ }
// A non-text part is named rather than dropped. A model told "[image]" can say the tool
// returned an image; a model handed nothing concludes the tool returned nothing.
return `[${item.type ?? "unknown"}]`;
diff --git a/server/tests/mcp-result.test.ts b/server/tests/mcp-result.test.ts
index 5e3cf02e..a93dbc39 100644
--- a/server/tests/mcp-result.test.ts
+++ b/server/tests/mcp-result.test.ts
@@ -130,6 +130,95 @@ describe("a result with something in it", () => {
);
});
+ test("reads a resource_link's uri, name and description, as a server points at a file", () => {
+ // MCP's resource_link is a pointer, not the file: a URI, a name, and often a sentence of
+ // what it is. Named as "[resource_link]", the model was told a link arrived and never shown
+ // where it went, so a search that answered with pages produced no pages it could open.
+ // The URI leads and each field is labelled, so the model tells them apart by name.
+ expect(
+ resultText([
+ {
+ type: "resource_link",
+ uri: "notion://page/q3-budget",
+ name: "Q3 budget",
+ description: "The approved numbers for the quarter",
+ mimeType: "text/html",
+ },
+ ]).text,
+ ).toBe(
+ "uri: notion://page/q3-budget\nname: Q3 budget\ndescription: The approved numbers for the quarter",
+ );
+ });
+
+ test("shows a resource_link's title over its name, when the server gives one", () => {
+ // The spec's `title` is the name meant for people; `name` is the one meant for programs.
+ expect(
+ resultText([
+ {
+ type: "resource_link",
+ uri: "notion://page/q3-budget",
+ name: "q3_budget",
+ title: "Q3 budget",
+ },
+ ]).text,
+ ).toBe("uri: notion://page/q3-budget\ntitle: Q3 budget");
+ });
+
+ test("a resource_link with only a uri is still that uri, not an empty name", () => {
+ expect(
+ resultText([{ type: "resource_link", uri: "file:///notes.md" }]).text,
+ ).toBe("uri: file:///notes.md");
+ });
+
+ test("a resource_link's long name cannot push its uri past the result cap", () => {
+ // The URI is the link's identity; the name is metadata. Truncation may lose what a resource
+ // was called, never where it is: a name as long as the whole cap must leave the pointer
+ // readable, rather than a link with nowhere to go, which is the failure this reader removes.
+ const { text, truncated } = resultText([
+ {
+ type: "resource_link",
+ name: "x".repeat(MAX_RESULT_CHARS),
+ uri: "https://example.com/source",
+ },
+ ]);
+ expect(text.startsWith("uri: https://example.com/source\n")).toBe(true);
+ expect(text).toContain("https://example.com/source");
+ expect(truncated).toBe(false);
+ expect(text.length).toBeLessThan(MAX_RESULT_CHARS);
+ });
+
+ test("bounds a resource_link's description, and marks the cut", () => {
+ const description = "d".repeat(1_000);
+ const { text } = resultText([
+ { type: "resource_link", uri: "file:///a.md", description },
+ ]);
+ expect(text).toBe(`uri: file:///a.md\ndescription: ${"d".repeat(400)}…`);
+ });
+
+ test("a resource_link that names nothing is still named, rather than dropped", () => {
+ expect(resultText([{ type: "resource_link" }]).text).toBe(
+ "[resource_link]",
+ );
+ expect(
+ resultText([{ type: "resource_link", uri: " ", name: "" }]).text,
+ ).toBe("[resource_link]");
+ });
+
+ test("joins a resource_link beside a text part", () => {
+ expect(
+ resultText([
+ { type: "text", text: "matching pages:" },
+ {
+ type: "resource_link",
+ uri: "https://example.com/policy",
+ name: "Expense policy",
+ },
+ ]).text,
+ ).toBe(
+ "matching pages:\nuri: https://example.com/policy\nname: Expense policy",
+ );
+ });
+
test("names a null or non-object part rather than throwing", () => {
// Content arrives from a vendor's server; a null entry must not throw.
expect(resultText([null]).text).toBe("[unknown]");