Supermemory MCP Server 深度解析OAuth 认证、空间解析与 MCP Apps 的云端实现【免费下载链接】supermemoryMemory and context engine app that is extremely fast, scalable, and can be run fully locally. The Memory API for the AI era.项目地址: https://gitcode.com/GitHub_Trending/su/supermemorySupermemory 的 MCP Server 是部署在 Cloudflare Workers 上的一个无状态 HTTP 服务部署地址https://mcp.supermemory.ai/mcp为经过认证的 AI 客户端提供记忆检索、文档管理、空间切换与交互式 MCP Apps 能力。本文以 apps/mcp/README.md 为核心骨架结合仓库源码apps/mcp/src/server/下的 Hono 入口、Durable Object、工具注册与认证实现系统讲解其运行时模型、OAuth 认证流程、空间解析优先级、全部工具与资源清单以及本地开发与部署配置。读完本文你将掌握如何在 Claude、ChatGPT 等 MCP 客户端中接入该服务理解其每请求新建 McpServer、无协议级会话的设计原理并能基于仓库命令独立构建、测试与本地调试这套 MCP 服务。运行时模型无状态、每请求一个 McpServerSupermemory MCP Server 的架构核心可以用一句话概括没有持久的 MCP 协议会话。根据 apps/mcp/README.md 的 Runtime Model 一节其设计要点如下MCP SDK v2每个 HTTP 请求都会创建一个全新的McpServer实例协议版本采用现代2026-07-28同时为 2025 年客户端提供无状态兼容README 中表述为 stateless compatibility for 2025 clients每次请求都做 OAuth token 校验不维护 MCP 协议会话也不存在协议层的 Durable Object当前活动空间active space以应用状态形式存放在一个专用的 Durable Object 中空间状态以认证后的organizationId userId组合为键。这一设计与每个请求新建 Server 实例的代码路径相互印证在 入口文件 中handleMcpRequest先解析 Bearer token、完成认证然后通过createMcpHandler(() createSupermemoryServer(...))为当前请求即时构建 Serverserver.ts 中的createSupermemoryServer每次都会new McpServer(...)并注册全部工具、资源与 prompt。无状态化带来两个直接收益横向扩展无需共享协议状态协议层故障不会污染后续请求。而活动空间这类必须跨请求保持的应用状态则被刻意下放到 Durable Object见下文空间解析一节实现协议无状态、业务状态持久的分层。空间解析优先级一次操作最终使用的空间space按以下顺序解析工具或 prompt 参数中显式传入的containerTag账号持久化的活动空间durable active spaceSupermemory 客户端默认值sm_project_default。并且关键约束是显式覆盖只对本次调用生效不会修改活动空间。也就是说调用时传了containerTag就优先用它但该选择不会写回 Durable Object只有专门调用set-active-tagApp-only 工具才会持久化活动空间。从源码可以进一步看到这条解析链的实现space.ts 中resolveContainerTag(explicit, getActiveContainerTag)的逻辑就是explicit ?? (await getActiveContainerTag())——显式参数优先否则读 Durable Object 中保存的活动标签而在 server.ts 中最终兜底值是DEFAULT_PROJECT_ID即sm_project_default定义见 client/index.ts。服务器地址与客户端接入生产环境的 MCP 端点固定为https://mcp.supermemory.ai/mcp一个标准的客户端配置示例如下{ mcpServers: { supermemory: { url: https://mcp.supermemory.ai/mcp } } }客户端通过/.well-known/oauth-protected-resource/mcp发现 OAuth 授权服务器信息。从源码看入口文件 同时暴露了多个 Well-Known 端点/.well-known/oauth-protected-resource与/.well-known/oauth-protected-resource/mcp返回受保护资源的元数据包括resource即MCP_RESOURCE、authorization_servers默认指向https://api.supermemory.ai/api/auth、scopes_supportedopenid、profile、email、offline_access与bearer_methods_supportedheader/.well-known/oauth-authorization-server从API_URL对应的上游代理授权服务器元数据/.well-known/openai-apps-challenge用于 OpenAI Apps 域验证返回OPENAI_APPS_CHALLENGE环境变量内容。浏览器端跨域访问由 Hono 的 CORS 中间件处理见 index.ts允许GET/POST/DELETE/OPTIONS并暴露WWW-Authenticate与Retry-After响应头同时通过allowedOriginHostnames维护一份内置的浏览器来源白名单详见配置项一节。认证机制OAuth token 与 API Key 双通道README 强调每次请求都做 OAuth token 验证而 auth/index.ts 中的实现实际上支持两条认证路径OAuth Bearer token通过validateOAuthToken使用jose库基于远程 JWKScreateRemoteJWKSet按 URL 缓存完成 JWT 签名校验并核对受众audience是否为MCP_RESOURCESupermemory API Key形如sm_开头通过isApiKey正则/^sm_\S{17,}$/识别再调用/v3/session换取会话信息完成认证每次校验结果在 isolate 内缓存 60 秒避免繁忙会话在每条 JSON-RPC 消息上重复请求。值得注意的错误处理细节代码中专门区分了token 无效与上游暂时不可用两类失败TransientAuthError涵盖 AbortError、JWKS 超时与 JOSE 通用错误等因为把暂时性故障误报为invalid_token会导致客户端丢弃本可正常工作的凭据。对应地入口文件 会返回两类 401未携带 token 时返回带resource_metadata的WWW-Authenticate头以引导 OAuth 发现token 无效时返回 JSON-RPC 格式的-32000错误而瞬时故障则返回 503 并附带Retry-After: 5错误码为-32001。认证通过后AuthUseruserId、organizationId、bearerToken、oauthClientId、scopes等会包装为ActorContext传入 Server并在authInfoFor中附带 OAuth 客户端信息供 MCP SDK 的授权上下文使用。工具清单三层工具体系README 将工具划分为三类源码注册顺序见 tools/index.ts模型可见工具Model-visible tools工具用途search_memory搜索记忆可选择性附带 profile 上下文listDocuments列出空间内文档元数据与摘要getDocument按 ID 读取单个文档的可用内容listMemories列出提取出的记忆条目及其来源文档 IDlistSpaces列出当前认证账号可见的空间whoAmI返回身份、访问权限与活动空间上下文add_memory保存或遗忘一条记忆以search_memory为例search-memory.ts其输入参数为query必填最大 1000 字符自然语言检索词includeProfile可选默认true是否同时拉取该空间的 profile 摘要containerTag可选空间键省略时使用活动空间或账号默认空间。其输出同时包含两段内容一段人类可读的文本依次是## Profile静态档案、## Recent context动态上下文、## Matching memories匹配记忆每条记忆标注相似度百分比以及一份结构化内容query、containerTag、profile、results、total、timing方便客户端程序化消费。该工具带有只读注解READ_ONLY_TOOL_ANNOTATIONS便于模型判断其副作用。whoAmIwho-am-i.ts则并行调用会话接口与活动空间读取返回userId、email、name、role、accessType、activeSpace、assignedSpaces仅受限访问账号返回与scope等上下文。MCP App 启动器MCP App launchers工具用途select-space打开交互式空间选择器memory-graph打开交互式记忆图谱guided-save打开引导式记忆表单upload-file打开文件上传表单这类工具不会直接返回数据而是唤起一个内嵌在客户端中的 Web 应用界面MCP App由用户在界面中完成操作。它们在模型侧作为打开界面的入口存在。App-only 工具对模型隐藏工具用途set-active-tag持久化所选活动空间save-memory提交引导式保存表单prepare-file-upload准备安全的直传文件上传会话fetch-graph-data为 App 拉取图谱文档数据这些工具仅对内嵌的 MCP App 开放、对模型隐藏是界面与后端之间的桥接层。例如set-active-tag负责把用户在空间选择器中做出的选择写回 Durable Object即活动空间持久化prepare-file-upload会生成一个带过期时间的直传会话TTL 为 2 分钟见 server.ts随后浏览器直接向/upload/:uploadId提交 multipart 表单由 Worker 代理到上游/v3/documents/file接口见 index.ts。资源与 PromptREADME 列出的资源与 prompt 如下种类名称或 URI用途Resourcesupermemory://profile生效空间中的档案事实Resourcesupermemory://spaces可见的空间列表Resourceui://supermemory/app-sha256.html内嵌的 MCP App 包Promptcontext可选空间的档案与近期上下文其中 App 资源与工具元数据在 MCP Apps 完成 SDK v2 迁移前同时携带当前的嵌套ui元数据和旧的扁平资源 URI 键Worker 运行时不再引入 SDK v1 的 Apps 服务端辅助函数。从注册代码看server.tsprofile与spaces资源由registerProfileResource、registerContainerTagsResource注册contextprompt 由registerContextPrompt注册App 包则由registerWidgetResource基于mcpOrigin提供。此外server.ts 为整个服务设置了一段系统指令SERVER_INSTRUCTIONS当用户想要回忆已保存内容、检查存储来源或提取的记忆、记住或上传新信息、查看账号与权限、切换活动空间或探索记忆图谱时模型应主动使用这些工具即使用户没有明确提到 Supermemory 的名字同时约定仅在用户明确要求时才更改活动空间。空间状态存储只存标签不存凭据SpaceStatespace-state.ts是一个 Cloudflare Durable Object其职责被刻意收窄getActiveContainerTag/setActiveContainerTag读写活动空间标签写入前会用containerTagSchema校验标签长度 1128 字符见 container-tag.tscreateUploadSession/consumeUploadSession创建并单次消费文件上传会话token 以 SHA-256 哈希存储而非明文配合setAlarm到期自动清理。README 明确承诺SpaceState只保存活动空间的容器标签绝不存储 bearer token、MCP 客户端身份或协议消息。结合 space.ts 的命名规则space:${JSON.stringify([organizationId, userId])}可以确认每个账号的空间状态相互隔离键由认证身份派生符合按organizationId userId键控的设计描述。本地开发与测试README 给出的开发流程从仓库根目录开始bun install启动本地 Worker需要进入apps/mcp目录cd apps/mcp bun run dev本地开发 URL 为http://mcp.dev.supermemory由 package.json 中的 portless 配置映射实际经由wrangler dev --port ${PORT:-8788}启动。常用命令bun run build # 构建 MCP App 内嵌 widget bun run check-types # widget 构建 双 tsconfig 类型检查 bun run test:unit # 单元测试vitestsrc 目录 bun run test:e2e # 端到端测试viteste2e 目录其中build实际执行build:widget运行scripts/build-widget.ts将 React 界面打包为内嵌 HTMLcheck-types会同时用tsconfig.json与tsconfig.widget.json两个工程做类型检查。端到端测试需要真实 OAuth 凭据先运行bun e2e/capture-oauth-token.ts捕获并保存 OAuth token对应 e2e/capture-oauth-token.ts。若本地未存储 OAuth 凭据需要认证的测试组会自动跳过但公开的 OAuth 发现与拒绝类测试仍会照常执行——这保证了 CI 在没有真实账号时也能覆盖核心认证链路。配置项与环境变量README 中的配置表及说明如下变量用途默认值API_URLSupermemory API 与 OAuth 签发方https://api.supermemory.aiMCP_RESOURCE期望的 OAuth audiencehttps://mcp.supermemory.ai/mcpALLOWED_MCP_ORIGIN_HOSTNAMES额外补充的浏览器来源逗号分隔内置主机白名单POSTHOG_API_KEY服务端 MCP 工具分析的项目密钥禁用POSTHOG_HOSTPostHog 采集主机https://us.i.posthog.com结合 入口文件 的源码内置的浏览器来源白名单包括app.supermemory.ai、mcp.supermemory.ai、mcp.dev.supermemory.ai、mcp.dev.supermemory、claude.ai、chatgpt.com、chat.openai.com、gemini.google.com、grok.com、x.ai、t3.chat、localhost、127.0.0.1、[::1]。通过ALLOWED_MCP_ORIGIN_HOSTNAMES追加的值会与内置白名单去重合并allowedOriginHostnames函数见 index.ts。运行时还引用MCP_PUBLIC_ORIGIN上传 URL 的公开来源与OPENAI_APPS_CHALLENGEOpenAI Apps 域验证两个附加变量。POSTHOG_API_KEY未设置时分析功能默认禁用启用后通过 analytics.ts 的createTrackedToolServer对每次工具调用做服务端埋点并携带客户端名称与版本信息。存储与灰度策略非破坏性迁移关于旧实现的兼容README 说明旧的SupermemoryMCP类与其绑定在一个发布周期内保持惰性inert从而让迁移非破坏、可回滚待生产流量与回滚窗口确认安全后后续部署再删除旧协议类。在源码中可以看到这一痕迹index.ts 仍从./legacy-protocol-state导入SupermemoryMCP并在文件末尾导出index.ts同时legacy-protocol-state.ts文件保留在仓库中但当前请求处理链路已经完全走createSupermemoryServercreateMcpHandler的新路径。这正是惰性保留、择机清理灰度策略的代码级体现。总结Supermemory MCP Server 的设计可以归纳为三层协议层采用 MCP SDK v2 的无状态模型每个 HTTP 请求重建 Server认证层在每次请求入口校验 OAuth JWT 或 API Key并对瞬时故障与无效 token 做精细区分状态层仅用 Durable Object 保存活动空间标签与一次性上传会话不落任何敏感凭据。空间解析遵循显式参数 持久化活动空间 账号默认空间的优先级且显式覆盖不写回状态。配套的 MCP Apps 体系空间选择器、记忆图谱、引导式保存、文件上传通过 App-only 工具与模型可见工具解耦把交互交给界面、把数据读写留给模型。若要在本地复现这套服务按 README 的bun installbun run dev即可在http://mcp.dev.supermemory上调试测试与类型检查命令也已完备。对于希望深入源码的读者建议从 入口文件认证与路由、server.tsServer 组装、space-state.ts状态存储与 tools/index.ts工具注册四个文件入手。【免费下载链接】supermemoryMemory and context engine app that is extremely fast, scalable, and can be run fully locally. The Memory API for the AI era.项目地址: https://gitcode.com/GitHub_Trending/su/supermemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考