【学习心得】MCP工具开发学习笔记

本笔记回答一个问题:从零开始怎么写一个MCP工具,第一步干嘛,第二步干嘛,写完之后怎么用?

〇、先建立一句话的心智模型

MCP = 用JSON-RPC消息告诉AI:"我这里有哪些工具、干什么用的、怎么调用",再由AI决定调不调,何时调用。

你写的东西本质是一个"函数清单 + 函数本体",剩下的(协议、传输、握手)全是现成的轮子,MCP框架都帮你写好了。所以写一个MCP工具 == 写几个普通Python函数,加装饰器,完事了。MCP有三种传输方式,怎么选择见下表:

场景 选什么
本机自用(接 Claude Code、IDE) stdio(默认,最简单)
给别人远程用 / 部署到服务器 Streamable HTTP
老教程里的 SSE 别用,已弃用

一、准备环境

推荐用 uv(Astral 出品的新一代包管理器,官方教程默认用它):

bash 复制代码
# 1. 安装 uv(只需一次,之后所有项目通用)
pip install uv

# 2. 建项目并进入
mkdir my-mcp-tool
cd my-mcp-tool

# 3. 初始化项目
uv init
uv venv

# 4. 安装官方 SDK(写入 pyproject.toml 并装进 .venv)
#    [cli] 是可选依赖组,第三步的 `mcp dev` 调试命令需要它
uv add "mcp[cli]"

二、写服务端

新建 server.py,这是完整可运行的最小例子:

python 复制代码
# server.py

from mcp.server.mcpserver import MCPServer

mcp = MCPServer("my-first-tool")


@mcp.tool()
def add(a: float, b: float) -> str:
    """把两个数字相加,返回结果"""          # ← docstring 会原样给 AI 看,务必写清楚
    return f"{a} + {b} = {a + b}"


if __name__ == "__main__":
    mcp.run()   # 默认 stdio 传输:等客户端来启动我
代码 作用
MCPServer("名字") 给你的工具集起名,会出现在握手的 serverInfo 里
@mcp.tool() 把函数注册为工具;函数签名自动变成参数 schema(类型注解是契约,别乱写)
docstring 工具描述,AI 靠它判断"什么时候该调我这个工具"------写得越具体,AI 用得越准
mcp.run() 启动 stdio 通道,阻塞等待消息(终端里"卡住"是正常的,它在等人对话)

写工具的三条纪律:

  1. **docstring 认真写:**它不是给你看的,是给 AI 看的"使用说明书"。
  2. 类型注解要准确: a: float 会被生成参数 schema,AI 按它传参,写错了 AI 就传错。
  3. 绝不在工具里 print(...): 因为stdio 模式下 stdout 是协议通道,print 会污染消息流。要输出日志用 print(..., file=sys.stderr) 或 logging。

三、测试

① 方法A:用MCP库自带的Inspector官方调试器,最推荐

bash 复制代码
uv run mcp dev server.py

浏览器会打开一个界面,可以点按钮握手、列工具、填参数调用。不用写一行客户端代码。

Inspector 两个常见困惑

  1. 没有"添加 Server"按钮 :mcp dev 启动的 Inspector 是只读模式

    (页面顶部会显示 "Read-only session"),只能看不能改。想手动添加

    server、自己填命令,用不带参数的方式独立启动:

    复制代码
    npx @modelcontextprotocol/inspector@latest
  2. 默认的 uv 命令 Failed / Connection closed :mcp dev 生成的启动

    命令假设你用 uv。没装 uv 就会这样------不是你的 server 写错了。

    装 uv 或换自己的命令即可(见第一步的注意事项)。

② 方法B:写一个客户端自己去调,这个不推荐

四、接入真实的AI客户端使用

工具写好是给 AI 用的。以 Claude Code 为例(也适用于 Claude Desktop、Cursor 等,格式大同小异)。

在项目根目录新建.mcp.json文件写入:

bash 复制代码
{
  "mcpServers": {
    "my-tool": {
      "command": "e:\\my-mcp-tool\\.venv\\Scripts\\python.exe",
      "args": ["e:\\my-mcp-tool\\server.py"]
    }
  }
}

要点:

  • command 用 venv 里的 python 绝对路径 ,别写 python(会找不到 mcp 包)
  • Windows 路径在 JSON 里要写双反斜杠 \\
  • 重启 Claude Code 后,输入 /mcp 可以看到连接状态

如果是远程工具(HTTP 版),server 端改成**mcp.run(transport="streamable-http")**,客户端配置改成:

bash 复制代码
{
  "mcpServers": {
    "my-tool": {
        "type": "http",
        "url": "http://your-server:8000/mcp"
    }
  }
}

三种传输只是这条消息走的管道不同:stdio 走子进程 stdin/stdout;Streamable HTTP 走 HTTP POST(响应可为 SSE 流)。

相关推荐
Flying Bear1 小时前
Keithley 2450 SourceMeter源表上位机开发笔记
笔记·单片机·嵌入式硬件
旖旎夜光1 小时前
【C++ 基础入门】智能指针:RAII、unique_ptr 与 shared_ptr 循环引用
c++·笔记·学习·智能指针
饮水桶_T2 小时前
Python 面向对象(十七)|继承、封装、多态 笔记
数据结构·笔记·算法
星恒随风3 小时前
MySQL 从零入门(十):MVCC、Undo Log 与 Read View 详解——InnoDB 如何实现事务隔离?
linux·数据库·笔记·sql·mysql
zdr尽职尽责3 小时前
终端工具凭空消失:Codex + GPT-6 的一次完整排障复盘
数据库·gpt·学习·ai
蒸蒸yyyyzwd5 小时前
计算机网络后端面试错题
笔记·学习
艾莉丝努力练剑6 小时前
【AI大模型接入SDK】C++的SessionManager 线程安全
java·开发语言·前端·c++·人工智能·学习·安全
蒸蒸yyyyzwd7 小时前
数据库相关错题笔记
笔记·学习
蒸蒸yyyyzwd9 小时前
后端学习笔记,设计模式相关以及微服务相关
笔记·学习
Hhy_11079 小时前
《C++深度解构07》手撕 vector —— 从底层三指针架构到迭代器失效彻底吃透
c语言·开发语言·c++·学习·visual studio