当前位置： 首页 > news >正文

TypeScript 开发AI Agents MCP 完整实战指南

news 2026/7/8 9:50:02

TypeScript 开发AI Agents MCP 完整实战指南（适配 @modelcontextprotocol/sdk 1.29.0）

前言

MCP（Model Context Protocol，模型上下文协议）是大模型、AI Agent、外部工具/数据源统一交互的标准化协议，替代各框架私有 Function Calling，实现工具跨模型、跨项目复用。
本文基于稳定版@modelcontextprotocol/sdk@1.29.0，全程无废弃API、无TS编译报错，包含完整可运行TS案例、Claude Code官方接入流程、私有NPM包打包发布全流程，适合团队分享落地参考。

一、MCP 核心架构与价值

1.1 核心定位

MCP 采用 Client-Server 分层 STDIO 通信架构，解决传统AI Agent开发碎片化痛点：

  1. 工具逻辑与大模型推理完全解耦；
  2. 一套工具同时适配 Claude、GPT、Codex 等所有主流模型；
  3. 统一管理工具函数、业务资源、提示词模板；
  4. 强类型约束，TS 编译期拦截参数异常。

1.2 三层核心组件

  1. MCP Server：能力提供方，注册工具、业务资源，对外标准化输出能力；
  2. MCP Client：对接大模型应用，负责调用服务端工具、读取上下文资源；
  3. Host：AI应用主体（Claude Code、自定义Agent、Codex服务），发起工具调用决策。

1.3 三大核心能力

  • Tools：可执行函数（时间查询、文本处理、接口请求等）；
  • Resources：静态业务上下文、知识库、配置文件；
  • Prompts：可复用标准化提示模板。

二、环境初始化（零报错配置）

2.1 安装依赖

npminit-y# 锁定1.29.0稳定SDKnpminstall@modelcontextprotocol/sdk@1.29.0 zod# TS类型与编译工具npminstalltypescript ts-node @types/node-D

2.2 tsconfig.json 最终稳定配置（解决Buffer、TS5110报错）

{"compilerOptions":{"target":"ES2022","module":"NodeNext","moduleResolution":"NodeNext","outDir":"./dist","rootDir":"./src","strict":true,"esModuleInterop":true,"resolveJsonModule":true,"types":["node"]},"include":["src/**/*"],"type":"module"}

2.3 package.json 基础脚本

{"type":"module","scripts":{"build":"tsc","dev":"ts-node src/server.ts","start":"node dist/client.js"}}

三、完整可运行Demo（适配1.29.0，无废弃API）

3.1 MCP服务端 src/server.ts

使用官方推荐McpServer高阶API，zod强类型参数校验：

import{McpServer}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport}from"@modelcontextprotocol/sdk/server/stdio.js";import{z}from"zod";// 初始化MCP服务constserver=newMcpServer({name:"ts-custom-mcp-server",version:"1.0.0"});// 工具1：获取当前服务器时间server.tool("get-current-time","获取服务器本地标准时间，用于时间类业务判断",{},async()=>{return{content:[{type:"text",text:newDate().toLocaleString()}]};});// 工具2：文本字数统计（zod强类型校验入参）server.tool("count-text-length","统计中英文混合文本总字符数",{text:z.string().describe("待统计的文本内容")},async({text})=>{return{content:[{type:"text",text:`文本总字数：${text.length}`}]};});// 注册业务上下文资源server.resource("agent-common-config","biz://agent-common-config",{description:"AI通用业务约束上下文"},async()=>{return{contents:[{uri:"biz://agent-common-config",text:"回复简洁专业，优先调用工具获取实时数据，输出精准数字结果"}]};);// STDIO标准传输启动服务consttransport=newStdioServerTransport();awaitserver.connect(transport);console.log("✅ MCP Server 启动完成，等待客户端连接");

3.2 MCP客户端 src/client.ts

1.29.0 无McpClient，仅原生Client可用，无模块缺失报错：

