MCP 实战第 1 篇。先厘清概念、角色与业务边界再运行一个不需要模型密钥的本地练习。本文不安装 MCP SDK不启动 MCP 服务也不声称已经接入任何 AI 客户端。在前面的 Dify 系列中我们已经搭建应用、调用工作流并给业务后端补上了任务管理。接下来一个很自然的需求是让 AI 查询项目缺陷、读取团队文档再把相关信息整理成一份测试建议。这时常常会听到四种说法“调一下 API”“装个插件”“接一个 MCP”“做成 Agent”。它们可能出现在同一套系统中却各自解决不同问题。如果一开始就混在一起后面很容易把配置成功当成业务可用把模型说“查到了”当成实际访问过系统。本文用一个贯穿案例展开团队研发助手查询某个项目尚未关闭的缺陷并按原始记录生成摘要。第一步只允许查询创建和修改缺陷放到后续有权限控制的章节再讨论。一、从业务需求开始理解 MCP假设测试人员问“帮我看看演示项目有哪些未关闭的缺陷。”要回答这句话系统至少得完成下面几件事识别项目找到能够查询缺陷的能力把参数交给实际程序执行取得记录再整理答案。语言模型本身不会因为听到项目名称就自然拥有你公司缺陷平台的登录权限。即使模型能根据上下文组织出一段像样的报告也不代表这些缺陷真的存在。我们需要一条能检查执行结果的信息通道。MCP 的全称是 Model Context Protocol。它约定 AI 应用与提供工具、资料等能力的程序怎样交换信息。官方将其定位为上下文交换协议模型推理与上下文的具体管理仍属于 AI 应用的职责。MCP 官方架构概览放到这个案例里我们可以编写一个缺陷查询服务让它暴露list_demo_issues这样的工具。支持相关能力的 AI 客户端接入后可以发现工具的名称和参数结构并通过协议请求执行。真正查数据的仍然是服务端业务代码。它可以访问本地样例也可以在正确授权后调用缺陷平台 API。MCP 不会替你生成真实业务权限也不会让一个查询函数自动变成完整的测试平台。二、API、插件、MCP、Agent 分别处在哪一层为了方便讨论本文采用下面这组工程口径。尤其“插件”和“Agent”在不同产品中有不同含义不能把这张表理解为所有厂商共同遵守的定义。名称主要关注的问题放到缺陷查询案例里API程序通过什么接口请求另一项能力缺陷平台提供查询接口插件某个宿主产品怎样扩展功能客户端安装一个缺陷平台扩展MCPAI 应用怎样按统一协议发现、访问相关能力服务暴露可查询的工具及其参数Agent系统怎样围绕目标选择动作、观察结果并继续处理判断要先查缺陷再读取需求最后整理建议这里的 API 不特指 HTTP。我们后续接第三方平台时会经常用到 HTTP API因此也会遇到地址、认证头、状态码等内容。插件则取决于宿主产品提供的扩展机制。一个插件可以直接调用 HTTP API也可能包含 MCP 接入逻辑。只看到“插件安装成功”还需要继续检查它提供了哪些能力、实际使用哪一套凭据。MCP 服务也可能只是已有 API 外面的一层适配将平台接口整理成适合 AI 使用的工具描述、输入约束与结果。平台 API 仍然存在业务错误和权限校验也仍然需要处理。至于 Agent本文关注的是执行过程模型或程序根据目标选择下一步宿主检查请求工具完成操作然后系统根据观察结果决定继续或结束。它可以使用 MCP 工具也可以只使用普通函数。接入 MCP 后是否需要自主规划要由具体任务决定。例如“读取一个已知 ID 的缺陷并展示字段”普通脚本可能已经足够。若需求是“先理解问题、检索相关缺陷再决定还缺哪些信息”才有必要讨论更复杂的任务组织方式。三、谁在连接谁Host、Client、ServerMCP 架构中的 Host、Client、Server 分别承担应用管理、协议连接与能力提供的职责。它们是逻辑角色不需要机械地理解成三台机器。官方架构说明角色本文案例中的职责Host承载交互组织模型、连接配置与工具执行策略Client在 Host 一侧与某个 MCP Server 进行协议通信Server暴露缺陷查询能力执行业务校验并返回结果可以把一次查询画成下面这条路径。箭头只表示业务交互关系省略了版本协商、错误处理和具体传输细节测试人员提出问题 ↓ AI 应用 Host识别意图组织工具请求与权限检查 ↓ Host 内的 MCP Client ↓ MCP 协议通信 缺陷查询 MCP Server ↓ 本地演示数据 / 经过授权的缺陷平台 API ↓ 结构化结果 → Host → 整理给用户的回答不要把模型生成的工具调用意图等同于实际执行。宿主可能拒绝该调用服务器也可能因参数错误或权限不足返回失败。只有工具实际返回可核验的结果系统才有相应的数据依据。同样Server 可以是本机进程也可以运行在远程环境。官方列出 stdio 与 Streamable HTTP 等传输方式具体接入时需要匹配客户端、服务实现和协议版本。官方传输说明本系列不会在这一篇手写握手消息避免把某个版本的底层示例当成所有客户端都能照抄的配置。后续进入安装篇时再明确采用的 SDK、运行环境和验证方式。四、Tools、Resources、Prompts 怎样选一个服务不必同时实现所有能力。先确定业务需要再选择合适的表达方式。Tools 用于明确的操作。查询缺陷、计算统计或创建记录都可以设计成工具。名称、描述和参数结构应让调用方知道“做什么、需要什么、会得到什么”。官方工具规范定义了tools/list和tools/call等操作。Tools 规范在本文中list_demo_issues只查询固定虚构项目。这里特意保留了 demo 字样让操作者不容易把样例误当成真实生产数据。Resources 用于提供上下文资料。比如项目说明、字段字典和接口文档可以作为资源供应用读取。读取哪些内容、如何放进模型上下文由宿主应用组织不能假定服务器提供的全部资料都会自动进入每轮对话。Resources 规范Prompts 用于提供可复用的提示模板。例如“根据给定缺陷记录生成测试风险摘要”可以预先约定输入和输出要求。模板可以帮助表达任务但不能代替查询程序也不能凭空补齐缺失的数据。Prompts 规范团队需求本文建议的起点按项目和状态查询缺陷一个查询 Tool提供团队字段说明一份 Resource统一风险摘要的组织方式一份 Prompt判断是否还要查询其他资料Host 或 Agent 的任务组织逻辑具体客户端可能只实现其中一部分界面呈现也可能不同。不能只凭“支持 MCP”就认定它完整支持某个服务器的全部能力。五、先把一个工具的职责写清楚现在回到团队研发助手。第一版只解决一件事读取固定演示项目中的 open 或 closed 缺陷限制返回数量并明确标识结果来自本地样例。我们先给业务函数约定以下输入和输出项目约定项目固定为 demo-project状态open 或 closed默认 open数量整数 120默认 10返回数据来源、查询条件、返回条数、缺陷列表副作用不写文件不调用外部平台不修改缺陷不要一开始就提供“执行任意 SQL”“请求任意网址”这样的入口。对于当前案例它们增加了实现范围却没有帮助我们更清楚地表达缺陷查询需求。下面是单个工具定义的示意保存为mcp-01-tool-definition-demo.json。它展示名称、描述和输入 schema不是完整协议响应也不能单独作为客户端配置文件使用。此文件没有被下文函数自动加载默认值和校验分别由 Python 实现真正注册时再检查两者是否一致。{name:list_demo_issues,description:查询固定虚构项目中的演示缺陷。只返回本地样例不访问真实缺陷平台。,inputSchema:{type:object,properties:{project:{type:string,enum:[demo-project]},status:{type:string,enum:[open,closed],default:open},limit:{type:integer,minimum:1,maximum:20,default:10}},required:[project],additionalProperties:false}}参数里的 project 只是调用者提供的查询条件。即使 schema 将它限制为固定值也不能把这个设计推广成真实鉴权机制。接入真实平台时要根据可信登录身份在服务端决定允许访问哪些项目。六、完整本地练习先验证业务函数保存为mcp-01-business-demo.py。练习只使用 Python 标准库建议使用 Python 3.10 或更新版本本次实际运行环境为 macOS、Python 3.13.3。Local business-function exercise only. Not an MCP server or protocol client.importargparseimportjson PROJECTdemo-projectISSUES({id:DEMO-001,title:演示提交按钮重复响应,status:open},{id:DEMO-002,title:演示报告标题显示异常,status:open},{id:DEMO-003,title:演示空列表提示缺失,status:closed},)deflist_demo_issues(project,statusopen,limit10):# A fixed demo project is a fixture boundary, not a real authorization system.ifproject!PROJECT:raisePermissionError(demo_project_only)ifnotisinstance(status,str)orstatusnotin{open,closed}:raiseValueError(invalid_status)iftype(limit)isnotintornot1limit20:raiseValueError(invalid_limit)rows[dict(row)forrowinISSUESifrow[status]status][:limit]return{source:local-fixture,project:PROJECT,status:status,count:len(rows),issues:rows}defmain():parserargparse.ArgumentParser(description__doc__)parser.add_argument(--project,requiredTrue)parser.add_argument(--status,defaultopen,choices[open,closed])parser.add_argument(--limit,default10,typeint)argsparser.parse_args()try:resultlist_demo_issues(args.project,args.status,args.limit)except(ValueError,PermissionError)aserror:print(json.dumps({error:str(error)}))return2print(json.dumps(result,ensure_asciiFalse,indent2))return0if__name____main__:raiseSystemExit(main())这个文件只是后续准备封装的业务能力目前没有 MCP 通信层。它不使用模型不会出现在任何客户端的工具列表里也没有启动监听服务。Mac 终端中在保存文件的目录执行python3 mcp-01-business-demo.py--projectdemo-project--statusopen--limit10Windows PowerShell 中py-3 mcp-01-business-demo.py--project demo-project--status open--limit 10如果 Windows 中的 Python 安装没有提供 py 启动器使用自己的 Python 解释器执行同一文件。这里不要求安装 Docker、Node.js 或客户端应用。输出应包含sourcelocal-fixture、count2以及 DEMO-001、DEMO-002 两条 open 记录。将--status改为 closed会得到 DEMO-003将--limit改为 1只返回一条。再执行一次错误项目查询python3 mcp-01-business-demo.py--projectother-project预期输出为下面的业务拒绝进程退出码为 2Windows 只需替换解释器命令。{error:demo_project_only}这组限制让练习具有确定的边界但还没有真实用户、项目权限或远程认证。不要把它包装成“已经完成安全的企业查询服务”。七、给业务能力保留一份可重复检查保存为mcp-01-test-business-demo.py与业务脚本放在同一个目录。测试检查查询、过滤、数量限制、非法参数和结果副本不会连接任何真实设备或服务。Run beside mcp-01-business-demo.py. All records are local fixtures.importimportlib.utilfrompathlibimportPathimportunittest specimportlib.util.spec_from_file_location(business,Path(__file__).with_name(mcp-01-business-demo.py))businessimportlib.util.module_from_spec(spec)spec.loader.exec_module(business)classBusinessTests(unittest.TestCase):deftest_open_issues(self):resultbusiness.list_demo_issues(demo-project)self.assertEqual(result[count],2)self.assertEqual(result[source],local-fixture)self.assertTrue(all(row[status]openforrowinresult[issues]))deftest_closed_issues(self):self.assertEqual(business.list_demo_issues(demo-project,closed)[issues][0][id],DEMO-003)deftest_limit(self):self.assertEqual(business.list_demo_issues(demo-project,limit1)[count],1)deftest_other_project_rejected(self):withself.assertRaises(PermissionError):business.list_demo_issues(other-project)deftest_invalid_status(self):forstatusin(all,[],None):withself.subTest(statusstatus),self.assertRaises(ValueError):business.list_demo_issues(demo-project,status)deftest_invalid_limit(self):forlimitin(0,21,True,1.0,2):withself.subTest(limitlimit),self.assertRaises(ValueError):business.list_demo_issues(demo-project,limitlimit)deftest_result_does_not_mutate_fixture(self):resultbusiness.list_demo_issues(demo-project)result[issues][0][title]changedself.assertNotEqual(business.list_demo_issues(demo-project)[issues][0][title],changed)if__name____main__:unittest.main(verbosity2)运行方式python3 mcp-01-test-business-demo.pyWindows 使用py -3 mcp-01-test-business-demo.py。本次实际结果为 7 个测试通过。这能证明本地函数满足当前样例约定不能证明 MCP 客户端发现、协议协商和真实模型工具选择已经通过。先把业务函数和协议适配分开有助于以后定位问题函数直接执行都失败先修业务实现函数正确而客户端看不到工具再检查服务注册和连接配置客户端看到工具却没有调用还需要查看描述、上下文、权限与模型行为。八、什么时候值得引入 MCP如果你只有一个固定脚本每天由一个定时任务执行普通函数或 API 调用可能更容易维护。选择 MCP 的理由应来自实际接入需求例如希望让不同的兼容 AI 客户端发现同一组能力或者将业务工具独立维护。对本文团队助手而言先完成一个只读工具比一次接通文档、数据库、缺陷创建、通知发送更便于验收。前者能逐项检查输入条件、实际执行和返回记录后者遇到问题时很难判断卡在哪一层。选择接入方式前可以回答四个问题谁会使用这个工具数据归谁管理允许读写哪些内容以及发生错误时怎样拿到执行证据。答案不明确时增加协议层通常不会自动解决这些问题。九、不要把“接通了”当作“能放心使用”一个真实的查询链路至少要分别验收服务是否能启动、客户端能否发现工具、传入参数是否经过校验、是否按用户身份限制项目、返回内容是否来自真实请求以及最后答案是否忠实于记录。后续还需要区分三种情况查询成功但没有记录查询失败以及返回结果被限制了数量。它们应有不同证据不能都用一句“没有发现问题”带过。本篇的 count 仅表示实际返回条数不表示整个项目缺陷总量。写操作则需要独立设计。比如创建缺陷时网络超时后是否已经创建成功、重复请求是否会多建一条、操作者能否修改这个项目都属于具体业务合同。MCP 不会自动提供这些业务保证。同样工具返回的文档或缺陷描述是业务数据里面即使出现“忽略规则”等文字也不能自动变成新的操作授权。这个原则要体现在宿主的任务策略和工具的权限检查中不能只放在提示词结尾作为一句口号。十、这一篇完成了什么下一篇写什么这一篇已经把一个抽象需求拆成可讨论的连接关系并准备了一份可运行、可检查的业务函数。没有发起真实 MCP 调用没有使用大模型密钥没有接入缺陷平台也没有在 Windows 实机执行。下一篇进入《MCP 开发环境搭建Mac 与 Windows》核对选用的 Python SDK 和客户端支持再准备真正的服务与连接验证。官方 Python SDK 的实现与说明会持续变化安装时应锁定明确版本不要把本篇的本地函数直接当成 SDK 示例。官方 Python SDK后续仍以团队研发助手为主线依次加入工具注册、文件资料、HTTP 查询、数据库只读访问、权限、日志和部署。MySQL MCP、桌面客户端与浏览器工具会在相应章节结合具体场景展开本系列先把基础连接与验证方法补齐。核对日期2026-10-29。角色、传输和服务器能力的具体引用见各节固定版本链接用于说明对应版本的概念不代表本篇已经安装了该协议版本的 SDK。客户端配置和协议消息细节会在后续实操篇单独固定与验证。