From 973b3ab734f98d502607adf91aa3ebde99443b38 Mon Sep 17 00:00:00 2001 From: Christopher Kim <1006807+cswkim@users.noreply.github.com> Date: Wed, 5 Nov 2025 15:18:02 -0500 Subject: [PATCH 1/2] fix: add ping keepalive configuration for HTTP stream transport to prevent SSE timeouts --- .env.example | 18 +++++++++++++++++- README.md | 3 +++ src/config.ts | 8 ++++++++ src/index.ts | 3 +++ 4 files changed, 31 insertions(+), 1 deletion(-) diff --git a/.env.example b/.env.example index beb640c..4a3c6bf 100644 --- a/.env.example +++ b/.env.example @@ -7,4 +7,20 @@ DISCOGS_MEDIA_TYPE=application/vnd.discogs.v2.discogs+json DISCOGS_USER_AGENT=DiscogsMCPServer/ PORT=3001 # SSE port SERVER_HOST=0.0.0.0 # Server host address (0.0.0.0 allows external connections, 127.0.0.1 restricts to localhost) -SERVER_NAME="Discogs MCP Server" \ No newline at end of file +SERVER_NAME="Discogs MCP Server" + +# Ping/Keepalive Configuration (for HTTP stream transport) +# These settings help prevent SSE timeout errors by sending periodic keepalive messages +# All ping settings are optional with sensible defaults + +# Optional: Enable ping/keepalive (default: true) +# Set to false to disable ping messages +# PING_ENABLED=true + +# Optional: Ping interval in milliseconds (default: 30000 = 30 seconds) +# Recommended: Keep this well under your client timeout (e.g., 30s for a 60s timeout) +# PING_INTERVAL_MS=30000 + +# Optional: Log level for ping-related messages (default: debug) +# Options: debug, info, notice, warn, error, critical, alert, emergency +# PING_LOG_LEVEL=debug \ No newline at end of file diff --git a/README.md b/README.md index fb9297f..99d3832 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,9 @@ To get your Discogs personal access token, go to your [Discogs Settings > Develo The other environment variables in `.env.example` are optional and have sensible defaults, so you don't need to set them unless you have specific requirements. - `SERVER_HOST`: The host address to bind the server to (default: `0.0.0.0`). Set to `0.0.0.0` to allow connections from outside the container/machine, or `127.0.0.1` to restrict to localhost only. +- `PING_ENABLED`: Enable or disable ping/keepalive for HTTP stream transport (default: `true`). Set to `false` to disable. Ping is automatically enabled for HTTP stream transport to prevent SSE timeouts. +- `PING_INTERVAL_MS`: Interval in milliseconds between ping messages (default: `30000` = 30 seconds). This helps maintain long-lived SSE connections and prevent timeouts. +- `PING_LOG_LEVEL`: Log level for ping-related messages (default: `debug`). Options: `debug`, `info`, `warn`, `error`. ## Running the Server Locally diff --git a/src/config.ts b/src/config.ts index 9d8c7df..e4638f2 100644 --- a/src/config.ts +++ b/src/config.ts @@ -1,4 +1,5 @@ import dotenv from 'dotenv'; +import type { LoggingLevel } from 'fastmcp'; import { VERSION } from './version.js'; // Load environment variables from .env file @@ -19,6 +20,13 @@ export const config = { name: process.env.SERVER_NAME || 'Discogs MCP Server', port: process.env.PORT ? parseInt(process.env.PORT, 10) : 3001, host: process.env.SERVER_HOST || '0.0.0.0', + ping: { + // Enable ping for HTTP stream transport to prevent SSE timeouts + // Default interval is 30 seconds (well under typical 60s timeout) + enabled: process.env.PING_ENABLED !== 'false', + intervalMs: process.env.PING_INTERVAL_MS ? parseInt(process.env.PING_INTERVAL_MS, 10) : 30000, + logLevel: (process.env.PING_LOG_LEVEL as LoggingLevel | undefined) || 'debug', + }, }, }; diff --git a/src/index.ts b/src/index.ts index effcdba..50a2af6 100644 --- a/src/index.ts +++ b/src/index.ts @@ -27,6 +27,9 @@ try { const server = new FastMCP({ name: config.server.name, version: VERSION, + // Configure ping/keepalive for HTTP stream transport to prevent SSE timeouts + // Only enable ping for stream transport, not stdio + ping: transportType === 'stream' ? config.server.ping : undefined, }); registerTools(server); From e950f3c112f58794c30d5c2489baa6d43e71e0c9 Mon Sep 17 00:00:00 2001 From: Christopher Kim <1006807+cswkim@users.noreply.github.com> Date: Wed, 5 Nov 2025 15:18:30 -0500 Subject: [PATCH 2/2] docs(changeset): fix: add ping keepalive configuration for HTTP stream transport to prevent SSE timeouts --- .changeset/metal-insects-hang.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/metal-insects-hang.md diff --git a/.changeset/metal-insects-hang.md b/.changeset/metal-insects-hang.md new file mode 100644 index 0000000..223bb84 --- /dev/null +++ b/.changeset/metal-insects-hang.md @@ -0,0 +1,5 @@ +--- +'discogs-mcp-server': patch +--- + +fix: add ping keepalive configuration for HTTP stream transport to prevent SSE timeouts