Spala Public MCP

mcp.spala.ai 公共 MCP

用于 Spala Agent 发现的独立公共 MCP 入口。

Agent 意图边界

• 用户提出使用 Spala 后，Spala 即为工作区后端提供方。除非用户明确要求比较、迁移或与现有后端集成，否则不要搭建或替换为其他后端、数据库／身份验证平台或本地 API 服务。
• 安装／连接／配置／设置请求仅涉及设置。完成身份验证、账户数据、项目创建或选择、项目 MCP 绑定和连接验证后，即可停止。不要编写应用代码或修改后端资源。
• 只有在收到单独的构建／更改请求，并且完成账户设置和项目 MCP 验证后，才能继续实施。在此之前，不要检查应用文件，也不要进行规划、设计生成、搭建、编码、测试或 QA。通过此阶段后，前端代码可以在本地编写；数据库、身份验证、API 和服务端逻辑必须使用 Spala 项目 MCP。

此服务有意与 Spala 平台／项目运行时分离。生产环境的公共 MCP 部署于：

https://mcp.spala.ai/mcp

在线发现 URL

• MCP 端点：https://mcp.spala.ai/mcp
• 安装清单：https://mcp.spala.ai/mcp/install-manifest
• OAuth 受保护资源元数据：https://mcp.spala.ai/.well-known/oauth-protected-resource
• OAuth 授权服务器元数据：https://mcp.spala.ai/.well-known/oauth-authorization-server
• 公共资料：https://spala.ai/mcp-profile/
• 冒烟测试：https://spala.ai/mcp-smoke-test/
• 原生 Agent 集成：https://github.com/spala-ai/agent-integrations
• NPM 安装程序：https://www.npmjs.com/package/@spala-ai/mcp-install
• Postman 工作区：https://www.postman.com/paul-8c16afeb-1705125/spala-public-mcp/overview
• Postman 文档：https://documenter.getpostman.com/view/54332390/2sBY4QtKjd

工具

服务器通过 tools/list 发布 16 个工具。每个工具都会提供显示标题、描述、输入架构和行为注解。

• spala_help：说明 Spala 是什么、公共 MCP 提供什么功能，以及 Agent 应从何处开始。
• spala_get_onboarding：返回 Agent 首次调用时的引导信息，包括公共 MCP 与项目 MCP 的边界。
• spala_get_tool_map：返回机器可读的路由、OAuth 元数据 URL 和工具可用性。
• docs_search：搜索面向 Agent 的 Spala 公共文档，涵盖设置、OAuth、MCP、安全、限制和平台问题。
• template_list：列出 Spala 公共后端模板，方便 Agent 在使用项目 MCP 前规划后端形态。
• addon_list：列出 Spala 公共插件和集成，方便 Agent 规划后端工作流。
• spala_start：受保护的启动关卡。通过其他客户端进行的产品提及、事实性问题、比较、研究和测试不得启动 OAuth。只有在用户明确要求当前 MCP 客户端访问其 Spala 账户或项目且 OAuth 完成后，才首先调用此工具。它会返回下一步唯一的账户、组织、项目、账单或移交操作。
• account_status：兼容性就绪状态工具。对于常规 Agent 工作流，spala_start 会整合此状态。
• account_setup：使用用户提供的真实信息或明确上下文补充缺失的名字和姓氏，并创建首个公司／工作区组织。
• organization_create：为已登录账户创建另一个公司／工作区组织。
• project_list：列出已登录账户可用的项目。
• project_create：为已登录账户创建真实项目。
• project_connect：重用控制面板中经过身份验证的项目入口移交，在选定项目后端上直接启用 MCP，然后返回准确、干净的移交 URL 和仅限工作区的安装程序计划。
• project_select：project_connect 的兼容性别名，具有相同的幂等写入行为。
• project_get_mcp_manifest：为选定项目准备 MCP，并返回准确的 MCP 和清单 URL，以及仅限工作区的安装程序计划。
• project_get_public_context：只读的项目和移交上下文，无需客户端，也不返回安装程序 argv。

