Calypso Multimodal RAG

Calypso MCP Server

为 Claude Desktop、Cursor 和 Agent 工作流提供托管式多模态 RAG——只需一条 npx 命令。

针对 PDF、截图、图表和示意图提问，还可上传新的源材料，无需运行向量存储、Docker 堆栈或 OCR 流水线。答案附带可供核查的引用。

此服务是 Calypso Context 的一个入口界面——它与支持 Calypso WhatsApp 服务的知识层相同，现已开放给 MCP 客户端使用。了解各部分如何协同 →

• 一条命令即可设置：npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-your-key-here
• 真正的多模态 RAG：通过 Gemini File Search 原生处理文本和视觉内容
• 上传和查询：提供专用工具，用于管理持久知识文件和批量上传
• 多轮对话：提供具备上下文感知能力的回答，并可通过 /new 重置
• 可发现的工作流：提供资源和提示词，用于安全的 RAG、上传和摄取流程

GitHub | 文档 | Smithery | 官方 MCP 注册表

标签：multimodal-rag、gemini-rag、hosted-rag-mcp、mcp-server

与其让每个 Agent 或工作流都连接到单独的文档搜索堆栈，不如将此 MCP 用作面向 Agent 的入口，接入一个可重复使用的答案层：只需上传一次源材料，即可检索文本和视觉内容，并返回附有用户可核验证据的答案。

快速开始

# One-liner with npx
npx -y @calypsohq/multimodal-rag-mcp-server --api-key "sk-your-key-here"

也可以使用环境变量：

CALYPSO_API_KEY="sk-..." npx -y @calypsohq/multimodal-rag-mcp-server

然后，使用下方的配置示例，将同一条命令添加到 Claude Desktop、Cursor 或 Smithery。

为什么选择 Calypso

无需本地向量存储、Docker Compose，也无需在 Agent 提出有依据的问题前另行搭建 OCR 或视觉流水线。为服务提供 Calypso API 密钥后，它会在连接时自动发现团队的 Agent 和知识库。

• 零基础设施：只需一条 npx 命令；无需托管或运维任何组件。
• 多模态，无需第二条流水线：文本和视觉内容会一起索引，因此图表或截图可以像段落一样被查询。
• 答案附带证据：响应包含来源引用和检索元数据。
• 读取和写入：可通过同一服务查询知识并添加内容，包括文件、批次和网站。

你将获得

• 支持多轮记忆的生产级 Calypso 多模态 Agent
• 内置的单文件上传工具和批量知识上传工具
• 自动发现团队的 RAG 变体和知识库
• 可核验的引用，附带来源引用和检索元数据
• 用于安全工作流的只读资源和可重复使用的提示词

为什么选择多模态优先的 RAG

公司的大部分知识不只有文本。答案往往分布在设置截图、PDF 表格、产品示意图、帮助中心页面或报告中的图表里。Calypso 将完整的知识范围整合到单一检索层，让 Agent 能够提出有依据的问题，而不必猜测通用模型记忆中的内容。

• 搜索用户实际依赖的格式：文档、PDF、截图、图表、示意图、产品图片、支持文章、手册、政策、常见问题解答和报告。
• 先为答案提供依据，再由模型撰写：Gemini File Search 会先检索相关文本和视觉上下文，然后 Calypso Agent 再根据这些源材料作答。
• 展示证据链：回答可以包含来源引用、基于页面的依据和检索元数据，方便人们在信任答案前进行核实。
• 使用元数据限定检索范围：使用工作区、团队、客户、语言、文件类型、状态或其他元数据，让回答保持相关，而无需重复创建知识库。
• 在各处复用同一知识层：将 Cursor、Claude Desktop、AI Agent、n8n 工作流、产品界面、支持流程和网站体验连接到同一个有来源依据的知识层。

实际上，这意味着你的 Agent 可以回答以下问题：

• “解释这张设置截图和附带的政策 PDF。支持专员接下来应该怎么做？”
• “这份入门 PDF 中关于审批规则的内容是什么？”
• “这个设置界面为什么无法正常运行？”
• “将定价图表与我们的套餐文档进行比较，并推荐合适的套餐。”
• “总结适用于此支持工单的政策。”
• “根据我们的定价文档，哪个产品套餐适合这位客户？”
• “比较图示中的数据导入流程和检索流程。”

