《实用笔记：模型上下文协议（MCP）详解——初学者指南》

可将此内容视为《Model Context Protocol (MCP)详解：初学者指南》中概念面向操作员的简化版本：清晰的阶段划分、有序的代码模块，以及能在交接过程中保留的恢复说明。 将“概览”阶段视为可量化的界面使用效果最佳。在扩大范围之前，先记录一份理想的操作日志、一个故障案例以及回滚说明。 应将配置与应用程序代码分开。环境文件、密钥存储和功能标志应集中存放于一个位置，以便操作员无需查看整个系统结构即可进行审核。

MCP最简明的解释

在最简单的解释阶段，应在修改代码之前明确输入内容、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。 当下一步操作是编写代码或调用工具时，应优先使用具有结构化格式且经过模式验证的输出，而非自由形式的文字描述。

MCP试图解决的问题

针对MCP阶段存在的问题，在修改代码之前应明确输入参数、该步骤的负责人以及终止标准。操作人员应当能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比冗长的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能指向单一责任主体，而非复杂的流程链。如果后续步骤是代码调用或工具调用，相比自由形式的文字描述，带有架构验证的结构化输出更为合适。

AI application A → Git integration
AI application A → database integration
AI application A → issue-tracker integration

AI application B → Git integration
AI application B → database integration
AI application B → issue-tracker integrationAI application C → Git integration
AI application C → database integration
AI application C → issue-tracker integration

AI applications → MCP interface → external systems

必须分开处理的三个层次

对于所划分的三个层次，在修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将这一阶段视为输入与已验证输出之间的契约。为相关成果命名，定义成功判定条件，并拒绝默许的半完成状态。 当下一步操作为代码编写或工具调用时，优先采用具有架构验证的结构化输出，而非自由形式的文本描述。 对于所划分的三个层次，在修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个操作人员可审计的位置，无需查看整个系统结构。

1. AI模型

在处理“AI模型”这一阶段时，首先需明确相关约定：所需的输入参数、成功标志，以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误消息处理都是产品功能的一部分，而非后续需要补充的内容。 对稳定的系统指令和工具结构进行缓存。重复发送相同的开头信息是导致资源浪费的常见原因。

2. MCP

在处理两个MCP阶段时，首先写下契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应能指向单一的责任模块，而非复杂的流程链。 缓存稳定的系统指令和工具架构。重复发送相同的开头信息是导致资源浪费的常见原因。

3. 底层系统

在处理“底层系统”阶段的三个步骤时，首先需写下契约：所需的输入参数、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 将此阶段视为输入与已验证输出之间的契约。为相关组件命名，明确成功判定标准，杜绝无声的半完成状态。 缓存稳定的系统指令和工具架构。重复发送相同的开头信息是导致资源浪费的常见原因。 在处理“底层系统”阶段的三个步骤时，首先需写下契约：所需的输入参数、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一处，以便操作人员无需查看整个系统结构即可进行审计。

AI model:
“What should I ask for?”

MCP:
“How do I request it in a standard way?”Underlying system:
“What is the authoritative result?”

MCP主机、客户端与服务器

将MCP主机、客户端及相关流程视为可度量的对象，才能实现最佳运行效果。在扩大范围之前，需记录一份成功的操作案例、一个故障场景以及回滚说明。同时将正常流程与恢复流程都记录下来。重试机制、人工审核环节以及错误处理方式都是产品本身的一部分，而非后续需要补充的内容。需为每次交互及每个会话设定令牌预算——智能工具往往会大量消耗上下文，设置上限可避免演示过程变成意外的费用账单。

MCP主机

MCP主机阶段在被视为可测量的界面时表现最佳。在扩大范围之前，先记录一份成功的示例、一个故障案例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤出现故障时，故障应指向单一责任模块，而非复杂的流程链。 为每轮对话和每次会话设定令牌预算。智能代理工具会大量消耗上下文资源，设置上限可避免演示过程变成意外的费用账单。

MCP客户端

