Skip to content

feat: add structured content #780

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
nirinchev wants to merge 5 commits into
base: main
Choose a base branch
from
Draft

feat: add structured content #780

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
da5b4e0
feat: add structured content to insertmany
nirinchev Dec 3, 2025
0650454
update start script
nirinchev Dec 3, 2025
b0e1210
fix tests
nirinchev Dec 4, 2025
e6dbf5f
clean up imports
nirinchev Dec 4, 2025
c3dcfc5
add structured content to list-databases
nirinchev Dec 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@
"dist"
],
"scripts": {
"start": "node dist/index.js --transport http --loggers stderr mcp --previewFeatures vectorSearch",
"start": "node dist/index.js --transport http --loggers stderr mcp --previewFeatures search",
"start:stdio": "node dist/index.js --transport stdio --loggers stderr mcp",
"prepare": "husky && pnpm run build",
"build:clean": "rm -rf dist",
Expand Down
17 changes: 15 additions & 2 deletions src/tools/mongodb/create/insertMany.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { z } from "zod";
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import { DbOperationArgs, MongoDBToolBase } from "../mongodbTool.js";
import type { ToolResult } from "../../tool.js";
import { type ToolArgs, type OperationType, formatUntrustedData } from "../../tool.js";
import { zEJSON } from "../../args.js";
import { type Document } from "bson";
Expand Down Expand Up @@ -37,14 +37,21 @@ export class InsertManyTool extends MongoDBToolBase {
),
}
: commonArgs;

protected outputShape = {
success: z.boolean(),
insertedCount: z.number(),
insertedIds: z.array(z.any()),
};

static operationType: OperationType = "create";

protected async execute({
database,
collection,
documents,
embeddingParameters: providedEmbeddingParameters,
}: ToolArgs<typeof this.argsShape>): Promise<CallToolResult> {
}: ToolArgs<typeof this.argsShape>): Promise<ToolResult<typeof this.outputShape>> {
const provider = await this.ensureConnected();

const embeddingParameters = this.isFeatureEnabled("search")
Expand All @@ -70,8 +77,14 @@ export class InsertManyTool extends MongoDBToolBase {
`Inserted \`${result.insertedCount}\` document(s) into ${database}.${collection}.`,
`Inserted IDs: ${Object.values(result.insertedIds).join(", ")}`
);

return {
content,
structuredContent: {
Copy link
Collaborator

@fmenezes fmenezes Dec 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI the spec says we should return the json serialised instead of formatted text at https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content, I don't know if you would be thinking about automating it as well

Copy link
Collaborator Author

@nirinchev nirinchev Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we touched on it at some point in Slack, but in my opinion the target of the "SHOULD" here is the backwards compatibility part, not the exact shape of the response. That is, we want to make sure clients that don't support structured content still work as expected, but I don't believe those matching precisely is critical.

I've decided to keep the prompt injection mitigation in place as, if a client does not support structured content, returning json with potentially malicious content is risky. Technically, automating it further is feasible - we can have formatUntrustedData both construct the content with the injection mitigation and returned the structured content as is, but it seemed like we're not winning a lot by doing that (the code would get more complex with a bunch of generics to enforce the output shape).

success: true,
insertedCount: result.insertedCount,
insertedIds: Object.values(result.insertedIds),
},
};
}

Expand Down
23 changes: 15 additions & 8 deletions src/tools/mongodb/metadata/listDatabases.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,31 @@
import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
import { MongoDBToolBase } from "../mongodbTool.js";
import type * as bson from "bson";
import type { OperationType } from "../../tool.js";
import type { OperationType, ToolResult } from "../../tool.js";
import { formatUntrustedData } from "../../tool.js";
import z, { type ZodNever } from "zod";

export const ListDatabasesToolOutputShape = {
dbs: z.array(z.object({ name: z.string(), sizeOnDisk: z.string(), sizeUnit: z.literal("bytes") })),
};

export type ListDatabasesToolOutput = z.objectOutputType<typeof ListDatabasesToolOutputShape, ZodNever>;

