tendril/SSE_MODE_ANALYSIS.md

SSE Mode Analysis & Investigation

Date: November 10, 2024
Status: Investigated and Removed
Decision: Deprecated in favor of STDIO mode (proven working)

Investigation Findings

What We Discovered

During testing of SSE (Server-Sent Events) mode in v0.0.1, we found:

1. gitea-mcp Removed SSE Support

   • SSE mode was removed from gitea-mcp in a recent commit
   • Reference: 88471b5de0
   • The MCP specification itself has moved beyond SSE

2. MCP Specification Evolution

   • Old standard: HTTP + SSE transport (deprecated)
   • New standard: Streamable HTTP transport (as of MCP 2025-03-26)
   • Reference: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports

3. Test Results When Attempting SSE Mode

   Zed Log:
   ERROR [context_server::client] Unhandled JSON from context_server
   ERROR [context_server::client] cancelled csp request task for "initialize" 
   ERROR [project::context_server_store] Context server failed to start: 
   Context server request timeout
   
   gitea-mcp Log:
   INFO: Gitea MCP SSE server listening on :8987
   (No further initialization)
   

   The binary started but couldn't complete the MCP initialization handshake.

What Changed

Removed Features

• use_sse configuration option
• gitea_port setting (was only for SSE mode)
• All SSE-specific code paths
• SSE mode documentation

Kept Stable

• STDIO Mode: Direct stdin/stdout communication (proven working)
• All other configuration options
• Self-hosted Gitea support
• Self-signed certificate handling

Current Architecture

STDIO Transport (What We Use Now)

Zed IDE
   ↓ (spawns process)
Tendril Extension
   ↓ (starts with args: -t stdio)
gitea-mcp Binary
   ↓ (communicates via stdin/stdout)
Gitea Instance

Characteristics:

• ✅ Direct process communication
• ✅ No network setup required
• ✅ Fully tested and working
• ✅ Standard MCP transport
• ✅ Low latency

Future: HTTP Streaming Transport

Zed IDE
   ↓ (HTTP connection)
Tendril Extension
   ↓ (connects to HTTP endpoint)
gitea-mcp Binary (HTTP server mode)
   ↓ (HTTP requests)
Gitea Instance

Characteristics:

• Modern MCP standard (2025-03-26+)
• Requires separate HTTP server setup
• Supports multiple connections
• More complex implementation
• Status: Not yet implemented

Why We Made This Decision

Reasons for Removing SSE Support

1. Dead Technology: SSE mode was removed from gitea-mcp itself

   • No point supporting a mode the server doesn't provide

2. Specification Obsolete: The HTTP+SSE transport is deprecated

   • MCP spec moved to Streamable HTTP (2025-03-26)
   • Supporting old standards prevents adoption of new ones

3. Never Worked Reliably: Your original notes indicated SSE never worked

   • Testing confirmed it still doesn't work
   • Maintaining non-functional code adds burden

4. STDIO Works Great: We have a perfectly good, tested alternative

   • No user complaints or issues
   • Simple and reliable
   • Meets all current use cases

5. Cleaner Codebase: Removing unused features simplifies maintenance

   • Easier to understand
   • Fewer code paths to test
   • Clearer configuration

Migration Path for Users

If You Were Using SSE Mode (v0.0.1)

Change from:

{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_TOKEN",
        "use_sse": true,
        "gitea_port": 8080
      }
    }
  }
}

To (v0.0.2+):

{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_TOKEN"
      }
    }
  }
}

STDIO mode is now the default and only mode. It works the same way and requires no port configuration.

Future Consideration: HTTP Streaming

When We Might Revisit HTTP Streaming

If we need to support:

• Remote gitea-mcp servers (not localhost)
• Multiple concurrent connections from Zed
• Load balancing
• Cloud-based gitea-mcp deployments

What Would Be Required

1. Update gitea-mcp binary to support HTTP streaming mode
2. Add HTTP endpoint discovery to Tendril
3. Implement HTTP client in Rust extension
4. Handle connection pooling and session management
5. Test with both local and remote deployments

Estimated Effort

• Analysis: 4-8 hours
• Implementation: 8-16 hours
• Testing: 8-12 hours
• Documentation: 4 hours
• Total: ~24-40 hours (1 week of focused work)

References

• gitea-mcp Repository: https://gitea.com/gitea/gitea-mcp
• MCP Specification (Current): https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
• MCP Transports Documentation: https://docs.roocode.com/features/mcp/server-transports
• Streamable HTTP Transport: https://levelup.gitconnected.com/mcp-server-and-client-with-sse-the-new-streamable-http-d860850d9d9d

Commit Information

• Version: v0.0.2 (after this cleanup)
• Deprecation Date: November 10, 2024
• Replacement: STDIO mode (primary), HTTP Streaming (future)
• Impact: Configuration simplification, code cleanup

Questions?

If you have questions about this decision:

1. Check the references above for MCP transport documentation
2. Review the gitea-mcp repository for current capabilities
3. Open an issue: https://git.parkingmeter.info/Mycelium/tendril/issues

---

Summary: SSE mode has been officially removed from Tendril as it's no longer supported by gitea-mcp and is superseded by the newer HTTP Streaming transport standard in MCP. STDIO mode (the primary transport) continues to work excellently and requires no changes for existing users.