此 MCP 的功能

使用 calypso-agent，你可以：

• 针对已配置的 Calypso 知识库提出有依据的问题
• 使用可选的 model 参数选择任意已发现的团队 RAG 变体
• 通过原生 /v1/responses 对话模型继续多轮对话
• 使用 /new 重置对话上下文
• 使用为 calypso-agent 提供服务的同一个兼容 OpenAI 的 Responses 端点
• 发现受支持的 Calypso 工作流内置的资源和提示词

要求

• Node.js 18+
• 服务端使用 Web Fetch API 原语（fetch、Headers、Request、Response、FormData、Blob 和 File）进行 API 调用并兼容 SDK。对于只提供部分 Node 18+ Web API 表面的 MCP 运行时，程序包会在启动时补齐缺失的全局对象。
• 可访问以下端点的 Calypso API：
  • POST /v1/responses
  • GET /v1/rag-agent/models
  • GET /v1/knowledge/buckets
  • POST /v1/knowledge/files/upload-session
  • POST /v1/knowledge/files/upload-session/{session_id}/finalize
  • POST /v1/knowledge/files:batch/upload-session
  • POST /v1/knowledge/files:batch/upload-session/{batch_id}/finalize
  • GET /v1/knowledge/batches/{batch_id}
• Calypso API 密钥（sk-...）

配置

环境变量：

• CALYPSO_API_KEY（必需）
• CALYPSO_API_BASE_URL（可选，默认值为 https://api.calypso.so/v1）

CLI 标志：

• --api-key
• --api-base-url

配置优先级：

1. CLI 标志 / Smithery 提供的命令参数
2. 环境变量
3. 默认基础 URL（https://api.calypso.so/v1）

使用 npx 运行

npx -y @calypsohq/multimodal-rag-mcp-server --api-key "sk-..."

使用环境变量运行

env CALYPSO_API_KEY="sk-..." CALYPSO_API_BASE_URL="https://api.calypso.so/v1" npx -y @calypsohq/multimodal-rag-mcp-server

在 Cursor 中配置

添加一个新的 MCP 服务（命令类型），例如：

npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-... --api-base-url https://api.calypso.so/v1

在 Claude Desktop 中配置

1. 打开 Claude Desktop MCP 配置

在 Claude Desktop 中：

Claude -> Settings -> Developer -> Edit Config

在 macOS 上，文件通常位于：

~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop 使用 claude_desktop_config.json 配置桌面 MCP 服务。Claude Code 使用单独的配置位置，例如 ~/.claude.json 或项目级 .mcp.json。

2. 添加 Calypso MCP 服务

将以下内容粘贴到 claude_desktop_config.json 中：

{
  "mcpServers": {
    "Calypso Multimodal RAG": {
      "command": "npx",
      "args": [
        "-y",
        "@calypsohq/multimodal-rag-mcp-server"
      ],
      "env": {
        "CALYPSO_API_KEY": "sk-your-calypso-api-key",
        "CALYPSO_API_BASE_URL": "https://api.calypso.so/v1"
      }
    }
  }
}

替换：

• sk-your-calypso-api-key

为你的真实 Calypso API 密钥。

3. 完全重启 Claude Desktop

完全退出 Claude Desktop，然后重新打开。

不要只关闭窗口。在 macOS 上：

Cmd + Q

重启后，Claude 中应会出现 MCP，并提供以下工具：

• calypso-agent
• calypso-list-buckets
• calypso-upload-file
• calypso-upload-files-batch

可选：将 Claude 生成的文件保存到 Mac

Calypso 提供托管式多模态 RAG 工具。它不会将生成的报告、摘要、CSV、JSON 文件或网页搜索内容直接写入你的本地计算机。

若要让 Claude Desktop 在本地保存生成的文件，请在 Calypso 旁边添加标准文件系统 MCP 服务，并将其限制在专用安全文件夹中。

先创建文件夹：

mkdir -p ~/Claude

然后将两个服务都添加到 claude_desktop_config.json 中：