export class ListDatabasesTool extends MongoDBToolBase {
public name = "list-databases";
protected description = "List all databases for a MongoDB connection";
protected argsShape = {};
protected outputShape = ListDatabasesToolOutputShape;
static operationType: OperationType = "metadata";

protected async execute(): Promise<CallToolResult> {
protected async execute(): Promise<ToolResult<typeof this.outputShape>> {
const provider = await this.ensureConnected();
const dbs = (await provider.listDatabases("")).databases as { name: string; sizeOnDisk: bson.Long }[];
const dbs = ((await provider.listDatabases("")).databases as { name: string; sizeOnDisk: bson.Long }[]).map(
(db) => ({ name: db.name, sizeOnDisk: db.sizeOnDisk.toString(), sizeUnit: "bytes" as const })
);

return {
content: formatUntrustedData(
`Found ${dbs.length} databases`,
...dbs.map((db) => `Name: ${db.name}, Size: ${db.sizeOnDisk.toString()} bytes`)
),
content: formatUntrustedData(`Found ${dbs.length} databases`, JSON.stringify(dbs)),
structuredContent: { dbs },
};
}
}
22 changes: 16 additions & 6 deletions src/tools/tool.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
import type { z } from "zod";
import { type ZodRawShape, type ZodNever } from "zod";
import type { z, ZodTypeAny, ZodRawShape, ZodNever } from "zod";
import type { RegisteredTool, ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
import type { CallToolResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
import type { Session } from "../common/session.js";
Expand All @@ -14,6 +13,12 @@ import type { PreviewFeature } from "../common/schemas.js";
export type ToolArgs<Args extends ZodRawShape> = z.objectOutputType<Args, ZodNever>;
export type ToolCallbackArgs<Args extends ZodRawShape> = Parameters<ToolCallback<Args>>;

export type ToolResult<OutputSchema extends ZodRawShape | undefined = undefined> = {
content: { type: "text"; text: string }[];
structuredContent: OutputSchema extends ZodRawShape ? z.objectOutputType<OutputSchema, ZodTypeAny> : never;
isError?: boolean;
};

export type ToolExecutionContext<Args extends ZodRawShape = ZodRawShape> = Parameters<ToolCallback<Args>>[1];

/**
Expand Down Expand Up @@ -274,6 +279,8 @@ export abstract class ToolBase {
*/
protected abstract argsShape: ZodRawShape;

protected outputShape?: ZodRawShape;

private registeredTool: RegisteredTool | undefined;

protected get annotations(): ToolAnnotations {
Expand Down Expand Up @@ -462,11 +469,14 @@ export abstract class ToolBase {
}
};

this.registeredTool = server.mcpServer.tool(
this.registeredTool = server.mcpServer.registerTool(
this.name,
this.description,
this.argsShape,
this.annotations,
{
description: this.description,
inputSchema: this.argsShape,
annotations: this.annotations,
outputSchema: this.outputShape,
},
callback
);

Expand Down
2 changes: 1 addition & 1 deletion tests/integration/helpers.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,7 +184,7 @@ export function setupIntegrationTest(
}

// eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
export function getResponseContent(content: unknown | { content: unknown }): string {
export function getResponseContent(content: unknown | { content: unknown; structuredContent: unknown }): string {
return getResponseElements(content)
.map((item) => item.text)
.join("\n");
Expand Down
45 changes: 32 additions & 13 deletions tests/integration/tools/mongodb/create/insertMany.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,10 +72,11 @@ describeWithMongoDB("insertMany tool when search is disabled", (integration) =>
},
});

const content = getResponseContent(response.content);
const content = getResponseContent(response);
expect(content).toContain(`Inserted \`1\` document(s) into ${integration.randomDbName()}.coll1.`);

await validateDocuments("coll1", [{ prop1: "value1" }]);
validateStructuredContent(response.structuredContent, extractInsertedIds(content));
});

it("returns an error when inserting duplicates", async () => {
Expand All @@ -95,7 +96,7 @@ describeWithMongoDB("insertMany tool when search is disabled", (integration) =>
},
});

const content = getResponseContent(response.content);
const content = getResponseContent(response);
expect(content).toContain("Error running insert-many");
expect(content).toContain("duplicate key error");
expect(content).toContain(insertedIds[0]?.toString());
Expand Down Expand Up @@ -174,12 +175,14 @@ describeWithMongoDB(
},
});

