网硕互联帮助中心【免费下载链接】mcp-for-beginners
This open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.
项目地址：
https://gitcode.com/GitHub_Trending/mc/mcp-for-beginners
点击查看 免费下载
导读
在微软 Foundry Toolkit for Visual Studio Code（AITK）的实操课程中，你已经通过 @server.tool() 装饰器为计算器 MCP 服务器注册了 add、subtract、multiply、divide 四个基础运算工具。本篇文章以该课程的作业解法（关联文档）为骨架，完整讲解如何为这个服务器新增一个 sqrt 平方根工具，深入剖析 math.sqrt()、ValueError 错误处理与 FastMCP 工具注册机制，并给出重启服务器与自然语言验证提示词，帮助你掌握"向既有 MCP 服务器增量添加能力"这一核心开发模式。
一、背景：从"能算四则运算"到"能开平方"
在本课程主教程（07-aitk/README.md）中，你已经完成了一条完整的 AITK 开发链路：
主教程的作业环节要求你"尝试在 server.py 中添加额外工具（例如返回一个数字的平方根）"。本篇文章正是这份作业的标准解法。完成之后，你的 AI 智能体将能够理解并回答诸如 "16 的平方根是多少？"、"计算 √49" 这样的自然语言数学问题，无需硬编码逻辑或构建自定义 API。
二、核心实现：在 server.py 中添加 sqrt 工具
在 server.py 文件中定义一个以 @server.tool() 装饰的 sqrt 函数，即可完成功能接入。完整代码如下：
"""
Sample MCP Calculator Server implementation in Python.
This module demonstrates how to create a simple MCP server with calculator tools
that can perform basic arithmetic operations (add, subtract, multiply, divide).
"""
from mcp.server.fastmcp import FastMCP
import math
server = FastMCP("calculator")
@server.tool()
def add(a: float, b: float) -> float:
"""Add two numbers together and return the result."""
return a + b
@server.tool()
def subtract(a: float, b: float) -> float:
"""Subtract b from a and return the result."""
return a – b
@server.tool()
def multiply(a: float, b: float) -> float:
"""Multiply two numbers together and return the result."""
return a * b
@server.tool()
def divide(a: float, b: float) -> float:
"""
Divide a by b and return the result.
Raises:
ValueError: If b is zero
"""
if b == 0:
raise ValueError("Cannot divide by zero")
return a / b
@server.tool()
def sqrt(a: float) -> float:
"""
Return the square root of a.
Raises:
ValueError: If a is negative.
"""
if a < 0:
raise ValueError("Cannot compute the square root of a negative number.")
return math.sqrt(a)
与主教程中的初始版本相比，这里只做了两处关键改动：在文件顶部新增 import math，以及新增一个 sqrt 工具函数。其余四个基础运算工具保持不变，体现了"增量式扩展"的服务器演进方式。
三、工作原理逐条拆解
3.1 math 模块：超越基础运算的能力来源
Python 内置的 math 模块提供了超越基本算术的大量数学函数与常量。通过 import math 导入后，即可调用 math.sqrt() 来计算一个数字的平方根。这是实现该工具的技术地基——你不需要自己实现牛顿迭代等求根算法，标准库已经提供了经过充分测试的浮点实现。
3.2 @server.tool() 装饰器：把普通函数变成 MCP 工具
@server.tool() 装饰器将 sqrt 函数注册为可由 AI 智能体调用的 MCP 工具。这是整个 MCP 服务器开发中最核心的声明式模式：你只需编写普通的 Python 函数，装饰器会基于函数的签名（参数名、类型注解）和 docstring 自动生成工具的输入 Schema 与描述，并注册到协议层。仓库中其余课程也采用完全一致的 API 风格，例如 01-first-server 的 Python 解法 同样通过 mcp.tool() 注册 add、subtract 工具，并用 mcp.resource("greeting://{name}") 注册动态资源——同一套 FastMCP 框架既支持工具（tools），也支持资源（resources），是理解 MCP 三个核心原语（工具、资源、提示词）的入口。
3.3 输入参数：单个 float 类型参数
sqrt 函数只接受一个参数 a，类型注解为 float。由于 AITK 计算器模板的四个基础工具也统一采用 float 类型参数，新增工具与既有工具在参数风格上保持一致。float 类型注解会被 FastMCP 翻译为 JSON Schema 中的 number 类型，使智能体能够以 JSON 格式正确传参。
3.4 错误处理：拒绝负数的平方根
实数域内 math.sqrt() 不支持负数输入（会抛出 ValueError: math domain error）。因此函数在调用 math.sqrt() 之前先做显式校验：
if a < 0:
raise ValueError("Cannot compute the square root of a negative number.")
提前抛出语义清晰的 ValueError，既避免了晦涩的底层异常，也为 AI 智能体提供了可理解的错误反馈——错误信息会通过 MCP 协议返回给客户端，帮助模型在下一轮对话中调整策略。这种"先校验、后计算"的模式与既有 divide 工具中"除零保护"（if b == 0: raise ValueError("Cannot divide by zero")）一脉相承，体现了整个服务器统一的输入防御风格。
3.5 返回值：委托给 math.sqrt()
对于非负输入，函数直接返回 math.sqrt(a) 的计算结果。返回值同样是 float，由 FastMCP 序列化为 JSON 后回传给 MCP 客户端，最终呈现在 Agent (Prompt) Builder 的 Tool Response 区域。
四、将代码落盘：AITK 模板中的 server.py
在 AITK 的 python-weather 模板项目中，server.py 位于 src 目录下。操作路径为：在 Explorer 视图中展开 src 目录，选中 server.py 打开编辑器，用上述完整代码替换文件内容并保存。替换完成后，服务器文件同时保留四个基础工具与新增的 sqrt 工具，智能体即可在一次会话中按需调度任意一个工具。
五、重启服务器：让新工具生效
在 AITK 的 Agent Builder 开发模式下，MCP 服务器是在本地开发机上通过调试方式启动的。新增 sqrt 工具之后，必须重启 MCP 服务器，智能体才能重新完成工具清单（tool list）的发现与注册，识别并调用新功能。这也是主教程作业环节特别强调"Be sure to restart the server to load newly added tools"的原因——工具注册发生在服务器启动阶段，热修改代码不会自动同步到已运行的会话中。
六、自然语言验证：用提示词测试新工具
服务器重启后，可以在 Agent (Prompt) Builder 的 User prompt 输入框中提交以下自然语言提示词，验证智能体是否能够正确触发 sqrt 工具并返回结果：
- "25 的平方根是多少？"
- "计算 81 的平方根。"
- "求 0 的平方根。"
- "2.25 的平方根是多少？"
预期行为：模型识别出平方根需求后，调用 sqrt 工具，将 a 参数分别赋值为 25、81、0、2.25，并在 Tool Response 中返回 5.0、9.0、0.0、1.5 等结果。测试完成后，可在终端中按 CTRL/CMD+C 停止服务器。
七、总结与进一步扩展
完成本次作业后，你实际收获了三项能力：
你可以沿着同样的思路继续实验，例如再添加幂运算（exponentiation）或对数运算（logarithmic）工具，进一步丰富 Calculator Agent 的数学能力。每个新工具都遵循完全相同的模式：导入所需模块、编写带类型注解与 docstring 的函数、处理异常边界、用 @server.tool() 注册、重启服务器并验证。这套"声明式工具扩展"方法正是 MCP 协议让智能体能力随需而长的核心价值所在。
赞
【免费下载链接】mcp-for-beginners
This open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.
项目地址：
https://gitcode.com/GitHub_Trending/mc/mcp-for-beginners
点击查看 免费下载
相关推荐
UnityGLTF扩展功能全解析：从材质变体到音频发射器
OpenRocket实战指南：从零开始构建高精度火箭仿真系统
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
评论前必须登录！
注册