MCP客户端阶段若被视作可度量的工作面，效果会最佳。在扩大范围之前，需记录一份理想的处理结果、一个故障案例以及回滚说明。 应将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，杜绝默许的半完成状态。 需为每轮对话及每次会话设定token预算。智能工具往往会过度扩展上下文，设置上限可避免演示过程变成意外的费用账单。 MCP客户端阶段若被视作可度量的工作面，效果会最佳。在扩大范围之前，需记录一份理想的处理结果、一个故障案例以及回滚说明。 应将配置信息置于应用程序代码之外。环境文件、密钥存储及功能开关应集中存放于一处，以便操作人员无需查看整个系统结构即可进行审计。

AI development environment
    ├── MCP client → source-control server
    ├── MCP client → documentation server
    └── MCP client → test-results server

MCP服务器

在MCP服务器阶段，修改代码之前需先明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误消息处理都是产品功能的一部分，而非后续需要补充的内容。 当下一步操作为代码编写或工具调用时，应优先使用具有结构化格式且经过模式验证的输出，而非自由形式的文本。

MCP的三种基本元素：工具、资源与提示词

对于三个MCP基础操作阶段，在修改代码之前需明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比冗长的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能指向单一责任主体，而非复杂的流程链。若后续步骤为代码或工具调用，应优先使用具有结构化格式且经过模式验证的输出，而非自由形式的文字描述。

1. 工具

在“1个工具”阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将此阶段视为输入与已验证输出之间的契约。为相关成果命名，定义成功判定条件，并拒绝默许的半完成状态。 当下一步操作为代码编写或工具调用时，优先采用具有架构验证的结构化输出，而非自由形式的文本描述。 在“1个工具”阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将配置信息置于应用程序代码之外。环境文件、密钥存储及功能开关应集中存放于一个操作人员可审核的位置，无需阅读整个系统结构。

search_documents(query)
get_weather(location)
compare_test_runs(current_run, baseline_run)
create_issue_draft(title, description)
calculate_total(values)

工具可获取信息或产生副作用

在处理“工具可获取信息”这一阶段时，首先需明确相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复流程。重试机制、人工审核环节以及错误消息处理都是产品本身的一部分，而非后续需要补充的功能。 缓存系统中稳定的指令及工具结构。重复发送相同的开头信息是导致资源浪费的常见原因。

get_build_status(build_id)

trigger_build(branch)

2. 资源

在处理“2个资源”阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 优先选择小型且可测试的单元，而非冗长的脚本。当某个步骤失败时，故障应能指向单一的责任模块，而非复杂的流程链。 缓存系统中稳定的指令和工具结构。重复发送相同的开头信息是导致资源浪费的常见原因。

docs://onboarding/mcp-overview
database://schemas/orders
regression://runs/RUN-2048/summary
artifact://builds/BUILD-701/manifest

3. 提示语

在完成“3个提示词”阶段时，首先需写下契约：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持透明。 将此阶段视为输入与验证后输出之间的契约。为相关成果命名，明确成功判定标准，杜绝无声的半完成状态。 缓存稳定的系统指令和工具架构。重复发送相同的开头信息是造成资源浪费的常见原因。 在完成“3个提示词”阶段时，首先需写下契约：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持透明。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一处，以便操作人员无需查看整个系统结构即可进行审计。

compare_releases:
    current_version
    baseline_version
    audience

工具、资源与提示词

将工具、资源与阶段视为可度量的指标最为有效。在扩大范围之前，先记录一份最佳案例、一个失败案例以及回滚说明。同时记录正常流程与恢复流程。重试机制、人工审核环节以及死信处理都是产品的一部分，而非后续需要补充的内容。为每轮对话和每次会话设定预算额度。智能工具会大量消耗上下文信息，设置上限可避免演示过程变成意外的费用账单。

MCP支持的助手使用工具时会发生什么？

当将某个阶段视为可测量的对象时，其效果会最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某一步骤失败时，故障应能指向单一的责任主体，而非复杂的流程链。 为每轮对话和每次会话设定预算额度。智能工具会大量消耗上下文资源；设置上限可避免演示过程变成意外的费用账单。