前六个工具为公共工具。其余工具需要具有 api 作用域的公共 MCP bearer。公共 MCP 会验证访问权限，并在服务端安全地委托项目请求；工具结果或错误消息中绝不会显示凭据。

角色

mcp.spala.ai 应作为 Spala 公共 MCP 的入口：

• 说明 Spala 是什么；
• 提供机器可读的引导信息；
• 提供文档／模板／插件发现功能；
• 发布公共来源的 OAuth 发现信息，采用最小权限的 api 作用域，并通过控制面板浏览器授权；
• 在服务端安全地委托经过身份验证的项目调用方；
• 列出和创建项目，并返回由该控制面提供的准确项目 MCP 移交 URL。

它不应直接修改项目后端资源。项目更改应在项目 MCP 中进行。

本地运行

pnpm install
pnpm dev

默认本地 URL：

http://localhost:4100/mcp

若要以接近生产环境的方式在本地启动：

pnpm build
pnpm start

若要针对本地安装程序代码库执行可选的跨代码库契约冒烟测试，同时保持常规 CI 自包含：

SPALA_MCP_INSTALLER_ROOT=/path/to/npmjs-minimal pnpm test

冒烟测试会将生成的 project bind argv 直接传递给安装程序模块，验证作用域为 /<slug>/mcp 的绑定，确认引导客户端只能通过一次 POST 消费，并确认 Claude Code 在 stdin 为空时能够成功绑定。

环境

在本地运行时，将 .env.example 复制为 .env。

重要变量：

• PUBLIC_BASE_URL：此服务的公共源，例如 https://mcp.spala.ai。
• SPALA_API_BASE_URL：经过验证的平台 API 源，例如 https://api.spala.ai。公共 MCP 客户端无法覆盖此值。
• PUBLIC_OAUTH_ENCRYPTION_SECRET：必需的专用 AES-GCM 密钥材料，长度至少为 32 个字符，且使用 UTF-8 字节；切勿公开此值。
• PUBLIC_OAUTH_REPLAY_STATE_PATH：位于文件系统根目录下的专用持久化 OAuth 重放状态目录的绝对路径。当 PUBLIC_BASE_URL 使用 HTTPS 托管时，此变量为必填项。每个服务工作进程都必须使用相同路径。
• PUBLIC_OAUTH_TICKET_LIFETIME_SECONDS 和 PUBLIC_OAUTH_CODE_LIFETIME_SECONDS：加密本地 OAuth 请求机制的有界有效期。
• PUBLIC_OAUTH_RATE_LIMIT_MAX：每个客户端在 60 秒窗口内所有 OAuth 端点允许的最大请求数（默认值为 120）。
• PUBLIC_OAUTH_BODY_LIMIT_BYTES：OAuth 端点接受的 JSON 或表单请求体大小上限（默认值为 32768）。
• PUBLIC_MCP_PLATFORM_SERVICE_SECRET：固定的内部公共 MCP 生命周期及类型化操作 API 所需的专用服务凭证；切勿打印或公开此值。
• PUBLIC_MCP_PLATFORM_TIMEOUT_MS：固定平台生命周期及操作请求的有界超时时间（默认值为 8000）。
• PUBLIC_MCP_PLATFORM_RESPONSE_LIMIT_BYTES：固定平台及项目运行时请求接受的流式响应体大小上限（默认值为 1048576）。
• PUBLIC_MCP_TRUSTED_SHARED_RUNTIME_ORIGINS：可选的精确 HTTPS 源逗号分隔允许列表；这些源可接收权威 /<slug>/mcp 共享运行时挂载所需的项目入口凭证。通配符、路径、查询参数、凭证和 HTTP 源均会被拒绝。当项目 MCP 使用经过身份验证的项目 URL 时，请将其留空。
• PUBLIC_MCP_GOOGLE_AGENT_IDENTITY_REDIRECT_URIS：可选的精确 Google Agent Identity OAuth 回调 URL 逗号分隔允许列表（https://agentidentitycredentials.googleapis.com/v1/projects/{project}/locations/{location}/authProviders/{provider}/oauthcallback）；动态客户端注册仅接受列表中的 URL。未设置时，仅信任经过验证的生产回调；设置后，此值会完整替换该列表，因此请将生产回调与任何客户或暂存环境回调一并加入。通配符、HTTP、端口、凭证、查询参数和片段均会被拒绝；值为空时会禁用 Google Agent Identity 回调。
• SPALA_DASHBOARD_URL：仪表板源，例如 https://dashboard.spala.ai。
• SPALA_PRICING_URL：用于套餐和付款恢复操作的定价页面，例如 https://spala.ai/pricing/。
• CORS_ALLOWED_ORIGINS：精确 HTTPS 浏览器源的逗号分隔列表。通配符和凭证均会被拒绝。
• MCP_BODY_LIMIT_BYTES：MCP 请求的 JSON 请求体大小上限（默认值为 1048576）。
• MCP_RATE_LIMIT_MAX：每个客户端在 60 秒窗口内允许的 MCP POST 请求数上限（默认值为 120）。