{
  "mcpServers": {
    "Calypso Multimodal RAG": {
      "command": "npx",
      "args": [
        "-y",
        "@calypsohq/multimodal-rag-mcp-server"
      ],
      "env": {
        "CALYPSO_API_KEY": "sk-your-calypso-api-key",
        "CALYPSO_API_BASE_URL": "https://api.calypso.so/v1"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Claude"
      ]
    }
  }
}

更改配置后，请完全退出并重新打开 Claude Desktop。

提示词示例：

Use Calypso for the grounded RAG answer, then save the final report as /Users/yourname/Claude/report.md using the filesystem tool.

为确保安全，只授予文件系统对 ~/Claude 等专用文件夹的访问权限，不要授予对整个主目录的访问权限。

用途	最佳负责方
基于来源的 RAG 答案	Calypso MCP
将文件上传到 Calypso	Calypso MCP
将 .md、.pdf、.json、.csv 等文件写入 Mac	文件系统 MCP
Claude 的网页搜索内容	Claude 和文件系统 MCP 提示词

Smithery

该服务可通过 Smithery 使用，并通过与桌面客户端相同的 npx 包路径启动。

Smithery 用户配置：

• calypsoApiKey（必填）
• calypsoApiBaseUrl（可选，默认值为 https://api.calypso.so/v1）

Smithery 的启动方式等同于：

npx -y @calypsohq/multimodal-rag-mcp-server --api-key sk-... --api-base-url https://api.calypso.so/v1

仅当目标为可自托管的 Calypso 兼容部署时，才使用 calypsoApiBaseUrl。云端默认配置无需覆盖。

故障排除

• 缺少 API 密钥：提供 --api-key 或 CALYPSO_API_KEY
• API 主机错误：确保 --api-base-url / CALYPSO_API_BASE_URL 以 /v1 结尾
• 可自托管部署：只有在不使用 https://api.calypso.so/v1 时才覆盖基础 URL
• Smithery 启动方式不匹配：使用打包的 npx -y @calypsohq/multimodal-rag-mcp-server 路径，而不要在全新克隆的仓库中运行 node dist/index.js
• FormData is not defined 或 Headers is not defined：升级到最新版本的包。MCP 服务会在上传工具运行前初始化缺失的 Web Fetch API 全局对象。
• /mnt/user-data/uploads/... 出现 ENOENT 错误：该路径属于托管 Agent 或附件沙箱，不一定是 MCP 服务所在的位置。请改用 contentBase64，不要使用 filePath。
• 保存本地文件：Calypso 的答案可与 Claude Desktop 的文件系统 MCP 服务配合使用，但必须明确要求 Claude 将最终输出保存到允许的本地路径。

选择 filePath 还是 contentBase64

对于本地 MCP 安装，请使用 filePath，包括 Claude Desktop 和 Cursor 配置中通过本地命令启动此包的情况，例如：

npx -y @calypsohq/multimodal-rag-mcp-server

在这种设置下，MCP 服务进程会在你的计算机上运行，并可读取同一用户账户可访问的路径。直接传入本地路径即可；服务会读取原始字节，并通过 Calypso 上传会话 URL 上传文件。无需对本地文件进行 Base64 编码。

对于托管或远程 MCP 客户端，请使用 contentBase64，包括由 Smithery 托管的服务、浏览器/云端运行时、生成的内存内容以及 Agent 容器。在这些环境中，Mac 或工作站上的路径无法被 MCP 服务进程读取。

如果路径以 /mnt/user-data/uploads、/mnt/data、/mnt/attachments 或其他托管沙箱前缀开头，除非此 MCP 服务也在同一沙箱中运行，否则不要将其作为 filePath 发送。请改用 contentBase64 或其他内联字节来源。

可用工具

calypso-agent

直接访问 Calypso Agent。

说明：

• 不会自动路由到其他角色或 Agent。
• 启动时会自动发现 API 密钥可用的 calypso-agent 变体。
• 使用可选的 model 参数选择指定变体，例如 calypso-agent:pricing。
• 每个模型变体都有独立的 MCP 对话链，因此切换变体时不会接续错误的对话线程。
• 使用 POST /v1/responses，而非 POST /v1/chat/completions。
• 首轮会创建一个命名对话，后续轮次通过 previous_response_id 接续。
• 支持使用可选的 fileIds 提出限定检索范围的问题。新上传的文件应使用持久化知识上传工具，并等待索引完成后再提问。
• 使用 /new 作为提示词可重置 MCP 对话。