const content = getResponseContent(response.content);
const content = getResponseContent(response);
const insertedIds = extractInsertedIds(content);
expect(insertedIds).toHaveLength(1);

const docCount = await collection.countDocuments({ _id: insertedIds[0] });
expect(docCount).toBe(1);

validateStructuredContent(response.structuredContent, insertedIds);
});

it("returns an error when there is a search index and embeddings parameter are wrong", async () => {
Expand Down Expand Up @@ -214,7 +217,7 @@ describeWithMongoDB(
},
});

const content = getResponseContent(response.content);
const content = getResponseContent(response);
expect(content).toContain("Error running insert-many");
const untrustedContent = getDataFromUntrustedContent(content);
expect(untrustedContent).toContain(
Expand Down Expand Up @@ -263,10 +266,11 @@ describeWithMongoDB(
},
});

const content = getResponseContent(response.content);
const content = getResponseContent(response);
expect(content).toContain("Documents were inserted successfully.");
const insertedIds = extractInsertedIds(content);
expect(insertedIds).toHaveLength(1);
validateStructuredContent(response.structuredContent, insertedIds);

const doc = await collection.findOne({ _id: insertedIds[0] });
expect(doc).toBeDefined();
Expand Down Expand Up @@ -316,10 +320,11 @@ describeWithMongoDB(
},
});

const content = getResponseContent(response.content);
const content = getResponseContent(response);
expect(content).toContain("Documents were inserted successfully.");
const insertedIds = extractInsertedIds(content);
expect(insertedIds).toHaveLength(2);
validateStructuredContent(response.structuredContent, insertedIds);

const doc1 = await collection.findOne({ _id: insertedIds[0] });
expect(doc1?.title).toBe("The Matrix");
Expand Down Expand Up @@ -369,10 +374,11 @@ describeWithMongoDB(
},
});

const content = getResponseContent(response.content);
const content = getResponseContent(response);
expect(content).toContain("Documents were inserted successfully.");
const insertedIds = extractInsertedIds(content);
expect(insertedIds).toHaveLength(1);
validateStructuredContent(response.structuredContent, insertedIds);

const doc = await collection.findOne({ _id: insertedIds[0] });
expect(doc?.info).toBeDefined();
Expand Down Expand Up @@ -417,10 +423,11 @@ describeWithMongoDB(
},
});

const content = getResponseContent(response.content);
const content = getResponseContent(response);
expect(content).toContain("Documents were inserted successfully.");
const insertedIds = extractInsertedIds(content);
expect(insertedIds).toHaveLength(1);
validateStructuredContent(response.structuredContent, insertedIds);

const doc = await collection.findOne({ _id: insertedIds[0] });
expect(doc?.title).toBe("The Matrix");
Expand Down Expand Up @@ -452,10 +459,11 @@ describeWithMongoDB(
},
},
});
const content = getResponseContent(response.content);
const content = getResponseContent(response);
expect(content).toContain("Documents were inserted successfully.");
const insertedIds = extractInsertedIds(content);
expect(insertedIds).toHaveLength(1);
validateStructuredContent(response.structuredContent, insertedIds);

const doc = await collection.findOne({ _id: insertedIds[0] });
expect((doc?.title as Record<string, unknown>)?.text).toBe("The Matrix");
Expand Down Expand Up @@ -495,7 +503,7 @@ describeWithMongoDB(
},
});

const content = getResponseContent(response.content);
const content = getResponseContent(response);
expect(content).toContain("Error running insert-many");
expect(content).toContain("Field 'nonExistentField' does not have a vector search index in collection");
expect(content).toContain("Only fields with vector search indexes can have embeddings generated");
Expand Down Expand Up @@ -529,10 +537,11 @@ describeWithMongoDB(
},
});

const content = getResponseContent(response.content);
const content = getResponseContent(response);
expect(content).toContain("Documents were inserted successfully.");
const insertedIds = extractInsertedIds(content);
expect(insertedIds).toHaveLength(1);
validateStructuredContent(response.structuredContent, insertedIds);

const doc = await collection.findOne({ _id: insertedIds[0] });
expect(doc?.title).toBe("The Matrix");
Expand Down Expand Up @@ -564,9 +573,10 @@ describeWithMongoDB(
},
});

