convez.ai
MCP ServerIntegração & APIsIntermediário
tomripp

Weather MCP Server

tomripp/mcp-server

MCP server de clima com duplo transporte HTTP (JSON/SSE)

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que fornece dados meteorológicos via API Open-Meteo, com suporte a dois modos de transporte (JSON e SSE). Implementa ferramentas para busca de localidades, clima atual, previsão e alertas severos, com endpoints HTTP estateful spec-compliant.

Instalação

$npx convez-ai tomripp/mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Integrar dados meteorológicos em agents Claude
  • Testar diferentes modos de transporte MCP (JSON vs SSE)
  • Fornecer contexto climático em automações e fluxos

Veredito

Exemplo técnico bem-estruturado de MCP server com implementação dual de transporte. Útil como referência ou base para integração de dados meteorológicos, mas escopo limitado a um caso de uso específico.

README

A tradução para o português deste README ainda está na fila.

Weather MCP Server

A small example Model Context Protocol server exposing weather tools, a resource template, and a prompt. It is deployed with two Streamable HTTP endpoints serving the identical capability set — one returning plain JSON, the other returning SSE — so MCP clients can be tested against both transport response modes.

Data source: Open-Meteo (free, no API key).


1. Endpoints

PurposeURLResponse format
JSON modehttps://mcpserver-production-dd31.up.railway.app/json/mcpapplication/json
SSE modehttps://mcpserver-production-dd31.up.railway.app/sse/mcptext/event-stream
Healthhttps://mcpserver-production-dd31.up.railway.app/healthapplication/json ({"status":"ok"})

Both MCP endpoints implement the full stateful Streamable HTTP flow: initialize → notifications/initialized → any number of tool/resource/prompt calls, all carrying an mcp-session-id header returned by initialize.

Both are spec-compliant — MCP's Streamable HTTP transport explicitly allows either JSON or SSE for request/response pairs. The JSON endpoint is easier to consume from generic HTTP clients (Node-RED, curl, n8n HTTP nodes); the SSE endpoint is the default behavior you'll see from most MCP SDKs.

Project files

MCPserver/
├── server.py           # Dual-endpoint Starlette app + FastMCP instances
├── weather_client.py   # Async Open-Meteo wrapper
├── requirements.txt    # mcp[cli], httpx, starlette, uvicorn
├── Procfile
├── railway.json
├── .gitignore
└── README.md           # (this file)

2. Server settings — JSON vs SSE

The server in server.py mounts the same tools/resources/prompts twice by building two FastMCP instances with different response modes, then mounting them under different path prefixes in a Starlette app.

Key per-instance options:

FastMCP(
    name="weather-example-json",
    json_response=True,      # plain JSON response bodies
    ...
)

FastMCP(
    name="weather-example-sse",
    json_response=False,     # default — SSE streaming
    ...
)
OptionEffect
json_response=TrueEach response body is a single application/json blob. Easier for plain HTTP tooling.
json_response=False (default)Responses are served as text/event-stream frames: event: message\ndata: <json>\n\n. Matches what MCP SDKs emit by default.
stateless_http=True(Not used here.) Skips the session/init handshake; every request is independent.
Default (stateful)Requires initialize → notifications/initialized → tool calls, with mcp-session-id header on every call after init.

Required request headers (both endpoints)

HeaderValue
Content-Typeapplication/json
Acceptapplication/json, text/event-stream (both required by the spec)
mcp-session-idThe session id returned in the initialize response header — set on every call after initialize.

3. Tools, resource, and prompt

Tools

NameArgsPurpose
search_locationsquery: stringGeocode a place name → up to 5 candidate lat/lon results.
get_current_weatherlocation: stringCurrent temp, humidity, wind, WMO weather code.
get_forecastlocation: string, days: int = 3Daily forecast (tmin/tmax, precip, code). days clamped to 1..16.
get_severe_alertslocation: stringSynthesized severe-weather signal (heavy rain ≥25 mm, heat ≥38 °C, cold ≤ −15 °C) over the next 2 days.

Resource (template)

URI templateReturns
weather://briefing/{location}Bundled JSON {current, forecast (3 days), alerts} for the given location.

Listed via resources/templates/list, read via resources/read with a concrete URI like weather://briefing/Karlsruhe, Germany.

Prompt

NameArgsWhat it does
weather_briefinglocation: string, audience: string = "general"Generates a user-message asking the model to use the weather tools and compose a briefing tailored to the audience.

4. MCP Streamable HTTP flow at a glance

