feat: Modernize to Streamable HTTP transport with JSON-RPC 2.0

[T-rav]

Replace deprecated SSE transport with modern Streamable HTTP transport for better future compatibility and standards compliance.

Changes:

• Update mcp_server.py to use transport="http" instead of "sse"
• Update cli.py to use HTTP transport
• Update README.md with Streamable HTTP terminology
• Update CLAUDE.md architecture documentation
• Remove deprecated SSE endpoint documentation

Benefits:

• Future-proof: uses latest MCP protocol standard (2024-11-05)
• Explicit JSON-RPC 2.0 wire protocol
• Better session management
• No breaking changes to /mcp endpoint

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added optional Bearer token authentication.

• Refactor

  • Migrated MCP transport from SSE to Streamable HTTP using JSON-RPC 2.0.
  • Updated server naming to reflect the new transport.

• Documentation

  • Revised README and architecture visuals to describe the new transport and endpoint behavior.
  • Expanded notes on authentication, deployment, multi-arch builds, Python requirements, and default rate limits.

• Chores

  • Docker tooling now starts the server with the new HTTP transport.
  • Added references to tests, integration markers, and security considerations.

[coderabbitai]

Walkthrough

Replaces MCP transport from SSE to Streamable HTTP using JSON-RPC 2.0 across docs and Docker entrypoints. Updates CLI and server startup to use transport="http" and revises documentation to reflect the new transport, authentication note, and naming (FastAPI → FastMCP). No exported/public API changes.

Changes

Cohort / File(s)	Summary of Changes
Docs: Transport and Architecture CLAUDE.md, README.md	Updated transport from SSE to Streamable HTTP with JSON-RPC 2.0; adjusted architecture/flow text, endpoint references (/mcp), auth notes (optional Bearer), and tech stack wording (FastMCP, JSON-RPC 2.0). Removed FastAPI references; added deployment and testing notes.
Docker MCP Server Startup docker/cli.py, docker/mcp_server.py	Switched mcp_server.run transport argument from "sse" to "http"; host/port/path unchanged. No other control-flow or signature changes.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor Client as MCP Client
  participant HTTP as HTTP Endpoint (/mcp)
  participant Server as FastMCP Server

  Note over Client,Server: New: Streamable HTTP + JSON-RPC 2.0

  rect rgba(200,235,255,0.25)
    Client->>HTTP: Open HTTP stream
    Client->>HTTP: JSON-RPC request (e.g., initialize, call)
    HTTP->>Server: Forward request
    Server-->>HTTP: JSON-RPC response/stream chunks
    HTTP-->>Client: Streamed response frames
  end

  alt Error
    Server-->>HTTP: JSON-RPC error
    HTTP-->>Client: Error object
  else Auth (optional)
    Client->>HTTP: Authorization: Bearer <token>
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• fixes for streamable and updated readme #16 — Similar change in MCP server transport configuration in docker/mcp_server.py moving from SSE to streamable HTTP/JSON-RPC.

Poem

I hop from SSE to streams anew,
JSON-RPC whispers, tidy and true.
Through /mcp the packets glide,
A modern hop on the server side.
Ears up, tail twitch—ship it, woo! 🐇✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title “feat: Modernize to Streamable HTTP transport with JSON-RPC 2.0” accurately conveys the primary change of replacing SSE with a modern HTTP transport and specifying the JSON-RPC 2.0 protocol, which aligns precisely with the pull request’s objectives and scope. It is concise, uses clear terminology, and highlights the most significant architectural update without unnecessary detail. A reviewer scanning the history can immediately understand the main feature introduced.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/modernize-transport-http

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 175d42f and f638c1c.

📒 Files selected for processing (4)

• CLAUDE.md (3 hunks)
• README.md (4 hunks)
• docker/cli.py (1 hunks)
• docker/mcp_server.py (1 hunks)

🧰 Additional context used

📓 Path-based instructions (3)

**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.py: Format all Python code with Black (line-length=88) and isort (profile="black"); flake8 E501 is delegated to Black
Prefer absolute imports (e.g., from docker.mcp_server import ...) rather than relative imports
All function signatures must include type hints (checked by mypy)
Public functions must use Google-style docstrings
Limit nesting depth in functions to a maximum of 3 levels; refactor deeper logic into helpers
One class per file (applies to production and test infrastructure)
Extract helper methods for each logical concept; prefer multiple small methods over large ones

Files:

• docker/cli.py
• docker/mcp_server.py

docker/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

All Python files in docker/ are included in coverage; add tests rather than excluding files

Files:

• docker/cli.py
• docker/mcp_server.py

docker/mcp_server.py

📄 CodeRabbit inference engine (CLAUDE.md)

Define new MCP tools in docker/mcp_server.py using the @mcp_server.tool decorator

Files:

• docker/mcp_server.py

🪛 markdownlint-cli2 (0.18.1)

CLAUDE.md

19-19: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (10)

docker/cli.py (1)

81-84: LGTM! Consistent transport update across entry points.

The CLI entry point correctly mirrors the transport change from docker/mcp_server.py, ensuring consistency across both server startup paths. The comment clearly documents the transport modernization.

README.md (4)

44-47: LGTM! Clear and accurate feature descriptions.

The updated feature bullet points correctly describe the modern HTTP transport and accurately list the tech stack components (FastMCP, Readability, html2text). The terminology is consistent with the code changes and provides clear value to users.

---

99-99: LGTM! Accurate endpoint documentation.

The MCP endpoint description correctly reflects the new Streamable HTTP with JSON-RPC 2.0 transport, providing users with clear expectations about the protocol in use.

---

146-156: LGTM! Architecture diagram accurately reflects the modernization.

The updated architecture flow clearly shows the transition from SSE to Streamable HTTP with JSON-RPC 2.0, and properly describes the authentication as optional. The diagram maintains clarity while incorporating the technical transport details.

---

160-162: LGTM! Tech stack accurately documented.

The tech stack section correctly separates FastMCP (for MCP protocol implementation with modern HTTP transport) from JSON-RPC 2.0 (the wire protocol), providing clear technical context for developers.

CLAUDE.md (4)

11-13: LGTM! Accurate project overview.

The overview correctly describes the Streamable HTTP transport with JSON-RPC 2.0 and accurately lists the tech stack. The removal of FastAPI is appropriate since FastMCP is the actual framework in use.

---

20-27: LGTM! Clear architecture flow description.

The high-level flow accurately depicts the modernized transport layer, showing FastMCP Server with Streamable HTTP + JSON-RPC 2.0. The ASCII diagram clearly illustrates the request flow through the system.

---

31-35: LGTM! Component descriptions accurately updated.

The MCP Server component description correctly identifies it as Python/FastMCP (not FastAPI) and specifies the Streamable HTTP transport in the mcp_server.py entry point. This provides accurate guidance for developers working with the codebase.

---

421-422: LGTM! Important notes accurately capture key details.

The updated notes correctly emphasize the use of Streamable HTTP transport with JSON-RPC 2.0 as a modern, future-proof choice, and appropriately clarify that bearer token authentication is optional rather than required. These are important details for developers and integrators.

docker/mcp_server.py (1)

82-88: Verify external MCP client compatibility
No references to the old sse transport remain in tests or code. Confirm that all external MCP clients (Claude Desktop, LiteLLM, etc.) support the new Streamable HTTP transport and update any client code or documentation as needed.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}