AI导哈

天气工具服务器

一个基于Express构建的Model Context Protocol (MCP)服务器，提供由美国国家气象局(NWS) API支持的天气工具，适用于AI代理和客户端调用。

  • by blockvoltcr7
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 blockvoltcr7/mcp-with-express

使用说明

Vercel上的Express MCP服务器（天气）

使用Express构建的模型上下文协议（MCP）服务器，该服务器提供了由美国国家气象局（NWS）API支持的天气工具。随附可流式传输的HTTP传输和示例代理脚本，用于本地测试或部署测试。

这个应用的作用

  • 暴露MCP工具 通过HTTP访问 POST /mcp 针对AI代理/客户端。
  • 可用的工具 （在……中定义 src/create-server.ts):
    • 获取警报获取美国某州的实时天气警报。输入： { state: "CA" } （2字母代码）。
    • 获取天气预报获取纬度/经度的天气预报。输入： { latitude: 37.7749, longitude: -122.4194 }。
  • 使用NWS API (api.weather.gov) 具有可配置的 User-Agent。

架构概述

  • **src/index.ts**Express 启动、CORS（跨域资源共享）、静态文件、MCP 路由（POST /mcp， GET /mcp， DELETE /mcp）。 实现了基于会话的可流式传输HTTP传输：新会话被创建并存储在 initialize；后续请求将重用已存储的传输（或“已存储的传输方式”） mcp-session-id。
  • **src/create-server.ts**创建 McpServer，寄存器 get-alerts 并且 get-forecast使用Zod验证输入，调用NWS（美国国家气象局），并格式化结果。
  • **public/**静态资源。
  • **build/**编译后的JS输出（请勿直接编辑）。
  • **scripts/agent.mjs**一个最小化连接的代理 /mcp 并运行一个提示（服务器分配会话ID）。
  • **scripts/multi-agent.mjs**同时运行两个代理；每个代理都有自己的MCP HTTP会话（由服务器分配）。
  • **scripts/vercel-ai-agent.mjs**使用Vercel AI SDK的MCP客户端来发现此服务器上的工具。

交通： 可流式传输的HTTP 来自 @modelcontextprotocol/sdk，这需要一个MCP（多点控制单元） initialize 在调用工具之前进行握手。服务器分配会话ID；客户端不得硬编码或预先生成它们。

先决条件

  • Node 18或更高版本（推荐使用Node 20）
  • pnpm（首选）

本地安装并运行

pnpm install
pnpm dev
# Server listens on http://localhost:3000

构建并运行编译后的包：

pnpm build
pnpm start

环境变量（通过 dotenv 在 src/index.ts 和 scripts/*.mjs):

  • PORT （可选）：默认为 3000.
  • OPENAI_API_KEY （需使用OpenAI模型运行示例代理脚本）。
  • MCP_URL （脚本中可选）：例如。 http://localhost:3000/mcp 或者您已部署的 /mcp URL（统一资源定位符）。
  • AGENT_PROMPT， AGENT_A_PROMPT， AGENT_B_PROMPT （可选）：自定义脚本提示。

创建一个 .env 根据需要，在仓库根目录中：

OPENAI_API_KEY=sk-...
MCP_URL=http://localhost:3000/mcp

使用MCP Inspector（图形用户界面）进行测试

  • 安装/运行 MCP检查器。
  • 使用以下方式连接：
    • 交通HTTP
    • URL（统一资源定位符）: http://localhost:3000/mcp （或你已部署的 /mcp）
  • 检查器处理MCP握手和头部信息，并允许您交互式地调用工具。

使用提供的代理脚本进行测试

这些脚本使用OpenAI Agents SDK和Vercel AI SDK来连接到MCP服务器并运行提示。服务器在MCP握手过程中分配会话ID。

  1. 单一代理（默认提示要求CA警报）：
pnpm agent
# or override the prompt
AGENT_PROMPT="Forecast for 37.7749,-122.4194" pnpm agent
  • 脚本： scripts/agent.mjs
  1. 多代理（两个代理，独立会话，并发执行）：
pnpm agents:multi
# with prompt overrides
AGENT_A_PROMPT="List tools with schemas" \
AGENT_B_PROMPT="Forecast for 40.7128,-74.0060" \
pnpm agents:multi
  • 脚本： scripts/multi-agent.mjs
  1. Vercel AI SDK MCP 客户端（工具发现）：
pnpm vercel:agent
  • 脚本： scripts/vercel-ai-agent.mjs

使用curl进行测试（高级）

Streamable HTTP传输需要同时满足以下两个条件：

  • Accept: application/json, text/event-stream
  • 一个MCP（Multi-Channel Processor，多通道处理器） initialize 在任何（行动）之前先握手 tools/* （电话）呼叫

因为使用curl管理会话/握手容易出错，所以建议使用Inspector或脚本。如果您仍然想尝试使用curl，请确保：

  • 包含 Accept 请求头。
  • 执行 initialize 首先，并在后续调用中重用同一个会话。

列出工具（未初始化时将失败）：

curl -s http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

部署（Vercel）

  • 通过Vercel按钮或您的工作流程进行部署。确保 /mcp 路由可达。
  • 在客户端中使用您的部署URL： https://<your-deployment>.vercel.app/mcp。
  • 冷启动：此服务器现在等待初始化后才能提供服务 /mcp减少“服务器未初始化”的响应。

NWS注：

  • USER_AGENT 在 src/create-server.ts 如果你发布这个，应该将其更新为你自己的标识符。

故障排除

  • 不可接受：客户端必须同时接受 application/json 和 text/event-stream

    • 添加标题： -H 'Accept: application/json, text/event-stream'

  • 错误请求：服务器未初始化

    • 您的客户必须执行MCP（最小化兼容协议/流程，具体含义根据上下文确定） initialize 首先进行握手。服务器将分配一个会话ID；客户端应在后续请求中重用该ID。检查器和提供的脚本会自动处理这一过程。

  • 无效请求：服务器已初始化

    • 您尝试对一个已存在的可流式传输HTTP会话进行重新初始化。请不要发送第二个（请求/初始化） initialize 对于同一个会话；相反，应重用服务器返回的会话ID。

  • 客户端提供的会话ID失败

    • 不要预先生成 sessionId 客户端。让服务器在期间分配它 initialize，然后在后续请求中通过（某种方式）将其包含进去 mcp-session-id 头部（SDK 会为您处理这部分）。

  • 端口3000正在使用中

    • 终止正在使用该进程的程序，或者设置 PORT 在 .env 并重新启动。

  • zod 的同级依赖警告

    • 你可以对齐版本，例如：。 pnpm add zod@^3.25.40，但在本地测试时它是非阻塞的。

项目脚本

  • pnpm dev – 在TypeScript中启用watch + nodemon build/index.js。
  • pnpm build – 编译为 build/。
  • pnpm start – 运行编译后的服务器。
  • pnpm agent – 使用HTTP上的MCP（可能是指某种通信协议或中间件）的单代理示例。
  • pnpm agents:multi – 两名代理同时进行，各自拥有独立会话。
  • pnpm vercel:agent – Vercel AI SDK 客户端，用于连接 MCP 服务器并发现工具。

API终端点

  • POST /mcp – 可流式传输的HTTP MCP端点。用于初始化和JSON-RPC方法调用。
  • GET /mcp – 为当前会话流式传输响应。
  • DELETE /mcp – 关闭当前会话。

回购指南

以下 TypeScript 源代码 src/不要编辑 build/使用 pnpm 进行安装。环境通过 dotenv. 见 AGENTS.md 关于存储库规范和注意事项。

要深入了解会话管理的变化以及如何避免常见陷阱，请参阅 docs/session-management-fix.md。

相关 MCP