bug: `createChatPrompt` MCP tool does not support `placeholder` messages like the SDK

问题场景

用户通过 MCP 客户端（如 Claude Code）连接 Langfuse MCP 服务（Langfuse Cloud），调用 `createChatPrompt` 工具创建或更新包含占位符消息的 chat prompt。占位符消息用于后续注入图片等动态内容。当传入 `{“type”:”placeholder”,”name”:”history”}` 格式的消息时，MCP 工具在输入校验阶段即失败，无法到达 Langfuse API；当更新已有含占位符的 prompt 时，会因为校验失败导致占位符内容被破坏，只能删除重建。

报错原文

MCP error -32602: Validation failed: prompt.1.role: Invalid input: expected string, received undefined, prompt.1.content: Invalid input: expected string, received undefined

原因分析

可能原因：`createChatPrompt` MCP 工具（`web/src/features/mcp/features/prompts/tools/createChatPrompt.ts`）在定义输入 schema 时只允许 `{role: string, content: string}` 结构且 `additionalProperties: false`，没有为 Langfuse 支持的占位符消息（`{type: “placeholder”, name: string}`）定义对应的 schema。

Issue 中的代码注释表明，选择这种简化结构是为了规避 MCP 规范对 `oneOf`/`anyOf` 联合类型的限制，但这也导致占位符消息无法通过 MCP 传递。底层 API（`packages/shared/src/server/llm/types.ts`）已通过联合类型支持两种消息格式，因此这不是后端能力缺失，而是 MCP 工具层 schema 设计问题。

环境排查

• 确认 MCP 服务端版本：检查是否已包含修复 PR #13323 的发布版本。
• 确认 MCP 客户端（如 Claude Code）对 JSON Schema 的 `oneOf`/`anyOf` 支持情况，部分客户端在渲染表单时会错误处理嵌套联合类型。
• 确认 `createChatPrompt` 工具 schema 中 `additionalProperties: false` 的设置（可在 MCP 服务端代码中检查）。

解决步骤

1. 首选尝试：升级 langfuse-mcp 服务到包含 PR #13323（“feat: Support placeholder messages in MCP”）的版本。该 PR 采用双层 schema 方案：对外暴露扁平 schema（所有字段可选），避免客户端对 `oneOf`/`anyOf` 的处理问题；内部使用 Zod 的 `.superRefine()` 进行严格运行时校验，强制要求“内容消息”或“占位符消息”二选一。
2. 临时规避：在修复版本发布前，避免通过 MCP 工具创建或更新包含占位符消息的 chat prompt，改用 Langfuse UI 或 SDK 操作。
3. 数据修复：如果已有 prompt 因该问题导致占位符被破坏，需删除该 prompt 并重新创建。
4. 如需自行修复：可参考 PR #13323 的实现，在 `createChatPrompt.ts` 中调整输入 schema 和校验逻辑；注意占位符名称需符合正则 `/^[a-zA-Z][a-zA-Z0-9_]*$/`。

验证方法

升级或修复后，重新调用 `createChatPrompt` 工具，传入包含占位符消息的 `prompt` 数组，确认不再出现 `MCP error -32602` 校验错误；再通过 UI 打开新版本 prompt，确认占位符消息被保留且调用时能正常注入内容。

参考来源

langfuse/langfuse #15905

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。