Client                                    Server
  │                                         │
  │── POST /…/mcp  initialize ─────────────▶│   (no session id yet)
  │◀── 200 + header: mcp-session-id: <ID>  ─│
  │                                         │
  │── POST /…/mcp  notifications/initialized▶   (header: mcp-session-id: <ID>)
  │◀── 202 Accepted ───────────────────────│
  │                                         │
  │── POST /…/mcp  tools/call ─────────────▶│   (header: mcp-session-id: <ID>)
  │◀── 200 + result ───────────────────────│
  │                                         │
  │── POST /…/mcp  tools/call … ───────────▶│
  │◀── 200 + result ───────────────────────│
  │             (repeat as needed)          │

The JSON and SSE endpoints maintain independent session spaces. A session id obtained from /json/mcp only works against /json/mcp, and similarly for SSE.


5. curl / bash — sample calls (JSON and SSE)

Reusable setup for both modes:

JSON_URL="https://mcpserver-production-dd31.up.railway.app/json/mcp"
SSE_URL="https://mcpserver-production-dd31.up.railway.app/sse/mcp"
CT="Content-Type: application/json"
ACCEPT="Accept: application/json, text/event-stream"

5.1 initialize → session id

JSON

# Capture the mcp-session-id header from the initialize response
SID_JSON=$(curl -s -D - -X POST "$JSON_URL" -H "$CT" -H "$ACCEPT" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"cli","version":"1.0"}}}' \
  | grep -i "mcp-session-id:" | awk '{print $2}' | tr -d '\r\n')
echo "json session: $SID_JSON"

SSE

SID_SSE=$(curl -s -D - -X POST "$SSE_URL" -H "$CT" -H "$ACCEPT" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"cli","version":"1.0"}}}' \
  | grep -i "mcp-session-id:" | awk '{print $2}' | tr -d '\r\n')
echo "sse session: $SID_SSE"

5.2 notifications/initialized

Same request shape for both — only the URL differs.

JSON

curl -s -o /dev/null -w "notify HTTP %{http_code}\n" -X POST "$JSON_URL" \
  -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_JSON" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

SSE

curl -s -o /dev/null -w "notify HTTP %{http_code}\n" -X POST "$SSE_URL" \
  -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_SSE" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

5.3 tools/list

JSON

curl -s -X POST "$JSON_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_JSON" \
  -d '{"jsonrpc":"2.0","id":10,"method":"tools/list"}'

Sample reply (truncated):

{"jsonrpc":"2.0","id":10,"result":{"tools":[{"name":"search_locations", ...}, ...]}}

SSE

curl -s -X POST "$SSE_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_SSE" \
  -d '{"jsonrpc":"2.0","id":10,"method":"tools/list"}'

Sample reply (SSE framing — parse the data: line as JSON):

event: message
data: {"jsonrpc":"2.0","id":10,"result":{"tools":[{"name":"search_locations", ...}, ...]}}

5.4 tools/call — current weather for Karlsruhe

JSON

curl -s -X POST "$JSON_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_JSON" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_current_weather","arguments":{"location":"Karlsruhe, Germany"}}}'

SSE

curl -s -X POST "$SSE_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_SSE" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_current_weather","arguments":{"location":"Karlsruhe, Germany"}}}'

5.5 resources/templates/list

JSON

curl -s -X POST "$JSON_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_JSON" \
  -d '{"jsonrpc":"2.0","id":11,"method":"resources/templates/list"}'

SSE

curl -s -X POST "$SSE_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_SSE" \
  -d '{"jsonrpc":"2.0","id":11,"method":"resources/templates/list"}'

5.6 resources/read — briefing bundle

JSON

curl -s -X POST "$JSON_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_JSON" \
  -d '{"jsonrpc":"2.0","id":20,"method":"resources/read","params":{"uri":"weather://briefing/Karlsruhe, Germany"}}'

SSE

curl -s -X POST "$SSE_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_SSE" \
  -d '{"jsonrpc":"2.0","id":20,"method":"resources/read","params":{"uri":"weather://briefing/Karlsruhe, Germany"}}'

5.7 prompts/list

JSON

curl -s -X POST "$JSON_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_JSON" \
  -d '{"jsonrpc":"2.0","id":12,"method":"prompts/list"}'

SSE

curl -s -X POST "$SSE_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_SSE" \
  -d '{"jsonrpc":"2.0","id":12,"method":"prompts/list"}'

5.8 prompts/get

JSON

curl -s -X POST "$JSON_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_JSON" \
  -d '{"jsonrpc":"2.0","id":30,"method":"prompts/get","params":{"name":"weather_briefing","arguments":{"location":"Karlsruhe, Germany","audience":"pilots"}}}'

SSE

