教程文档人工智能【免费下载链接】mcp-for-beginnersThis open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.项目地址https://gitcode.com/GitHub_Trending/mc/mcp-for-beginners点击查看免费下载本文围绕 mcp-for-beginners 仓库中 04-PracticalImplementation/samples/typescript 的 TypeScript MCP Server 示例展开结合其完整源码讲解如何用modelcontextprotocol/sdk与 Zod 定义类型安全的 Tool 和 Resource并通过 stdio 传输启动服务。读完本文你将掌握 MCP Server 在 TypeScript 下的工程结构、工具注册、资源暴露、事件埋点与本地运行验证的全套方法。示例概览一个 TypeScript 版 MCP Server该示例位于仓库的 04-PracticalImplementation/samples/typescript 目录是第四章「Practical Implementation」中按语言组织的多语言示例之一另有 C#、Java with Spring、JavaScript、Python 版本见 04-PracticalImplementation/README.md。示例通过官方 TypeScript SDK 实现了一个完整的 MCP Server主要包含两类核心能力Tool工具一个名为completion的补全工具接收model、prompt与可选options参数返回模拟的 LLM 补全结果Resource资源一个名为search的资源使用ResourceTemplate暴露test://{query}形式的动态资源地址返回模拟搜索结果。整个示例以「先 mock、后接入真实模型」的渐进思路编写非常适合作为学习 MCP Server 的第一个 TypeScript 参考实现。工程结构解析示例的完整文件结构如下均在仓库根目录下04-PracticalImplementation/samples/typescript/ ├── src/ │ └── index.ts # 服务端核心实现 ├── README.md # 示例说明文档 ├── package.json # 依赖与脚本定义 ├── package-lock.json # 依赖锁定文件 └── tsconfig.json # TypeScript 编译配置依赖清单package.json查看 package.json 可以看到示例的关键依赖{ name: tutorial-mcp, version: 1.0.0, type: module, scripts: { start: tsc node ./build/index.js, build: tsc node ./build/index.js }, dependencies: { modelcontextprotocol/sdk: ^1.26.0, openai: ^4.95.0, zod: ^3.24.2 }, devDependencies: { types/node: ^22.13.17, typescript: ^5.8.2 } }这里有三点值得注意modelcontextprotocol/sdk^1.26.0是 MCP 官方 TypeScript SDK提供McpServer、StdioServerTransport、ResourceTemplate等核心构件zod^3.24.2用于声明工具参数的运行时校验 Schema——这是 MCP TypeScript 生态的标准做法openai^4.95.0已作为依赖声明对应源码中「真实实现中应调用 AI 模型」的演进方向示例当前以 mock 响应代替真实调用。编译配置tsconfig.jsontsconfig.json 采用 ES2022 目标与 Node16 模块解析rootDir指向./src编译产物输出到./build并开启了strict严格模式。由于package.json中声明了type: module源码使用 ESM 风格的import语法。用 Zod 注册类型安全的 completion 工具示例文档 04-PracticalImplementation/samples/typescript/README.md 给出了工具注册的核心片段即通过this.mcpServer.tool(...)注册completion工具this.mcpServer.tool( completion, { model: z.string(), prompt: z.string(), options: z.object({ temperature: z.number().optional(), max_tokens: z.number().optional(), stream: z.boolean().optional() }).optional() }, async ({ model, prompt, options }) { console.log(Processing completion request for model: ${model}); // Validate model if (!this.models.includes(model)) { throw new Error(Model ${model} not supported); } // Emit event for monitoring/metrics this.events.emit(request, { type: completion, model, timestamp: new Date() }); // In a real implementation, this would call an AI model // Here we just echo back parts of the request with a mock response const response { id: mcp-resp-${Date.now()}, model, text: This is a response to: ${prompt.substring(0, 30)}..., usage: { promptTokens: prompt.split( ).length, completionTokens: 20, totalTokens: prompt.split( ).length 20 } }; // Simulate network delay await new Promise(resolve setTimeout(resolve, 500)); // Emit completion event this.events.emit(completion, { model, timestamp: new Date() }); return { content: [ { type: text, text: JSON.stringify(response) } ] }; } );参数 Schema 与 MCP 类型映射mcpServer.tool()的第二个参数使用 Zod Schema 描述工具入参SDK 会自动将其转换为 MCP 协议要求的 JSON Schema参数类型是否必填说明modelz.string()必填目标模型名称需在服务端支持列表中promptz.string()必填用户输入提示词options.temperaturez.number()可选采样温度options.max_tokensz.number()可选最大生成 token 数options.streamz.boolean()可选是否流式返回处理函数的关键设计从源码src/index.ts可以看到处理函数内部的三段式逻辑这也是生产级 MCP 工具可复用的骨架模型校验if (!this.models.includes(model))抛错拒绝不支持的模型保证失败快速暴露事件埋点通过 Node 内置EventEmitter分别发出request与completion事件为监控/指标采集预留接口返回 MCP 标准内容块返回值遵循 MCP 的content数组约定此处使用type: text的文本内容块将 mock 响应以JSON.stringify形式返回。模拟的 500ms 网络延迟则对应真实场景中调用远端模型的开销。源码纵深ExtendedMcpServer 类的完整实现示例文档只展示了工具注册片段而其完整实现位于 src/index.ts。源码将能力封装为ExtendedMcpServer类构造函数接受{ serverName?, version?, models? }三个可选配置项并完成三件事用new McpServer({ name, version })创建核心 MCP 服务器实例调用registerCompletionTool()注册上文讲解的 completion 工具调用registerSearchResource()注册 search 资源。通过 ResourceTemplate 暴露动态资源在registerSearchResource()src/index.ts中示例展示了 Resource 的注册方式this.mcpServer.resource( search, new ResourceTemplate(test://{query}, { list: undefined }), async (uri, { query }) { // Simulate search processing await new Promise(resolve setTimeout(resolve, 300)); const results [ { title: Result 1, snippet: Related to ${query}... }, { title: Result 2, snippet: Information about ${query}... }, { title: Result 3, snippet: More details on ${query}... } ]; return { contents: [ { uri: uri.href, text: JSON.stringify(results) } ] }; } );与 Tool 不同Resource 面向「提供上下文与数据」的场景。这里使用ResourceTemplate定义带 URI 参数模板的地址模式test://{query}当客户端读取匹配该模板的 URI 时回调收到解析出的{ query }参数返回contents数组作为资源内容。{ list: undefined }表明该模板不参与资源列表枚举。基于 stdio 的传输连接connect()方法src/index.ts负责将服务器绑定到标准输入输出传输public async connect(): Promisevoid { const transport new StdioServerTransport(); await this.mcpServer.connect(transport); console.log(Server connected via stdio transport); }StdioServerTransport是 MCP 最常见的本地传输方式服务器通过 stdin/stdout 与宿主如 VS Code、Claude Desktop 或自定义客户端通信非常适合本地开发和调试。可观测性与对外访问接口类还提供了on(event, listener)事件监听注册、getMcpServer()获取底层实例、getSupportedModels()返回受支持模型列表等公开方法。文件末尾的演示代码展示了完整的启动序列src/index.tsconst server new ExtendedMcpServer({ serverName: TypeScript MCP Demo Server, version: 1.0.0 }); server.on(request, (data) { console.log(Request received: ${JSON.stringify(data)}); }); server.on(completion, (data) { console.log(Completion finished: ${JSON.stringify(data)}); }); server.connect().catch(error { console.error(Failed to connect server:, error); process.exit(1); });从源码结构可以推断这套「类封装 事件埋点 模块化注册方法」的设计意在将 MCP Server 的初始化、工具/资源注册与传输连接解耦方便后续扩展更多工具与资源。安装与运行安装依赖在示例目录下执行对应文档中的 Install 步骤npm install该命令会依据 package.json 与package-lock.json安装modelcontextprotocol/sdk、zod、openai及 TypeScript 工具链。启动服务npm start需要注意start脚本的真实行为是tsc node ./build/index.jspackage.json先由 TypeScript 编译器将src/编译到build/再直接运行编译产物。因此首次运行会自动完成编译启动后控制台会依次输出服务器初始化信息、受支持模型列表随后通过 stdio 传输等待客户端连接。快速验证思路启动后可用 MCP Inspectornpx modelcontextprotocol/inspector以 stdio 方式连接本服务或在宿主机如 VS Code Agent 模式中将其注册为 MCP Server进而调用completion工具并读取test://{query}资源——这与仓库中 04-PracticalImplementation/README.md 介绍的 MCP Inspector 测试方法一致。若传入不在支持列表中的模型名服务端会按设计抛出Model ... not supported错误可作为校验 Zod Schema 与业务校验链路的测试用例。延伸阅读多语言对照实现C#、Java with Spring、JavaScript、Python分页与大数据集处理04-PracticalImplementation/pagination/README.md章节总览与实战目标04-PracticalImplementation/README.md赞分享教程文档人工智能【免费下载链接】mcp-for-beginnersThis open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.项目地址https://gitcode.com/GitHub_Trending/mc/mcp-for-beginners点击查看免费下载相关推荐MCP for Beginners 项目实战使用 Python 构建 MCP Calculator ServerMCP for Beginners 项目实战使用 Python 构建 MCP Calculator Server 本指南以 mcp for beginners教程文档人工智能在 mcp-for-beginners 中构建 MCP TypeScript 客户端基于官方 SDK 的 stdio 传输与工具调用实战在 mcp for beginners 中构建 MCP TypeScript 客户端基于官方 SDK 的 stdio 传输与工具调用实战 本文围绕 mcp f教程文档人工智能MCP stdio 传输实战基于 mcp-for-beginners 多语言示例构建本地 MCP ServerMCP stdio 传输实战基于 mcp for beginners 多语言示例构建本地 MCP Server 本文以 mcp for beginners 仓教程文档人工智能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