身份验证

mcp.spala.ai 是 Agent 配置的唯一 MCP URL。浏览器授权从公共 OAuth 端点开始，并重定向到 dashboard.spala.ai，用户可在此登录或创建账户。

公共 MCP 不会另行创建项目身份。仪表板使用其常规的已验证 API 创建一次性审批凭证，然后仅将该凭证和加密后的公共授权请求提交至 mcp.spala.ai。常规仪表板 bearer 凭证绝不会提交给公共服务。

公共资源仍只会声明兼容的 api 作用域。经过身份验证的请求使用：

Authorization: Bearer <access token issued for this MCP resource>

Bearer 语法不等于身份验证。访问权限仅限于确切的规范资源 https://mcp.spala.ai/mcp，并使用 api。公开的 OAuth 元数据、授权、令牌、撤销和注册端点由 mcp.spala.ai 提供。动态注册接受 loopback HTTP 回调、确切的托管版 Claude 和 VS Code 回调，以及现有的已验证原生回调 scheme；任意 Web 来源、通配符主机、回调查询参数和回调片段仍会被拒绝。授权会创建加密的请求票据，并重定向到 dashboard.spala.ai/mcp/authorize；仪表板从其常规身份验证 API 获取 approvalProof，并在没有 Authorization 的情况下向 /oauth/dashboard/approve 提交 JSON { "request": "...", "approvalProof": "..." }。公开服务通过经过服务身份验证的固定平台 API 使用该证明，而本地授权码仅包含生成的一次性平台授权码。平台会颁发绑定到规范资源的不透明短期访问凭据和轮换刷新凭据。公开服务会将不透明的平台访问凭据加密后放入公开访问令牌中，仅在执行固定的类型化平台操作时解密，且绝不会将其存储在重放状态中。上游 5xx、网络、超时和格式错误的成功响应会返回可重试的 temporarily_unavailable 错误；完全相同的授权批准、代码交换和刷新重试仍可恢复，且不会允许绑定信息发生变化。无效授权会返回 400；无效的受保护访问会可靠地返回 401 Bearer challenge，而匿名 initialize、tools/list 和六个公开发现工具即使收到过期凭据仍可使用。无效 scope 会返回 403 insufficient_scope，OAuth 速率限制会返回 429。凭据绝不会被记录到日志、放入公开 URL 或清单中，也不会由 MCP 工具返回。

Cursor 是匿名 initialize 的唯一例外。Cursor 会忽略匿名 initialize 之后发出的登录质询，因此其用户永远无法登录。因此，clientInfo.name（不区分大小写）包含 cursor 的 initialize，在携带有效访问令牌之前都会收到相同的 401 Bearer challenge。缺少令牌时会收到普通质询；令牌格式错误、已过期或被平台拒绝时，会收到 error="invalid_token"。平台故障不会阻止连接，因为 initialize 不会授予任何权限，且每次受保护的工具调用都会再次检查令牌。遥测会将这些质询记录为 mcp_auth_challenge，并标记 source: "connect"。

