refact(mcp): portable sse transport and readme

Author: Daniele Briggi

.gitignore

@@ -1,3 +1,4 @@
 node_modules
 build/
-.vscode/
+.vscode/
+sqlitecloud-mcp-server-*.tgz

package-lock.json

@@ -1,22 +1,25 @@
 {
   "name": "@sqlitecloud/mcp-server",
   "version": "0.0.1",
-  "description": "",
-  "main": "index.ts",
+  "description": "Model Context Protocol server for SQLite Cloud database",
+  "author": "SQLite Cloud",
+  "homepage": "https://sqlitecloud.ai",
+  "repository": {
+    "url": "https://github.com/sqlitecloud/sqlitecloud-mcp-server",
+    "type": "git"
+  },
+  "bugs": "https://github.com/sqlitecloud/sqlitecloud-mcp-server/issues",
+  "keywords": [],
+  "main": "./build/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
-    "build": "tsc && chmod 755 build/index.js"
+    "build": "rm -rf build && tsc && chmod 755 build/index.js"
   },
   "type": "module",
-  "bin": {
-    "weather": "./build/index.js"
-  },
+  "bin": "./build/index.js",
   "files": [
     "build"
   ],
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.9.0",
     "@sqlitecloud/drivers": "^1.0.438",

package.json

@@ -27,7 +27,7 @@ The MCP Server provides the following tools:
 To use the MCP Server, ensure you have a valid connection string for your SQLite Cloud database. The server can be started using the following command:
 
 ```bash
-node build/index.js --connectionString <your_connection_string>
+npx @sqlitecloud/mcp-server --connectionString <your_connection_string>
 ```
 
 Replace `<your_connection_string>` with the appropriate connection string for your SQLite Cloud project.
@@ -47,23 +47,82 @@ Replace `<your_connection_string>` with the appropriate connection string for yo
   "mcp": {
     "inputs": [],
     "servers": {
+      // local (for development)
       "sqlitecloud-mcp-server": {
         "type": "stdio",
         "command": "node",
         "args": [
-          "build/index.js",
+          "./build/index.ts",
           "--connectionString",
-          "<your_connection_string>"
+          "<CONNECTION_STRING>"
         ]
-      }
+      },
+      // via package manager
+      "sqlitecloud-mcp-server": {
+        "type": "stdio",
+        "command": "npx",
+        "args": [
+          "y"
+          "@sqlitecloud/mcp-server",
+          "--connectionString",
+          "<CONNECTION_STRING>"
+        ]
+      },
+      // SSE
+      "sqlitecloud-mcp-server-sse": {
+        "type": "sse",
+        "url": "<YOUR_NODE_ADDRESS>/v1/mcp/sse",
+        "headers": {
+          "Authorization": "Bearer <CONNECTION_STRING>"
+        }
+      },
     }
   }
 }
 ```
 
-# Build
+# Development
+
+## Build
 
 
 ```bash
 npm run build
-```
+```
+
+## Run
+Build the package and then run it:
+
+```bash
+node build/index.js --connectionString <CONNECTION_STRING>
+```
+
+## Locally test the package
+
+```bash
+npm pack
+```
+
+Then:
+```bash
+npx <PACKAGE_FILENAME>.tgz --connectionString <CONNECTION_STRING>
+```
+
+## Inspection
+Use the inspector to test both `stdio` and `sse` transports.
+First build the package then run:
+```bash
+npx npx @modelcontextprotocol/inspector@latest
+```
+and open it at the page: http://127.0.0.1:6274/
+
+### Stdio Transport
+- **Transport type**: `stdio`
+- **Command**: `npx`
+- **Arguments**: `<PATH_TO_PACKAGE_FOLDER>  --connectionString <CONNECTION_STRING>`
+
+_Note: use the `PATH_TO_PACKAGE_FOLDER` from your home directory or you might get permission errors_
+
+### SSE Transport
+To test `sse` transport to a remote or local server use  
+**URL**: `http://localhost:8090/v1/mcp/sse`

readme.md

@@ -1,11 +1,14 @@
+#!/usr/bin/env node
+
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { parseArgs } from "node:util";
 import { SQLiteCloudMcpServer } from "./server.js";
