新闻详情

新闻详情

首页 / 资讯中心 / 详情

FastMCP 开发 MCP Server 完全实战指南:用装饰器与 config.toml 接入 TaoToken

发布时间:2026/11/17 15:39:59来源:尧图网络
FastMCP 开发 MCP Server 完全实战指南:用装饰器与 config.toml 接入 TaoToken
1. 为什么 FastMCP 值得你花一个下午跑通如果你写过原生 MCP Python SDK 的 Server大概记得那种感觉注册一个工具要手写 JSON Schema、手动分发tools/list和tools/call、参数校验和错误处理全靠自己兜。一个能用的 Server 动辄三四十行样板代码改一个参数类型要同步改三处。FastMCP 把这件事压成了装饰器函数签名即 Schemadocstring 即工具描述mcp.tool一贴就注册完成。它现在是 Python 圈构建 MCP Server 最主流的框架绝大多数公开的 MCP Server 都用它写。这篇面向已经会写 Python、想快速把本地能力暴露给 AI 客户端的开发者。我会带你从零搭一个可运行的 Server重点讲清楚三件事装饰器怎么注册工具与资源、参数校验怎么靠类型注解自动完成、以及怎么用一份config.toml把模型调用统一走 TaoToken 的 Key 和 API 通道。全程可复制跑完你能得到一个本地能调、客户端能连、模型能用的完整链路。适合谁想给自己项目加 MCP 能力的后端、想把内部工具接进 Cursor/Claude 的工程师、以及第一次接触 MCP 协议想找条最短路径的人。2. 前置准备环境、依赖与 TaoToken 通道2.1 Python 环境与 FastMCP 安装要求 Python 3.10 以上推荐 3.12。包管理我建议用 uvFastMCP 的命令行工具依赖它速度也比 pip 快很多。# 安装 uvmacOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows PowerShell powershell -c irm https://astral.sh/up/install.ps1 | iex # 验证 uv --version建项目并装依赖mkdir fastmcp-demo cd fastmcp-demo uv init uv add fastmcp httpx如果你习惯 pippip install fastmcp httpx同样可以只是后面fastmcp dev这类命令需要 uv 在 PATH 里。2.2 为什么要在 MCP Server 里接 TaoTokenMCP Server 本身只负责暴露工具但很多工具内部要调模型——比如一个「代码审查」工具、一个「文本摘要」工具。如果每个工具各自去配 Key、各自处理不同厂商的 base_url配置会散得到处都是。TaoToken 提供统一的 Key 和 API 通道你只需要在config.toml里写一份所有工具共享。这样换模型、换通道只改一个文件不用动业务代码。先去控制台拿 Key访问 https://taotoken.net/console 在 API Keys 页面创建一个。接入文档在 https://taotoken.net/doc 里面有各语言的调用示例。API 基址是https://taotoken.net/api注意这个地址不带任何查询参数。注意Key 只显示一次创建后立刻复制保存。不要把它硬编码进提交到 Git 的代码里用环境变量或本地配置文件。3. 可复制配置config.toml 骨架与 Server 代码3.1 config.toml 完整骨架在项目根目录建config.toml# config.toml —— MCP Server 统一配置 [server] name FastMCP Demo transport stdio # 本地开发用 stdio远程部署改 streamable-http host 0.0.0.0 port 8000 [taotoken] # 统一模型通道所有工具共享这一份配置 base_url https://taotoken.net/api api_key sk-你的Key # 生产环境请改用环境变量注入 default_model claude-sonnet-4-20250514 timeout 60 [tools] # 工具级开关方便按环境裁剪 enable_summarize true enable_code_review true max_input_chars 8000读取配置用一个轻量函数避免引入额外依赖# config_loader.py import tomllib from pathlib import Path def load_config(path: str config.toml) - dict: with open(Path(path), rb) as f: return tomllib.load(f) CONFIG load_config()tomllib是 Python 3.11 起的内置库3.10 用户装tomli并把 import 换成import tomli as tomllib即可。3.2 用装饰器注册工具与资源核心文件server.py。这里演示三种注册方式普通工具、带校验的工具、以及只读资源。# server.py import httpx from typing import Literal, Optional from fastmcp import FastMCP from fastmcp.exceptions import ToolError from config_loader import CONFIG mcp FastMCP( nameCONFIG[server][name], instructions演示用 MCP Server提供文本摘要与代码审查工具。, ) TAO CONFIG[taotoken] async def call_model(prompt: str, model: Optional[str] None) - str: 统一走 TaoToken 通道调用模型 payload { model: model or TAO[default_model], messages: [{role: user, content: prompt}], } headers { Authorization: fBearer {TAO[api_key]}, Content-Type: application/json, } async with httpx.AsyncClient(timeoutTAO[timeout]) as client: resp await client.post( f{TAO[base_url]}/v1/chat/completions, jsonpayload, headersheaders, ) resp.raise_for_status() data resp.json() return data[choices][0][message][content] mcp.tool async def summarize(text: str, style: Literal[brief, detailed] brief) - str: 对输入文本做摘要。 Args: text: 待摘要的原文长度不超过配置上限 style: 摘要风格brief 为要点式detailed 为段落式 Returns: 摘要结果字符串 limit CONFIG[tools][max_input_chars] if len(text) limit: raise ToolError(f输入长度 {len(text)} 超过上限 {limit}请先截断) if not text.strip(): raise ToolError(text 不能为空) instruction 用三到五条要点总结 if style brief else 用一段话详细总结 return await call_model(f{instruction}以下内容\n\n{text}) mcp.tool async def code_review(code: str, language: str python) - str: 对代码片段做审查返回问题清单与改进建议。 if not CONFIG[tools][enable_code_review]: raise ToolError(code_review 工具在当前环境已禁用) prompt ( f你是资深 {language} 工程师请审查以下代码 f指出潜在 bug、性能问题与可读性问题\n\n{language}\n{code}\n ) return await call_model(prompt) mcp.resource(config://runtime) def runtime_config() - dict: 暴露当前运行配置脱敏供客户端查看。 return { server_name: CONFIG[server][name], default_model: TAO[default_model], max_input_chars: CONFIG[tools][max_input_chars], } if __name__ __main__: transport CONFIG[server][transport] if transport streamable-http: mcp.run( transportstreamable-http, hostCONFIG[server][host], portCONFIG[server][port], ) else: mcp.run()几个关键点值得展开。mcp.tool会自动把函数名当工具名、docstring 当描述、类型注解转成 JSON Schema所以style: Literal[brief, detailed]会被约束成枚举客户端传别的值直接报错不用你写校验。ToolError抛出的消息会原样返回给 AI写清楚「哪里错了、该怎么改」比抛通用异常有用得多。资源用mcp.resource(scheme://path)注册只读、无副作用适合放配置、文档、统计这类上下文。3.3 参数校验的边界FastMCP 基于 Pydantic 做校验常见类型都支持int/float/str/bool、List[T]、Dict[K,V]、Optional[T]、Literal[...]、Union、以及 Pydantic 的BaseModel。不支持的包括裸Tuple和自定义非 Pydantic 类。如果你要传复杂结构定义一个BaseModel子类当参数类型最省事from pydantic import BaseModel class ReviewRequest(BaseModel): code: str language: str python max_issues: int 10 mcp.tool async def review_structured(req: ReviewRequest) - str: 结构化入参的代码审查。 return await call_model(f审查 {req.language} 代码最多列 {req.max_issues} 个问题\n{req.code})4. 启动验证与调用测试4.1 用 Inspector 做可视化调试最快的方式是fastmcp dev它会启动你的 Server 并自动打开 MCP Inspectoruv run fastmcp dev server.py浏览器打开http://127.0.0.1:6274在 Tools 标签页能看到summarize和code_review填参数点 Run Tool 就能看到返回。Resources 标签页里config://runtime会显示脱敏后的运行配置。这一步能确认工具注册成功、Schema 生成正确。4.2 用内置 Client 写程序化测试Inspector 适合手动点回归测试用 Client 更靠谱# test_server.py import asyncio from fastmcp import Client async def main(): async with Client(server.py) as client: await client.ping() print(Server 在线) tools await client.list_tools() print(工具列表:, [t.name for t in tools]) result await client.call_tool( summarize, {text: FastMCP 用装饰器简化了 MCP Server 开发。, style: brief}, ) print(摘要结果:, result.content[0].text) cfg await client.read_resource(config://runtime) print(运行配置:, cfg) asyncio.run(main())运行uv run python test_server.py。如果模型通道配置正确你会看到摘要文本返回如果 Key 或 base_url 有问题这里会直接抛 HTTP 错误方便定位。4.3 接入客户端以 Cursor 为例在.cursor/mcp.json里加{ mcpServers: { fastmcp-demo: { command: uv, args: [--directory, /绝对路径/fastmcp-demo, run, python, server.py] } } }路径必须用绝对路径这是最常见的连不上的原因。Claude Desktop 的配置在~/Library/Application Support/Claude/claude_desktop_config.jsonmacOS结构相同。改完重启客户端在工具列表里就能看到你的 Server。5. 本篇常见错排查工具不出现九成是忘了贴mcp.tool或者函数定义在if __name__块里没被执行到。检查装饰器是否紧贴函数。客户端连不上先看路径是不是绝对路径再看 JSON 有没有多余逗号。用uv run python server.py手动跑一遍能正常等待输入说明 Server 本身没问题。参数校验失败报错信息里会写清楚哪个字段、期望什么类型。常见是客户端传了字符串10而注解是int或者Literal传了不在枚举里的值。模型调用 401Key 错了或没带Bearer前缀。检查config.toml里的api_key和base_urlbase_url 结尾不要多加斜杠。模型调用超时把timeout调大或者检查网络。长文本摘要建议在工具里先截断别把几万字直接塞进去。改了代码不生效fastmcp dev有热重载但客户端连接的是独立进程改完要重启客户端。6. 把链路固定下来跑通之后建议把 Key 从config.toml挪到环境变量用os.environ[TAOTOKEN_API_KEY]读取配置文件里只留占位。这样提交代码不会泄露凭证。工具粒度上一个 Server 专注一类能力别把摘要、审查、数据库查询全塞一起客户端选择工具时会更准。docstring 写详细点AI 靠它判断什么时候调用你的工具写得含糊它就不敢用。需要长期跑编码类 Agent、把 MCP 工具接进日常开发流的可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。想先在网页里验证模型通道是否通用模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。Key 管理和接入细节分别在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 和 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。
网站建设高端定制企业官网
RELATED