calypso-search

直接搜索你的知识并返回匹配段落，不会要求 Agent 编写答案。

当你需要证据而非文字说明时使用它 — 例如检查是否已建立索引、在做决定前收集来源，或让调用方 Agent 自行推理这些段落。

说明：

• 使用 POST /v1/search。
• 必须提供 query。
• agent 将搜索范围限定为某个 Agent 变体的知识；buckets 可将范围缩小到指定存储桶。
• maxResults 的取值会限制在 1–20 之间。

示例：

{
  "query": "annual plan refund window",
  "buckets": ["support-handbook"],
  "maxResults": 5
}

calypso-list-buckets

列出与配置的 Calypso API 密钥关联的团队存储桶。

说明：

• 使用 GET /v1/knowledge/buckets。
• 不接受 team_id；Calypso 会根据 API 密钥确定团队范围。
• 返回存储桶 ID、slug、名称、状态、成员数、来源数和存储桶存储就绪状态。
• 默认只列出活跃存储桶。需要在审计或清理时查看已归档存储桶，请传入 includeArchived: true。
• 需要选择目标存储桶时，请在使用 calypso-upload-file 或 calypso-upload-files-batch 前调用此工具。
• calypso://rag-agent-models 会说明哪些存储桶绑定到各个 RAG 变体。calypso-list-buckets 会说明该 API 密钥所属团队有哪些存储桶。

示例：

{
  "includeArchived": false
}

calypso-get-file

根据文件 ID 获取一个知识文件的元数据和索引状态。

说明：

• 使用 GET /v1/knowledge/files/{file_id}。
• 将 calypso-list-buckets 返回的不透明 fileIds 解析为文件名、MIME 类型、大小、索引状态和各存储桶的同步状态。
• 传入 verify: true 可与提供方交叉核对（?verify=gemini）——速度较慢，但当状态似乎过时，结果更具权威性。

示例：

{
  "fileId": "file_123",
  "verify": true
}

calypso-add-website

将网站导入知识存储桶，使网页内容可以与上传的文件一起被查询。

说明：

• 使用 POST /v1/knowledge/websites。
• 必须提供 url 和目标位置 — 目标位置可以是 bucketIds、bucketSlugs 或 bucket 之一。
• 可选的 title、tagsHint 和 preferredLanguage 有助于对来源进行分类。
• 传入 idempotencyKey 可确保重试安全；该值会作为 Idempotency-Key 标头发送。
• 与文件上传一样，接收请求并不意味着内容已可查询 — 页面仍需完成索引。

示例：

{
  "url": "https://example.com/pricing",
  "bucket": "pricing",
  "title": "Public pricing page",
  "idempotencyKey": "pricing-page-2026-08"
}

calypso-create-bucket

为先创建、再填充的工作流创建一个空存储桶。

说明：

• 使用 POST /v1/knowledge/buckets（要求后端已部署此端点，且 API 密钥具备 knowledge:bucket:create 能力）。
• 服务器会规范化 slug；发生冲突时会返回类型化的 bucket_slug_exists 错误。
• 重放 idempotencyKey 请求时会返回已有存储桶，而不是报错。
• 上传时仍可通过 bucketSlugs + createMissingBuckets 隐式创建存储桶；此工具用于预先创建目标存储桶。

示例：

{
  "name": "Product docs",
  "slug": "product-docs",
  "idempotencyKey": "create-product-docs-1"
}

calypso-create-agent

创建绑定到一个或多个存储桶的 Calypso Agent 变体。

注意：

• 使用 POST /v1/rag-agent/agents（需要已部署此端点的后端，以及 API 密钥具备 rag:agent:create 能力）。
• 成功响应以 model 开头，可直接传给 calypso-agent。
• 存储桶绑定由服务器端验证：未知或已归档的存储桶会返回 bucket_not_found；Agent ID 冲突会返回 agent_id_exists；超出套餐的 Agent 数量上限会返回 agent_limit_reached。
• 创建 Agent 会刷新模型目录，并发出 MCP tools/list_changed + resources/list_changed 通知，因此无需重新连接即可使用新变体。

