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: https://gitea.com/gitea/gitea-mcp/commit/88471b5de048ee35e929a5c3e5789f50ba57a845
   - 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:
```json
{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_TOKEN",
        "use_sse": true,
        "gitea_port": 8080
      }
    }
  }
}
```

To (v0.0.2+):
```json
{
  "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.