相关资讯

更多精彩内容,欢迎继续阅读

较早相关资讯

最新相关资讯

【外设】之大彩串口显示屏 2026/11/17 7:04:08

【外设】之大彩串口显示屏

大彩串口屏初步使用 1 .官网下载 STM32 屏幕 GUI 设计资料 http://www.gz-dc.com/category/typeid/4112 找到 STM32 Keil 工程,移植相关代码因项目而异进行移植,由于项目简单,本人只对用到的指令接口进行修改。 比如:注意事项&…

阅读更多 →
无法下载Windows系统iso文件 2026/11/17 5:42:44

无法下载Windows系统iso文件

当我遇到这个问题的时候,我打开了一个网站: 登录 然后我打算下载的时候: 突然那个官方的连接就可以下载了:

阅读更多 →
【清华代码熊】DeepSeek V4.1 Flash 后训练详解 2026/11/16 19:23:38

【清华代码熊】DeepSeek V4.1 Flash 后训练详解

📌 上期解析了 DeepSeek V4.1 Flash 模型架构改进,本期解析 DeepSeek V4.1 Flash 预训练/后训练技术: 🌟 预训练:45T 文本 多模态混合语料、直接训练 sparse attention(取消 DeepSeek V4 的 dense 冷启动&…

阅读更多 →
Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ... 2026/11/17 6:55:04

Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ...

文章主要内容和创新点 主要内容 本文聚焦于多模态大语言模型(MLLM)强化学习(RL)训练中的效率问题,提出了一个名为Shuffle-R1的框架。研究发现,当前RL训练存在两个关键缺陷: 优势值坍缩(Advantage Collapsing):批次中大多数优势值集中在零附近,导致有效梯度信号被淹…

阅读更多 →
PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction 2026/11/17 5:57:47

PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction

一、文章主要内容总结 本文聚焦于利用大型语言模型(LLMs)实现个人身份信息(PII)脱敏的研究,旨在解决传统脱敏方法(如基于规则的系统、领域特定命名实体识别(NER)模型)泛化能力差、跨格式/跨语境适应性弱的问题。 研究通过全面评估多种LLM架构(包括密集型LLM(D-LLM…

阅读更多 →
LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model 2026/11/16 17:28:18

LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model

文章主要内容和创新点 主要内容 本文聚焦于二进制图像-文本相关性评估任务(判断图像与文本“相关”或“不相关”),针对该任务中文本格式多样、相关性定义随场景变化等挑战,提出了基于多模态大语言模型(MLLM)的解决方案LLaVA-RE。 模型设计:LLaVA-RE基于LLaVA 1.5架构,…

阅读更多 →

今日资讯

本周资讯

本月资讯

看完文章仍有疑问?

联系尧图顾问,获取一对一建站咨询

立即免费咨询 📞 400-888-8888
📞 ✉