第一步：用户提出请求

在将“第一步：用户阶段”视为可度量的对象时，其效果最佳。在扩大范围之前，需记录一份理想的操作日志、一个故障案例以及回滚说明。 应将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，绝不允许出现悄无声息的半完成状态。 需为每轮对话及每次会话设定token预算。智能工具往往会过度扩展上下文，设置上限可避免演示过程变成意外的费用账单。 在将“第一步：用户阶段”视为可度量的对象时，其效果最佳。在扩大范围之前，需记录一份理想的操作日志、一个故障案例以及回滚说明。 应将配置信息置于应用程序代码之外。环境文件、密钥存储及功能开关应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。

第二步：主机查看可用功能

在第二步“主机阶段”中，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。 当下一步操作为代码编写或工具调用时，应优先使用具有结构化格式且经过模式验证的输出，而非自由形式的文字描述。

get_latest_run()
get_last_successful_run()
compare_runs(current_run_id, baseline_run_id)

第三步：模型选择工具

在第三步的模型阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比冗长的脚本，更应采用小型且可测试的单元。当某一步骤失败时，故障原因应能指向单一责任主体，而非复杂的流程链。如果后续步骤是代码调用或工具调用，相比自由形式的文字描述，结构化且经过模式验证的输出更为合适。

{
  "current_run_id": "RUN-5021",
  "baseline_run_id": "RUN-4989"
}

第四步：主机实施控制

在第四步“主机阶段”中，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将此阶段视为输入与已验证输出之间的契约。为相关成果命名，定义成功判定条件，并拒绝默许的半完成状态。 当下一步操作为代码编写或工具调用时，优先采用具有架构验证的结构化输出，而非自由形式的文本描述。 在第四步“主机阶段”中，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个操作人员可审计的位置，无需查看整个系统结构。

第5步：服务器调用底层系统

在处理“服务器”这一阶段时，首先需明确相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复流程。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。 对稳定的系统指令和工具结构进行缓存。重复发送相同的开头信息是导致资源浪费的常见原因。

第6步：结果返回给模型

在完成第6步“结果生成”阶段时，首先写下相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 建议使用小型、可测试的单元，而非冗长的脚本。当某一步骤失败时，故障应指向单一责任模块，而非复杂的流程链。 缓存系统中稳定的指令和工具结构。重复发送相同的开头信息是导致资源浪费的常见原因。

{
  "current_pass_rate": 91.4,
  "baseline_pass_rate": 97.8,
  "new_failures": 14,
  "missing_results": 7,
  "matching_known_failures": 9
}

第7步：助手解释相关证据

在完成第7步“助手阶段”时，首先需写下契约内容：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 将此阶段视为输入与验证后输出之间的契约。为相关产物命名，明确成功检测标准，并杜绝无声的半完成状态。 缓存稳定的系统指令和工具架构。重复发送相同的开头信息是导致资源浪费的常见原因。 在完成第7步“助手阶段”时，首先需写下契约内容：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一处，以便操作人员无需查看整个系统结构即可进行审计。

MCP的通信方式

将MCP的通信流程视为可测量的对象来分析最为有效。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。同时记录正常流程和恢复流程的细节。重试机制、人工审核环节以及错误处理都是产品本身的一部分，而非后续需要补充的内容。为每轮对话和每次会话设定令牌预算。智能工具会大量消耗上下文资源，设置上限可避免演示过程变成意外的费用账单。

stdio

将stdio阶段视为可测量的对象来处理时，其效果最佳。在扩大范围之前，先记录一个成功的示例、一个失败案例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应指向单一的责任模块，而非复杂的流程链。 为每轮及每次会话设定token预算。智能工具会大量消耗上下文资源；设置上限可避免演示过程变成意外的费用账单。

流式HTTP