curl -s -X POST "$SSE_URL" -H "$CT" -H "$ACCEPT" -H "mcp-session-id: $SID_SSE" \
  -d '{"jsonrpc":"2.0","id":30,"method":"prompts/get","params":{"name":"weather_briefing","arguments":{"location":"Karlsruhe, Germany","audience":"pilots"}}}'

6. Node-RED — function code for HTTP Request nodes

Two variants of the flow are provided: one targeting the JSON endpoint and one targeting the SSE endpoint. The session / init sequence is identical; the only differences are the URL and how you parse the response body.

6.1 Flow shape (both variants)

inject
  → [Fn1 init req]     → [HTTP 1: initialize]
  → [Fn2 notify req]   → [HTTP 2: notify]       (body is empty, status 202)
  → [Fn3 tools/call]   → [HTTP 3: tools/call]
  → [Fn4 unwrap]
  → debug

HTTP Request node settings:

  • Method: - use msg.method -
  • URL: - use msg.url -
  • JSON variant: HTTP 1 and HTTP 3 return a parsed JSON object; HTTP 2 returns a UTF-8 string.
  • SSE variant: HTTP 1, HTTP 2, and HTTP 3 all return a UTF-8 string (SSE framing has to be parsed manually).

After each HTTP Request node, msg.headers holds the response headers, so Fn2 can pull mcp-session-id out of it.

6.2 JSON variant — function code

Fn1 — build initialize request

msg.method = "POST";
msg.url = "https://mcpserver-production-dd31.up.railway.app/json/mcp";
msg.headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream"
};
msg.payload = {
    jsonrpc: "2.0",
    id: 1,
    method: "initialize",
    params: {
        protocolVersion: "2025-06-18",
        capabilities: {},
        clientInfo: { name: "node-red", version: "1.0" }
    }
};
return msg;

Fn2 — extract session id, build notifications/initialized

const sessionId = msg.headers && msg.headers["mcp-session-id"];
if (!sessionId) {
    node.error("No mcp-session-id header in initialize response", msg);
    return null;
}
flow.set("mcpSessionIdJson", sessionId);

msg.method = "POST";
msg.url = "https://mcpserver-production-dd31.up.railway.app/json/mcp";
msg.headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "mcp-session-id": sessionId
};
msg.payload = {
    jsonrpc: "2.0",
    method: "notifications/initialized"
};
return msg;

Fn3 — call get_current_weather for Karlsruhe

const sessionId = flow.get("mcpSessionIdJson");
msg.method = "POST";
msg.url = "https://mcpserver-production-dd31.up.railway.app/json/mcp";
msg.headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "mcp-session-id": sessionId
};
msg.payload = {
    jsonrpc: "2.0",
    id: 2,
    method: "tools/call",
    params: {
        name: "get_current_weather",
        arguments: { location: "Karlsruhe, Germany" }
    }
};
return msg;

Fn4 — unwrap the MCP envelope (JSON variant)

// msg.payload is the parsed JSON envelope from HTTP 3.
const text = msg.payload?.result?.content?.[0]?.text;
if (!text) {
    node.error("Unexpected MCP response shape", msg);
    return null;
}
msg.payload = JSON.parse(text);
// msg.payload.current.temperature_2m, .relative_humidity_2m, .wind_speed_10m, …
return msg;

6.3 SSE variant — function code

The requests are identical in structure; only the URL and the Fn4 parser differ. HTTP Request nodes must return a UTF-8 string for all three steps.

Fn1 — build initialize request (SSE)

msg.method = "POST";
msg.url = "https://mcpserver-production-dd31.up.railway.app/sse/mcp";
msg.headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream"
};
msg.payload = {
    jsonrpc: "2.0",
    id: 1,
    method: "initialize",
    params: {
        protocolVersion: "2025-06-18",
        capabilities: {},
        clientInfo: { name: "node-red", version: "1.0" }
    }
};
return msg;

Fn2 — extract session id, build notifications/initialized (SSE)

const sessionId = msg.headers && msg.headers["mcp-session-id"];
if (!sessionId) {
    node.error("No mcp-session-id header in initialize response", msg);
    return null;
}
flow.set("mcpSessionIdSse", sessionId);

msg.method = "POST";
msg.url = "https://mcpserver-production-dd31.up.railway.app/sse/mcp";
msg.headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "mcp-session-id": sessionId
};
msg.payload = {
    jsonrpc: "2.0",
    method: "notifications/initialized"
};
return msg;

Fn3 — call get_current_weather for Karlsruhe (SSE)