import{Client}from"@modelcontextprotocol/sdk/client/index.js";import{StdioClientTransport}from"@modelcontextprotocol/sdk/client/stdio.js";asyncfunctionrunDemo(){// 初始化客户端constclient=newClient({name:"ts-mcp-client-demo",version:"1.29.0"});// 连接本地编译后的服务端consttransport=newStdioClientTransport({command:"node",args:["./dist/server.js"]});awaitclient.connect(transport);console.log("✅ 客户端连接MCP服务成功");// 拉取全部可用工具const{tools}=awaitclient.listTools();console.log("可用工具列表：",tools.map(item=>item.name));// 调用时间工具consttimeRes=awaitclient.callTool({name:"get-current-time",arguments:{}});console.log("\n当前时间：",timeRes);// 调用文本统计工具consttextRes=awaitclient.callTool({name:"count-text-length",arguments:{text:"TypeScript开发MCP AI Agent"}});console.log("\n文本统计结果：",textRes);// 读取业务资源上下文constresourceRes=awaitclient.readResource({uri:"biz://agent-common-config"});console.log("\n业务配置上下文：",resourceRes);}runDemo().catch(console.error);

3.3 编译运行

# 编译TS代码至dist文件夹npmrun build# 执行客户端测试全链路调用npmstart

四、集成 Claude Code（官方标准命令行方式）

4.1 核心说明

  1. 新版Claude Code废弃独立mcp.json，不推荐手动修改settings.json；
  2. 统一使用claude mcp add命令自动写入配置，规避JSON语法错误；
  3. 两种挂载范围：--scope user全局生效 / 默认local仅当前项目生效。

4.2 挂载自定义MCP服务

# 全局挂载（所有项目均可调用该套工具，替换为你的dist/server.js绝对路径）claude mcpadd--scopeuser ts-custom-mcp-server --node/Users/xxx/project/dist/server.js

4.3 配套运维命令

# 查看所有已挂载MCP服务，校验是否注册成功claude mcp list# 查看指定服务详情claude mcp inspect ts-custom-mcp-server# 删除已挂载服务claude mcp remove--scopeuser ts-custom-mcp-server

4.4 验证效果

重启Claude Code会话，输入自然语言指令：
帮我获取当前系统时间，并统计文本"MCP开发AI工具"的字数
模型会自动识别并调用我们注册的两个自定义工具。

五、集成 OpenAI Codex 大模型

Codex无原生MCP支持，通过MCP Client中转工具调用，实现模型决策+标准化工具执行：

5.1 安装依赖

npminstallopenai

5.2 联动代码 src/codex-agent.ts

import{Client}from"@modelcontextprotocol/sdk/client/index.js";import{StdioClientTransport}from"@modelcontextprotocol/sdk/client/stdio.js";importOpenAIfrom"openai";constopenai=newOpenAI({apiKey:process.env.OPENAI_API_KEY});asyncfunctioncodexMcpAgent(){// 初始化MCP客户端constmcpClient=newClient({name:"codex-mcp-bridge",version:"1.29.0"});consttransport=newStdioClientTransport({command:"node",args:["./dist/server.js"]});awaitmcpClient.connect(transport);const{tools}=awaitmcpClient.listTools();// Codex自动判断是否调用工具constchatRes=awaitopenai.chat.completions.create({model:"code-davinci-002",messages:[{role:"user",content:"获取当前时间并统计文本「MCP Agent开发」字数"}],tools:tools,tool_choice:"auto"});constmessage=chatRes.choices[0].message;if(message.tool_calls){for(constcallofmessage.tool_calls){constresult=awaitmcpClient.callTool({name:call.function.name,arguments:JSON.parse(call.function.arguments||"{}")});console.log("MCP工具执行输出：",result);}}}codexMcpAgent().catch(console.error);

六、打包发布私有NPM包（企业团队复用）

6.1 package.json 发包标准配置

{"name":"@team/ts-mcp-server","version":"1.0.0","type":"module","main":"dist/server.js","types":"dist/server.d.ts","bin":{"ts-mcp-server":"./dist/server.js"},"files":["dist/**/*"],"scripts":{"build":"tsc","prepublishOnly":"npm run build","start":"node dist/server.js"},"dependencies":{"@modelcontextprotocol/sdk":"1.29.0","zod":"^3.24.0"},"devDependencies":{"@types/node":"^22.0.0","ts-node":"^10.9.0","typescript":"^5.5.0"},"private":true,"description":"企业内部私有MCP工具服务，统一AI Agent能力","license":"MIT"}

关键配置说明：

  1. private: true：禁止公网发布，仅私有仓库可用；
  2. bin：安装后全局命令ts-mcp-server一键启动；
  3. prepublishOnly：发布前自动编译，保证dist文件最新。

6.2 完整发包流程（解决CNPM/OTP报错）

问题1：CNPM报错 Public registration is not allowed

淘宝镜像registry.npmmirror.com关闭公共注册，登录/发包必须切换官方源：

# 切换官方NPM源npmconfigsetregistry https://registry.npmjs.org/# 校验源是否切换成功npmconfig get registry
问题2：npm login invalid otp 验证码无效
  1. 开启设备自动同步时间，OTP基于时间校验，时差超30s直接失效；
  2. 关闭VPN/代理，避免时区错乱；
  3. 长期方案：使用永久Access Token替代验证码登录
# 官网npmjs.com创建Classic Publish Token，登录时密码粘贴tokennpmlogin --auth-type=legacy
发布步骤
# 1. 编译代码npmrun build# 2. 登录官方npm源npmlogin# 3. 发布私有包npmpublish
团队安装使用
npminstall@team/ts-mcp-server# 全局命令启动MCP服务ts-mcp-server

七、高频踩坑汇总

  1. TS2307 找不到 client/mcp.js
    1.29.0版本客户端无McpClient，仅服务端支持McpServer，客户端统一使用原生Client；
  2. TS2591 Buffer类型不存在
    tsconfig新增"types": ["node"]，确保安装@types/node；
  3. TS5110 module配置不匹配
    module、moduleResolution必须同时为NodeNext；
  4. Claude MCP挂载失败
    使用claude mcp add命令行挂载，路径必须填绝对路径；
  5. CNPM无法登录发包
    发包强制切换官方registry，日常安装包可切淘宝镜像加速；
  6. invalid otp 验证码报错
    同步系统时间，使用永久Publish Token绕过动态验证码。

八、适用业务场景

  1. 企业内部文档处理Agent：封装文件读取、摘要、格式转换工具；
  2. 业务智能问答：MCP Resources存储知识库，Tools调用业务接口；
  3. 多模型统一工具中台：一套MCP服务同时对接Claude、GPT、Codex；
  4. IDE本地AI插件：Claude Code挂载私有工具，实现自定义工程化能力。

九、总结

基于TypeScript+MCP 1.29.0搭建AI Agent工具层，是当前工程化最优方案：通过标准化协议解耦模型与业务逻辑，依托TS强类型降低线上异常，同时支持Claude Code本地接入、私有NPM包团队复用，适合企业规模化AI应用落地。

http://www.jsqmd.com/news/1146963/

相关文章：

  • 【JAVA毕设源码分享】基于SpringBoot+Vue的万象影视购票平台的设计与实现(程序+文档+代码讲解+一条龙定制)
  • FPGA实战（35）：DAC多通道NCO频率上传设置模块设计与实现
  • 基于ADS127L11和MK60DN512VLQ10的高精度数据采集系统设计
  • 精密电子配件质量升级｜蔡司 ATOS Q 三维扫描赋能线束端子全尺寸数字化检测
  • STM32与PAM8904实现智能声音警报系统设计
  • 如何快速配置AzurLaneAutoScript的MAA模块：完整优化指南
  • Sunshine游戏串流终极指南：轻松搭建家庭游戏共享中心
  • 2026年全国GEO/SEO优化培训班解析与选型，培训机构推荐及避坑指南
  • [特殊字符] OpenClaw 完整命令手册：从入门到精通的 CLI 终极指南
  • 【Java课程设计/毕业设计】基于前后端分离的智慧高校实验教学管理系统的设计与实现 基于 SpringBoot 的高校实训实验室综合管理系统【附源码、数据库、万字文档】
  • 军队文职备考进阶论：中教睿海如何以“全电子商务”专业服务成就修炼
  • ThinkPad风扇终极控制指南：如何在Windows上实现双风扇智能管理
  • A3910与PIC32MZ2048EFH144在嵌入式电机控制中的黄金组合
  • 静态住宅 IP 和动态住宅 IP 有什么区别？从公网地址、稳定性到使用场景一文讲清
  • Airtest自动化测试入门第一篇：环境搭建与5分钟上手
  • MCP3428与MK24FN1M0VDC12在工业数据采集中的优化应用
  • 直线电机在3D打印中的高速高精度运动控制实践
  • 手机号查询QQ终极指南：3步实现高效查询的完整解决方案
  • 9大网盘直链解析神器LinkSwift：告别限速困扰的终极解决方案
  • Ricon组态可视化编辑器 - 所见即所得的工业画布
  • MonoDETR 深度引导Transformer实战：KITTI数据集AP3D提升至28.84%的代码复现指南
  • 如何快速构建思源黑体TTF字体：免费商用中文字体完全指南
  • 咖啡门店点餐小程序怎么做？餐宝盈/BBWEYY/小艺助手/ModelArts/openPangu 2.0 Pro这5个小程序制作工具助你零基础搭建
  • CefFlashBrowser：Flash时代终结后的终极解决方案
  • MCP3428与MKV44F128VLH16在工业数据采集中的高精度应用
  • Java毕设选题推荐：基于 SpringBoot 的大学生实验教学项目管理系统的设计与实现 基于 SpringBoot+Vue 的实验室教学排班【附源码、mysql、文档、调试+代码讲解+全bao等】
  • CAD看图软件高频功能盘点，详解七大实用工具！
  • 3种方案解除笔记本异常降频：从软件解锁到硬件排查的完整决策树
  • 高压安全隔离技术：ISOM8710与MK20DX128VFM5方案解析
  • 锂离子电池组电压平衡方案：MCP3202与PIC18F4458实现