feat: Add Streamable HTTP transport for cloud deployments #5

BenGWeeks · 2025-10-25T17:03:28Z

Summary

Implements GitHub issue #4 - adds Streamable HTTP transport support for Azure Container Apps and Smithery deployment while maintaining full backward compatibility with STDIO mode.

Closes #4

Changes Overview

🆕 New Files

src/http-server.ts: Stateless HTTP server using Express and MCP Streamable HTTP transport
docs/azure-deployment.md: Comprehensive deployment guide for Azure Container Apps

🔄 Core Refactoring

Upgraded @modelcontextprotocol/sdk from 0.6.0 to ^1.20.2
Refactored src/server.ts to be transport-agnostic (no STDIO coupling)
Updated src/index.ts as dedicated STDIO entry point (maintains backward compatibility)
Added Express, CORS, and TypeScript development dependencies

⚙️ Configuration Updates

Dockerfile: Updated for HTTP server execution with health checks (EXPOSE 3000)
smithery.yaml: Changed from stdio to http type with health endpoint configuration
package.json: Added start:http and dev:http scripts

📚 Documentation

README.md: Added comprehensive "Transport Modes" section
Documented stateless architecture and HTTP endpoints
Included Docker and Azure deployment instructions

Architecture

The HTTP implementation follows the MCP SDK's recommended pattern for stateless HTTP servers:

✅ Stateless Design: Creates new server/transport instance per request
✅ Collision Prevention: Prevents request ID collisions
✅ Auto Cleanup: Automatic resource cleanup on connection close
✅ Horizontal Scaling: No session state to manage

API Endpoints

POST /mcp: Handle MCP JSON-RPC requests (stateless)
GET /health: Health check endpoint for Azure Container Apps probes

Testing

All tests passed successfully:

✅ TypeScript compilation with upgraded SDK
✅ STDIO mode backward compatibility (node build/index.js)
✅ HTTP server startup and health endpoint
✅ MCP protocol flow:
- Initialize request/response
- Tools list (returns all 9 tools)
- Tool execution (tested with proper error handling)

Deployment Options

This PR enables three deployment scenarios:

STDIO Mode (existing): Claude Desktop, local MCP clients
HTTP via Docker: Azure Container Apps, containerized environments
HTTP via Smithery: Cloud hosting platform integration

Breaking Changes

None - STDIO mode remains the default and is fully backward compatible.

Migration Guide

No migration needed for existing users. HTTP mode is opt-in:

# Existing STDIO mode (no changes needed)
node build/index.js

# New HTTP mode
npm run start:http

🤖 Generated with Claude Code

Implements GitHub issue #4 - adds HTTP transport support for Azure Container Apps and Smithery deployment while maintaining backward compatibility with STDIO mode. ## Changes ### New Files - src/http-server.ts: Stateless HTTP server using Express and Streamable HTTP transport - docs/azure-deployment.md: Comprehensive Azure Container Apps deployment guide ### Core Changes - Upgraded @modelcontextprotocol/sdk from 0.6.0 to ^1.20.2 - Refactored src/server.ts to be transport-agnostic - Updated src/index.ts to maintain STDIO backward compatibility - Added Express, CORS, and development dependencies ### Configuration - Dockerfile: Updated for HTTP server with health checks - smithery.yaml: Changed from stdio to http type with health endpoint - package.json: Added start:http and dev:http scripts ### Documentation - README.md: Added Transport Modes section with architecture details - Documented stateless design and HTTP endpoints ## Architecture The HTTP implementation follows the SDK's recommended pattern: - Creates new server/transport instance per request (stateless) - Prevents request ID collisions - Automatic cleanup on connection close - Scales horizontally without session state ## Endpoints - POST /mcp: Handle MCP JSON-RPC requests - GET /health: Health check for Azure probes ## Testing All tests passed: - ✅ TypeScript compilation - ✅ STDIO backward compatibility - ✅ HTTP server functionality - ✅ MCP protocol flow (initialize, tools/list, tools/call) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Copilot

