前言说实话MCP 协议从去年底爆火到现在已经成了 AI 开发圈绕不开的话题。但你真要动手写一个 Server很多教程要么讲得太浅要么跳过了关键细节。今天就手把手带大家写一个文件搜索工具 MCP Server功能很简单让 AI 能通过 MCP 协议搜索本地文件。但麻雀虽小五脏俱全整个过程你能完整理解 MCP 的工作原理。MCP 是什么一句话说清楚MCP (Model Context Protocol) 是 Anthropic 去年推出的一种开源协议专门解决 AI 模型和外部工具之间的通信问题。通俗点说MCP 就是 AI 世界的 USB 接口。以前你给 AI 加功能每个 AI 有自己的一套插件系统像不同品牌的充电器不通用。MCP 统一了接口标准写一次工具任何支持 MCP 的 AI 客户端都能用。环境准备首先确保你的环境满足以下条件# Python 3.10python--version# 安装 MCP 开发包pipinstallmcp我们用 Python 实现因为生态最成熟。如果你不会 Python用 TypeScript 也行官方支持两种语言。第一步定义工具MCP Server 的核心是暴露工具Tool给 AI 调用。每个工具需要定义名称— AI 调用时用的标识符参数描述— 告诉 AI 需要什么参数实现逻辑— 实际干活的代码frommcp.serverimportServerfrommcp.typesimportTool,TextContentfromtypingimportAnyimportosimportfnmatch# 创建 Server 实例serverServer(file-search-server)# 注册工具server.list_tools()asyncdeflist_tools()-list[Tool]:return[Tool(namesearch_files,description搜索本地文件支持通配符模式,inputSchema{type:object,properties:{pattern:{type:string,description:文件搜索模式例如 *.py 或 data/*.csv},root_dir:{type:string,description:搜索根目录默认为当前目录},max_results:{type:integer,description:最大返回结果数默认 20,default:20}},required:[pattern]})]第二步实现工具逻辑工具定义好了接下来实现 AI 发起调用时实际执行的代码server.call_tool()asyncdefcall_tool(name:str,arguments:dict)-list[TextContent]:ifnamesearch_files:patternarguments[pattern]root_dirarguments.get(root_dir,.)max_resultsarguments.get(max_results,20)results[]forroot,dirs,filesinos.walk(root_dir):# 跳过隐藏目录dirs[:][dfordindirsifnotd.startswith(.)]# 跳过 node_modules 等大目录dirs[:][dfordindirsifdnotin(node_modules,__pycache__,.git,venv)]forfilenameinfiles:iffnmatch.fnmatch(filename,pattern):filepathos.path.join(root,filename)try:sizeos.path.getsize(filepath)results.append({path:filepath,size:size,size_str:format_size(size)})exceptOSError:continue# 按大小排序最大的在前results.sort(keylambdax:x[size],reverseTrue)resultsresults[:max_results]return[TextContent(typetext,textformat_results(results,pattern))]else:raiseValueError(fUnknown tool:{name})第三步传输层配置MCP 支持两种传输方式标准输入输出stdio和 SSEServer-Sent Events。本地开发用 stdio 最简单defformat_size(size:int)-str:格式化文件大小forunitin[B,KB,MB,GB]:ifsize1024:returnf{size:.1f}{unit}size/1024returnf{size:.1f}TBdefformat_results(results:list[dict],pattern:str)-str:格式化搜索结果ifnotresults:returnf没有找到匹配 {pattern} 的文件lines[f找到{len(results)}个匹配 {pattern} 的文件\n]forrinresults:lines.append(f-{r[path]}({r[size_str]}))return\n.join(lines)if__name____main__:frommcp.server.stdioimportstdio_serverimportasyncioprint(启动 MCP File Search Server...)asyncio.run(stdio_server(server))第四步配置客户端Server 写好了怎么让 AI 用起来以 Claude Desktop 为例{mcpServers:{file-search:{command:python,args:[path/to/search_server.py]}}}配置完成后重启 Claude DesktopAI 就能自动发现并使用你的文件搜索工具了。踩坑指南写 MCP Server 最常遇到的几个坑1. 参数描述不够详细AI 模型依赖参数描述来理解怎么用。如果描述太模糊AI 可能传错参数。建议每个参数都写清楚「这个参数干什么用的」「什么格式」。2. 超时处理MCP 默认有超时时间如果你的工具执行时间太长比如扫描几百万个文件AI 会超时。建议加入超时限制和进度反馈。3. 工具返回值太长AI 模型的上下文窗口有限一次性返回太多结果会被截断。建议加 max_results 限制或者分页返回。# 加入超时控制的改进版本importasyncioimportsignalasyncdefsearch_with_timeout(pattern,root_dir,max_results,timeout30):try:resultawaitasyncio.wait_for(search_files_async(pattern,root_dir,max_results),timeouttimeout)returnresultexceptasyncio.TimeoutError:return[{error:搜索超时请缩小搜索范围}]进阶玩法写完了基础版你还可以扩展更多功能文件内容搜索结合 grep 模式搜索文件内容实时文件监控用 watchfiles 监听文件变化多 Agent 协作让多个 MCP Server 协同工作总结MCP 协议的价值不在于技术有多复杂而在于它定义了一个通用的接口标准。以前的 AI 工具链像一个个孤岛MCP 就是连接这些孤岛的桥梁。写完这个 demo 你会发现MCP 本身并不难真正的难点在于设计好的工具接口。好的工具接口 清晰的参数描述 合理的错误处理 可预期的行为。下一步推荐你试试把搜索工具改成异步实现asyncio加上文件内容预览功能试试用 SSE 模式部署成远程服务有什么问题欢迎在评论区讨论
企业数字化 ERP 产品动态
相关推荐
FILCO方法：提升检索增强生成中的上下文过滤技术 1. 项目概述：检索增强生成中的上下文过滤技术 在开放域问答和事实核查等知识密集型任务中，动态检索相关知识已成为构建可靠系统的关键环节。但现实场景中，检索系统返回的结果往往包含不相关甚至误导性内容，这会导致生成模型出现两… · 2026/8/24 23:15:41
2026年在线问诊平台口碑榜：这5个平台用着最放心 2026年在线问诊平台口碑榜：这5个平台用着最放心
你家娃半夜发烧，跑医院排队3小时才挂上号，医生看诊只用了3分钟。这样的场景，多少家长经历过？截至2025年，中国在线问诊用户规模已超3.5亿，但平台质… · 2026/9/21 11:53:38
2026年空调热泵销售厂家口碑揭秘：这3家为何备受青睐？ 2026年，空调热泵市场竞争进入白热化阶段。从北方“煤改电”的持续加码，到南方工业厂房恒温恒湿需求爆发，用户选厂越来越理性——不再只看价格，而是死磕“核心部件真实案例”。过去一年，我调研了超过200个投标现场&… · 2026/8/3 9:32:21
别再乱买seo优化推广软件了这3个最佳实践省一半钱 别再乱买seo优化推广软件了这3个最佳实践省一半钱 改个需求建站公司拖一周，这是多少中小老板的噩梦？你急得抓耳挠腮，对方却在群里回个“正在处理”，这种被动等待的日子，靠花钱买所谓的“seo优化推广软件”能解决吗？别天真了。软件只是工具，不懂… · 2026/9/27 14:34:42
网站一直百度上搜不到是怎么回事：3个排查步骤+对比评测 网站一直百度上搜不到是怎么回事：3个排查步骤+对比评测 刚把新站丢到百度里搜，半天没动静？别急，先看看是不是备案流程卡住了，或者服务器配置出了岔子。我见过太多新手因为搞不清备案流程一头雾水，导致网站权重被降，这时候盲目做SEO全是无用功。今… · 2026/9/27 14:34:30
湖北建设网站信息查询中心从零搭建:搞定备案不迷路 湖北建设网站信息查询中心从零搭建:搞定备案不迷路 第一次接到“湖北建设网站信息查询中心”这个需求时，我脑子里蹦出的第一个念头不是技术多难，而是 备案流程一头雾水… · 2026/9/27 14:34:30
织梦网站模板怎么做完整流程含安全加固实战 织梦网站模板怎么做完整流程含安全加固实战 域名服务器搞不懂，是很多新手接手织梦（DedeCMS）项目时最头疼的坑。你以为买了个便宜模板，上传就能用，结果后台打不开、前台报错，甚至被黑客植入了暗链，这时候才意识到： 织梦网站模板怎么做… · 2026/9/27 14:34:23
wordpress头部工具栏优化5大注意事项与源码解析 wordpress头部工具栏优化5大注意事项与源码解析 刚接到个急活，客户急着上线外贸站，结果后台一打开，那个熟悉的灰色条状物——WordPress 默认头部工具栏（Admin… · 2026/9/27 14:33:57
网站开发与建设主要干什么？揭秘费用明细与免费工具避坑指南 网站开发与建设主要干什么？揭秘费用明细与免费工具避坑指南 网站做好了没人访问，这是90%企业老板上线后最头疼的噩梦。别急着怪算法，先看看你手里的钱是不是花错了地方。很多甲方拿着预算单，心里没底，不知道 网站开发与建设主要干什么… · 2026/9/27 14:33:57
MATLAB雷达信号脉冲压缩仿真：LFM线性调频、匹配滤波与距离分辨率实现 简介：这套Matlab仿真工具完整呈现雷达信号脉冲压缩过程，从线性调频（LFM）信号生成、目标回波仿真到匹配滤波压缩处理均有可运行代码支撑，面向电子信息工程、计算机、数学等专业学生，适用于课程设计、期末大作… · 2026/9/27 0:00:01
汕头网站建设制作厂家避坑指南：5大注意事项救急 汕头网站建设制作厂家避坑指南：5大注意事项救急 改个需求建站公司拖一周，这种憋屈事我见得太多了。 很多汕头老板找本地建站团队，签合同前看着方案挺美，一上线就变脸。 今天不聊虚的，直接拆解找 汕头网站建设制作厂家 时的5个核心 注意事项… · 2026/9/27 0:00:01
多模态虚假新闻检测实战：BERT+ResNet双塔与对比学习 简介：基于PyTorch的多模态虚假新闻检测项目完整代码包，面向自然语言处理与计算机视觉交叉方向的开发者、科研人员及毕业设计选题者，解决社交媒体中文本与图像联合识别虚假新闻的问题。系统以BERT预训练模型提取文本语义特征，以Res… · 2026/9/27 0:00:01
MATLAB雷达信号脉冲压缩仿真：LFM线性调频、匹配滤波与距离分辨率实现 简介：这套Matlab仿真工具完整呈现雷达信号脉冲压缩过程，从线性调频（LFM）信号生成、目标回波仿真到匹配滤波压缩处理均有可运行代码支撑，面向电子信息工程、计算机、数学等专业学生，适用于课程设计、期末大作… · 2026/9/27 0:00:01
汕头网站建设制作厂家避坑指南：5大注意事项救急 汕头网站建设制作厂家避坑指南：5大注意事项救急 改个需求建站公司拖一周，这种憋屈事我见得太多了。 很多汕头老板找本地建站团队，签合同前看着方案挺美，一上线就变脸。 今天不聊虚的，直接拆解找 汕头网站建设制作厂家 时的5个核心 注意事项… · 2026/9/27 0:00:01
多模态虚假新闻检测实战：BERT+ResNet双塔与对比学习 简介：基于PyTorch的多模态虚假新闻检测项目完整代码包，面向自然语言处理与计算机视觉交叉方向的开发者、科研人员及毕业设计选题者，解决社交媒体中文本与图像联合识别虚假新闻的问题。系统以BERT预训练模型提取文本语义特征，以Res… · 2026/9/27 0:00:01