将 Streamable HTTP 阶段视为可度量的对象来使用效果最佳。在扩大范围之前，先记录一份理想的处理结果、一个故障案例以及回滚说明。 把这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，绝不允许出现无声的半完成状态。 为每轮操作和每次会话设定令牌预算。智能工具往往会过度扩展上下文；设置上限可避免演示过程变成意外的费用账单。 将 Streamable HTTP 阶段视为可度量的对象来使用效果最佳。在扩大范围之前，先记录一份理想的处理结果、一个故障案例以及回滚说明。 将配置信息置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。

MCP 与普通 API 的区别

在将 MCP 与普通流程进行对比时，应在修改代码之前明确输入参数、各步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程与异常恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。 当下一步操作为代码编写或工具调用时，应优先使用具有结构化格式且经过模式验证的输出，而非自由形式的文本。

REST API 可能会这样表述：

A REST API在修改代码之前，应先确定阶段、输入参数、该步骤的负责人以及结束标准。操作人员应当能够从已知的检查点重新运行该步骤，而无需猜测隐藏的状态。相比冗长的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能明确指向某个具体的责任模块，而非整个复杂的流程。如果后续步骤是代码调用或工具调用，应优先使用具有结构化格式且经过模式验证的输出，而非自由形式的文本。

GET /regression/runs/5021
POST /jobs/5021/rerun

MCP服务器可以提供：

在修改代码之前，An MCP服务器应先确定该阶段的输入内容、负责执行该步骤的负责人以及完成标准。操作人员应当能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。 应将这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功判定标准，并拒绝默许部分完成的情况。 当后续步骤为代码编写或工具调用时，应优先使用具有结构化格式且经过模式验证的输出，而非自由形式的文本描述。

get_run_summary(run_id)
request_approved_rerun(run_id, test_ids)

对于An MCP服务器可能涉及的流程，应在修改代码之前明确输入参数、该步骤的负责人以及结束条件。操作员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，这样操作员无需查看整个流程即可进行审核。

MCP与函数调用的区别

在处理MCP与函数调用阶段时，首先需明确接口规范：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复流程。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。 缓存稳定的系统指令和工具架构。重复发送相同的报文是导致资源浪费的常见原因。

MCP与检索增强生成技术

在处理MCP与检索增强生成阶段时，首先明确规范：所需的输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应指向单一责任点，而非复杂的流程链。 缓存稳定的系统指令和工具架构。重复发送相同的开头信息是造成资源浪费的常见原因。

RAG:
Find the most relevant troubleshooting guide.

MCP resource:
Retrieve a specific approved troubleshooting guide.MCP tool:
Check the status of the affected service.Workflow engine:
Restart the service after approval.

MCP与AI智能体

在处理 MCP 与 AI 阶段时，首先需明确契约内容：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 将这一阶段视为输入与验证后输出之间的契约。为相关产物命名，定义成功检测标准，并拒绝默许部分完成的情况。 缓存稳定的系统指令和工具架构。重复发送相同的开头信息是导致资源浪费的常见原因。 在处理 MCP 与 AI 阶段时，首先需明确契约内容：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放，以便操作员无需查看整个系统结构即可进行审计。

Agent:
Plans a sequence of actions.

MCP:
Provides a standard way to discover and request capabilities.Tool or backend:
Performs each requested operation.

用 Python 构建你的第一个 MCP 服务器

在构建第一个 MCP 的阶段，最好将其视为一个可衡量的测试对象。在扩大范围之前，先记录一份成功的操作案例、一个失败案例以及回滚说明。同时文档化正常流程和故障恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的一部分，而非后续需要补充的内容。在讲解循环逻辑之前，先锁定解释器和依赖项的版本。笔记本电脑与持续集成环境之间的差异是 API 演示中最常见的隐性故障原因。

前置条件

将“前置条件”阶段视为可衡量的工作面最为有效。在扩大范围之前，先记录一份理想的测试用例、一个失败案例以及回滚说明。相比庞大的脚本，应优先选择小型且可测试的单元。当某一步骤失败时，故障应能指向单一责任主体，而非复杂的流程链。需为每轮操作和每次会话设定token预算——智能工具会大量消耗上下文，设置上限可避免演示过程突然产生额外费用。

第一步：创建项目

将“第一步：创建阶段”视为可度量的工作面时效果最佳。在扩大范围之前，需记录一份理想案例、一个故障场景以及回滚说明。 应将此阶段视为输入与已验证输出之间的契约。为相关成果命名，明确成功标准，杜绝默许的半完成状态。 需为每轮及每次会话设定预算额度。智能工具往往会过度扩展上下文，设置上限可避免演示过程变成意外账单。 将“第一步：创建阶段”视为可度量的工作面时效果最佳。在扩大范围之前，需记录一份理想案例、一个故障场景以及回滚说明。 应将配置信息置于应用程序代码之外。环境文件、密钥存储及功能开关应集中存放于一处，以便操作人员无需查看整个系统结构即可进行审计。

uv init mcp-learning-server
cd mcp-learning-server
uv add "mcp[cli]>=1.27,<2"

mkdir mcp-learning-server
cd mcp-learning-server

python -m venv .venv
source .venv/bin/activatepip install "mcp[cli]>=1.27,<2"

.venv\Scripts\Activate.ps1

第2步：创建server.py

在“第2步：创建服务器”阶段，需先定义输入参数、该步骤的负责人以及结束标准，然后再进行代码修改。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理都是产品功能的一部分，而非后续需要补充的内容。 当下一步操作为编写代码或调用工具时，建议使用具有结构化格式且经过模式验证的输出，而非自由形式的文字描述。

from mcp.server.fastmcp import FastMCP

# Create the MCP server.
mcp = FastMCP("MCP Learning Server")
@mcp.tool()
def calculate_test_completion(completed: int, total: int) -> dict:
    """
    Calculate test completion percentage.    This is deterministic application logic exposed as an MCP tool.
    """
    if total <= 0:
        raise ValueError("total must be greater than zero")    if completed < 0 or completed > total:
        raise ValueError("completed must be between zero and total")    percentage = round((completed / total) * 100, 2)    return {
        "completed": completed,
        "total": total,
        "completion_percentage": percentage,
    }
@mcp.resource("guide://mcp/basics")
def get_mcp_basics() -> str:
    """
    Return a short MCP reference as a resource.
    """
    return """
    MCP connects AI applications to external context and tools.    Core server primitives:
    - Resources provide contextual information.
    - Tools expose callable operations.
    - Prompts provide reusable interaction templates.    MCP does not replace the backend systems that perform the work.
    """
@mcp.prompt()
def explain_mcp_concept(
    concept: str,
    audience: str = "beginner",
) -> str:
    """
    Create a reusable prompt for explaining an MCP concept.
    """
    return (
        f"Explain the MCP concept '{concept}' to a {audience}. "
        "Use one practical example, distinguish MCP from the AI model, "
        "and mention any important security boundary."
    )
if __name__ == "__main__":
    # stdio is convenient for a local beginner project.
    mcp.run(transport="stdio")

这段代码的功能

在“此代码的功能”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比冗长的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能指向单一责任主体，而非复杂的流程链。如果后续步骤是代码或工具调用，相比自由形式的文字描述，更有结构化的、经过模式验证的输出更为合适。

FastMCP

在 FastMCP 阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止条件。操作员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将此阶段视为输入与已验证输出之间的契约。为相关成果命名，定义成功判定标准，并拒绝默许的半完成状态。 当下一步操作是代码编写或工具调用时，优先采用具有架构验证的结构化输出，而非自由形式的文本。 在 FastMCP 阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止条件。操作员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将配置信息置于应用程序代码之外。环境文件、密钥存储及功能开关应集中存放于一个操作员可审核的位置，无需阅读整个系统结构。

@mcp.tool()

在处理 mcp 工具阶段时，首先写下契约内容：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的组成部分，而非后续需要补充的功能。 缓存稳定的系统指令和工具架构。重复发送相同的报文头是导致资源浪费的常见原因。

completed: int
total: int

@mcp.resource()

在处理 mcp 资源阶段时，首先写下契约内容：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 优先选择小型、可测试的单元，而非冗长的脚本。当某个步骤失败时，故障应指向单一的责任模块，而非复杂的流程链。 缓存稳定的系统指令和工具结构。重复发送相同的开头信息是导致资源浪费的常见原因。

guide://mcp/basics

@mcp.prompt()

在处理 MCP 提示阶段时，首先需写明契约内容：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 将此阶段视为输入与验证后输出之间的契约。为相关成果命名，明确成功判定标准，杜绝无声的半完成状态。 缓存稳定的系统指令和工具架构。重复发送相同的开头信息是导致资源浪费的常见原因。 在处理 MCP 提示阶段时，首先需写明契约内容：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一处，以便操作员无需查看整个系统结构即可进行审计。

mcp.run(transport="stdio")

将mcp run transport stdio阶段视为可度量的对象来处理时，其效果最佳。在扩大范围之前，先记录一份成功的测试案例、一个失败案例以及回滚说明。同时文档化正常流程与恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的内容。为每次轮次和每次会话设定token预算。智能工具会大量消耗上下文资源，设置上限可避免演示过程变成意外的费用账单。

步骤3：使用MCP Inspector测试服务器

将“第3步：测试”阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某一步骤失败时，故障应指向单一责任点，而非复杂的流程链。 为每轮及每次会话设定令牌预算。智能工具会大量消耗上下文资源，设置上限可避免演示过程变成意外的费用账单。

npx -y @modelcontextprotocol/inspector uv run server.py

{
  "completed": 87,
  "total": 100
}

{
  "completed": 87,
  "total": 100,
  "completion_percentage": 87.0
}

底层到底发生了什么？

将“舞台下方发生的一切”视为可测量的对象来处理效果最佳。在扩大范围之前，先记录一份完美的操作日志、一个故障案例以及回滚说明。 把这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，绝不允许默默完成部分任务。 为每轮操作和每次会话设定预算额度。智能工具往往会过度扩展上下文；设置上限可避免演示过程变成意外的费用账单。 将“舞台下方发生的一切”视为可测量的对象来处理效果最佳。在扩大范围之前，先记录一份完美的操作日志、一个故障案例以及回滚说明。 将配置信息置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审计。

{
  "method": "tools/call",
  "params": {
    "name": "calculate_test_completion",
    "arguments": {
      "completed": 87,
      "total": 100
    }
  }
}

你如何将这台服务器与人工智能应用连接起来？

在“如何连接”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。 当下一步操作为代码编写或工具调用时，应优先使用具有结构化格式且经过模式验证的输出，而非自由形式的文字描述。

{
  "mcpServers": {
    "learning-server": {
      "command": "uv",
      "args": [
        "run",
        "/absolute/path/to/server.py"
      ]
    }
  }
}

一个实际的案例：GPU回归问题排查

在“实际应用示例”阶段，应在修改代码之前明确输入内容、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比冗长的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能指向单一责任模块，而非复杂的流程链。如果后续步骤是代码调用或工具调用，相比自由形式的文字描述，结构化且经过模式验证的输出更为合适。

回归测试结果 MCP服务器

在回归结果MCP服务器阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。 应将此阶段视为输入与已验证输出之间的契约。为相关成果命名，定义成功判定条件，并拒绝默许的半完成状态。 当后续步骤为代码或工具调用时，优先采用具有架构验证的结构化输出，而非自由形式的文本。 在回归结果MCP服务器阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个操作人员可审核的位置，无需阅读整个系统结构。

get_latest_sanity_run()
get_last_known_good_run()
compare_runs(current_run, baseline_run)

regression://runs/{run_id}/summary
regression://runs/{run_id}/failed-tests

Artifact MCP服务器

在处理Artifact MCP服务器阶段时，首先需明确相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。 缓存稳定的系统指令和工具架构。重复发送相同的开头信息是导致资源浪费的常见原因。

get_build_manifest(build_id)
compare_artifacts(current_build, baseline_build)

日志分析MCP服务器

在处理日志分析MCP服务器阶段时，首先需明确相关规范：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。 建议采用小型、可测试的单元而非冗长的脚本。当某个步骤失败时，故障应能指向具体的责任模块，而非复杂的流程链。 应对稳定的系统指令和工具结构进行缓存。重复发送相同的开头信息是导致资源浪费的常见原因。

get_sanitized_log(test_execution_id)
find_matching_failure_signatures(signature)

源代码控制MCP服务器

在处理源代码控制MCP服务器阶段时，首先需明确合同条款：所需的输入参数、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改始终符合约定。 将此阶段视为输入与经过验证的输出之间的契约。为相关产物命名，定义成功检测标准，并拒绝默许的部分完成状态。 缓存稳定的系统指令和工具架构。重复发送相同的开头信息是导致资源浪费的常见原因。 在处理源代码控制MCP服务器阶段时，首先需明确合同条款：所需的输入参数、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改始终符合约定。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一处，以便操作员无需查看整个系统结构即可进行审计。

get_change_summary(from_revision, to_revision)

文档化MCP服务器

将文档 MCP 服务器阶段视为可度量的对象来处理，效果最佳。在扩大范围之前，先记录一份理想的操作流程、一个故障案例以及回滚说明。同时记录正常流程与恢复流程的文档。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的内容。为每次交互和每个会话设定令牌预算。智能工具会大量消耗上下文资源，设置上限可避免演示过程变成意外的费用账单。

runbook://sanity/pass-rate-drop
failure-library://known-signatures

安全性：初学者绝不能跳过的部分

在初学者阶段，将安全性视为可度量的指标最为有效。在扩大范围之前，先记录一份优秀的操作案例、一个故障实例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某一步骤出错时，故障应能指向单一责任主体，而非复杂的流程链。 为每轮操作和每次会话设定token预算。智能代理工具会大量消耗上下文资源，设置上限可避免演示过程变成意外的费用账单。

将每台服务器都视为需要谨慎决策的对象

将“把每台服务器视为舞台”这一理念付诸实践时，最好将其视为一個可度量的对象。在扩大范围之前，先记录一份完美的操作日志、一个故障案例以及回滚说明。 把这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，绝不允许出现悄无声息的半完成状态。 为每轮操作及每次会话设定预算限制。智能工具往往会过度扩展上下文；设置上限可避免演示过程变成意外的费用账单。 将“把每台服务器视为舞台”这一理念付诸实践时，最好将其视为一個可度量的对象。在扩大范围之前，先记录一份完美的操作日志、一个故障案例以及回滚说明。 将配置信息置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审计。

优先选择功能精简的工具

在“优先使用结构化工具”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。 当下一步操作为代码编写或工具调用时，应优先使用具有架构验证功能的结构化输出，而非自由形式的文本。

execute_shell_command(command)
run_arbitrary_sql(query)
read_any_file(path)

get_run_summary(run_id)
search_approved_documents(query)
validate_test_configuration(config_id)
create_issue_draft(project_id, evidence)

分离读写功能

在独立的读写阶段，修改代码之前应先明确输入参数、该步骤的负责人以及终止条件。操作人员应当能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 相较于冗长的脚本，应优先使用小型且可测试的单元。当某个步骤失败时，故障原因应能指向单一责任模块，而非复杂的流程链。 如果后续步骤是代码调用或工具调用，应优先采用带有架构验证的结构化输出，而非自由形式的文本。

Server A:
Read-only regression metadata

Server B:
Restricted logsServer C:
Human-approved operational actions

让人类持续参与其中

为确保人类能持续参与该流程，应在修改代码之前明确输入参数、各步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行相应步骤，而无需猜测隐藏状态。 应将此阶段视为输入与已验证输出之间的契约。为相关成果命名，设定成功判定标准，并拒绝默许部分完成的情况。 当后续步骤为代码或工具调用时，优先采用具有结构化格式且经过模式验证的输出，而非自由形式的文本。 为确保人类能持续参与该流程，应在修改代码之前明确输入参数、各步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行相应步骤，而无需猜测隐藏状态。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个操作人员可审计的位置，无需查看整个系统结构。