Pull Request Overview

This PR implements Streamable HTTP transport support for cloud deployments (Azure Container Apps and Smithery) while maintaining full backward compatibility with STDIO mode. The architecture follows a stateless design pattern where each HTTP request creates a new server/transport instance to prevent request ID collisions.

Key Changes:

Upgraded MCP SDK from 0.6.0 to ^1.20.2 to support HTTP transport
Refactored core server to be transport-agnostic with dedicated entry points for STDIO and HTTP modes
Added comprehensive Azure deployment documentation and Docker support

Reviewed Changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/server.ts	Refactored to accept any Transport type, removing STDIO coupling and SIGINT handler
src/index.ts	Updated as dedicated STDIO entry point with transport initialization
src/http-server.ts	New HTTP server implementation with Express and stateless request handling
smithery.yaml	Changed from stdio to http configuration with health endpoint
package.json	Added HTTP dependencies and scripts, upgraded MCP SDK
docs/azure-deployment.md	New comprehensive Azure Container Apps deployment guide
README.md	Added Transport Modes section documenting STDIO and HTTP usage
Dockerfile	Updated to run HTTP server with port 3000
.claude/settings.local.json	Added local Claude Code permissions configuration

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-10-25T17:07:42Z

src/http-server.ts

+    const config = getNeo4jConfig();
+    server = new Neo4jServer(config);
+    transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined, // Let SDK manage session IDs
+      enableJsonResponse: true,
+    });


Creating a new Neo4jServer instance for each request may lead to excessive resource usage. Each server instance creates a new Neo4j driver connection (from line 22 in src/server.ts), which is expensive. Consider implementing connection pooling or reusing server instances with transport-level isolation instead.

Copilot · 2025-10-25T17:07:42Z

docs/azure-deployment.md

+{
+  "status": "ok",
+  "service": "mcp-neo4j-agent-memory",
+  "activeSessions": 0,


The health check response example includes an 'activeSessions' field that does not exist in the actual implementation. The /health endpoint in src/http-server.ts (lines 33-39) only returns status, service, and timestamp fields.

Suggested change

"activeSessions": 0,

Copilot · 2025-10-25T17:07:42Z

docs/azure-deployment.md

+### Session Issues
+
+The HTTP server maintains sessions with 30-minute timeout. Check:
+- Active sessions via `/health` endpoint
+- Session cleanup in logs
+- Memory usage if sessions accumulate


The documentation incorrectly states that 'The HTTP server maintains sessions with 30-minute timeout.' The implementation in src/http-server.ts is stateless and creates a new server/transport for each request (lines 48-54), with no session persistence. This contradicts the stateless architecture described elsewhere in the PR.

Suggested change

### Session Issues

The HTTP server maintains sessions with 30-minute timeout. Check:

- Active sessions via `/health` endpoint

- Session cleanup in logs

- Memory usage if sessions accumulate

### Stateless HTTP Server

The HTTP server is stateless and does not maintain sessions between requests. If you encounter issues:

- Check the `/health` endpoint for server status

- Review logs for request/response errors

- Monitor memory usage for unexpected growth

BenGWeeks requested a review from Copilot October 25, 2025 17:06

Copilot AI reviewed Oct 25, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat: Add Streamable HTTP transport for cloud deployments #5

feat: Add Streamable HTTP transport for cloud deployments #5

Uh oh!

BenGWeeks commented Oct 25, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 25, 2025

Uh oh!

Copilot AI Oct 25, 2025

Uh oh!

Copilot AI Oct 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

feat: Add Streamable HTTP transport for cloud deployments #5

Are you sure you want to change the base?

feat: Add Streamable HTTP transport for cloud deployments #5

Uh oh!

Conversation

BenGWeeks commented Oct 25, 2025

Summary

Changes Overview

🆕 New Files

🔄 Core Refactoring

⚙️ Configuration Updates

📚 Documentation

Architecture

API Endpoints

Testing

Deployment Options

Breaking Changes

Migration Guide

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 25, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 25, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants