@ decocms/ 运行时间

提供在 Studio 后方使用已键入的 MCP 应用程序构建框架 工具、绑定、认证、OAuth、资源、提示和触发.

概览

@decocms/runtime mCP 服务器连接到 录音室 它将申报工具、提示、资源、代理和约束转化为 获取兼容的处理器 。 运行时间还提供请求扫描工作室 上下文,用于身份、连接元数据、证书、, 并呼叫绑定MCP.

该包通过明确的包子路径暴露出源类型Script. 消费者 只能导入拥有所需能力的子路径.

责任

• 以 Zod 输入和输出计划创建 MCP 工具 .
• 将工具、提示、资源和事件处理器挂载在一个兼容的MCP上 服务器.
• 解析 Studio 请求的上下文和每个请求的绑定连接 .
• 强制获得经认证的受保护工具、提示和资源.
• 当 OAuth 配置存在时服务 OAuth 元数据和 OAuth 路由 .
• 通过金库客户端曝光范围访问 Studio 管理的证书.
• 创建触发管理工具并发送触发回调到 Studio.
• 为连接代理、 MCP 客户端根、 资产和decopilot 提供助手 应用.

使用量

在 MCP 应用程序中安装软件包 :

bun add @decocms/runtime

定义工具并导出运行时间处理器 :

import {
  withRuntime,
} from "@decocms/runtime";
import {
  createTool,
  ensureAuthenticated,
} from "@decocms/runtime/tools";
import { z } from "zod";

const greet = createTool({
  id: "GREET",
  description: "Greet the signed-in user",
  inputSchema: z.object({
    name: z.string(),
  }),
  outputSchema: z.object({
    message: z.string(),
  }),
  execute: async ({ context, runtimeContext }) => {
    const user = ensureAuthenticated(runtimeContext);

    return {
      message: `Hello, ${context.name}. Signed in as ${user.email}.`,
    };
  },
});

export default withRuntime({
  tools: [greet],
});

withRuntime() 返回带有 fetch() 处理者。 它为MCP服务 结束点 /mcp,代表任何与任择申请不符的请求 fetch 处理器,并应用配置的 CORS 和 OAuth 行为.

提示和资源使用相同的请求上下文:

import { createPrompt, createResource } from "@decocms/runtime";
import { z } from "zod";

const reviewPrompt = createPrompt({
  name: "review",
  description: "Review a change",
  argsSchema: {
    path: z.string().optional(),
  },
  execute: ({ args }) => ({
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `Review ${args.path ?? "the current change"}.`,
        },
      },
    ],
  }),
});

const statusResource = createResource({
  uri: "studio://status",
  name: "Status",
  mimeType: "application/json",
  read: () => ({
    uri: "studio://status",
    mimeType: "application/json",
    text: JSON.stringify({ ready: true }),
  }),
});

createPrompt() 财务报告和审定财务报表 createResource() 默认时保护他们的处理者。 使用 明确 createPublicPrompt() 或者说 createPublicResource() 仅当 内容在没有工作室身份的情况下可以安全曝光.

建筑

withRuntime() 是构成根。 对于收到的每项请求,它:

1. 将Cononic Studio环境域规范化,并支持遗留别名.
2. 创建包含身份和约束状态的请求范围上下文.
3. 初始化已配置绑定 .
4. 将 MCP 请求发送到由工具、 提示、 资源创建的服务器, 特工和事件处理员.
5. 应用 OAuth 和 CORS 围绕结果的行为.
6. 回到自己的应用程序 fetch() 非运行时间路线的操作者.

请求上下文以同步请求范围化存储. 接收工具代码 作为第二个背景 execute() 参数; 不应读取环境 HTTP 对象或从全进程状态重建 Studio 身份.

绑定描述连接执行的MCP能力. withBindings() 解决对请求的约束,同时 BindingOf, (中文(简体) ), AgentOf,以及 proxyConnectionForId() 向需要的消费者提供类型的准入模式 给他们打电话.

发展

从寄存器根运行包检查 :

bun run --cwd=packages/runtime check
bun run --cwd=packages/runtime test

延长时运行焦点测试文件 :

bun test packages/runtime/src/tools.test.ts

执行前的格式和插入寄存器更改 :

