十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

基于 fastmcp.json 的 FastMCP 服务器声明式配置实战:从 dependencies 参数迁移到单一配置源

基于 fastmcp.json 的 FastMCP 服务器声明式配置实战:从 dependencies 参数迁移到单一配置源 基于 fastmcp.json 的 FastMCP 服务器声明式配置实战从 dependencies 参数迁移到单一配置源【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp本指南以仓库中的 fastmcp_config_demo 示例 为主线讲解 FastMCP 官方推荐的服务器配置方式把入口文件、Python 环境、依赖、传输协议与日志级别全部声明在一个fastmcp.json文件中。读完本文你将掌握fastmcp.json的三大区块结构source / environment / deployment、从旧的dependencies代码参数迁移的方法、多种启动方式以及环境变量插值、CLI 参数覆盖、多环境配置等进阶技巧并能结合源码理解其底层实现原理。为什么需要 fastmcp.json从 dependencies 参数说起在 FastMCP 2.11.4 之前该写法已标记为 deprecated服务器的第三方依赖需要在 Python 代码中通过FastMCP(...)构造函数的dependencies参数声明mcp FastMCP(Demo Server, dependencies[pyautogui, Pillow])这种方式有几个明显的痛点依赖与代码耦合换一台机器或换一个场景需要修改源代码才能调整依赖导入时机问题依赖是在服务器代码被导入之后才被察觉的缺少依赖时会出现 import-time 错误难以共享想把自己的服务器配置分享给同事或部署到 CI必须连同源码一起传递隐性信息。现在依赖声明被移到了fastmcp.json配置文件中{ environment: { dependencies: [pyautogui, Pillow] } }这种声明式配置成为 FastMCP 项目的推荐方式官方文档 server-configuration 将其定位为 canonical and preferred way它用一份结构化、可共享、可校验的文件取代了记忆命令行参数或编写 shell 脚本的繁琐流程。认识示例项目一份完整的 fastmcp.json仓库中的 examples/fastmcp_config_demo 目录包含三个文件README.md使用说明、fastmcp.json配置文件和 server.py服务器代码。配置文件完整内容如下{ $schema: https://gofastmcp.com/public/schemas/fastmcp.json/v1.json, source: { path: server.py }, environment: { python: 3.11, dependencies: [pyautogui, Pillow] }, deployment: { transport: stdio, log_level: INFO } }与之配套的 server.py 是一个屏幕截图演示服务器代码中不再出现任何依赖声明只负责定义工具from fastmcp import FastMCP from fastmcp.utilities.types import Image # Create server - dependencies are now in fastmcp.json mcp FastMCP(Screenshot Demo) mcp.tool def take_screenshot() - Image: Take a screenshot of the users screen and return it as an image. import pyautogui ...注意两个细节pyautogui和Pillow虽然在工具函数内部import但它们的安装声明完全由fastmcp.json的environment.dependencies负责服务器源码保持了纯粹的业务代码形态。take_screenshot返回 FastMCP 的Image类型截图压缩为 JPEG 以控制体积而第二个工具analyze_colors则演示了同一服务器如何复用pyautogui依赖做屏幕主色分析。fastmcp.json 的三大区块结构fastmcp.json围绕三个问题组织配置每个区块解决一类关切区块回答的问题是否必填sourceWHERE服务器代码在哪里必填environmentWHAT它需要什么样的环境可选deploymentHOW它应该如何运行可选从源码 mcp_server_config.py 可以看到MCPServerConfig模型正是由source、environment、deployment三个 Pydantic 字段构成environment和deployment都带有默认工厂UVEnvironment()与Deployment()因此省略时自动取默认值只有source是必需的。source告诉 FastMCP 服务器代码在哪source决定 FastMCP 如何找到并加载服务器。当前支持filesystem类型本地 Python 文件也是默认类型省略type即视为 filesystem未来将扩展git版本库与cloud托管服务器类型。关键字段path必填指向包含 FastMCP 服务器的 Python 文件路径相对路径以配置文件所在目录为基准解析源码 filesystem.py 中同样按此约定解析。entrypoint可选模块内服务器实例或工厂函数的名称。可以是mcp FastMCP(MyServer)这样的实例也可以是无参数、返回 FastMCP 服务器的函数。省略时 FastMCP 会在mcp、server、app等常见名称中自动查找。示例中的配置source: { path: server.py }省略了entrypoint此时 FastMCP 自动探测到server.py中定义的mcp实例见 server.py。environment声明 Python 环境与依赖environment控制服务器的构建期环境确保服务器在精确的 Python 版本与依赖集合下运行。FastMCP 采用可扩展的环境系统基类Environment目前内置UVEnvironmenttype省略时默认uv由uv负责依赖解析与隔离环境创建。核心字段定义于 uv.pypythonPython 版本约束。支持精确版本3.12、最低版本3.10、版本区间3.10,3.13三种写法。dependenciespip 包列表支持 PEP 508 版本说明符如[pandas2.0, requests, httpx]。requirementsrequirements.txt文件的路径相对配置文件位置解析。project包含pyproject.toml的项目目录路径用于 uv 项目级管理。editable以可编辑开发模式安装的包路径列表支持多个路径适合 monorepo 或共享库场景如[.]或[., ../shared-lib]。只要设置了以上任一字段FastMCP 就会自动用uv创建隔离环境。示例中的python: 3.11会把 Python 版本固定为 3.11dependencies: [pyautogui, Pillow]则声明两个运行依赖。deployment控制服务器的运行方式deployment控制服务器的运行时行为包括传输协议、网络绑定、日志级别、环境变量与执行上下文定义于 mcp_server_config.py 的Deployment模型字段默认值说明transportstdio通信协议。http与streamable-http都对应 Streamable HTTP 传输sse对应 SSE。桌面客户端Claude Desktop、Cursor 等通常用 stdio网络访问用 httphost127.0.0.1HTTP 传输的绑定网卡。0.0.0.0表示所有网卡port8000HTTP 传输的端口path/mcpMCP 端点 URL 路径Streamable HTTP 默认/mcpSSE 默认/sselog_levelINFO日志级别DEBUG/INFO/WARNING/ERROR/CRITICALenv无运行时注入的环境变量支持${VAR_NAME}插值cwd无服务器进程的工作目录相对路径以配置文件位置解析args无传递给服务器--之后的命令行参数如[--config, server-config.json]示例配置使用了transport: stdio与log_level: INFO即默认的桌面客户端通信方式加标准日志输出。启动服务器多种运行方式有了fastmcp.json启动服务器变得极其简单。CLI 会自动探测当前目录下名为fastmcp.json的文件源码 find_config 只精确匹配这个文件名# 方式一自动探测当前目录下的 fastmcp.json cd examples/fastmcp_config_demo fastmcp run # 方式二显式指定配置文件 fastmcp run examples/fastmcp_config_demo/fastmcp.json # 方式三开发模式附带 Inspector UI fastmcp dev examples/fastmcp_config_demo/fastmcp.json在 run.py 中可以看到运行流程load_mcp_server_config()通过MCPServerConfig.from_file()解析 JSON随后调用config.deployment.apply_runtime_settings(config_path)应用环境变量与工作目录等运行时设置接着把deployment中的 transport / host / port / path / log_level / args 与 CLI 参数合并CLI 优先再通过config.source.load_server()加载服务器并运行。注意fastmcp.json按严格 JSON 解析不支持注释和尾随逗号。此外只有文件名精确为fastmcp.json才会被自动探测其他命名如dev.fastmcp.json、prod.fastmcp.json必须显式传入路径。从命令行参数迁移对照与等价关系如果你现在还在用一长串命令行参数或uv run --with ...脚本迁移到fastmcp.json后整个工作流会被大幅简化。以下是一组典型等价对照迁移前的 CLI 命令uv run --with pandas --with requests \ fastmcp run server.py \ --transport http \ --port 8000 \ --log-level INFO迁移后的 fastmcp.json{ $schema: https://gofastmcp.com/public/schemas/fastmcp.json/v1.json, source: { path: server.py, entrypoint: mcp }, environment: { dependencies: [pandas, requests] }, deployment: { transport: http, port: 8000, log_level: INFO } }之后只需要一条命令fastmcp run。CLI 参数覆盖临时调整不必改文件CLI 参数的优先级高于配置文件值方便做临时调整详见官方文档 CLI Override Behavior 一节# 配置里写的是 8000 端口这里临时覆盖为 8080 fastmcp run fastmcp.json --port 8080 # 配置里是 stdio临时切换为 HTTP fastmcp run fastmcp.json --transport http # 追加配置里没有的依赖 fastmcp run fastmcp.json --with requests --with httpx跳过环境准备--skip-env / --skip-source当目标环境已经就绪例如已在激活的虚拟环境中、依赖已预装的 Docker 容器、CI 已预构建环境、或正处于 uv 管理的环境内可以用--skip-env跳过环境创建避免无限递归fastmcp run fastmcp.json --skip-env对于未来支持的需要拉取源码的 source 类型git / cloud若源码已在本地可搭配--skip-source。对本地 filesystem 源而言该参数无实际影响。预构建环境fastmcp project prepare在部署场景中可以把建环境慢与跑服务快分离。fastmcp project prepare会创建一个持久化的 uv 项目并把依赖全部预装好# 创建持久化环境 fastmcp project prepare fastmcp.json --output-dir ./env # 复用预构建环境运行服务器 fastmcp run fastmcp.json --project ./env环境变量插值动态配置的秘密武器deployment.env字段支持${VAR_NAME}语法做运行时插值。底层实现位于 apply_runtime_settings正则\$\{([^}])\}匹配占位符若系统环境变量存在则替换否则保留占位符原样不会抛错也不会替换为空字符串。{ deployment: { env: { API_URL: https://api.${ENVIRONMENT}.example.com, DATABASE_URL: postgres://${DB_USER}:${DB_PASS}${DB_HOST}/mydb, CACHE_KEY: myapp_${ENVIRONMENT}_${VERSION} } } }假设系统已设置ENVIRONMENTproduction、DB_HOSTdb.example.com运行时就得到https://api.production.example.com、postgres://${DB_USER}:...等解析结果。这特别适用于开发 / 预发布 / 生产多环境共用同一份配置、敏感值不入库、动态拼接 URL 与连接串、按环境生成前缀或后缀等场景。cwd字段同样支持相对路径按配置文件位置解析后os.chdir。多环境配置与共享一个常用模式是维护多份命名配置分别面向不同环境fastmcp.json—— 默认配置唯一会被自动探测的文件名dev.fastmcp.json—— 开发环境HTTP DEBUG 日志prod.fastmcp.json—— 生产环境0.0.0.0绑定 严格日志 requirements 文件fastmcp run dev.fastmcp.json # 开发 fastmcp run prod.fastmcp.json # 生产配合 IDE 校验体验更好。在文件顶部声明$schema后地址为仓库 schema 目录 docs/assets/schemas 下生成的版本化 schema亦可通过 generate_schema 在本地重新生成VS Code 等现代 IDE 会自动提供自动补全、校验与内联文档。底层原理一次 fastmcp run 的完整旅程结合源码梳理一次fastmcp run fastmcp.json的执行链路解析配置MCPServerConfig.from_file()读取 JSON 并通过 Pydantic 校验source/environment/deployment各自经 field_validator 归一化为类型化对象见 mcp_server_config.py。应用运行时设置deployment.apply_runtime_settings()先完成env插值并写入os.environ再按需chdir到cwd。准备环境若environment中配置了 python / dependencies / requirements / project / editable 任一字段则调用UVEnvironment.prepare()——uv init初始化项目、uv python pin固定版本、uv add --no-sync添加依赖注意源码 uv.py 会自动把fastmcp追加进依赖列表、最后uv sync安装。若系统未安装 uv会抛出明确错误提示安装命令。合并 CLI 覆盖transport / host / port / path / log_level / args 以CLI 优先原则合并见 run.py。加载并运行服务器source.load_server()按 entrypoint 探测规则加载服务器实例最终调用server.run_async(**kwargs)。整个过程保证了依赖一定在服务器被导入前就绪这也是无导入期错误这一收益的根源。收益总结采用fastmcp.json声明式配置带来的核心收益原文档与官方文档的共同结论单一事实来源入口、环境、依赖、运行时全部集中在一处环境隔离依赖安装于 uv 管理的隔离环境不污染系统 Python也不会与其他项目冲突无导入期问题依赖在服务器导入前完成安装IDE 支持JSON Schema 提供自动补全与校验可共享完整的服务器配置可以随文件直接分享实现跨环境、跨团队的复现式部署从本地开发到生产服务器保持一致。若想看到更多不同规模的配置示例可继续阅读 server-configuration 官方文档含基础、开发、生产、数据科学、多环境五套完整示例或参考仓库中 fastmcp_config 目录下的full_example.fastmcp.json与 mcp_server_config_schema 测试 了解字段校验行为。【免费下载链接】fastmcp The fast, Pythonic way to build MCP servers and clients.项目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表