TypeScript 开发AI Agents MCP 完整实战指南适配 modelcontextprotocol/sdk 1.29.0前言MCPModel Context Protocol模型上下文协议是大模型、AI Agent、外部工具/数据源统一交互的标准化协议替代各框架私有 Function Calling实现工具跨模型、跨项目复用。本文基于稳定版modelcontextprotocol/sdk1.29.0全程无废弃API、无TS编译报错包含完整可运行TS案例、Claude Code官方接入流程、私有NPM包打包发布全流程适合团队分享落地参考。一、MCP 核心架构与价值1.1 核心定位MCP 采用 Client-Server 分层 STDIO 通信架构解决传统AI Agent开发碎片化痛点工具逻辑与大模型推理完全解耦一套工具同时适配 Claude、GPT、Codex 等所有主流模型统一管理工具函数、业务资源、提示词模板强类型约束TS 编译期拦截参数异常。1.2 三层核心组件MCP Server能力提供方注册工具、业务资源对外标准化输出能力MCP Client对接大模型应用负责调用服务端工具、读取上下文资源HostAI应用主体Claude Code、自定义Agent、Codex服务发起工具调用决策。1.3 三大核心能力Tools可执行函数时间查询、文本处理、接口请求等Resources静态业务上下文、知识库、配置文件Prompts可复用标准化提示模板。二、环境初始化零报错配置2.1 安装依赖npminit-y# 锁定1.29.0稳定SDKnpminstallmodelcontextprotocol/sdk1.29.0 zod# TS类型与编译工具npminstalltypescript ts-node types/node-D2.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无废弃API3.1 MCP服务端 src/server.ts使用官方推荐McpServer高阶APIzod强类型参数校验import{McpServer}frommodelcontextprotocol/sdk/server/mcp.js;import{StdioServerTransport}frommodelcontextprotocol/sdk/server/stdio.js;import{z}fromzod;// 初始化MCP服务constservernewMcpServer({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标准传输启动服务consttransportnewStdioServerTransport();awaitserver.connect(transport);console.log(✅ MCP Server 启动完成等待客户端连接);3.2 MCP客户端 src/client.ts1.29.0 无McpClient仅原生Client可用无模块缺失报错import{Client}frommodelcontextprotocol/sdk/client/index.js;import{StdioClientTransport}frommodelcontextprotocol/sdk/client/stdio.js;asyncfunctionrunDemo(){// 初始化客户端constclientnewClient({name:ts-mcp-client-demo,version:1.29.0});// 连接本地编译后的服务端consttransportnewStdioClientTransport({command:node,args:[./dist/server.js]});awaitclient.connect(transport);console.log(✅ 客户端连接MCP服务成功);// 拉取全部可用工具const{tools}awaitclient.listTools();console.log(可用工具列表,tools.map(itemitem.name));// 调用时间工具consttimeResawaitclient.callTool({name:get-current-time,arguments:{}});console.log(\n当前时间,timeRes);// 调用文本统计工具consttextResawaitclient.callTool({name:count-text-length,arguments:{text:TypeScript开发MCP AI Agent}});console.log(\n文本统计结果,textRes);// 读取业务资源上下文constresourceResawaitclient.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 核心说明新版Claude Code废弃独立mcp.json不推荐手动修改settings.json统一使用claude mcp add命令自动写入配置规避JSON语法错误两种挂载范围--scope user全局生效 / 默认local仅当前项目生效。4.2 挂载自定义MCP服务# 全局挂载所有项目均可调用该套工具替换为你的dist/server.js绝对路径claude mcpadd--scopeuser ts-custom-mcp-server --node/Users/xxx/project/dist/server.js4.3 配套运维命令# 查看所有已挂载MCP服务校验是否注册成功claude mcp list# 查看指定服务详情claude mcp inspect ts-custom-mcp-server# 删除已挂载服务claude mcp remove--scopeuser ts-custom-mcp-server4.4 验证效果重启Claude Code会话输入自然语言指令帮我获取当前系统时间并统计文本MCP开发AI工具的字数模型会自动识别并调用我们注册的两个自定义工具。五、集成 OpenAI Codex 大模型Codex无原生MCP支持通过MCP Client中转工具调用实现模型决策标准化工具执行5.1 安装依赖npminstallopenai5.2 联动代码 src/codex-agent.tsimport{Client}frommodelcontextprotocol/sdk/client/index.js;import{StdioClientTransport}frommodelcontextprotocol/sdk/client/stdio.js;importOpenAIfromopenai;constopenainewOpenAI({apiKey:process.env.OPENAI_API_KEY});asyncfunctioncodexMcpAgent(){// 初始化MCP客户端constmcpClientnewClient({name:codex-mcp-bridge,version:1.29.0});consttransportnewStdioClientTransport({command:node,args:[./dist/server.js]});awaitmcpClient.connect(transport);const{tools}awaitmcpClient.listTools();// Codex自动判断是否调用工具constchatResawaitopenai.chat.completions.create({model:code-davinci-002,messages:[{role:user,content:获取当前时间并统计文本「MCP Agent开发」字数}],tools:tools,tool_choice:auto});constmessagechatRes.choices[0].message;if(message.tool_calls){for(constcallofmessage.tool_calls){constresultawaitmcpClient.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}关键配置说明private: true禁止公网发布仅私有仓库可用bin安装后全局命令ts-mcp-server一键启动prepublishOnly发布前自动编译保证dist文件最新。6.2 完整发包流程解决CNPM/OTP报错问题1CNPM报错 Public registration is not allowed淘宝镜像registry.npmmirror.com关闭公共注册登录/发包必须切换官方源# 切换官方NPM源npmconfigsetregistry https://registry.npmjs.org/# 校验源是否切换成功npmconfig get registry问题2npm login invalid otp 验证码无效开启设备自动同步时间OTP基于时间校验时差超30s直接失效关闭VPN/代理避免时区错乱长期方案使用永久Access Token替代验证码登录# 官网npmjs.com创建Classic Publish Token登录时密码粘贴tokennpmlogin --auth-typelegacy发布步骤# 1. 编译代码npmrun build# 2. 登录官方npm源npmlogin# 3. 发布私有包npmpublish团队安装使用npminstallteam/ts-mcp-server# 全局命令启动MCP服务ts-mcp-server七、高频踩坑汇总TS2307 找不到 client/mcp.js1.29.0版本客户端无McpClient仅服务端支持McpServer客户端统一使用原生ClientTS2591 Buffer类型不存在tsconfig新增types: [node]确保安装types/nodeTS5110 module配置不匹配module、moduleResolution必须同时为NodeNextClaude MCP挂载失败使用claude mcp add命令行挂载路径必须填绝对路径CNPM无法登录发包发包强制切换官方registry日常安装包可切淘宝镜像加速invalid otp 验证码报错同步系统时间使用永久Publish Token绕过动态验证码。八、适用业务场景企业内部文档处理Agent封装文件读取、摘要、格式转换工具业务智能问答MCP Resources存储知识库Tools调用业务接口多模型统一工具中台一套MCP服务同时对接Claude、GPT、CodexIDE本地AI插件Claude Code挂载私有工具实现自定义工程化能力。九、总结基于TypeScriptMCP 1.29.0搭建AI Agent工具层是当前工程化最优方案通过标准化协议解耦模型与业务逻辑依托TS强类型降低线上异常同时支持Claude Code本地接入、私有NPM包团队复用适合企业规模化AI应用落地。