bun run fmt
bun run lint

边界

• 这个软件包是一个MCP应用框架,而不是工作室控制平面. 这个 不得导入服务器执行细节 apps/api 或用户界面细节 apps/web。 。 。 .
• 将请求范围运行时间上下文作为身份授权, Studio 元数据 和捆绑服务 不要在请求间缓存 .
• 一种工具之所以得不到保护,只是因为它在MCP端点后行走。 打电话 ensureAuthenticated() 在需要用户的工具中.
• 提示和资源默认得到认证。 公共变体必须曝光 只有非敏感数据.
• 信誉访问是选入和范围限制的. 永远不要要求更多的证书 并且从未坚持返回的秘密.
• 已发布的包需要节点.js 24或更新. 个人助手使用网络 获取 API; 文件备份触发存储等针对环境的帮助 资产服务器还需要其记录主机能力.
• 遗产 MESH_* 环境领域和环境领域 meshUrl 仍然是相容性别名. 新代码必须使用 STUDIO_* 名称和名称 studioUrl。 。 。 .

导出表面

这是唯一得到支持的软件包切入点。 在下面不导入文件 @decocms/runtime/src。 。 。 .

认证和证书访问

ensureAuthenticated(runtimeContext) 返回工作室用户或当 请求未经认证。 它是受保护工具的正常护卫.

需要工作室管理的证书的应用程序声明明确 绑定范围权限并创建从靴子拖曳到的客户端 configuration.onInstall 或者说 configuration.onChange数字 :

import {
  CREDENTIAL_ACCESS_TOKEN_READ_SCOPE,
  createStudioVaultClient,
  type ConfigurationScope,
} from "@decocms/runtime";
import type { StudioVaultBootstrap } from "@decocms/runtime/tools";

const scopes = [
  `github::${CREDENTIAL_ACCESS_TOKEN_READ_SCOPE}`,
] satisfies ConfigurationScope[];

function vaultClient(bootstrap: StudioVaultBootstrap) {
  return createStudioVaultClient({
    baseUrl: bootstrap.baseUrl,
    org: bootstrap.org,
    token: bootstrap.token,
  });
}

使用 CREDENTIAL_ACCESS_TOKEN_READ_SCOPE 供供应商访问符和 CREDENTIAL_CONFIGURATION_READ_SCOPE 用于非证书配置. 刷新令牌和OAuth客户端的秘密留在工作室金库里,而不是 申请提交合同的一部分.

触发和持久性

createTriggers() 创建 TRIGGER_LIST 财务报告和审定财务报表 TRIGGER_CONFIGURE 输入工具 触发定义。 内容 notify() 方法是指故意起火并遗忘: 发送失败会被记录下来,不会被扔回网络处理器.

触发配置为进程本地化, 除非应用程序提供一个 TriggerStorage启用 StudioKV 当工作室 KV 可用时, JsonFileStorage 仅用于适当的本地节点/分机部署,或提供适配器,由 应用程序的持久存储.

配置、约束和事件

configuration.state 接受持续 MCP 配置的 Zod 方案. BindingOf() 选项 已输入客户端 STUDIO_REQUEST_CONTEXT.state。在 configuration.scopes; 工作室在配置时评价这些范围 连接.

configuration.onChange 运行配置更新并接收解析 州,授予范围, 和可选的金库靴子. configuration.onInstall 运行第一个保存的配置并接收代理提供 帮手 因为网络或部署失败 中断这些回调的工作.

events.handlers 通过绑定密钥宣告 CloudEvent 处理器或 SELF。 。 。 . 运行时间显示相应的 ON_EVENTS 并同时支持两个批次 结果和每个事件的结果。 本订户合同不提供 发布者或发送队列。 呼叫者自有交付和重试;操作者必须 处理重复的事件.

何时 oauth 配置,运行时间服务保护资源元数据, 授权服务器元数据、授权、召回、符号和动态客户端 登记路线。 应用程序提供供应商特定授权 和交换证物的行为.

可选 cors 属性控制运行时间 CORS 处理; 设置为 false 改为 禁用内置层。 可选申请 fetch() 处理器接收 不匹配运行时间、 OAuth 或工具调用路径的请求.

相关文件

• 绑定指南
• 仓库准则
• 测试战略