基于FastAPI与MCP协议构建多服务AI工具集成平台

1. 项目概述与核心价值最近在折腾AI助手和代码编辑器集成的时候发现一个挺有意思的需求如何让Claude、Cursor或者Windsurf这类工具能直接调用外部的天气、新闻、汇率这些实时数据总不能每次都手动查了再复制粘贴吧。传统的做法可能是写一堆独立的API接口然后在编辑器里配置各种插件但这样管理起来太零散了。正好看到了Model Context Protocol这个标准它提供了一种统一的方式让AI工具和外部服务对话。于是我就琢磨着能不能用一个项目把多个常用的公共服务都封装成MCP Server然后通过一个统一的FastAPI应用来托管和管理。这个fastapi-multi-server-mcp项目就是基于这个想法诞生的。它的核心价值在于用一个工程化的方式集中管理多个功能独立的MCP服务器。比如你正在用Cursor写一个需要展示天气数据的应用或者用Claude分析财经新闻现在可以直接在编辑器里通过MCP协议调用我部署好的服务来获取实时信息无需中断你的工作流。项目目前内置了四个最常用的服务天气基于OpenWeatherMap、新闻基于NewsAPI、货币汇率转换以及名人名言/趣味事实。整个架构清晰从环境配置、服务运行到测试部署都提供了完整的方案特别适合希望为AI工作流增强实时数据能力的开发者、以及想深入学习FastAPI和MCP协议集成实践的工程师。我选择FastAPI作为底座主要是看中了它的高性能和异步支持非常适合这种IO密集型的API代理场景。用UV作为包管理器则是为了获得更快的依赖安装速度和可复现的环境。整个项目虽然代码量不大但涉及了配置管理、错误处理、API客户端封装、多路由挂载等后端开发的常见模式是一个很好的练手项目。2. 核心架构与设计思路拆解2.1 为什么选择MCP与FastAPI的组合首先得聊聊为什么是MCP。Model Context Protocol是由Anthropic提出的一种开放协议旨在标准化AI模型与外部工具、数据源之间的通信方式。你可以把它想象成AI世界的“USB协议”——只要设备工具支持USBMCP就能即插即用。对于开发者来说为你的服务实现MCP接口就意味着所有支持MCP的AI工具如Claude Desktop、Cursor、Windsurf都能直接发现并使用你的工具无需为每个工具单独开发适配器。这极大地降低了集成成本。而FastAPI作为一个现代、快速高性能的Python Web框架以其简洁的语法、自动化的API文档生成Swagger UI和原生的异步支持著称。将多个MCP Server托管在一个FastAPI应用下有以下几个明显优势统一入口与运维所有服务共享同一个进程、端口和中间件栈如CORS、日志、监控部署和监控成本大大降低。资源复用可以共享数据库连接池、HTTP客户端会话、缓存实例等资源提高效率。开发体验一致使用相同的配置管理、错误处理模式和测试框架团队协作更顺畅。易于扩展当需要增加一个新的MCP服务比如股票行情时只需在servers/目录下新增一个模块并在主应用中挂载路由即可架构侵入性极小。项目的目录结构也体现了这种清晰的分层思想。servers/目录下每个文件都是一个独立的MCP服务器实现utils/目录存放了被所有服务器复用的工具代码比如封装了重试和错误处理的HTTP客户端main.py作为总控中心负责初始化FastAPI应用、加载配置、并挂载各个子服务器。2.2 多服务器路由设计与隔离策略一个关键的设计点是如何在一个FastAPI应用中优雅地挂载多个独立的子应用每个MCP Server本质上是一个独立的FastAPI应用或路由器。这里采用了app.mount()方法。mount与include_router不同它允许子应用拥有完全独立的路由前缀和中间件栈更像是在主应用下“挂载”了一个完整的子应用。例如天气服务的所有端点都会以/weather为前缀其内部的MCP SSEServer-Sent Events端点可能位于/weather/mcp/。这样的设计带来了良好的隔离性路径清晰/weather/*下的所有请求都由天气服务器处理/news/*下的由新闻服务器处理互不干扰。独立配置理论上每个子服务器可以配置自己的依赖项和中间件虽然本项目为简化起见共享了部分全局配置。便于调试在浏览器中直接访问http://localhost:10000/weather或http://localhost:10000/news可以分别看到各自服务的独立API文档如果暴露了标准HTTP接口的话。在main.py中你会看到类似下面的核心代码逻辑from fastapi import FastAPI from servers.weather_server import create_weather_app from servers.news_server import create_news_app # ... 导入其他服务器 app FastAPI(titleMulti-SCP MCP Host) # 挂载子应用 weather_app create_weather_app() news_app create_news_app() # ... app.mount(/weather, weather_app) app.mount(/news, news_app) # ...这种模式使得每个功能模块高度内聚同时又通过主应用统一暴露非常灵活。3. 环境配置与依赖管理详解3.1 UV新一代Python包管理利器项目推荐使用UV这并非偶然。UV是用Rust重写的pip和venv的极速替代品由Astral团队开发也是Ruff和Uvicorn的幕后团队。在实际使用中它的速度提升是颠覆性的。创建虚拟环境和安装requirements.txt中的所有依赖耗时可能只有传统pip的十分之一。安装UV非常简单通常一条命令搞定# 使用pipx安装推荐用于管理全局Python工具 pipx install uv # 或者使用curl curl -LsSf https://astral.sh/uv/install.sh | sh使用UV初始化本项目环境# 克隆项目后进入目录 cd fastapi-multi-server-mcp # 使用uv创建虚拟环境并安装依赖一步到位 uv syncuv sync命令会读取pyproject.toml或requirements.txt文件创建虚拟环境并安装所有依赖。之后激活环境# Linux/macOS source .venv/bin/activate # Windows .venv\Scripts\activate如果你习惯传统的venvpip流程UV也完全兼容uv venv # 创建.venv虚拟环境 source .venv/bin/activate uv pip install -r requirements.txt注意使用UV时项目根目录下的pyproject.toml文件是它的首选配置源。如果同时存在requirements.txt和pyproject.tomluv sync会优先依据pyproject.toml。本项目为了兼容性通常两者会保持同步。确保你的依赖在两个文件中一致避免环境混乱。3.2 敏感信息管理与API密钥配置所有外部服务OpenWeatherMap, NewsAPI等都需要API Key。绝对不要将这些密钥硬编码在代码中。本项目采用.env文件配合pydantic-settings进行管理这是目前Python生态中处理配置的最佳实践之一。首先复制项目提供的环境变量模板cp .env.example .env然后用你喜欢的编辑器打开.env文件填入你申请到的各个API密钥# 天气API (OpenWeatherMap) OPENWEATHER_API_KEYyour_actual_openweather_api_key_here # 新闻API NEWS_API_KEYyour_actual_newsapi_key_here # 汇率API EXCHANGE_RATES_API_KEYyour_actual_exchangerate_api_key_here # 名言API (部分服务可能需要根据quote_server实现而定) QUOTES_API_KEYyour_actual_quotesapi_key_here # 服务器配置 PORT10000 HOST0.0.0.0 LOG_LEVELinfo接下来在代码中通常是utils/config.py你会看到如何使用pydantic-settings来安全地加载这些配置from pydantic_settings import BaseSettings from pydantic import Field class Settings(BaseSettings): openweather_api_key: str Field(..., aliasOPENWEATHER_API_KEY) news_api_key: str Field(..., aliasNEWS_API_KEY) exchange_rates_api_key: str Field(..., aliasEXCHANGE_RATES_API_KEY) quotes_api_key: str Field(, aliasQUOTES_API_KEY) # 可能非必需 host: str Field(0.0.0.0, aliasHOST) port: int Field(10000, aliasPORT) class Config: env_file .env case_sensitive False # 环境变量名通常不区分大小写 settings Settings()这样在项目的任何地方通过from utils.config import settings导入然后使用settings.openweather_api_key即可安全地获取配置值。pydantic会自动进行类型验证并确保必需的字段已填写。实操心得.env文件务必添加到.gitignore中防止密钥意外提交到代码仓库。对于团队协作或生产环境推荐使用更安全的密钥管理服务如AWS Secrets Manager、HashiCorp Vault或者至少使用CI/CD系统的环境变量功能。在本地开发时一个.env文件是最便捷的选择。4. 核心MCP服务器实现解析4.1 MCP服务器的基础构造块一个MCP服务器本质上是一个遵循特定JSON-RPC over HTTP/SSE/stdio协议的服务。对于基于HTTP/SSE的传输方式这也是本项目采用的方式服务器需要暴露一个端点例如/mcp/客户端通过这个端点建立Server-Sent Events连接然后双方通过这个连接交换JSON-RPC格式的消息。FastAPI对SSE有很好的原生支持。一个最简化的MCP服务器骨架可能长这样# servers/base_server.py (抽象示例) from fastapi import FastAPI, Request from fastapi.responses import StreamingResponse import json import asyncio from mcp import Server, StdioServerParameters # 假设使用mcp库 class BaseMCPServer: def __init__(self, server_name: str): self.app FastAPI(titlef{server_name} MCP Server) self.server Server(nameserver_name) self._register_tools() # 子类实现此方法以注册工具 self.setup_routes() def _register_tools(self): 由具体服务器注册其工具如get_current_weather raise NotImplementedError def setup_routes(self): self.app.post(/mcp/) async def handle_mcp_sse(request: Request): async def event_stream(): # 处理初始握手和请求流 async for message in self.server.handle_request_stream(request): yield fdata: {json.dumps(message)}\n\n return StreamingResponse( event_stream(), media_typetext/event-stream, headers{ Cache-Control: no-cache, Connection: keep-alive, } ) self.app.get(/) async def root(): return {server: self.server.name, status: online}在实际项目中我们可能会使用更成熟的MCP SDK例如mcp库来简化协议处理。每个具体的服务器如weather_server.py继承这个基类并在_register_tools方法中定义自己的工具。4.2 天气服务器深度剖析以servers/weather_server.py为例我们来看一个完整的实现。它的核心是向MCP客户端暴露几个工具get_current_weather、get_weather_forecast和get_weather_by_coordinates。首先它需要调用OpenWeatherMap的API。在utils/api_clients.py中我们通常会封装一个通用的、带重试和错误处理的异步HTTP客户端# utils/api_clients.py import httpx from tenacity import retry, stop_after_attempt, wait_exponential from utils.config import settings class WeatherAPIClient: def __init__(self): self.api_key settings.openweather_api_key self.base_url https://api.openweathermap.org/data/2.5 self.client httpx.AsyncClient(timeout30.0) retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) async def get_current(self, city: str, units: str metric): 获取当前天气units: metric(摄氏度) 或 imperial(华氏度) params { q: city, appid: self.api_key, units: units, lang: zh_cn # 获取中文描述 } try: resp await self.client.get(f{self.base_url}/weather, paramsparams) resp.raise_for_status() data resp.json() # 提取并格式化关键信息 return { city: data[name], country: data[sys][country], temp: data[main][temp], feels_like: data[main][feels_like], humidity: data[main][humidity], pressure: data[main][pressure], description: data[weather][0][description], icon: data[weather][0][icon], wind_speed: data[wind][speed], wind_deg: data[wind].get(deg, 0), } except httpx.HTTPStatusError as e: # 根据状态码返回更友好的错误信息 if e.response.status_code 401: raise ValueError(无效的API密钥请检查配置。) elif e.response.status_code 404: raise ValueError(f未找到城市: {city}) else: raise RuntimeError(f天气API请求失败: {e}) finally: await self.client.aclose()在天气服务器中我们实例化这个客户端并将方法包装成MCP工具# servers/weather_server.py (部分代码) from mcp import Server, Tool class WeatherServer(BaseMCPServer): def __init__(self): super().__init__(Weather Server) self.api_client WeatherAPIClient() def _register_tools(self): self.server.tool() async def get_current_weather(city: str, units: str metric) - str: 获取指定城市的当前天气。 Args: city: 城市名例如 Beijing 或 北京,CN。 units: 温度单位metric (摄氏度) 或 imperial (华氏度)。 try: weather_data await self.api_client.get_current(city, units) # 将数据格式化为易读的字符串返回给AI助手 unit_symbol °C if units metric else °F return ( f{weather_data[city]}, {weather_data[country]} 当前天气\n f- 温度{weather_data[temp]}{unit_symbol} (体感 {weather_data[feels_like]}{unit_symbol})\n f- 湿度{weather_data[humidity]}%\n f- 气压{weather_data[pressure]} hPa\n f- 天气状况{weather_data[description]}\n f- 风速{weather_data[wind_speed]} m/s ) except Exception as e: return f获取天气信息失败{str(e)} # 类似地注册 get_weather_forecast 和 get_weather_by_coordinates这样当AI助手如Cursor里的Claude调用get_current_weather工具时它会收到一段格式清晰的天气描述可以直接展示给用户或用于后续分析。注意事项外部API通常有调用频率限制Rate Limit。在生产环境中务必在客户端或服务器端实现缓存和限流。例如可以为相同的city和units参数缓存结果5-10分钟避免短时间内重复调用API消耗配额。可以在WeatherAPIClient内部使用cachetools库的TTLCache来实现简单的内存缓存。4.3 新闻、汇率与名言服务器的实现模式其他服务器的实现模式与天气服务器类似都是“封装外部API - 格式化数据 - 通过MCP工具暴露”的流程但各有特点新闻服务器 (news_server.py)数据源主要依赖NewsAPI。它通常提供两种主要端点/top-headlines按国家/分类获取头条和/everything按关键词搜索。工具设计除了基本的get_top_headlines可以设计更精细的工具如search_news_by_date_range、get_news_from_specific_source如BBC, CNN。数据处理新闻数据量可能较大需要设计好分页或结果数量限制。返回给AI助手的信息应包含标题、来源、简要描述、发布时间和原文链接。挑战不同新闻源的字段格式可能不统一需要做一定的数据清洗和标准化。汇率服务器 (currency_server.py)数据源可以使用ExchangeRate-API、Fixer.io或Open Exchange Rates等。核心工具convert_currency货币转换和get_exchange_rates获取一篮子货币汇率是刚需。实现细节汇率转换需要处理货币代码的标准化如USD, EUR, CNY。API通常返回基础货币如USD对其他货币的汇率转换计算需要小心处理。例如将100欧元转换为日元amount_in_jpy 100 * (rate_usd_to_jpy / rate_usd_to_eur)。缓存策略汇率数据变化相对较慢但又是金融敏感信息。缓存策略可以更激进如每小时更新一次同时需要提供数据更新时间戳。名言服务器 (quote_server.py)数据源可能使用Quotes API或者更简单的从一个本地的、精心挑选的JSON文件中读取。工具设计get_random_quote随机名言、get_quote_by_author按作者、get_quote_by_category按分类如励志、爱情、哲学。离线支持这是唯一一个可以不依赖外部API的服务器。可以内置一个包含数百条名言的数据库SQLite或直接是Python列表实现零外部依赖保证服务的高可用性。5. 运行、调试与连接AI工具实战5.1 启动服务与验证配置好.env文件并安装依赖后启动服务非常简单。在开发环境下使用热重载模式uv run uvicorn main:app --reload --host 0.0.0.0 --port 10000这条命令做了几件事uv run确保在项目虚拟环境中执行命令uvicorn是ASGI服务器main:app指定了入口模块和FastAPI应用实例--reload使得代码修改后服务器自动重启非常适合开发。启动后打开浏览器访问http://localhost:10000/docs你应该能看到自动生成的Swagger UI文档里面列出了所有挂载的子服务的根路径如/weather,/news。访问http://localhost:10000/weather或http://localhost:10000/news等如果对应的子服务器暴露了HTTP接口也会显示其独立的文档页面。5.2 使用MCP Inspector进行协议调试MCP Inspector是一个官方提供的调试工具可以让你可视化地查看和测试MCP服务器的工具列表、调用工具并观察通信过程。这对于开发和验证服务器行为至关重要。首先确保你的服务正在运行。然后在另一个终端使用npx运行inspectornpx modelcontextprotocol/inspector uv run uvicorn main:app这条命令会启动inspector并尝试连接到你的FastAPI应用。但更常见的情况是我们手动配置连接。打开Inspector通常运行上述命令后会自动打开浏览器窗口或访问其指定的本地地址。在连接设置中Transport Type选择StreamableHTTP。这是FastAPI服务器暴露的传输方式。URLs根据你想调试的服务器填入对应的MCP端点。这是关键一步。根据项目说明端点格式为天气http://localhost:10000/weather/mcp/新闻http://localhost:10000/news/mcp/货币http://localhost:10000/currency/mcp/名言http://localhost:10000/quotes/mcp/点击“Connect”。连接成功后Inspector界面会分为两栏。左侧会列出该MCP服务器提供的所有工具如get_current_weather。点击一个工具右侧可以填写参数如{city: London}并执行。下方会显示完整的JSON-RPC请求和响应消息流这对于理解MCP协议的具体格式和排查通信问题非常有帮助。重要提示截至2025年6月Windsurf和Cursor等编辑器主要支持stdio和/sse这两种MCP传输类型对StreamableHTTP的支持可能不完整或处于实验阶段。因此在配置编辑器时通常需要选择/sse类型并填写对应的SSE端点URL例如http://localhost:10000/weather/mcp/。Inspector对StreamableHTTP的支持更好所以用它来调试协议本身是没问题的。实际在编辑器中使用时请查阅对应编辑器的最新MCP配置文档。5.3 配置AI编辑器以Cursor为例让MCP服务器在AI编辑器中生效是项目的最终目的。这里以Cursor为例展示配置步骤确保服务器运行你的fastapi-multi-server-mcp应用必须在后台运行uvicorn main:app ...。打开Cursor设置在Cursor中进入Settings-Features-MCP Servers。添加新服务器点击“Add New MCP Server”。填写配置Name 给你这个服务器起个名字例如“我的天气服务”。Type 选择sseServer-Sent Events。URL 填入你希望连接的服务的SSE端点例如http://localhost:10000/weather/mcp/。可选Command和Args 对于stdio类型的服务器才需要这里留空。保存并验证保存配置后Cursor通常会尝试连接。如果配置正确你在编辑器中与AI对话时就可以直接使用相关的工具了。例如在聊天框输入“/”可能会看到get_current_weather这个工具选项或者直接描述“上海现在的天气怎么样”AI助手会自动调用对应的工具并返回结果。对于Claude Desktop或Windsurf配置流程大同小异都是在设置中找到MCP配置部分添加服务器的连接信息类型和URL。6. 生产环境部署考量6.1 使用Gunicorn管理进程开发时用的uvicorn --reload不适合生产环境。生产环境推荐使用Gunicorn作为进程管理器配合Uvicorn工作进程来处理异步请求。Gunicorn负责管理多个工作进程提供更稳定的服务。一个基本的启动命令如下gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:10000-w 4 启动4个工作进程。一个常见的经验法则是设置为CPU核心数 * 2 1。对于IO密集型应用如本API代理项目可以适当增加。-k uvicorn.workers.UvicornWorker 指定使用Uvicorn的工作线程类以支持ASGI应用。--bind 0.0.0.0:10000 绑定到所有网络接口的10000端口。你还可以通过环境变量或配置文件设置更多参数例如超时时间、日志级别、进程守护等。6.2 Docker容器化部署项目提供了Dockerfile使得部署变得极其简单和一致。Docker化能确保在任何环境本地、云服务器中运行的应用其依赖和配置都是完全相同的。一个典型的Dockerfile内容如下# 使用官方Python轻量级镜像 FROM python:3.11-slim # 设置工作目录 WORKDIR /app # 复制依赖列表并安装 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 复制应用代码 COPY . . # 暴露端口与.env中的PORT一致 EXPOSE 10000 # 设置环境变量生产环境建议通过docker run -e传入或使用secrets ENV PORT10000 ENV HOST0.0.0.0 ENV LOG_LEVELinfo # 启动命令使用gunicorn CMD [gunicorn, main:app, -w, 4, -k, uvicorn.workers.UvicornWorker, --bind, 0.0.0.0:10000]构建和运行镜像# 在项目根目录构建镜像 docker build -t fastapi-mcp-server . # 运行容器将宿主机的10000端口映射到容器的10000端口并传入API密钥 docker run -d -p 10000:10000 \ -e OPENWEATHER_API_KEYyour_key \ -e NEWS_API_KEYyour_key \ -e EXCHANGE_RATES_API_KEYyour_key \ --name mcp-server \ fastapi-mcp-server安全提醒在Docker或任何生产环境中切勿将API密钥写在Dockerfile或代码里。应通过-e环境变量、Docker Secrets、或云平台的密钥管理服务注入。.env文件仅用于本地开发。6.3 性能优化与监控建议当服务正式上线后需要考虑以下几点反向代理与SSL在生产环境前务必放置一个反向代理如Nginx或Caddy。它不仅可以处理SSL/TLS终止提供HTTPS还能进行静态文件服务、负载均衡和基本的速率限制。# Nginx 配置示例片段 server { listen 443 ssl; server_name your-domain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location / { proxy_pass http://localhost:10000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }速率限制为了防止滥用需要对API调用进行限流。可以在FastAPI应用级别或Nginx级别实现。FastAPI可以使用slowapi或fastapi-limiter等中间件。日志与监控配置好日志将日志输出到标准输出stdout或文件方便被Docker或系统日志收集器如Fluentd, Loki抓取。同时可以集成像Prometheus这样的监控系统暴露应用指标如请求数、延迟、错误率。健康检查为每个子服务或主服务添加一个/health端点返回服务的状态如数据库连接、外部API可达性。这对于容器编排平台如Kubernetes的健康探针非常有用。缓存升级如前所述将内存缓存cachetools替换为分布式缓存如Redis特别是在多工作进程或多副本部署时可以保证缓存的一致性并共享缓存结果。7. 测试策略与质量保障7.1 单元测试与集成测试项目包含了tests/目录为每个服务器编写了测试用例。良好的测试是项目稳健的基石。测试主要分为两类单元测试测试单个函数或类的逻辑。例如测试WeatherAPIClient中处理API响应和错误格式化的逻辑。为了不实际调用外部API我们使用pytest和pytest-asyncio并结合pytest-httpx或responses来模拟mockHTTP请求。# tests/test_weather.py 示例 import pytest from unittest.mock import AsyncMock, patch from servers.weather_server import WeatherServer pytest.mark.asyncio async def test_get_current_weather_success(): # 模拟API客户端返回的数据 mock_data { name: Beijing, sys: {country: CN}, main: {temp: 22, feels_like: 20, humidity: 65, pressure: 1013}, weather: [{description: 晴朗, icon: 01d}], wind: {speed: 3.5} } # 使用patch模拟WeatherAPIClient的get_current方法 with patch(servers.weather_server.WeatherAPIClient.get_current, new_callableAsyncMock) as mock_get: mock_get.return_value mock_data server WeatherServer() # 这里需要调用内部方法或通过某种方式触发工具函数 # 假设我们有一个内部测试方法 result await server._test_tool_call(get_current_weather, {city: Beijing}) assert Beijing in result assert 22°C in result mock_get.assert_called_once_with(Beijing, metric)集成测试测试整个MCP工具调用的流程。这需要启动一个测试版的服务器实例然后使用MCP客户端库模拟AI助手发起工具调用验证端到端的响应。这种测试更重但能发现组件间集成的问题。运行测试很简单# 运行所有测试 pytest # 运行特定文件测试 pytest tests/test_weather.py -v # 运行测试并生成覆盖率报告 pytest --covservers --cov-reporthtml7.2 持续集成与自动化对于个人或团队项目建议配置GitHub Actions或GitLab CI等持续集成流水线。每次代码推送或合并请求时自动运行测试套件确保新代码不会破坏现有功能。一个简单的.github/workflows/test.yml配置示例name: Python Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Set up Python uses: actions/setup-pythonv4 with: python-version: 3.11 - name: Install UV run: pip install uv - name: Install dependencies run: uv sync - name: Run tests with pytest run: uv run pytest env: # 为测试设置虚拟的API密钥因为测试中会mock实际不会调用 OPENWEATHER_API_KEY: test_key NEWS_API_KEY: test_key EXCHANGE_RATES_API_KEY: test_key8. 常见问题与排查技巧实录在实际开发和部署过程中你可能会遇到以下问题。这里记录了我踩过的一些坑和解决方法。8.1 连接与通信问题问题1MCP Inspector或编辑器无法连接提示“Connection refused”或超时。检查服务是否运行首先确认uvicorn或gunicorn进程正在运行并且没有报错。使用ps aux | grep uvicorn或查看终端输出。检查端口和主机确保启动命令中的--host 0.0.0.0和--port 10000正确并且该端口没有被其他程序占用。可以用netstat -tulpn | grep :10000Linux或lsof -i :10000macOS检查。检查防火墙如果是在服务器或虚拟机上确保防火墙如ufw或安全组规则允许了10000端口的入站连接。检查URL路径这是最常见的问题。确保Inspector或编辑器中填写的URL完整且正确特别是末尾的/mcp/路径。应该是http://你的地址:端口/服务名/mcp/例如http://localhost:10000/weather/mcp/。缺少末尾的斜杠可能导致404错误。问题2连接成功但工具列表为空或调用工具时出错。检查MCP服务器初始化确认在main.py中正确创建并挂载了服务器实例。检查每个服务器的_register_tools方法是否被正确调用工具装饰器self.server.tool()使用是否正确。查看服务器日志启动服务时添加--log-level debug参数查看详细的请求和错误日志这能提供最直接的线索。验证外部API密钥工具调用失败可能是因为外部API返回了401或403错误。检查.env文件中的API密钥是否正确以及对应的外部服务账户是否活跃、是否有调用配额。8.2 性能与稳定性问题问题3响应慢尤其是调用新闻或天气API时。启用缓存如前所述为外部API响应实现缓存是提升性能的关键。对于天气数据缓存5-10分钟是合理的对于汇率可以缓存更久。检查网络延迟如果服务器部署在海外调用国内的某些API可能会有延迟。考虑将服务部署在离目标API地理上更近的区域或者使用CDN。并发限制外部API通常有并发限制。确保你的HTTP客户端如httpx.AsyncClient使用了连接池并且没有在短时间内发起大量请求。可以通过tenacity库添加重试和退避逻辑避免在API暂时不可用时雪崩。问题4服务运行一段时间后内存缓慢增长或崩溃。检查资源泄漏确保异步HTTP客户端在请求后正确关闭或使用上下文管理器。在FastAPI的lifespan事件或每个路由的依赖项中管理客户端生命周期。监控日志查看是否有未处理的异常导致进程不稳定。确保所有可能的异常都被捕获并记录而不是让整个请求崩溃。限制请求大小和频率在反向代理如Nginx或应用层实施速率限制防止恶意或异常的请求流量拖垮服务。8.3 开发与配置问题问题5修改了服务器代码但热重载没有生效。确认使用了--reload开发命令中必须包含--reload标志。检查文件监视在某些虚拟化环境或网络文件系统上文件系统事件可能无法正确触发重载。可以尝试使用--reload-dir选项明确指定要监视的目录例如--reload-dir ./servers。手动重启如果热重载一直有问题最可靠的方式是停止进程并重新启动。问题6在Docker中运行无法连接到localhost上的服务。理解Docker网络在Docker容器内部localhost指的是容器本身而不是宿主机。要从宿主机连接容器内的服务需要在运行容器时使用-p参数进行端口映射如-p 10000:10000然后通过宿主机的IP和映射的端口访问。在容器内连接其他服务如果MCP服务器需要访问宿主机上运行的其他服务如数据库不能使用localhost而应使用宿主机的真实IP或者Docker提供的特殊DNS名称host.docker.internal在macOS/Windows的Docker Desktop中可用。问题7UV安装依赖失败提示版本冲突或找不到包。清理并重建环境有时虚拟环境会处于不一致状态。可以删除.venv目录和uv.lock文件然后重新运行uv sync。检查Python版本确保本地安装的Python版本符合项目要求如3.11。可以使用uv python pin 3.11来指定版本。检查网络确保网络连接正常能够访问PyPI。如果使用代理可能需要为UV配置代理环境变量。这个项目麻雀虽小五脏俱全。从协议理解、API封装、服务架构到部署运维它覆盖了一个后端服务从开发到上线的多个关键环节。最重要的是它解决了一个非常实际的问题——让AI工具变得更“知情”和“能干”。希望这份详细的拆解能帮助你更好地理解、使用甚至扩展这个项目。如果在实践中遇到新的问题最好的办法永远是查看日志、阅读官方文档FastAPI、Uvicorn、MCP协议以及善用搜索引擎和社区。