示例：

{
  "agentId": "support",
  "name": "Support agent",
  "bucketSlugs": ["product-docs"],
  "idempotencyKey": "create-support-agent-1"
}

calypso-upload-file

将文件上传到持久化的、由存储桶支持的知识存储和索引流水线。

注意：

• 使用 POST /v1/knowledge/files/upload-session，将字节直接上传到存储，然后使用 POST /v1/knowledge/files/upload-session/{session_id}/finalize 完成操作。
• 上传采用 JSON 会话请求和签名二进制 PUT，而非 multipart 表单上传。
• 返回文件和任务元数据，而非聊天附件 file_id。
• 需要通过 bucketIds、bucketSlugs 或 bucket 指定一个存储桶目标。
• 对于服务器能够读取路径的本地 Claude Desktop/Cursor MCP 安装，请使用 filePath。对于无法读取本地路径的托管或远程 MCP 客户端，请使用 contentBase64。
• 如果 Agent 收到类似 /mnt/user-data/uploads/file.pdf 的路径，不应将其作为 filePath 发送，而应将文件字节作为 contentBase64 发送。
• 支持可选的 title、tags、metadata 和 idempotencyKey。
• 使用 bucketIds 或 bucketSlugs 将上传内容路由到现有存储桶，或者使用 bucket 作为单个 slug 的快捷方式。
• 如果希望 Calypso 在上传期间创建缺失的目标存储桶，请同时传入存储桶 slug 和 createMissingBuckets: true。
• 可选择等待索引达到就绪状态后再返回。

示例：

{
  "filename": "handbook.pdf",
  "mimeType": "application/pdf",
  "filePath": "/Users/me/Documents/handbook.pdf",
  "bucket": "support-handbook",
  "createMissingBuckets": true,
  "waitForIndexing": true
}

calypso-upload-files-batch

通过单个请求将 1 到 100 个文件上传到持久化知识存储。

注意：

• 使用 POST /v1/knowledge/files:batch/upload-session，将每个已接受的项目直接上传到存储，然后使用 POST /v1/knowledge/files:batch/upload-session/{batch_id}/finalize 完成操作。
• 上传采用 JSON 会话请求和签名二进制 PUT，而非 multipart 表单上传。
• 必须提供 batchIdempotencyKey；Calypso 会使用它为重试派生持久化批次 ID。
• 除非每个项目都提供自己的存储桶目标，否则必须通过 bucketIds、bucketSlugs 或 bucket 指定一个共享存储桶目标。
• 支持共享的 bucketIds、bucketSlugs、bucket 和 createMissingBuckets 默认值，以及项目级覆盖值。
• 对于服务器能够读取每个路径的本地 Claude Desktop/Cursor MCP 安装，请为每个项目使用 filePath。对于无法读取本地路径的托管或远程 MCP 客户端，请为每个项目使用 contentBase64。
• 如果未提供 clientFileId，则会生成符合 Firestore 要求的 client_file_id 值。
• accepted 或 queued 表示上传已持久化，并不一定表示内容已可供查询。使用 waitForBatchReady: true 轮询 GET /v1/knowledge/batches/{batch_id}?include_items=true。
• 查看每个项目的状态、bucketSyncStatus 和 bucketSync，以区分已索引内容与可通过存储桶检索的内容。

示例：

{
  "batchIdempotencyKey": "kb-seed-2026-06-04",
  "bucket": "support-handbook",
  "createMissingBuckets": true,
  "items": [
    {
      "filename": "faq.txt",
      "mimeType": "text/plain",
      "filePath": "/Users/me/Documents/faq.txt"
    }
  ],
  "waitForBatchReady": true
}

可用资源

calypso://server-info

只读服务器元数据，包括软件包版本、API 基础 URL、传输方式、身份验证模型和公开的能力。

calypso://rag-agent-models

只读运行时目录，列出从已配置的 API 密钥发现的、团队范围内的 calypso-agent 模型变体，包括每个变体的有效 buckets、bucket_ids 和 missing_bucket_ids。如果无法进行发现，此资源会回退到基础 calypso-agent。

