MCP TypeScript SDK 便签板实战用 Tools、Resources 与 Elicitation 搭建真实应用结课示例【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk本文基于 MCP TypeScript SDK 仓库中的examples/stickynotes示例完整拆解一个真实应用real app capstone的构建过程一个可增删查清的便签sticky-notes面板其中工具tools负责变更状态、每条便签都是一个资源resource、添加/删除时资源列表通过listChanged动态变化而破坏性的remove_all工具会被form 模式的服务端→客户端 elicitation拦截只有用户明确确认才会清空面板。读完本文你将掌握如何把 tools、resources、listChanged 通知、elicitation 四个 MCP 能力组合成一个有真实业务形态的端到端示例并理解它为何要在四种 transport/era 组合下分别验证。示例概览一个真正有状态的 MCP 应用examples/stickynotes是整个examples/目录中少有的结课型capstone示例——它不再孤立演示某一个 API而是把 SDK 的几大能力编织进一个自洽的小应用里。对应的示例清单将其定位为tools mutate state, a resource per note, listChanged, elicitation-confirmed clear。这个应用的核心行为是工具变更状态add_note(text)在进程内存储一条便签remove_note(id)删除一条remove_all()清空全部。每条便签是一个资源每添加一条便签就注册一个note:///{id}资源删除时同步注销。资源列表动态变化注册/注销资源时向客户端推送listChanged通知。破坏性操作需要确认remove_all()首先通过 form 模式的 elicitation 向用户弹出一个确认框cancel / 不勾选 / 确认三种结果分别对应三种处理路径只有明确确认才真正清空面板。示例以server.tsclient.ts一对文件的形式提供server.ts是你要部署的服务端client.ts则是宿主host视角的客户端——它连接、用公开客户端 API 驱动功能、用断言自验证结果、退出码 0 表示通过。运行方式同一份二进制跑通四种 transport/era 组合与仓库内其他示例一致stickynotes 使用examples/shared提供的parseExampleArgs()实现在 examples/shared/src/args.ts解析命令行参数因此一条命令即可在不同模式下运行。从仓库根目录执行# stdio默认客户端自行 spawn 服务端进程 pnpm --filter mcp-examples/stickynotes client # Streamable HTTP两个终端 pnpm --filter mcp-examples/stickynotes server -- --http --port 3000 pnpm --filter mcp-examples/stickynotes client -- --http http://127.0.0.1:3000/mcp # 追加 --legacy 切换到 2025 时代legacy era的 initialize 握手 pnpm --filter mcp-examples/stickynotes client -- --legacyparseExampleArgs解析的四个关键旋钮args.ts 源码参数含义默认值--http切换 transport 为 Streamable HTTP缺省为 stdio--http url客户端连接的 HTTP 端点http://127.0.0.1:port/mcp--port N服务端监听端口也读取$PORT3000--legacy协商 2025 时代协议versionNegotiation.mode: legacy缺省为 modern2026-07-28该示例的package.json中声明了example: { era: dual }见 examples/stickynotes/package.json表示它支持 modern legacy 两个协议时代而仓库的 CI 运行器 scripts/examples/run-examples.ts 会按每个 story 支持的 transport × era 组合逐一运行client.ts任何check.*断言失败都会使进程以非零码退出并导致构建失败——这就是自验证的保障机制。注意一个关键差异modern 与 http 两条腿只测试 add / list / read / remove跳过remove_allremove_all的 cancel / unchecked / confirm 全流程只在stdio/legacy组合上执行。原因详见后文为什么remove_all只在 stdio/legacy 上走通一节。服务端实现进程内状态 动态资源注册server.ts完整实现见 examples/stickynotes/server.ts把便签板状态放在一个进程内的Map中并维护一个自增 idconst notes new Mapstring, string(); let nextId 1; const uriFor (id: string) note:///${id};buildServer()每次调用都会新建一个McpServer并声明资源列表变更能力const server new McpServer( { name: stickynotes-example, version: 1.0.0 }, { capabilities: { resources: { listChanged: true } } } );每条便签一个资源注册与注销registerNote(id, text)为一条便签注册静态资源URI 形如note:///1并返回一个RegisteredResource句柄供后续注销const registerNote (id: string, text: string) { const r server.registerResource( note-${id}, uriFor(id), { mimeType: text/plain, description: Sticky note #${id} }, async uri ({ contents: [{ uri: uri.href, mimeType: text/plain, text: notes.get(id) ?? text }] }) ); registered.set(id, r); };registerResource的底层实现packages/server/src/server/mcp.ts在注册成功后会自动调用setResourceRequestHandlers()和sendResourceListChanged()——也就是说每注册一条便签资源SDK 会自动向客户端广播一次资源列表变更通知客户端无需轮询即可感知列表变化。同样地注销时调用registered.get(id)?.remove()也会触发对应的 listChanged 通知。对于 stdio 场景同一个McpServer实例在整个连接生命周期内固定复用因此运行时注册/注销资源没有问题对于 HTTP 的 per-request 路径createMcpHandler(buildServer)会在每次请求时调用工厂函数新建服务端实例因此buildServer()开头会把当前板上的所有便签先注册一遍保证每次请求都能看到最新状态。三个工具增、删、清add_note(text)存下便签并注册资源返回结构化结果{ id, uri }server.registerTool( add_note, { description: Add a sticky note; registers a note:///{id} resource for it., inputSchema: z.object({ text: z.string() }), outputSchema: z.object({ id: z.string(), uri: z.string() }) }, async ({ text }) { const id String(nextId); notes.set(id, text); registerNote(id, text); const structuredContent { id, uri: uriFor(id) }; return { content: [{ type: text, text: added note #${id} }], structuredContent }; } );remove_note(id)删除便签并注销其资源返回{ removed, id }server.registerTool( remove_note, { description: Remove one sticky note by id and unregister its resource., inputSchema: z.object({ id: z.string() }), outputSchema: z.object({ removed: z.boolean(), id: z.string() }) }, async ({ id }) { const removed notes.delete(id); if (removed) registered.get(id)?.remove(); return { content: [{ type: text, text: removed ? removed #${id} : not found }], structuredContent: { removed, id } }; } );remove_all()破坏性操作的典范——先发起 form 模式 elicitation只有拿到confirm: true才清空server.registerTool( remove_all, { description: Remove ALL sticky notes after confirming via a server→client elicitation., outputSchema: z.object({ status: z.string(), removed: z.number() }) }, async ctx { if (notes.size 0) { return { content: [{ type: text, text: nothing to clear }], structuredContent: { status: empty, removed: 0 } }; } const count notes.size; const result await ctx.mcpReq.elicitInput({ mode: form, message: Remove all ${count} sticky note(s)? This cannot be undone., requestedSchema: { type: object, properties: { confirm: { type: boolean, title: Yes, permanently delete every sticky note } }, required: [confirm] } }); if (result.action cancel) { return { content: [{ type: text, text: cancelled }], structuredContent: { status: cancelled, removed: 0 } }; } if (result.action ! accept || !(result.content as { confirm?: boolean } | undefined)?.confirm) { return { content: [{ type: text, text: declined }], structuredContent: { status: declined, removed: 0 } }; } for (const id of notes.keys()) registered.get(id)?.remove(); notes.clear(); return { content: [{ type: text, text: cleared ${count} }], structuredContent: { status: cleared, removed: count } }; } );注意这里的三态设计非常清晰cancel用户取消→cancelledaccept 但 confirm 为 false用户没勾选确认框→declinedaccept 且 confirm 为 true → 才真正cleared。三个状态都返回结构化的{ status, removed }便于客户端断言。双运输托管serveStdio 与 createMcpHandlerserver.ts用一个二进制同时支持两种 transportconst { transport, port } parseExampleArgs(); if (transport stdio) { void serveStdio(buildServer); console.error([server] serving over stdio); } else { const handler createMcpHandler(buildServer); // createMcpHonoApp() 默认在 localhost 主机/来源校验后面向 /mcp 暴露端点 const app createMcpHonoApp(); app.all(/mcp, c handler.fetch(c.req.raw)); serve({ fetch: app.fetch, port, hostname: 127.0.0.1 }, () { console.error([server] listening on http://127.0.0.1:${port}/mcp); }); }stdio 腿使用serveStdio(buildServer)来自modelcontextprotocol/server/stdio。HTTP 腿使用createMcpHandler(buildServer)生成无状态的 per-request handler再通过createMcpHonoApp()来自modelcontextprotocol/hono绑定在127.0.0.1的/mcp端点最后用hono/node-server的serve启动。createMcpHonoApp()默认启用 localhost host/origin 校验与框架工厂的默认行为一致。客户端实现连接、能力声明与三态验证client.ts完整实现见 examples/stickynotes/client.ts从构造Client开始就为 elicitation 做好了准备const client new Client( { name: stickynotes-example-client, version: 1.0.0 }, { versionNegotiation: { mode: era modern ? auto : legacy }, capabilities: { elicitation: { form: {} } } } );这里有两处关键声明versionNegotiation.mode决定协商 2026-07-28modern/auto还是 2025legacy时代capabilities.elicitation.form告诉服务端本客户端支持 form 模式 elicitation——这是服务端elicitInput能成功发送elicitation/create请求的前提。连接方式同样按 transport 分支await (transport stdio ? client.connect(new StdioClientTransport({ command: npx, args: [-y, tsx, siblingPath(import.meta.url, server.ts)] })) : client.connect(new StreamableHTTPClientTransport(new URL(url))));stdio 腿用siblingPath来自mcp-examples/shared解析出同目录的server.ts绝对路径并 spawnHTTP 腿直接连接StreamableHTTPClientTransport。处理服务端推送的 elicitation 请求客户端通过setRequestHandler(elicitation/create, ...)注册对服务端推送请求的处理函数用一个可切换的变量模拟用户在三个答案间的选择let elicitAnswer: cancel | unchecked | confirm cancel; client.setRequestHandler(elicitation/create, async () { if (elicitAnswer cancel) return { action: cancel }; return { action: accept, content: { confirm: elicitAnswer confirm } }; });自验证流程断言驱动的端到端测试随后 client 依次执行断言流程全部使用node:assert/strict重导出为check见 examples/shared/src/args.tsADD添加 Buy milk 与 Walk the dog 两条便签断言返回的 URI 匹配^note://\//且两个 id 不同。LIST/READlistResources()后过滤出note:///前缀的资源断言两条都在readResource读出第一条的内容应为 Buy milk。REMOVE ONEremove_note删除第一条断言removed true且再次 list 时该 URI 消失。分腿执行modern 或 http 腿直接删除第二条并断言资源列表为空跳过remove_alllegacy stdio 腿依次以cancel、unchecked、confirm三种答案调用remove_all分别断言status cancelled面板未动、status declined面板未动、status cleared且removed 1面板清空最后再调一次remove_all断言空板直接返回status empty而不再发起 elicitation。这一系列断言证明的核心事实正是 README 的标题句remove_all只有在用户明确确认时才会清空面板。为什么remove_all的确认流程只在 stdio/legacy 上走通这是本示例最值得深挖的一个设计约束README 与client.ts注释都做了明确交代2025 时代的 push 式 elicitation 需要长连接 见过 initialize 握手的服务端实例。elicitInput内部通过this.request({ method: elicitation/create, ... })向客户端推送请求实现见 packages/server/src/server/server.ts客户端必须已通过initialize声明其elicitation.form能力并且响应要能路由回同一个服务端实例。2026-07-28 协议根本没有服务端→客户端请求通道。因此在 modern 时代elicitInput会直接抛错_assertPushApiInServedEra(elicitation/create)等价物是多轮往返multi-round-trip的inputRequired结果——服务端返回inputRequired(...)客户端收集表单后重试同一 handler。两者的完整对照见 examples/elicitation/README.md。createMcpHandler的默认 legacy fallback 是每请求新建服务端的无状态模式每个 HTTP 请求都是一个全新的 per-request server客户端对elicitation/create的响应没有返回路径因此 HTTP 腿上即使协商到 legacy 也无法完成确认闭环。于是server.ts刻意用无状态的createMcpHandler托管 HTTP 腿而非像 examples/elicitation/server.ts 那样手写 sessionful 的NodeStreamableHTTPServerTransport来承接 legacy 流量从而把三条答案全流程的验证精确锁定在stdio/legacy这一条腿上——这本身就是对协议时代差异最直观的演示如果你需要在 HTTP 上提供同样的确认体验就得像 elicitation 示例那样引入 sessionful transport或者在 2026-07-28 时代改用inputRequired。底层原理elicitInput 的能力门禁与 schema 校验elicitInput的公开实现packages/server/src/server/server.ts#L1159-L1179在真正发送请求前会做两件事时代断言_assertPushApiInServedEra(elicitation/create)—— 在 2026-07-28 时代的请求上直接抛出该方法在源码注释中被标记为 deprecated明确指引改用inputRequired。客户端能力检查mode: url时要求客户端声明过elicitation.urlmode: form时要求声明过elicitation.form否则抛出SdkErrorCode.CapabilityNotSupported。这也解释了为什么客户端构造时必须声明capabilities: { elicitation: { form: {} } }。此外_sendElicitationLeg在收到accept且带 content 的响应后会用requestedSchema对应的 JSON Schema 校验器验证响应内容是否符合表单 schema不符合则抛出ProtocolErrorInvalidParams。也就是说服务端不仅把确认框推给客户端还会在协议层校验用户填回的内容防止非法载荷进入工具逻辑。学习要点与延伸阅读把状态与资源对齐是构建真实 MCP 应用的核心手法本示例中每条便签既是工具操作的业务对象又是客户端可readResource的资源状态变更时通过registerResource/remove()触发 listChanged让客户端始终看到一致的最新列表。破坏性操作必须走确认闭环remove_all的三态返回cancelled / declined / cleared展示了如何在工具层优雅地区分用户取消用户拒绝用户确认。协议时代差异是真实存在的约束push 式 elicitation 只属于 2025 时代2026-07-28 上的等价物是inputRequired多轮往返而 stateless legacy fallback 连往返都做不了。继续深入可以阅读同目录的完整实现examples/stickynotes/server.ts、examples/stickynotes/client.tselicitation 全模式对照form / url / throw含 2026 时代inputRequired实现examples/elicitation/README.mdregisterResource与 listChanged 的底层实现packages/server/src/server/mcp.tselicitInput的能力门禁与响应 schema 校验packages/server/src/server/server.ts参数解析与断言脚手架examples/shared/src/args.ts示例的总览与运行约定examples/README.md。【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
MCP TypeScript SDK 便签板实战用 Tools、Resources 与 Elicitation 搭建真实应用结课示例【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk本文基于 MCP TypeScript SDK 仓库中的examples/stickynotes示例完整拆解一个真实应用real app capstone的构建过程一个可增删查清的便签sticky-notes面板其中工具tools负责变更状态、每条便签都是一个资源resource、添加/删除时资源列表通过listChanged动态变化而破坏性的remove_all工具会被form 模式的服务端→客户端 elicitation拦截只有用户明确确认才会清空面板。读完本文你将掌握如何把 tools、resources、listChanged 通知、elicitation 四个 MCP 能力组合成一个有真实业务形态的端到端示例并理解它为何要在四种 transport/era 组合下分别验证。示例概览一个真正有状态的 MCP 应用examples/stickynotes是整个examples/目录中少有的结课型capstone示例——它不再孤立演示某一个 API而是把 SDK 的几大能力编织进一个自洽的小应用里。对应的示例清单将其定位为tools mutate state, a resource per note, listChanged, elicitation-confirmed clear。这个应用的核心行为是工具变更状态add_note(text)在进程内存储一条便签remove_note(id)删除一条remove_all()清空全部。每条便签是一个资源每添加一条便签就注册一个note:///{id}资源删除时同步注销。资源列表动态变化注册/注销资源时向客户端推送listChanged通知。破坏性操作需要确认remove_all()首先通过 form 模式的 elicitation 向用户弹出一个确认框cancel / 不勾选 / 确认三种结果分别对应三种处理路径只有明确确认才真正清空面板。示例以server.tsclient.ts一对文件的形式提供server.ts是你要部署的服务端client.ts则是宿主host视角的客户端——它连接、用公开客户端 API 驱动功能、用断言自验证结果、退出码 0 表示通过。运行方式同一份二进制跑通四种 transport/era 组合与仓库内其他示例一致stickynotes 使用examples/shared提供的parseExampleArgs()实现在 examples/shared/src/args.ts解析命令行参数因此一条命令即可在不同模式下运行。从仓库根目录执行# stdio默认客户端自行 spawn 服务端进程 pnpm --filter mcp-examples/stickynotes client # Streamable HTTP两个终端 pnpm --filter mcp-examples/stickynotes server -- --http --port 3000 pnpm --filter mcp-examples/stickynotes client -- --http http://127.0.0.1:3000/mcp # 追加 --legacy 切换到 2025 时代legacy era的 initialize 握手 pnpm --filter mcp-examples/stickynotes client -- --legacyparseExampleArgs解析的四个关键旋钮args.ts 源码参数含义默认值--http切换 transport 为 Streamable HTTP缺省为 stdio--http url客户端连接的 HTTP 端点http://127.0.0.1:port/mcp--port N服务端监听端口也读取$PORT3000--legacy协商 2025 时代协议versionNegotiation.mode: legacy缺省为 modern2026-07-28该示例的package.json中声明了example: { era: dual }见 examples/stickynotes/package.json表示它支持 modern legacy 两个协议时代而仓库的 CI 运行器 scripts/examples/run-examples.ts 会按每个 story 支持的 transport × era 组合逐一运行client.ts任何check.*断言失败都会使进程以非零码退出并导致构建失败——这就是自验证的保障机制。注意一个关键差异modern 与 http 两条腿只测试 add / list / read / remove跳过remove_allremove_all的 cancel / unchecked / confirm 全流程只在stdio/legacy组合上执行。原因详见后文为什么remove_all只在 stdio/legacy 上走通一节。服务端实现进程内状态 动态资源注册server.ts完整实现见 examples/stickynotes/server.ts把便签板状态放在一个进程内的Map中并维护一个自增 idconst notes new Mapstring, string(); let nextId 1; const uriFor (id: string) note:///${id};buildServer()每次调用都会新建一个McpServer并声明资源列表变更能力const server new McpServer( { name: stickynotes-example, version: 1.0.0 }, { capabilities: { resources: { listChanged: true } } } );每条便签一个资源注册与注销registerNote(id, text)为一条便签注册静态资源URI 形如note:///1并返回一个RegisteredResource句柄供后续注销const registerNote (id: string, text: string) { const r server.registerResource( note-${id}, uriFor(id), { mimeType: text/plain, description: Sticky note #${id} }, async uri ({ contents: [{ uri: uri.href, mimeType: text/plain, text: notes.get(id) ?? text }] }) ); registered.set(id, r); };registerResource的底层实现packages/server/src/server/mcp.ts在注册成功后会自动调用setResourceRequestHandlers()和sendResourceListChanged()——也就是说每注册一条便签资源SDK 会自动向客户端广播一次资源列表变更通知客户端无需轮询即可感知列表变化。同样地注销时调用registered.get(id)?.remove()也会触发对应的 listChanged 通知。对于 stdio 场景同一个McpServer实例在整个连接生命周期内固定复用因此运行时注册/注销资源没有问题对于 HTTP 的 per-request 路径createMcpHandler(buildServer)会在每次请求时调用工厂函数新建服务端实例因此buildServer()开头会把当前板上的所有便签先注册一遍保证每次请求都能看到最新状态。三个工具增、删、清add_note(text)存下便签并注册资源返回结构化结果{ id, uri }server.registerTool( add_note, { description: Add a sticky note; registers a note:///{id} resource for it., inputSchema: z.object({ text: z.string() }), outputSchema: z.object({ id: z.string(), uri: z.string() }) }, async ({ text }) { const id String(nextId); notes.set(id, text); registerNote(id, text); const structuredContent { id, uri: uriFor(id) }; return { content: [{ type: text, text: added note #${id} }], structuredContent }; } );remove_note(id)删除便签并注销其资源返回{ removed, id }server.registerTool( remove_note, { description: Remove one sticky note by id and unregister its resource., inputSchema: z.object({ id: z.string() }), outputSchema: z.object({ removed: z.boolean(), id: z.string() }) }, async ({ id }) { const removed notes.delete(id); if (removed) registered.get(id)?.remove(); return { content: [{ type: text, text: removed ? removed #${id} : not found }], structuredContent: { removed, id } }; } );remove_all()破坏性操作的典范——先发起 form 模式 elicitation只有拿到confirm: true才清空server.registerTool( remove_all, { description: Remove ALL sticky notes after confirming via a server→client elicitation., outputSchema: z.object({ status: z.string(), removed: z.number() }) }, async ctx { if (notes.size 0) { return { content: [{ type: text, text: nothing to clear }], structuredContent: { status: empty, removed: 0 } }; } const count notes.size; const result await ctx.mcpReq.elicitInput({ mode: form, message: Remove all ${count} sticky note(s)? This cannot be undone., requestedSchema: { type: object, properties: { confirm: { type: boolean, title: Yes, permanently delete every sticky note } }, required: [confirm] } }); if (result.action cancel) { return { content: [{ type: text, text: cancelled }], structuredContent: { status: cancelled, removed: 0 } }; } if (result.action ! accept || !(result.content as { confirm?: boolean } | undefined)?.confirm) { return { content: [{ type: text, text: declined }], structuredContent: { status: declined, removed: 0 } }; } for (const id of notes.keys()) registered.get(id)?.remove(); notes.clear(); return { content: [{ type: text, text: cleared ${count} }], structuredContent: { status: cleared, removed: count } }; } );注意这里的三态设计非常清晰cancel用户取消→cancelledaccept 但 confirm 为 false用户没勾选确认框→declinedaccept 且 confirm 为 true → 才真正cleared。三个状态都返回结构化的{ status, removed }便于客户端断言。双运输托管serveStdio 与 createMcpHandlerserver.ts用一个二进制同时支持两种 transportconst { transport, port } parseExampleArgs(); if (transport stdio) { void serveStdio(buildServer); console.error([server] serving over stdio); } else { const handler createMcpHandler(buildServer); // createMcpHonoApp() 默认在 localhost 主机/来源校验后面向 /mcp 暴露端点 const app createMcpHonoApp(); app.all(/mcp, c handler.fetch(c.req.raw)); serve({ fetch: app.fetch, port, hostname: 127.0.0.1 }, () { console.error([server] listening on http://127.0.0.1:${port}/mcp); }); }stdio 腿使用serveStdio(buildServer)来自modelcontextprotocol/server/stdio。HTTP 腿使用createMcpHandler(buildServer)生成无状态的 per-request handler再通过createMcpHonoApp()来自modelcontextprotocol/hono绑定在127.0.0.1的/mcp端点最后用hono/node-server的serve启动。createMcpHonoApp()默认启用 localhost host/origin 校验与框架工厂的默认行为一致。客户端实现连接、能力声明与三态验证client.ts完整实现见 examples/stickynotes/client.ts从构造Client开始就为 elicitation 做好了准备const client new Client( { name: stickynotes-example-client, version: 1.0.0 }, { versionNegotiation: { mode: era modern ? auto : legacy }, capabilities: { elicitation: { form: {} } } } );这里有两处关键声明versionNegotiation.mode决定协商 2026-07-28modern/auto还是 2025legacy时代capabilities.elicitation.form告诉服务端本客户端支持 form 模式 elicitation——这是服务端elicitInput能成功发送elicitation/create请求的前提。连接方式同样按 transport 分支await (transport stdio ? client.connect(new StdioClientTransport({ command: npx, args: [-y, tsx, siblingPath(import.meta.url, server.ts)] })) : client.connect(new StreamableHTTPClientTransport(new URL(url))));stdio 腿用siblingPath来自mcp-examples/shared解析出同目录的server.ts绝对路径并 spawnHTTP 腿直接连接StreamableHTTPClientTransport。处理服务端推送的 elicitation 请求客户端通过setRequestHandler(elicitation/create, ...)注册对服务端推送请求的处理函数用一个可切换的变量模拟用户在三个答案间的选择let elicitAnswer: cancel | unchecked | confirm cancel; client.setRequestHandler(elicitation/create, async () { if (elicitAnswer cancel) return { action: cancel }; return { action: accept, content: { confirm: elicitAnswer confirm } }; });自验证流程断言驱动的端到端测试随后 client 依次执行断言流程全部使用node:assert/strict重导出为check见 examples/shared/src/args.tsADD添加 Buy milk 与 Walk the dog 两条便签断言返回的 URI 匹配^note://\//且两个 id 不同。LIST/READlistResources()后过滤出note:///前缀的资源断言两条都在readResource读出第一条的内容应为 Buy milk。REMOVE ONEremove_note删除第一条断言removed true且再次 list 时该 URI 消失。分腿执行modern 或 http 腿直接删除第二条并断言资源列表为空跳过remove_alllegacy stdio 腿依次以cancel、unchecked、confirm三种答案调用remove_all分别断言status cancelled面板未动、status declined面板未动、status cleared且removed 1面板清空最后再调一次remove_all断言空板直接返回status empty而不再发起 elicitation。这一系列断言证明的核心事实正是 README 的标题句remove_all只有在用户明确确认时才会清空面板。为什么remove_all的确认流程只在 stdio/legacy 上走通这是本示例最值得深挖的一个设计约束README 与client.ts注释都做了明确交代2025 时代的 push 式 elicitation 需要长连接 见过 initialize 握手的服务端实例。elicitInput内部通过this.request({ method: elicitation/create, ... })向客户端推送请求实现见 packages/server/src/server/server.ts客户端必须已通过initialize声明其elicitation.form能力并且响应要能路由回同一个服务端实例。2026-07-28 协议根本没有服务端→客户端请求通道。因此在 modern 时代elicitInput会直接抛错_assertPushApiInServedEra(elicitation/create)等价物是多轮往返multi-round-trip的inputRequired结果——服务端返回inputRequired(...)客户端收集表单后重试同一 handler。两者的完整对照见 examples/elicitation/README.md。createMcpHandler的默认 legacy fallback 是每请求新建服务端的无状态模式每个 HTTP 请求都是一个全新的 per-request server客户端对elicitation/create的响应没有返回路径因此 HTTP 腿上即使协商到 legacy 也无法完成确认闭环。于是server.ts刻意用无状态的createMcpHandler托管 HTTP 腿而非像 examples/elicitation/server.ts 那样手写 sessionful 的NodeStreamableHTTPServerTransport来承接 legacy 流量从而把三条答案全流程的验证精确锁定在stdio/legacy这一条腿上——这本身就是对协议时代差异最直观的演示如果你需要在 HTTP 上提供同样的确认体验就得像 elicitation 示例那样引入 sessionful transport或者在 2026-07-28 时代改用inputRequired。底层原理elicitInput 的能力门禁与 schema 校验elicitInput的公开实现packages/server/src/server/server.ts#L1159-L1179在真正发送请求前会做两件事时代断言_assertPushApiInServedEra(elicitation/create)—— 在 2026-07-28 时代的请求上直接抛出该方法在源码注释中被标记为 deprecated明确指引改用inputRequired。客户端能力检查mode: url时要求客户端声明过elicitation.urlmode: form时要求声明过elicitation.form否则抛出SdkErrorCode.CapabilityNotSupported。这也解释了为什么客户端构造时必须声明capabilities: { elicitation: { form: {} } }。此外_sendElicitationLeg在收到accept且带 content 的响应后会用requestedSchema对应的 JSON Schema 校验器验证响应内容是否符合表单 schema不符合则抛出ProtocolErrorInvalidParams。也就是说服务端不仅把确认框推给客户端还会在协议层校验用户填回的内容防止非法载荷进入工具逻辑。学习要点与延伸阅读把状态与资源对齐是构建真实 MCP 应用的核心手法本示例中每条便签既是工具操作的业务对象又是客户端可readResource的资源状态变更时通过registerResource/remove()触发 listChanged让客户端始终看到一致的最新列表。破坏性操作必须走确认闭环remove_all的三态返回cancelled / declined / cleared展示了如何在工具层优雅地区分用户取消用户拒绝用户确认。协议时代差异是真实存在的约束push 式 elicitation 只属于 2025 时代2026-07-28 上的等价物是inputRequired多轮往返而 stateless legacy fallback 连往返都做不了。继续深入可以阅读同目录的完整实现examples/stickynotes/server.ts、examples/stickynotes/client.tselicitation 全模式对照form / url / throw含 2026 时代inputRequired实现examples/elicitation/README.mdregisterResource与 listChanged 的底层实现packages/server/src/server/mcp.tselicitInput的能力门禁与响应 schema 校验packages/server/src/server/server.ts参数解析与断言脚手架examples/shared/src/args.ts示例的总览与运行约定examples/README.md。【免费下载链接】typescript-sdkThe official TypeScript SDK for Model Context Protocol servers and clients项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
