Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

fix(mcp): support placeholder messages in createChatPrompt (#15931)

Diwakar Ray Yadavd8a75611bdad
diff --git a/web/src/__tests__/server/unit/mcp-create-chat-prompt-placeholder.servertest.ts b/web/src/__tests__/server/unit/mcp-create-chat-prompt-placeholder.servertest.ts
new file mode 100644
index 0000000000..b64b8d6611
--- /dev/null
+++ b/web/src/__tests__/server/unit/mcp-create-chat-prompt-placeholder.servertest.ts
@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ ChatMessageSchema,
+ createChatPromptTool,
+} from "@/src/features/mcp/features/prompts/tools/createChatPrompt";
+
+type JsonSchema = Record<string, unknown>;
+
+const promptItemJsonSchema = () => {
+ const inputSchema = createChatPromptTool.inputSchema as {
+ properties?: Record<string, unknown>;
+ };
+ const prompt = inputSchema.properties?.prompt as JsonSchema;
+ return prompt.items as JsonSchema;
+};
+
+describe("createChatPrompt placeholder messages", () => {
+ it("accepts literal chat messages (role + content)", () => {
+ expect(ChatMessageSchema.parse({ role: "user", content: "Hello" })).toEqual(
+ { role: "user", content: "Hello" },
+ );
+ });
+
+ it("accepts literal chat messages with an explicit 'message' type", () => {
+ expect(
+ ChatMessageSchema.parse({
+ type: "message",
+ role: "user",
+ content: "Hello",
+ }),
+ ).toEqual({ role: "user", content: "Hello" });
+ });
+
+ it("accepts placeholder messages referencing a runtime variable", () => {
+ expect(
+ ChatMessageSchema.parse({ type: "placeholder", name: "history" }),
+ ).toEqual({ type: "placeholder", name: "history" });
+ });
+
+ it("rejects placeholder messages without a name", () => {
+ expect(() => ChatMessageSchema.parse({ type: "placeholder" })).toThrow();
+ });
+
+ it("rejects placeholder names that do not start with a letter", () => {
+ expect(() =>
+ ChatMessageSchema.parse({ type: "placeholder", name: "1history" }),
+ ).toThrow();
+ });
+
+ it("rejects placeholder names containing invalid characters", () => {
+ expect(() =>
+ ChatMessageSchema.parse({ type: "placeholder", name: "hist ory" }),
+ ).toThrow();
+ });
+
+ it("serializes the base schema to JSON Schema without unions", () => {
+ const serialized = JSON.stringify(createChatPromptTool.inputSchema);
+ expect(serialized).not.toContain("oneOf");
+ expect(serialized).not.toContain("anyOf");
+ expect(serialized).not.toContain("allOf");
+ });
+
+ it("exposes the placeholder shape on the JSON Schema message items", () => {
+ const items = promptItemJsonSchema();
+ const properties = items.properties as Record<string, unknown>;
+
+ expect(properties.type).toEqual(
+ expect.objectContaining({ enum: ["message", "placeholder"] }),
+ );
+ expect(properties.name).toBeDefined();
+ expect(properties.role).toBeDefined();
+ expect(properties.content).toBeDefined();
+ });
+});
diff --git a/web/src/features/mcp/features/prompts/tools/createChatPrompt.ts b/web/src/features/mcp/features/prompts/tools/createChatPrompt.ts
index 29c1018f9e..fff26a5b77 100644
--- a/web/src/features/mcp/features/prompts/tools/createChatPrompt.ts
+++ b/web/src/features/mcp/features/prompts/tools/createChatPrompt.ts
@@ -14,19 +14,53 @@ import {
PROMPT_NAME_MAX_LENGTH,
} from "@langfuse/shared";
import { createPromptForApi } from "@/src/features/prompts/server/prompt-api-service";
-import { buildPromptUrl } from "@langfuse/shared/src/server";
+import {
+ buildPromptUrl,
+ PromptChatMessageSchema,
+} from "@langfuse/shared/src/server";
import { runMcpTool } from "../../../core/run-mcp-tool";
import { ParamCreatePromptLabels } from "../validation";
/**
- * Schema for a single chat message (role + content)
- * Note: Using simple object schema instead of union to comply with MCP spec
+ * JSON Schema facing shape for a single chat message (used by MCP clients for
+ * display). Kept union-free with all fields optional because MCP tool input
+ * schemas must serialize to a plain object schema (unions are rejected by
+ * defineTool). The runtime input schema below enforces the actual message
+ * shape ({role, content} or {type: 'placeholder', name}).
*/
-const ChatMessageSchema = z.object({
- role: z.string().describe("The role (e.g., 'system', 'user', 'assistant')"),
- content: z.string().describe("The message content"),
+export const ChatMessageBaseSchema = z.object({
+ type: z
+ .enum(["message", "placeholder"])
+ .optional()
+ .describe(
+ "Message type. Defaults to 'message'. Use 'placeholder' to reference a runtime variable value (e.g. conversation history) instead of a literal message.",
+ ),
+ role: z
+ .string()
+ .optional()
+ .describe(
+ "The role (e.g., 'system', 'user', 'assistant'). Required for 'message' type.",
+ ),
+ content: z
+ .string()
+ .optional()
+ .describe("The message content. Required for 'message' type."),
+ name: z
+ .string()
+ .optional()
+ .describe(
+ "The variable name for 'placeholder' type messages (e.g. 'history'). Required for 'placeholder' type.",
+ ),
});
+/**
+ * Runtime schema for a single chat message: a literal message ({role, content})
+ * or a placeholder reference ({type: 'placeholder', name}) that is replaced
+ * with a runtime variable value when the prompt is compiled. A strict union is
+ * only used at runtime — the base schema stays union-free for JSON Schema.
+ */
+export const ChatMessageSchema = PromptChatMessageSchema;
+
/**
* Base schema for JSON Schema generation (MCP client display)
* Uses simple types that serialize well to JSON Schema
@@ -38,9 +72,11 @@ const CreateChatPromptBaseSchema = z.object({
.max(PROMPT_NAME_MAX_LENGTH)
.describe("The name of the prompt"),
prompt: z
- .array(ChatMessageSchema)
+ .array(ChatMessageBaseSchema)
.min(1)
- .describe("Array of chat messages with role and content"),
+ .describe(
+ "Array of chat messages. Each message is either {role, content} or a placeholder {type: 'placeholder', name: '<variable>'} that is replaced with a runtime variable value",
+ ),
labels: z
.array(z.string())
.optional()
@@ -95,7 +131,8 @@ export const [createChatPromptTool, handleCreateChatPrompt] = defineTool({
"- Labels are unique across versions",
"",
"Message roles: system (instructions), user (input, can contain {{variables}}), assistant (examples)",
- "Accepts: name, prompt (array of {role, content}), optional labels, config, tags, commitMessage",
+ "Placeholder messages: {type: 'placeholder', name: '<variable>'} reference runtime variable values (e.g. conversation history) inserted when the prompt is used",
+ "Accepts: name, prompt (array of {role, content} or {type: 'placeholder', name}), optional labels, config, tags, commitMessage",
].join("\n"),
baseSchema: CreateChatPromptBaseSchema,
inputSchema: CreateChatPromptInputSchema,