const content = getResponseContent(response.content);
const content = getResponseContent(response);
expect(content).toContain("Documents were inserted successfully.");
const insertedIds = extractInsertedIds(content);
validateStructuredContent(response.structuredContent, insertedIds);

const doc = await collection.findOne({ _id: insertedIds[0] });
expect(Array.isArray(doc?.titleEmbeddings)).toBe(true);
Expand Down Expand Up @@ -614,9 +624,10 @@ describeWithMongoDB(
},
});

const content = getResponseContent(response.content);
const content = getResponseContent(response);
expect(content).toContain("Documents were inserted successfully.");
const insertedIds = extractInsertedIds(content);
validateStructuredContent(response.structuredContent, insertedIds);

const doc = await collection.findOne({ _id: insertedIds[0] });
expect(doc?.title).toBe("The Matrix");
Expand Down Expand Up @@ -692,3 +703,11 @@ function extractInsertedIds(content: string): ObjectId[] {
.map((e) => ObjectId.createFromHexString(e)) ?? []
);
}

function validateStructuredContent(structuredContent: unknown, expectedIds: ObjectId[]): void {
expect(structuredContent).toEqual({
success: true,
insertedCount: expectedIds.length,
insertedIds: expectedIds,
});
}
20 changes: 13 additions & 7 deletions tests/integration/tools/mongodb/metadata/listDatabases.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { describeWithMongoDB, validateAutoConnectBehavior } from "../mongodbHelpers.js";
import { getResponseElements, getParameters, expectDefined, getDataFromUntrustedContent } from "../../../helpers.js";
import { describe, expect, it } from "vitest";
import type { ListDatabasesToolOutput } from "../../../../../src/tools/mongodb/metadata/listDatabases.js";

describeWithMongoDB("listDatabases tool", (integration) => {
const defaultDatabases = ["admin", "config", "local"];
Expand All @@ -22,6 +23,9 @@ describeWithMongoDB("listDatabases tool", (integration) => {
const dbNames = getDbNames(response.content);

expect(dbNames).toIncludeSameMembers(defaultDatabases);

const structuredContent = response.structuredContent as ListDatabasesToolOutput;
expect(structuredContent.dbs.map((db) => db.name)).toIncludeSameMembers(defaultDatabases);
});
});

Expand All @@ -36,6 +40,13 @@ describeWithMongoDB("listDatabases tool", (integration) => {
const response = await integration.mcpClient().callTool({ name: "list-databases", arguments: {} });
const dbNames = getDbNames(response.content);
expect(dbNames).toIncludeSameMembers([...defaultDatabases, "foo", "baz"]);

const structuredContent = response.structuredContent as ListDatabasesToolOutput;
expect(structuredContent.dbs.map((db) => db.name)).toIncludeSameMembers([
...defaultDatabases,
"foo",
"baz",
]);
});
});

Expand Down Expand Up @@ -68,11 +79,6 @@ function getDbNames(content: unknown): (string | null)[] {
const responseItems = getResponseElements(content);
expect(responseItems).toHaveLength(2);
const data = getDataFromUntrustedContent(responseItems[1]?.text ?? "{}");
return data
.split("\n")
.map((item) => {
const match = item.match(/Name: ([^,]+), Size: \d+ bytes/);
return match ? match[1] : null;
})
.filter((item): item is string | null => item !== undefined);

return (JSON.parse(data) as ListDatabasesToolOutput["dbs"]).map((db) => db.name);
}
8 changes: 3 additions & 5 deletions tests/unit/toolBase.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,15 +141,13 @@ describe("ToolBase", () => {
beforeEach(() => {
const mockServer = {
mcpServer: {
tool: (
registerTool: (
name: string,
description: string,
paramsSchema: unknown,
annotations: ToolAnnotations,
config: { description: string; inputSchema: unknown; annotations: ToolAnnotations },
cb: ToolCallback<ZodRawShape>
): void => {
expect(name).toBe(testTool.name);
expect(description).toBe(testTool["description"]);
expect(config.description).toBe(testTool["description"]);
mockCallback = cb;
},
},
Expand Down