MCP Toseaai

mcp-ToseaAI

ToseaAI文档到演示工作流的官方MCP服务器。

此服务器将生产ToseaAI HTTP合约封装在 /api/mcp/v1 并为Claude Code、Cursor、Codex和其他MCP客户端提供稳定的MCP工具界面。

• API密钥保持在服务器端，并且从不回显到代理。
• 长期运行操作使用 presentation_id 加上投票，而不是原始的SSE。
• 变体工具支持后端支持的显式幂等性密钥。
• 支持导出的工具接受可选 export_filename 因此，下游客户端可以收到一个友好的附件名称。
• 文件上传保持在本地，直到MCP服务器通过HTTPS将它们流式传输到ToseaAI。

为什么要单独回购

此存储库应独立于主应用程序存储库。

• 发布节奏与后端不同。
• 对工具名称和提示的重大更改必须单独进行版本控制。
• 嵌套的git repos或子模块给MCP用户增加了不必要的操作摩擦。

安装

npm install
npm run build

必需的环境变量

TOSEA_API_KEY=sk_...
TOSEA_API_BASE_URL=https://tosea.ai

可选：

• TOSEA_TIMEOUT_MS
• TOSEA_MAX_RETRIES
• TOSEA_MAX_TOOL_CONCURRENCY
• TOSEA_MAX_MUTATING_CONCURRENCY
• TOSEA_MAX_PENDING_TOOL_REQUESTS
• TOSEA_POLL_INTERVAL_MS
• TOSEA_MAX_POLL_MS
• TOSEA_LOG_LEVEL

Claude代码示例

{
  "mcpServers": {
    "tosea": {
      "command": "node",
      "args": ["C:/new/mcp-ToseaAI/dist/src/index.js"],
      "env": {
        "TOSEA_API_KEY": "sk_...",
        "TOSEA_API_BASE_URL": "https://tosea.ai"
      }
    }
  }
}

客户特定示例 示例/README.md.

光标示例

使用 examples/cursor.mcp.json 作为您当地的起点 mcp.json.

OpenAI代理SDK示例

OpenAI的代理SDK支持stdio MCP服务器，因此此仓库可以直接用作本地子流程MCP，而不需要托管HTTP包装器。看 示例/openai-agents-typescript.ts.

如果您以后需要OpenAI Responses API托管的远程MCP模式，请添加一个单独的Streamable HTTP传输包装器，而不是就地更改此stdio包。

工具摘要

• tosea_health
• tosea_get_permissions_summary
• tosea_get_quota_status
• tosea_list_presentations
• tosea_get_presentation_full_data
• tosea_switch_template
• tosea_create_document_parse
• tosea_get_document_parse
• tosea_wait_for_document_parse
• tosea_get_document_parse_result
• tosea_parse_pdf
• tosea_generate_outline
• tosea_edit_outline_page
• tosea_render_slides
• tosea_edit_slide_page
• tosea_export_presentation
• tosea_pdf_to_presentation
• tosea_wait_for_job
• tosea_list_exports
• tosea_list_export_files
• tosea_redownload_export

可靠性模型

• GET 请求使用具有回退和抖动的有界重试。
• 只读工具使用 singleflight 针对相同的飞行中请求进行合并，因此重复的并发呼叫就像相同的一样 list_presentations 查询被合并为一个上游请求。
• 所有工具在一个MCP服务器进程内使用有界本地并发；一旦本地队列已满，MCP服务器就会返回一个可重试的背压错误，而不是让请求堆积起来，直到传输级失败。
• 可变工具在本地以有界并发进行门控，并为相同的对象进行写入 presentation_id 在一个MCP服务器进程内序列化。
• 上传创建端点(pdf-parse, pdf-to-presentation)接受 idempotency_key，但默认情况下，MCP服务器仍然避免对大型上传进行静默自动重试。
• outline edit, slide edit，以及 export 支持 idempotency_key；仅在重试相同的逻辑操作时才重用相同的值。
• tosea_export_presentation 和 tosea_pdf_to_presentation 接受可选 export_filename 当可见的导出附件名称很重要时。
• tosea_create_document_parse 是独立的Markdown/资产提取外观。它回来了 document_parse_id 并且仍然使用后端现有的身份验证、配额和计费规则。
• tosea_parse_pdf 对于继续到大纲生成和幻灯片渲染的工作流，仍然是分阶段演示文稿解析步骤。
• wait_for_job 遵循嵌套 data.job.status 当后端报告一个单独的导出/完整作业时，当不存在嵌套作业时，返回到顶级演示状态。
• html_zip HTML模式组支持导出，并且在后端仍然是免费导出。
• Stdio生命周期与主机进程相关：服务器在 stdin 关闭， SIGINT，以及 SIGTERM，意外的传输失败表现为可重试的主机传输错误，而不是不透明的原始异常。

附件交付

如果MCP客户端下载完成的导出，然后通过OpenClaw、微信、电子邮件或其他聊天界面转发：

• 通过 export_filename 当用户关心最终可见的附件名称时
• 保留文件名、扩展名和 Content-Type 重新上传工件时
• 不要将文件重新打包为匿名二进制附件，否则下游客户端可能只显示通用附件标签

资产文件_id输入

• logo_file_id 是 file_id 之前已确认上传的徽标资产。这不是一条本地道路。
• template_file_id 是 file_id 之前已确认上传的PPTX/PDF自定义模板资产。它不是源文档路径。
• template_file_id 仅在以下情况下有效 slide_mode="image".
• 当 template_file_id 如果存在，后端将请求视为 custom_template 自动。
• 此MCP包本身还没有生成这些资产ID。重用通过脚本创建的ID优先技能或其他可上传的产品流。

上传约束

• page_count_range 必须是其中之一 4-8, 8-12, 12-16, 16-20, 20-30, 30-40, 40-50，或 50-100.
• 源文件计数和总源页面限制由后端层策略强制执行。
• 当前默认/免费后端策略为 1 源文件和 60 总源页面数，除非服务器端策略覆盖它。

图像模式决策规则

• 保持 slide_mode="html" 默认情况下
• 使用 slide_mode="image" 仅当用户明确想要图像模式渲染或图像优先幻灯片合成时
• 使用图像模式时，通过 image_model 如果用户关心图像质量或再生一致性
• 使用 output_format="pptx_image" 当用户想要基于纯图像的PPTX导出时
• 使用 output_format="pdf" 用于图像模式审查切换
• 不要使用 output_format="html_zip" 用于图像模式组

安全注意事项

• API密钥必须以开头 sk_.
• 服务器根据出现的错误编辑承载机密。
• MCP工具层不公开仅JWT帐户操作。
• 导出历史记录仅公开后端返回的用户可见文件。

冒烟测试

此存储库包括一个非计费烟雾测试，可以在不创建演示文稿的情况下检查身份验证、运行状况、权限和列表访问：

npm run smoke

可选标志：

• --feature-key outline_generate
• --expect-tier pro
• --list-limit 5