Cleanup and refactor (#4)

* do not push examples to module

* install dev pkgs on CI

* move examples

* update files as examples are moved

* Update README

* Update README.md

Add note about npx.

* add dev deps

* Exit bridge when Claude Desktop exits (stdin closed)

* cosmetics

* Add debug for the endpoint event from SSE server

Author: dforsber

.github/workflows/ci.yml

@@ -2,25 +2,25 @@ name: CI
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
-    branches: [ main ]
+    branches: [main]
 
 jobs:
   build:
     runs-on: ubuntu-latest
-    
+
     steps:
       - uses: actions/checkout@v4
-      
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '22.x'
-          cache: 'yarn'
-          
+          node-version: "22.x"
+          cache: "yarn"
+
       - name: Install dependencies
         run: yarn install
-        
+
       - name: Build
-        run: yarn build
+        run: yarn build

.github/workflows/npm-publish.yml

@@ -11,10 +11,10 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: '22.x'
-          registry-url: 'https://registry.npmjs.org'
-      - run: yarn install
+          node-version: "22.x"
+          registry-url: "https://registry.npmjs.org"
+      - run: yarn install --production
       - run: yarn build
       - run: yarn publish
         env:
-          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
+          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

.gitignore

@@ -1,5 +1,6 @@
 node_modules/
 build/
+examples/*.js
 *.log
 .env*
 test.duckdb

README.md

@@ -11,13 +11,13 @@ You can install the package globally or use it directly with npx:
 npm install -g mcp-server-and-gw
 
 # Using npx (no installation required)
-npx claude_gateway http://localhost:9999
+npx claude_gateway http://localhost:8808/
 
 # If installed globally
-claude_gateway http://localhost:9999
+claude_gateway http://localhost:8808/
 
 # Using environment variables
-MCP_HOST=localhost MCP_PORT=9999 npx claude_gateway
+MCP_HOST=localhost MCP_PORT=8808 npx claude_gateway
 ```
 
 ## Add Configuration into Claude
@@ -38,26 +38,30 @@ echo '{
     "Claude Gateway Example": {
       "command": "/opt/homebrew/bin/npx",
       "args": [
-        "claude_gateway", "http://localhost:9999/"
+        "claude_gateway", "http://localhost:8808/"
       ]
     }
   }
 }' > ~/Library/Application\ Support/Claude/claude_desktop_config.json
 
 ## 3. Start server so that claude can connect to it for discoverying its resources, tools, etc.
-node build/server.js
+PORT=8808 node examples/server.js
 
 ## 4. Start Claude Desktop
 ```
 
 ## Example Server and Client
 
+```shell
+yarn install @types/express @types/json-bigint @types/node duckdb express json-bigint
+```
+
 You can also develop the SSE server independently from Claude Desktop so you get faster iterations. For example, run the `src/server.ts` and use the `src/client.ts` as the client.
 
 Start server, once you start the client on another terminal, you see the server output.
 
 ```shell
-% node build/server.js
+% node examples/server.js
 Server is running on port 8808
 
 --> Received connection: /sse
@@ -96,7 +100,7 @@ New SSE connection.
 Start the client
 
 ```shell
-% node build/client.js
+% node examples/client.js
 Connecting...
 Connected: { resources: {}, tools: {}, templates: {} }
 { resources: [] }

src/client.ts examples/client.ts

@@ -1,5 +1,5 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import eventsource from "eventsource";
+import * as eventsource from "eventsource";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import {
   CallToolResultSchema,

src/duckdb.ts examples/duckdb.ts

@@ -19,17 +19,17 @@
     "release:major": "npm version major && git push && git push --tags"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "0.6.0",
-    "@types/node": "22",
-    "duckdb": "^1.1.3",
-    "eventsource": "^2.0.2",
-    "express": "^4.21.1",
-    "json-bigint": "^1.0.0"
+    "@modelcontextprotocol/sdk": "1.8.0",
+    "eventsource": "^3.0.6"
   },
   "devDependencies": {
     "@types/eventsource": "^1.1.15",
-    "@types/express": "^5.0.0",
+    "@types/express": "^5.0.1",
     "@types/json-bigint": "^1.0.4",
+    "@types/node": "^22.13.14",
+    "duckdb": "^1.2.1",
+    "express": "^4.21.2",
+    "json-bigint": "^1.0.0",
     "typescript": "^5.3.3"
   }
 }

src/server.ts examples/server.ts

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
-import EventSource from "eventsource";
+import { EventSource } from "eventsource";
 
 // Get the backend URL from command line arg or environment variables
 let baseUrl: string;
 
 if (process.argv.length > 2) {
   baseUrl = process.argv[2];
-  if (!baseUrl.startsWith('http://') && !baseUrl.startsWith('https://')) {
+  if (!baseUrl.startsWith("http://") && !baseUrl.startsWith("https://")) {
     baseUrl = `http://${baseUrl}`;
   }
   // Remove trailing slash if present
-  if (baseUrl.endsWith('/')) {
+  if (baseUrl.endsWith("/")) {
     baseUrl = baseUrl.slice(0, -1);
   }
 } else {
@@ -20,7 +20,7 @@ if (process.argv.length > 2) {
 }
 
 const backendUrlSse = `${baseUrl}/sse`;
-const backendUrlMsg = `${baseUrl}/message`;
+let backendUrlMsg = `${baseUrl}/message`;
 
 const debug = console.error; // With stdio transport stderr is the only channel for debugging
 const respond = console.log; // Message back to Claude Desktop App.
@@ -35,14 +35,19 @@ const respond = console.log; // Message back to Claude Desktop App.
 
 // 1. Establish persistent MCP server SSE connection and forward received messages to stdin
 function connectSSEBackend() {
-  return new Promise((resolve, reject) => {
+  return new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("SSE Backend Connection timeout")), 10_000);
     const source = new EventSource(backendUrlSse);
-    source.onopen = (evt: MessageEvent) => resolve(evt);
-    source.addEventListener("error", (__e) => reject(__e));
-    source.addEventListener("open", (___e) => debug(`--- SSE backend connected`));
-    source.addEventListener("error", (__e) => debug(`--- SSE backend disc./error: ${(<any>__e)?.message}`));
-    source.addEventListener("message", (e) => debug(`<-- ${e.data}`));
+    source.onopen = (evt: Event) => resolve(clearTimeout(timer));
+    source.addEventListener("endpoint", (e) => {
+      backendUrlMsg = `${baseUrl}${e.data}`;
+      debug(`--- SSE backend sent "endpoint" event (${e.data}) ==> Setting message endpoint URL: "${backendUrlMsg}"`);
+    });
+    source.addEventListener("error", (e) => reject(e));
     source.addEventListener("message", (e) => respond(e.data)); // forward to Claude Desktop App via stdio transport
+    source.addEventListener("message", (e) => debug(`<-- ${e.data}`));
+    source.addEventListener("open", (e) => debug(`--- SSE backend connected`));
+    source.addEventListener("error", (e) => debug(`--- SSE backend disc./error: ${(<any>e)?.message}`));
   });
 }
 
@@ -51,13 +56,18 @@ async function processMessage(inp: Buffer) {
   const msg = inp.toString();
   debug("-->", msg.trim());
   const [method, body, headers] = ["POST", msg, { "Content-Type": "application/json" }];
-  await fetch(new URL(backendUrlMsg), { method, body, headers }).catch((e) => debug("fetch error:", e));
+  const resp = await fetch(new URL(backendUrlMsg), { method, body, headers }).catch((e) => debug("fetch error:", e));
+  if (resp && !resp?.ok) debug(`HTTP error: ${resp.status} ${resp.statusText}`);
 }
 
 async function runBridge() {
   debug(`-- Connecting to MCP server at ${baseUrl}`);
   await connectSSEBackend();
   process.stdin.on("data", processMessage);
+  process.stdin.on("end", () => {
+    debug("-- stdin disconnected, exiting");
+    process.exit(0);
+  });
   debug(`-- MCP stdio to SSE gateway running - connected to ${baseUrl}`);
 }