-import { SQLiteCloudMcpTransport } from "./transport.js";
+import { SQLiteCloudMcpTransport } from "./sqlitecloudTransport.js";
+import { parseArgs } from "util";
 
 const server = new SQLiteCloudMcpServer();
 
 async function main() {
+  console.log("Starting SQLite Cloud MCP Server...");
   const {
     values: { connectionString },
   } = parseArgs({

src/index.ts

@@ -0,0 +1,102 @@
+import { randomUUID } from 'node:crypto'
+import { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js'
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+import { JSONRPCMessage, JSONRPCMessageSchema } from '@modelcontextprotocol/sdk/types.js'
+
+interface PortableWriter {
+  write: (message: string) => Promise<void>
+  close: () => void
+}
+
+/**
+ * Server transport for SSE to send messages over an SSE connection.
+ * 
+ * This is a reimplementation of the `SSEServerTransport` class from `@modelcontextprotocol/sdk/server/see`
+ * without the dependency with ExpressJS.
+ */
+export class PortableSSEServerTransport implements Transport {
+  private _sseWriter?: PortableWriter
+  private _sessionId: string
+
+  onclose?: () => void
+  onerror?: (error: Error) => void
+  onmessage?: (message: JSONRPCMessage, extra?: { authInfo?: AuthInfo }) => void
+
+  /**
+   * Creates a new SSE server transport, which will direct the client to POST messages to the relative or absolute URL identified by `_endpoint`.
+   */
+  constructor(
+    private _endpoint: string,
+    private writableStream: PortableWriter
+  ) {
+    this._sessionId = randomUUID()
+  }
+
+  /**
+   * Handles the initial SSE connection request.
+   *
+   * This should be called when a GET request is made to establish the SSE stream.
+   */
+  async start(): Promise<void> {
+    if (this._sseWriter) {
+      throw new Error('SSEServerTransport already started! If using Server class, note that connect() calls start() automatically.')
+    }
+
+    this._sseWriter = this.writableStream
+
+    // Send the endpoint event
+    // Use a dummy base URL because this._endpoint is relative.
+    // This allows using URL/URLSearchParams for robust parameter handling.
+    const dummyBase = 'http://localhost' // Any valid base works
+    const endpointUrl = new URL(this._endpoint, dummyBase)
+    endpointUrl.searchParams.set('sessionId', this._sessionId)
+
+    // Reconstruct the relative URL string (pathname + search + hash)
+    const relativeUrlWithSession = endpointUrl.pathname + endpointUrl.search + endpointUrl.hash
+
+    this._sseWriter?.write(`event: endpoint\ndata: ${relativeUrlWithSession}\n\n`)
+  }
+
+  /**
+   * Handle a client message, regardless of how it arrived. This can be used to inform the server of messages that arrive via a means different than HTTP POST.
+   */
+  async handleMessage(message: unknown): Promise<void> {
+    if (!this._sseWriter) {
+      const message = 'SSE connection not established'
+      throw new Error(message)
+    }
+
+    let parsedMessage: JSONRPCMessage
+    try {
+      parsedMessage = JSONRPCMessageSchema.parse(message)
+      this.onmessage?.(parsedMessage)
+    } catch (error) {
+      this.onerror?.(error as Error)
+      throw error
+    }
+  }
+
+  async close(): Promise<void> {
+    this._sseWriter?.close()
+    this._sseWriter = undefined
+    this.writableStream.close()
+    this.onclose?.()
+  }
+
+  async send(message: JSONRPCMessage): Promise<void> {
+    if (!this._sseWriter) {
+      throw new Error('Not connected')
+    }
+
+    this._sseWriter.write(`event: message\ndata: ${JSON.stringify(message)}\n\n`)
+  }
+
+  /**
+   * Returns the session ID for this transport.
+   *
+   * This can be used to route incoming POST requests.
+   */
+  get sessionId(): string {
+    return this._sessionId
+  }
+}

src/portableSseTransport.ts

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { SQLiteCloudMcpTransport } from "./transport.js";
+import { SQLiteCloudMcpTransport } from "./sqlitecloudTransport.js";
 
 export class SQLiteCloudMcpServer {
   private mcpServer: McpServer;
@@ -18,9 +18,6 @@ export class SQLiteCloudMcpServer {
     const mcpTransport = transport.mcpTransport;
     let sessionId = mcpTransport.sessionId;
     if (!sessionId) {
-      console.warn(
-        "Transport does not have a session ID. Using the anonymous session."
-      );
       sessionId = "anonymous";
       mcpTransport.sessionId = sessionId;
     }