快速开始

本教程使用 MCP starter。添加工具不需要服务器工厂、注册数组、自定义传输层或第二份构建配置。这个示例也不需要智能体账号。

先安装 Node.js 22.19 或更高版本，并选择一个 Package preview 工作流已经成功的提交。下面使用该提交不可变的预览 SHA，而不是仅凭 agent-bundle 这个未限定名称选择 npm 包。

用脚手架创建项目

把 <preview-sha> 替换为该提交的 SHA：

AB_SHA='<preview-sha>'
npx "https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@${AB_SHA}" \
  my-plugin --template mcp-server --targets portable,claude,codex
cd my-plugin
npm install
npm run check

同时指定目录与模板会使用脚本化路径。预览脚手架从同一提交选择 compiler/runtime 配对。提交生成的锁文件；后续干净检出可以使用 npm ci。安装指南说明预览选择，以及正式发布的脚手架如何配对版本号独立的 compiler/runtime。

模板

模板	用途
`minimal`	静态 Skills，不需要 MCP 服务器或 React runtime。
`mcp-server`	约定式 MCP 工具及路由、投影测试；当前 starter 还演示了可选的库导出与产物脚本。
`cli-tool`	独立的路由式 CLI，附带脚本和库示例。

路由式模板会有意固定一组已验证的 React 与 React DOM 版本，使生成项目保持可复现，并避免全新安装选中不兼容的 peer 组合。

脚手架提供编译器构建的每一个 target：amp、portable、claude、codex 和 cursor。只有一种组合被拒绝，amp 与这个 MCP starter，因为 Amp 的 Skill 级 MCP 契约会拒绝 starter 中由编译器拥有的本地 status 服务器（amp.mcp.generated-local）。创建项目时就会说明这一点，并列出 Amp 可用的模板，因此拒绝发生在项目生成之前，而不是首次构建时。要做 Amp 插件，请脚手架 minimal 或 cli-tool 模板，或在恰好一个 Skill 旁声明远程服务器或可全局解析的命令服务器。添加原生 target 也不代表实时开发代理支持该宿主。见宿主安装。

添加第一个工具

Starter 已包含一个 status 服务器及其 report-status 工具。在旁边新增 src/mcp/status/tools/hello.tsx：

import { Agent } from '@agent-bundle/runtime';
import { defineTool } from 'agent-bundle/routes';
import { z } from 'zod';

export default defineTool({
  description: 'Return a greeting without changing anything.',
  annotations: { readOnlyHint: true },
  inputSchema: z.object({ name: z.string().min(1) }).strict(),
  resultSchema: z.object({ message: z.string() }).strict(),
}, async (input) => {
  const result = { message: `Hello, ${input.name}.` };
  return (
    <Agent.Result value={result}>
      <Agent.Text>{result.message}</Agent.Text>
    </Agent.Result>
  );
});

路径声明了 status 服务器上的 hello 工具；它的框架路由 ID 是 tool:status/hello。 value 是结构化结果，子节点描述面向智能体的呈现方式。结果应保持 JSON 兼容，并用 resultSchema 描述它的真实形状。

不要再把这个工具加入 agent-bundle.config.ts，也不要调用 registerTool。添加路由文件就是注册。领域实现可以放在路由目录以外并正常导入，不需要另一份操作注册表。

构建，或交互式开发

npm run dev -- --open

在 Workbench 的 Application 树中选择 status 下的 hello 工具，输入参数并调用：

{ "name": "Ada" }

渲染文档应显示 Hello, Ada.，结构化结果应包含 {"message":"Hello, Ada."}。 Trace 展示调用，Problems 展示构建诊断，Advanced 提供底层检视。普通路由调用并不能证明外部宿主已经安装或调用了插件。

修改问候语，等待本次重建完成后再调用。无效修改会保留上一个可用构建并显示诊断；之前的输出不是新源码已成功编译的证据。Workbench 不需要为了刷新视图而自动重复执行修改性操作。

不启动开发服务器、只构建一次时运行：

npm run build

测试路由

新增 tests/route-unit/hello.test.ts：

import { expect, it } from '@rstest/core';
import { renderRoute } from 'agent-bundle/test';

it('returns the greeting as structured data', async () => {
  const rendered = await renderRoute('tool:status/hello', {
    input: { name: 'Ada' },
  });
  expect(rendered.result).toEqual({ message: 'Hello, Ada.' });
});