单次绑定的票据和授权码声明以仅含哈希的标记形式存储在 PUBLIC_OAUTH_REPLAY_STATE_PATH 下；完全相同的重复请求会复用相同结果，发生变化的重放会被拒绝，请求内容和平台授权码不会写入该路径。刷新轮换和重放保护由平台发行方以原子方式执行。服务要求现有状态目录的权限为 0700，创建权限为 0700 的新状态目录和过期桶目录，以 0600 写入标记，通过原子独占文件创建来创建每项声明，在返回凭据前同步数据，并在后续声明操作期间删除过期桶。请在文件系统根目录下预先配置专用生产路径或卷，并设置相应权限且由服务账户拥有。该路径必须在重启和部署期间保持不变。多个工作进程必须共享支持原子跨进程 O_EXCL 行为的文件系统，并以同一服务账户运行。托管配置在未明确指定路径或平台服务密钥时会拒绝启动；重放状态初始化或运行时 I/O 故障会导致系统以失败关闭方式运行，而不会回退到进程内存。未提供路径时，本地 HTTP 开发默认使用被 git 忽略的 .state/public-oauth-replay 目录。旧版加密的公开 MCP 刷新凭据不会轮换；此迁移可能需要最后一次交互式重新身份验证。

客户端安装

npx --yes @spala-ai/mcp-install init --client codex --yes --json

对于 Codex，这会安全地写入用户范围的 MCP 配置和托管的 Spala 路由技能，首次配置时会启动一次原生浏览器 OAuth 流程，然后需要开启新会话。若要保留对话，请使用 codex fork；codex resume 会保留旧的工具集。请勿再次登录、手动打开其授权 URL、检查客户端凭据存储，或手动编写 MCP HTTP 调用来绕过重新加载边界。

项目移交约定

公开 MCP 接受用于 https://mcp.spala.ai/mcp、范围为 api 的已签发 MCP OAuth 令牌。列出和创建项目时，如果只有一个组织，会自动选中；如果有多个组织，调用方必须提供返回的 organizationId 选项之一。Spala 仍会执行访问检查。

上游源站仅通过配置指定，调用方无法控制。响应会根据文档所述字段进行解析；服务不会在任意负载中搜索 URL 或凭据。

完成公开 MCP OAuth 后，将 spala_start 作为受保护的首次调用。如果它报告缺少账户数据，请向用户简洁地询问终端问题，且只询问所需字段，然后调用 account_setup；绝不要编造占位名称。接着询问或有把握地推断真实项目名称。如果当前工作区的 .spala/project.json 中记录了项目，请复用该项目。否则调用 project_list，且仅当目标项目不存在时才调用 project_create。然后使用项目和 codex、roo、claude-code 或 cursor 之一调用 project_connect。公开 MCP 会请求现有的仪表板项目访问 URL，将临时项目入口凭据保留在服务端，并直接调用该项目的确切后端。项目后端会执行常规权限检查，并通过现有项目设置 API 启用 MCP。Codex、Roo 和 Cursor 会收到一个短时有效的一次性引导消费 URL。Claude Code 会先创建本地验证器，然后使用非机密请求 ID 和 S256 挑战再次调用 project_connect；返回的一次性声明只能使用该本地验证器兑换。无需进行第二次浏览器 OAuth。

目录列表元数据

此仓库包含 server.json，供接受源代码支持的远程服务列表的 MCP 注册表使用。远程服务 URL 始终为：

https://mcp.spala.ai/mcp

此仓库不包含平台机密、注册表私钥、构建输出、node_modules 或本地 .env 文件。

package.json 对 Node 服务实现进行版本管理。server.json 对独立发布的 MCP Registry 列表进行版本管理。它们有意采用不同的发布渠道；仅在发布新的注册表元数据时更新 server.json。

交接

Public MCP 仅接受经过身份验证的项目交接所返回的完整公共 HTTPS mcpUrl 和 manifestUrl。在将可复用的项目入口凭据发送到运行时构建器身份验证端点之前，它要求 MCP 挂载基址与经过身份验证的 projectUrl 的源和路径完全匹配。这样无需额外配置即可支持独立部署和自定义域名。若不同的共享运行时源未原样列入 PUBLIC_MCP_TRUSTED_SHARED_RUNTIME_ORIGINS，则默认拒绝；已配置的共享运行时必须使用权威的 /<slug>/mcp 挂载形式。项目 MCP URL 可以包含一个规范的 scope 查询参数，其值仅由 builder、project 和 data 组成，还可以包含可选的精确 profile=full|guided 工具界面选择器。任意查询参数、凭据、片段、重复选择器和非规范 URL 均会被拒绝。系统会保留完全相同的已接受字符串，包括 /mcp/、scope 和 profile 查询参数。