const sessionId = flow.get("mcpSessionIdSse");
msg.method = "POST";
msg.url = "https://mcpserver-production-dd31.up.railway.app/sse/mcp";
msg.headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "mcp-session-id": sessionId
};
msg.payload = {
    jsonrpc: "2.0",
    id: 2,
    method: "tools/call",
    params: {
        name: "get_current_weather",
        arguments: { location: "Karlsruhe, Germany" }
    }
};
return msg;

Fn4 — parse SSE frame, then unwrap the MCP envelope

// msg.payload is a raw SSE string like:
//   event: message
//   data: {"jsonrpc":"2.0","id":2,"result":{...}}
//
const raw = typeof msg.payload === "string" ? msg.payload : "";
const dataLine = raw.split(/\r?\n/).find(l => l.startsWith("data:"));
if (!dataLine) {
    node.error("No data: frame in SSE response", msg);
    return null;
}
const envelope = JSON.parse(dataLine.slice(5).trim());
const text = envelope?.result?.content?.[0]?.text;
msg.payload = text ? JSON.parse(text) : envelope;
return msg;

6.4 Browse (discovery) — swap into Fn3

Replace Fn3 with this to list tools/resources/prompts. Works for both variants — just use the matching URL and session-id key.

// Replace `method` with one of:
//   "tools/list"
//   "resources/templates/list"
//   "prompts/list"
const sessionId = flow.get("mcpSessionIdJson"); // or "mcpSessionIdSse"
msg.method = "POST";
msg.url = "https://mcpserver-production-dd31.up.railway.app/json/mcp"; // or /sse/mcp
msg.headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "mcp-session-id": sessionId
};
msg.payload = {
    jsonrpc: "2.0",
    id: 10,
    method: "tools/list"
};
return msg;

Matching unwrap for list results — JSON variant:

const r = msg.payload?.result;
msg.payload = r?.tools ?? r?.resourceTemplates ?? r?.prompts ?? r ?? msg.payload;
return msg;

Matching unwrap for list results — SSE variant:

const raw = typeof msg.payload === "string" ? msg.payload : "";
const dataLine = raw.split(/\r?\n/).find(l => l.startsWith("data:"));
const envelope = dataLine ? JSON.parse(dataLine.slice(5).trim()) : null;
const r = envelope?.result;
msg.payload = r?.tools ?? r?.resourceTemplates ?? r?.prompts ?? r ?? envelope;
return msg;

6.5 Tips

  • Sessions live per-endpoint and per-variant. The JSON and SSE endpoints have independent session spaces, so you need to init each one separately.
  • After initializing, you can skip Fn1/Fn2/HTTP1/HTTP2 on subsequent injects and run only Fn3→HTTP3→Fn4 — the session id is in flow.context.
  • If a later call errors out with a session-related message, re-run the full init sequence once.
  • msg.headers is replaced by the HTTP Request node with the response headers, so extract anything you need (like mcp-session-id) in the immediately following function node.
  • To call a different tool, change name and arguments in Fn3. The other tools are search_locations(query), get_forecast(location, days), and get_severe_alerts(location).

7. Integrating with MCP-native clients

Any client that speaks MCP Streamable HTTP natively can point at either endpoint. Use the SSE endpoint by default (it matches what every MCP SDK expects); use the JSON endpoint only if you need plain-JSON bodies for debugging or HTTP tooling.

{
  "mcpServers": {
    "weather-sse": {
      "type": "streamable-http",
      "url": "https://mcpserver-production-dd31.up.railway.app/sse/mcp"
    },
    "weather-json": {
      "type": "streamable-http",
      "url": "https://mcpserver-production-dd31.up.railway.app/json/mcp"
    }
  }
}

No auth headers needed — the server is public.


8. Notes and gotchas

  • No API key is required anywhere. Open-Meteo is free and keyless; the MCP server itself is unauthenticated.
  • Weather codes in responses are WMO codes (e.g. 0 clear, 3 overcast, 61 light rain, 95 thunderstorm).
  • Units are always included under units / daily_units in the payload, so consumers never have to guess (e.g. °C, %, km/h, mm).
  • Severe alerts are synthesized — Open-Meteo does not expose government alert feeds. Thresholds used: precipitation ≥ 25 mm/day, max temp ≥ 38 °C, min temp ≤ −15 °C. Adjust in weather_client.severe_alerts() if needed.
  • Location parsing uses Open-Meteo's geocoding API, which is forgiving ("Karlsruhe" alone works, but "Karlsruhe, Germany" removes ambiguity).
  • Session lifetime is managed server-side per endpoint. If a session goes stale, re-initialize.
  • SSE framing is a single-line data: prefix followed by \n\n. The server emits one event: message frame per response; multi-frame streams are possible in theory but not used by the current tools.
Ver o original no GitHub

Bom para

Relacionados