运行普通的测试命令：

npm test

在 MCP starter 中，npm test 会运行项目附带的每个测试池，普通模块测试、route-unit 池与内存 MCP 投影池，每个池作为独立的带标签运行，因此路由停止渲染时即使领域测试仍然通过，它也会失败。 npm run check 在其前面加上构建与类型检查，构成完整的 starter 门禁；聚焦路由时使用 npm run test:routes。真实 MCP 进程和浏览器 App 等进一步的证明级别见测试。

消费路由、provider 或 App 类型的 TypeScript 项目必须包含生成的 .agent-bundle/routes.d.ts。它是生成文件，不是手写注册表。在干净目录中单独检查类型，或添加、重命名路由后，先刷新它：

npm run validate
npm run typecheck

旧声明文件存在，不等于它是最新的。Starter 的完整 check 已把生成放在类型检查之前。

把工具复用为 CLI 命令

新增 src/mcp/status/tools/hello.cli.ts：

import type { CliProjectionConfig } from 'agent-bundle/routes';

export const config = {
  command: ['hello'],
} satisfies CliProjectionConfig;

它是同目录工具的投影，不是另一条工具路由或处理器。重新构建，再运行产物中生成的可执行文件：

npm run build
node artifact/bin/my-plugin.mjs hello --name Ada

使用的仍然是同一份 inputSchema、路由实现和结果，不需要再创建 src/cli/hello.ts。 src/cli/ 留给真正独立的 CLI 工作流。

自动 flag 推导只支持有界的 schema 语法。复杂嵌套或 union schema 不保证能使用这种命名投影；不要为了生成 flag 而复制或削弱工具 schema。包入口说明了支持的语法和已有的批量 MCP 命令 JSON 输入路径。

或者手写配置

在已有包中安装匹配的框架/runtime 配对，以及代码使用的渲染和 schema 依赖。约定式路由不需要 mcp.servers 条目：

import { const defineConfig: (config: AgentBundleConfig | ConfigFactory) => AgentBundleConfig | ConfigFactorydefineConfig } from 'agent-bundle/config';

export default function defineConfig(config: AgentBundleConfig | ConfigFactory): AgentBundleConfig | ConfigFactorydefineConfig({
  AgentBundleConfig.plugin: AgentBundlePluginConfigplugin: { AgentBundlePluginConfig.name: stringname: 'my-plugin', AgentBundlePluginConfig.description?: string | undefineddescription: 'Project tools for an agent.' },
  AgentBundleConfig.targets?: string[] | undefinedtargets: ['portable', 'claude', 'codex'],
});

版本保留在 package.json 中。省略 targets 时只选择 portable。自定义本地服务器、预构建服务器和远程服务器仍可通过显式模式使用；不要在同一个名称下混合手写服务器和生成式路由，并依赖静默优先级。

查看编译器的判断

在已经安装了正确编译器的项目中运行：

npx --no-install agent-bundle inspect --routes
npx --no-install agent-bundle validate
npx --no-install agent-bundle validate --artifact artifact

前两个命令读取源码项目，最后一个无需源码即可检查构建后的组合产物。用路由 ID 关联源码、Workbench 与测试输出。

安装结果

读取生成的 artifact/INSTALL.md，其中包含所选宿主的安装命令和插件真实名称。在当前开发项目中，已安装的编译器也能执行显式安装：

npx --no-install agent-bundle install claude --from artifact --scope user

这是对宿主状态的修改，不是 build 或 dev 的一部分。请明确选择宿主与作用域。 Amp 的原生插件位于嵌套目录中；框架安装器从组合根解析该目录。遵循生成的说明，不要假定所有宿主的原生安装根都相同。

npm 分发应使用生成的 npm 根目录和 prepack 门禁。消费者可以遵循交付的 INSTALL.md，或使用插件显式提供的包绑定安装器，不应为了安装插件而下载一个无关的同名 npm 包。

下一步

项目结构展示工具、CLI 投影、钩子、provider、状态、Skills 和浏览器 App 如何组合。MCP App 示例展示真实工具结果上的交互视图；钩子解释何时使用普通处理器，何时使用语义事件路由。

#快速开始

#用脚手架创建项目

#模板

#添加第一个工具

#构建，或交互式开发

#测试路由

#把工具复用为 CLI 命令

#或者手写配置

#查看编译器的判断

#安装结果

#下一步