AI导哈

模型上下文协议演示服务器

一个基于FastAPI实现的MCP演示服务器，提供天气、加密货币、文件和健康检查等工具接口，适用于与Claude等支持MCP协议的助手集成。

  • by Sir-Ian
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Sir-Ian/MCP_Demo

使用说明

MCP_Demo 翻译为中文是“MCP示例”或“MCP演示”

一个使用FastAPI实现的小型演示模型上下文协议（MCP）服务器。它附带了一个极简的前端和一些演示工具（天气、加密货币、文件、健康检查），以便您测试工具集成（例如与支持MCP风格工具钩子的Claude或其他助手）。

这个README文件展示了如何安装、运行以及将MCP服务器连接到Claude（或其他助手）。它包括故障排除说明以及服务器公开的API端点的简短参考。

内容

  • app.py — FastAPI MCP 示例服务器和静态用户界面挂载
  • static/ — 轻量级网页用户界面（index.html， app.js， style.css)
  • resources/docs/ — 已发送示例文件（通过 /mcp/file 工具)
  • requirements.txt — Python 依赖项

快速概览

服务器提供了以下演示工具： /mcp/*：

  • /mcp/weather (POST) — 返回每日小预报；接受 city 或者 lat/lon 和 days (1–7)。 支持 x-demo-fallback 头部设置用于跳过外部网络调用并返回确定性的演示数据。
  • /mcp/crypto (POST) — 返回一个价格给 btc， eth或者 sol; 支持 x-demo-fallback 确定性值的标题（或头部信息）。
  • /mcp/file (POST) — 从（某处）读取文件 resources/docs 并返回裁剪后的文本。
  • /mcp/health (GET) — 服务器健康状况和运行时间。

还有一个随附的微型前端界面 static/index.html 该程序用于测试这些终端点（API端点），并可通过根URL访问。

要求

  • Windows、macOS 或 Linux 系统，需安装 Python 3.11+（本 README 文件中的示例使用 Windows 的 PowerShell）。
  • 如果你克隆了仓库，使用 Git。

建议：使用虚拟环境以避免更改系统自带的Python。

安装（Windows PowerShell）

  1. 如果你没有安装Python，请从https://www.python.org/downloads/windows/下载并安装。安装过程中，请勾选“将Python添加到PATH”。

  2. 在仓库根目录下，创建并激活虚拟环境（PowerShell）：

python -m venv .venv
.\.venv\Scripts\Activate.ps1

如果你已经使用了一个不同的虚拟环境名称（例如 .venv-2），而是激活那个：

.\.venv-2\Scripts\Activate.ps1
  1. 安装依赖项：
pip install -r requirements.txt

注：FastAPI与Pydantic版本之间存在已知的兼容性差异。如果您遇到提及以下内容的错误： ForwardRef._evaluate() 或者类似的，尝试使用此仓库中使用的固定版本（通过 requirements.txt）。 如果您要升级包，请优先选择匹配的FastAPI/Pydantic组合（FastAPI与Pydantic v1配对，或FastAPI >=0.100与Pydantic v2配对）。请参阅下面的故障排除部分。

运行服务器

使用虚拟环境（venv）的Python启动应用程序（PowerShell）：


.\.venv\Scripts\python.exe app.py

# or if you used another env name:
.\.venv-2\Scripts\python.exe app.py

服务器将在 http://127.0.0.1:8000 默认情况下。在您的浏览器中打开该URL以查看演示用户界面。OpenAPI文档位于 http://127.0.0.1:8000/docs。

如果端口8000已被占用，请停止绑定到该端口的进程，或者通过编辑配置文件在另一个端口上运行服务器 uvicorn.run(...) 打电话进来 app.py 或者跑步 uvicorn 直接，例如：

.\.venv\Scripts\python.exe -m uvicorn app:app --host 127.0.0.1 --port 8001

API 参考（概要）

  • POST /mcp/weather 翻译为中文是：“向/mcp/weather发送POST请求”

    • 主体（Body）：{ city?: string（城市名，可选）, lat?: number（纬度，可选）, lon?: number（经度，可选）, days: number（天数） }
    • 标题： x-demo-fallback: 1|true 强制回退（不进行网络发送）。

  • POST /mcp/crypto 翻译为中文是：“POST 到 /mcp/crypto（路径）”。不过，通常在实际应用中，我们不会直接翻译路径这样的字符串，而是理解为“向 /mcp/crypto 路径发送 POST 请求”。但为了符合翻译要求，这里提供了直译版本

    • 主体：{ 符号：字符串，vs?: 字符串 }
    • 接受 symbol 像 btc， eth， sol。

  • POST /mcp/file 翻译成中文是：“发送至 /mcp/file（路径）”。不过，这样的翻译在中文语境下可能不太常见，因为“POST”通常用于描述网络请求方法，而“/mcp/file”是一个路径或端点。更自然的表达可能是：“向 /mcp/file 发送POST请求”或者“对/mcp/file执行POST操作”。但根据您的要求，直接翻译为“发送至 /mcp/file”也是可以的

    • 主体：{ 名称: 字符串, 最大字符数: 整数 }
    • name 解析为以下文件 resources/docs。

  • GET /mcp/health 翻译为中文是：“获取 /mcp/health（资源）”

    • 返回服务器名称、运行时间以及各版本信息。

提示：使用随附的前端（位于） / 快速使用工具。

克劳德（MCP）集成

这个项目旨在作为MCP（多助手协作协议）工具服务器，用于辅助集成。要将其连接到Claude Desktop（或其他支持MCP的助手）：

  1. 确保服务器正在运行，并且可以通过配置的基础URL（默认为 http://127.0.0.1:8000）。 打开健康检查端点以进行验证：
Tiny demo server to prove the MCP concept (tools+JSON+STDIO/http). This repository contains a minimal FastAPI app that exposes three "data lanes" (weather, crypto, file summarizer) plus a health endpoint.
curl http://127.0.0.1:8000/mcp/health
  1. 添加一个Claude配置JSON文件（示例见下文）。如果您使用的是Claude Desktop，配置文件通常存储在您的应用程序配置位置——在我们的测试中，我们使用了 claude_desktop_config.json。

示例：Claude MCP 配置（最小化）：

{
	"server_url": "http://127.0.0.1:8000",
	"tools": [
		{ "name": "weather", "path": "/mcp/weather", "input_schema": "WeatherIn", "output_schema": "WeatherOut" },
		{ "name": "crypto",  "path": "/mcp/crypto",  "input_schema": "CryptoIn",  "output_schema": "CryptoOut" },
		{ "name": "file",    "path": "/mcp/file",    "input_schema": "FileIn",    "output_schema": "FileOut" },
		{ "name": "health",  "path": "/mcp/health",  "input_schema": "none",     "output_schema": "HealthOut", "http_method": "GET" }
	]
}

克劳德集成说明：

  • 确保克劳德能够到达 http://127.0.0.1:8000 从它运行的机器中获取。如果Claude运行在其他地方（如云端），您需要将MCP服务器暴露出来（通过ngrok、localtunnel或公开托管），并适当确保其安全性。
  • 服务器已启用CORS（为演示方便）并支持一个简单的工具目录，位于 /mcp/tools。
  • 如果Claude在配置中需要明确的JSON模式，请包含 input_schema / output_schema （JSON Schema 中的）对象，而不仅仅是名称。仓库的文档/测试中提供了一个填充了示例模式的配置。
  1. 更新配置后，重启Claude（桌面版）以使其加载新工具。然后尝试让Claude使用工具，例如询问“芝加哥的天气怎么样？”。

开发说明/代码提示

  • app.py 集中管理端点和静态挂载。根路由重定向到 /static/index.html。
  • 该演示使用了 httpx 对于出站的HTTP请求；网络调用受到5秒超时的保护，并且具有确定性的回退模式。
  • 看看 resources/docs/ai-safety-notes.txt 用于文件工具的一个已发货的示例文件。

故障排除

  • “未找到 Python”——请安装 Python 并将其添加到 PATH 中，或者运行解释器的完整路径。
  • PowerShell中的激活错误——请确保允许脚本执行或使用 Activate.ps1 如上所示的脚本。如果你看到 source 错误，那是一个Unix shell命令；请使用PowerShell激活表单。
  • “端口8000已被占用”——停止现有进程（Ctrl+C 在服务器终端中）或使用 PowerShell 查找/终止进程： Stop-Process -Name python -Force （小心，这会终止所有Python进程）。
  • Pydantic/FastAPI 兼容性错误（示例： ForwardRef._evaluate() （缺少参数）——这些错误是由于在 Pydantic v2 运行时中混合使用了 Pydantic v1 风格的注解。建议的方法：
    • 使用指定版本的软件包 requirements.txt 对于所编写（或：如所编写）的代码。
    • 或者将应用程序模型升级为使用 Pydantic v2 的惯用法（该仓库包含一些带有注释的示例，用于兼容 Pydantic v2）。

快速冒烟测试示例（PowerShell）


.\.venv\Scripts\Activate.ps1
Run (recommended in a venv)
.\.venv\Scripts\python.exe app.py

curl http://127.0.0.1:8000/mcp/health

贡献；助力

欢迎进行小幅度且有针对性的更改。如果您添加或更改了API，请更新README文件和示例Claude配置。

如果你愿意，我也可以：

  • 添加一个 docker-compose.yml 在容器内运行服务器，
  • 创建一个预构建的Claude配置，其中包含完整的JSON Schema对象，或者
  • 添加一个小的测试脚本，以自动测试每个端点。

告诉我你接下来想要哪一个。

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.py

终点（或：终点指标）

  • GET /mcp/tools — 工具目录
  • POST /mcp/weather — 天气输入（WeatherIn）-> 天气输出（WeatherOut）
  • POST /mcp/crypto — CryptoIn（加密输入） -> CryptoOut（加密输出）
  • POST /mcp/file — 文件输入 -> 文件输出（读取资源中的docs目录下的文件）
  • GET /mcp/health — 健康检查（HealthOut）

前端演示

  1. 在虚拟环境中启动服务器：
python3 -m uvicorn app:app --host 127.0.0.1 --port 8000
  1. 打开您的浏览器，访问：http://127.0.0.1:8000/ —— 一个简洁的用户界面将允许您调用每个通道并显示JSON响应。该用户界面使用相同的HTTP端点，并展示了用于离线演示的确定性回退机制。

演示模式与编排

  • 用户界面包含一个“演示模式”选择器（实时/备用）。当设置为备用模式时，服务器将返回天气和加密货币的确定性备用值。这是通过发送一个 x-demo-fallback: 1 头球
  • 使用 agent_sim.py 模拟一个链接工具的大型语言模型（LLM）。示例：
# run with live calls (default)
python3 agent_sim.py

# force fallback deterministic mode
python3 agent_sim.py --fallback

90年代的演示叙事

  1. 读取文件：POST /mcp 文件名=ai-safety-notes.txt 最大字符数=200 — 确定性摘录
  2. 获取天气信息：POST /mcp/weather city=Chicago days=1 — 实时获取，具有确定性回退机制
  3. 实时编号：POST /mcp/crypto symbol=btc vs=usd — 来自 CoinGecko 的实时数据，备选方案
  4. 状态：GET /mcp/health — 运行时间 & 配置

相关 MCP