切勿将凭证传递给模型

在处理“勿传递凭证”这一阶段时，首先需明确相关规范：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复流程。重试机制、人工审核环节以及错误消息处理都是产品功能的一部分，而非后续需要补充的内容。 对稳定的系统指令和工具结构进行缓存。重复发送相同的开头信息是导致资源浪费的常见原因。

将获取的内容视为不可信数据

在处理“将检索到的内容视为阶段”这一任务时，首先需明确相关约定：所需的输入参数、成功信号，以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合预期。 相比庞大的脚本，应优先使用小型且可测试的单元。当某个步骤失败时，故障应能指向具体的责任模块，而非复杂的流程链。 对稳定的系统指令和工具结构进行缓存。重复发送相同的开头信息是导致资源浪费的常见原因。

两次验证工具参数

在完成“验证工具参数两次处理”阶段时，首先需明确合同条款：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 将此阶段视为输入与验证后输出之间的契约。为相关产物命名，定义成功检查标准，并杜绝无声的半完成状态。 缓存稳定的系统指令和工具架构。重复发送相同的开头信息是导致资源浪费的常见原因。 在完成“验证工具参数两次处理”阶段时，首先需明确合同条款：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 将配置信息置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放于一处，以便操作人员无需查看整个系统结构即可进行审计。

远程服务器的授权使用

将“远程阶段的授权使用”视为可度量的指标时，其效果最佳。在扩大范围之前，需记录一份成功的测试用例、一个失败案例以及回滚说明。同时文档化正常流程与恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的内容。

MCP无法解决的难题

MCP 不处理的内容，若将其视为可测量的界面来对待效果最佳。在扩大范围之前，先记录一份优秀的处理结果、一个失败案例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某一步骤失败时，故障应指向单一责任模块，而非复杂的流程链。 为每轮对话和每次会话设定令牌预算。智能代理工具会大量消耗上下文资源，设置上限可避免演示过程变成意外的费用账单。

何时应该使用 MCP？

“何时应使用该阶段”这一概念在被视为可度量的标准时效果最佳。在扩大范围之前，需记录一份理想案例、一个失败案例以及回滚说明。 应将此阶段视为输入与已验证输出之间的契约。为相关成果命名，明确成功标准，杜绝默许的半完成状态。 需为每轮对话及每次会话设定预算额度。智能工具往往会过度扩展上下文，设置上限可避免演示过程变成意外的费用账单。 “何时应使用该阶段”这一概念在被视为可度量的标准时效果最佳。在扩大范围之前，需记录一份理想案例、一个失败案例以及回滚说明。 应将配置信息置于应用程序代码之外。环境文件、密钥存储及功能开关应集中存放于一处，以便操作人员无需查看整个系统结构即可进行审计。

MCP在什么情况下可能没有必要？

在“MCP可能处于哪个阶段”这一环节中，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。同时需将正常流程与异常恢复路径一并记录下来。重试机制、人工审核环节以及错误处理都属于产品功能的一部分，而非后续需要补充的内容。当下一步操作是编写代码或调用工具时，应优先使用具有架构验证功能的结构化输出，而非自由形式的文本。

MCP实用学习路线图

在“MCP实用学习阶段”中，同样需要在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。

第1级：理解相关术语

第2级：构建一个只读本地服务器

第3级：封装现有API

第4级：添加远程传输功能

第5级：构建领域专用服务器

第6级：引入经过审批的操作

常见问题解答

MCP能否替代REST API？

MCP是数据库吗？

MCP是人工智能模型吗？

MCP服务器属于人工智能代理吗？

MCP能让工具更安全吗？

测试MCP服务器需要大型语言模型吗？

一个人工智能应用可以连接多个MCP服务器吗？

MCP服务器可以在本地运行吗？

MCP服务器可以是远程的吗？

下一步学习方向

推荐的相关文章

核心要点总结

官方资源与延伸阅读

操作检查清单