feat: Add binary path resolution and Docker support (v0.1.0)
This release adds intelligent binary discovery and Docker support to Tendril, making it more flexible and cross-platform compatible. ## Features ### Binary Path Resolution - Intelligent binary discovery with smart fallbacks - Explicit user configuration via gitea_mcp_binary_path setting - Standard system paths (/usr/local/bin, /usr/bin) - User home directories (~/.local/bin, ~/.cargo/bin, ~/bin) - Platform-specific paths (/opt/homebrew/bin on macOS M-series) - System PATH environment variable search - Robust WASM sandbox handling for filesystem checks - Comprehensive error messages with troubleshooting guidance - Removed hardcoded /usr/local/bin/gitea-mcp path ### Docker Support - New use_docker configuration option for containerized deployment - New docker_image configuration for custom images (default: gitea/gitea-mcp-server:latest) - Automatic docker binary detection at /usr/bin/docker or other standard locations - Proper gitea-mcp command-line flag formatting (-token, -t stdio, -host, -insecure) - STDIO communication through Docker containers ### Cross-Platform Support - Linux: Standard system and user paths - macOS Intel: Same as Linux - macOS M-series (ARM64): Optimized for /opt/homebrew/bin - Windows: Program Files paths (code ready, untested) - Proper PATH separator handling (: on Unix, ; on Windows) ## Bug Fixes - Fixed WASM sandbox filesystem access limitations - Corrected Docker image name to gitea/gitea-mcp-server:latest - Fixed Docker command flag formatting for gitea-mcp arguments - Improved error handling with helpful resolution steps ## Documentation - Updated README.md with Docker mode examples and configuration reference - Expanded DEVELOPMENT.md with architecture and testing roadmap - Updated PROJECT_STATUS.md with v0.1.0 feature status - Updated configuration with all new options and detailed comments - Added comprehensive inline code comments ## Testing - Binary mode auto-detection: Tested and working - Binary mode custom path: Tested and working - Docker mode with default image: Tested and working - Self-hosted Gitea instances: Tested and working - Self-signed certificate support: Tested and working ## Files Changed - src/mcp_server_gitea.rs: Core extension (~350 lines) - configuration/default_settings.jsonc: New settings - configuration/installation_instructions.md: Updated guide - README.md: Expanded documentation - DEVELOPMENT.md: Complete developer guide - PROJECT_STATUS.md: Updated status - .gitignore: Added comprehensive ignore file ## Breaking Changes None - fully backward compatible. ## Next Steps (v0.2.0) - Cross-platform testing - Interactive configuration wizard - Performance optimizations - Marketplace publication
This commit is contained in:
197
SSE_MODE_ANALYSIS.md
Normal file
197
SSE_MODE_ANALYSIS.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user