calypso://buckets

只读运行时列表，列出与配置的 API 密钥关联的团队知识桶。可用于检查知识桶 ID/slug，以及上传前知识桶存储的就绪状态。

calypso://workflows

支持的 RAG 和文件上传工作流简明指南。

calypso://security

关于 API 密钥、本地文件读取、上传和日志记录的操作安全说明。

可用提示词

• calypso-question：为 calypso-agent 起草有依据的知识库问题
• calypso-ingestion：准备持久化知识存储上传及后续查询
• calypso-reset-conversation：使用 /new 开始一个干净的 RAG 对话

常见工作流（复制/粘贴）

知识检索

• 总结某个主题：
  • Summarize the knowledge base guidance for campaign approvals
• 询问具体答案：
  • What does our documentation say about indexing retries?
• 比较两个概念：
  • Compare file indexing with retrieval execution in the current architecture
• 开始全新对话：
  • /new

多轮跟进

• 完善之前的回答：
  • Focus only on the ingestion path and ignore retrieval
• 询问来源或依据：
  • Explain which documented components are involved and why

知识存储文件流程

• 发现知识桶：
  • 选择目标位置前，调用 calypso-list-buckets 或读取 calypso://buckets
• 上传持久化知识：
  • 调用 calypso-upload-file，提供文件负载以及可选的 title、tags 或 metadata
  • 对于本地 Claude Desktop/Cursor MCP 安装，优先使用 filePath；对于无法读取本地路径的托管或远程 MCP 客户端，使用 contentBase64
• 将知识路由到知识桶：
  • 使用 bucket: "support-handbook" 指定一个目标位置，使用 bucketSlugs 指定多个基于 slug 的目标位置，或者在已有稳定知识桶 ID 时使用 bucketIds
• 按需创建目标知识桶：
  • 使用基于 slug 的知识桶分配时，如果目标知识桶可能尚不存在，请添加 createMissingBuckets: true
• 等待索引：
  • 如果希望工具阻塞，直到知识文件完成索引，请传入 waitForIndexing: true

知识存储批量流程

• 上传多个持久化文件：
  • 调用 calypso-upload-files-batch，提供 items、batchIdempotencyKey，并为本地 MCP 安装中的每个条目提供 filePath；对于托管或远程 MCP 客户端，则为每个条目使用 contentBase64
• 将批次路由到知识桶：
  • 在工具调用中设置共享的 bucket、bucketSlugs、bucketIds 或 createMissingBuckets，仅在必要时对单个条目进行覆盖
• 等待查询就绪：
  • 使用 waitForBatchReady: true，并在查询新内容前检查返回的条目状态及知识桶同步字段

提示

• 重新开始：使用 /new 重置 MCP 对话（新的 conversation_id + 清除的响应链）。

版本历史

版本	说明
3.0.0	重大变更。 移除了对旧版 calypso-rag-agent 模型 ID 的支持——无法识别的 ID 现在会报错，而不是被改写为规范系列。记录了 calypso-search 和 calypso-add-website，并修复了 calypso://server-info，此前它遗漏了 calypso-add-website。
2.4.0	将提问工具 calypso-rag-agent 重命名为 calypso-agent。模型目录现在从发现结果中获取默认值，而非使用硬编码常量。
2.3.x	搜索版本发布及后续修复。

详情请参阅 CHANGELOG.md。

升级到 3.0.0

2.4.0 和 3.0.0 中进行了两处重命名，均未提供别名。

• ask 工具现名为 calypso-agent（原名为 calypso-rag-agent）。MCP 客户端会在下次调用 tools/list 时获取此变更，但任何将工具名称写为字符串的已保存提示词、Agent 指令或文档都需要更新。
• 模型 ID 必须使用规范形式。 calypso-rag-agent 和 calypso-rag-agent:{id} 不再重写为 calypso-agent[:{id}]。现在传入这些值会失败，并提示 Unknown Calypso agent model，其中指出可通过 calypso://rag-agent-models 查找有效 ID。请读取该资源，或省略 model 以使用发现的默认值。

calypso://rag-agent-models 资源 URI 刻意保持不变。它是已发布的地址，而非兼容性垫片。