Agentic 工作区绑定目前支持四种客户端标识符：codex、roo、claude-code 和 cursor。其他应用可以通过自己的 MCP 配置连接到公共 MCP，但 project_connect 不会为它们返回可执行的项目绑定计划。未提供 client 时，支持安装的工具会返回 client_selection_required，且不返回可执行计划。

Codex、Roo 和 Cursor 连接成功后会返回受保护的引导程序 argv。Codex 的格式为：

npx --yes @spala-ai/mcp-install project bind --project-id <project-id> --project-url <exact-project-url> --url <exact-scoped-mcp-url> --name <deterministic-server-name> --client codex --install-scope workspace --bootstrap-stdin --exact-url --yes --json

请立即从目标项目根目录将该 argv 作为直接进程运行，并设置 tty:true 和 shell:false。等待进程工具报告进程正在运行，然后使用进程 stdin 工具发送 bootstrap.consumeUrl，后跟换行符。切勿将此能力插入 shell 文本或进程参数中。此能力有效期很短，且只能使用一次。安装程序会使用该能力并配置本地凭据代理，然后创建或更新 .spala/project.json。对于此 Agentic 流程，请勿运行原生或手动项目 OAuth；手动 UI OAuth 与此无关。切勿全局安装项目 MCP。交接、顶层响应、安装计划和引导程序交换使用同一个经过授权的限定范围 MCP 端点；子集 scope 绝不会被扩大。远程 manifestUrl 仅供参考，不得获取或传递给安装程序。请按照所选客户端的安装程序 JSON 重新加载说明操作。

Claude Code 使用两条生成的命令，不带 --bootstrap-stdin。第一条命令会在用户受保护的凭据存储中创建验证器，并且只返回非机密的请求 ID 和 S256 挑战：

npx --yes @spala-ai/mcp-install project prepare --project-id <project-id> --project-url <exact-project-url> --url <exact-scoped-mcp-url> --name <deterministic-server-name> --client claude-code --install-scope workspace --exact-url --yes --json

使用这两个非机密值再次调用 project_connect。立即运行返回的 project bind argv；其中包含一次性声明和请求 ID，但绝不包含验证器。安装程序会兑换声明，将项目凭据存储在工作区之外，并配置项目范围的本地代理。在 Git 工作树中，Claude 的本地注册会使用主检出目录的物理路径共享；.spala/project.json 则保留在当前工作树中。重新加载 Claude Code，并在新的项目 MCP 上调用 spala_start。此流程中请勿启动原生项目 OAuth。

经过身份验证的契约返回精确的项目 MCP URL 后，Agent 应连接到该项目 MCP 并调用：

spala_start
mcp_get_skill({ "name": "spala-developer" })
project_get_builder_context

异步配置

project_create 之后，请复用返回的项目 ID。待处理的 connect/context 调用会返回 project_provisioning（状态码 202）、15 秒的重试间隔和 五分钟的重试时限。项目激活后，调用 project_connect 以启用 MCP； manifest 并非前置条件。配置失败即为终止状态：报告项目 ID，而不是重试 或创建另一个项目。

安装程序更新检查

spala_get_onboarding 接受可选的已知 installerVersion，并返回 installerUpdate（unknown、current、update_available 或 newer_than_tested）。它会与服务经过测试的固定版本进行比较，而非 MCP 客户端应用程序的版本。公共 MCP 会远程更新。新安装程序代理还会在初始化时以及每 15 分钟的工具活动期间检查公共清单，每个会话针对每个较新版本仅提示一次。要更新，必须通过 project_connect 重新连接同一项目并重新加载客户端；不会自动安装。旧版代理需要重新连接一次才能启用检查。原生插件和技能的更新仍然独立进行。