Mycelium/tendril
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add binary path resolution and Docker support (v0.1.0)

Browse Source 
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:
Ryan Parmeter
2025-11-10 16:43:11 -07:00
parent 83d9664f72
commit 6a8dfa8b66
13 changed files with 2761 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
TESTING_FINDINGS.md Normal file
View File

@@ -0,0 +1,211 @@
# Testing Findings & Improvements
**Date**: November 10, 2024
**Tester**: User testing in Zed IDE
**Focus**: Transport modes and configuration validation
## Test Results Summary
### ✅ STDIO Mode - WORKING
- **Status**: Fully functional
- **Transport**: stdin/stdout direct communication
- **Configuration**: Minimal (token only)
- **Testing**: Confirmed working in production use
- **Recommendation**: Default and recommended mode
### ❌ SSE Mode - NOT WORKING (Removed)
- **Status**: Deprecated by gitea-mcp upstream
- **Issue**: MCP initialization timeout after 60 seconds
- **Root Cause**: gitea-mcp removed SSE mode in favor of HTTP Streaming
- **Action Taken**: Removed SSE support from Tendril v0.0.2+
- **Decision Rationale**: Dead code - no longer supported by server
## Key Findings
### 1. gitea-mcp Deprecated SSE Mode
- **Evidence**: Commit 88471b5de048ee35e929a5c3e5789f50ba57a845 on gitea-mcp
- **Reason**: MCP specification evolved to Streamable HTTP standard
- **Impact**: Any extension trying to use SSE mode will fail
- **Status**: Old MCP specification (pre-2025-03-26)
### 2. MCP Specification Update
- **Old Standard**: HTTP + SSE transport (Server-Sent Events)
- **New Standard**: Streamable HTTP transport (unified, bidirectional)
- **Effective Date**: MCP 2025-03-26 and later
- **Resource**: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
### 3. SSE Mode Error Signature
When attempting SSE mode, Zed produced:
```
ERROR [context_server::client] Unhandled JSON from context_server
ERROR [context_server::client] cancelled csp request task for "initialize" id 0 which took over 60s
ERROR [project::context_server_store] tendril-gitea-mcp context server failed to start:
Context server request timeout
```
Server logs showed:
```
2025-11-10 14:57:59 INFO operation/operation.go:61 Gitea MCP SSE server listening on :8987
(No further initialization - timeout occurs)
```
**Analysis**:
- Server started listening on port
- Zed tried to initialize MCP protocol
- Handshake timed out after 60 seconds
- Root cause: gitea-mcp's SSE mode not properly implementing MCP protocol over SSE
## Improvements Made
### Code Cleanup
- Removed `use_sse` configuration option
- Removed `gitea_port` setting (was SSE-only)
- Removed SSE-specific command-line argument handling
- Simplified `GiteaContextServerSettings` struct from 5 to 3 fields
- Hardcoded STDIO transport (the only working mode)
### Configuration Simplification
**Before (v0.0.1)**:
```json
{
"gitea_access_token": "token",
"gitea_host": "optional",
"gitea_port": "optional (for SSE)",
"gitea_insecure": "optional",
"use_sse": "optional (doesn't work)"
}
```
**After (v0.0.2+)**:
```json
{
"gitea_access_token": "token",
"gitea_host": "optional",
"gitea_insecure": "optional"
}
```
### Documentation Updates
- Updated `default_settings.jsonc` - removed SSE and port options
- Updated `installation_instructions.md` - removed SSE documentation
- Updated code comments - clarified STDIO as only transport
- Added `SSE_MODE_ANALYSIS.md` - detailed investigation document
## User Impact
### For Existing Users
- **STDIO mode users**: No changes needed - everything continues to work
- **SSE mode users**: Update config to remove `use_sse` and `gitea_port` options
- STDIO mode is now default (works the same way)
- No functionality lost
### For New Users
- Simpler configuration (3 options instead of 5)
- No confusing SSE mode option that doesn't work
- Clearer documentation focused on working features
- Faster setup time
## Performance Implications
### STDIO Mode (Current)
- Direct process communication
- No network overhead
- Sub-millisecond latency
- Single connection (sufficient for IDE usage)
- Perfect for local development
### HTTP Streaming (Future Alternative)
- Network round-trip latency
- Supports multiple concurrent connections
- Better for remote/shared servers
- Not yet implemented but documented for future
## Lessons Learned
### 1. Keep Code Sync with Upstream
- SSE mode removal in gitea-mcp wasn't immediately apparent
- Testing revealed the issue
- Dead code maintenance becomes technical debt
- Regular dependency audits would help catch this earlier
### 2. Test Against Real Implementations
- Code looked correct for SSE mode
- But gitea-mcp implementation changed
- Live testing revealed the disconnect
- Upstream changes need monitoring
### 3. Follow Spec Evolution
- MCP specification evolved (HTTP+SSE → Streamable HTTP)
- gitea-mcp followed the new spec
- Tendril should stay current with both upstream and spec
- Document planned support for new standards
### 4. Configuration Matters
- More options = more confusion
- Non-working options hurt credibility
- Simpler is better when it works
- Users appreciate clarity over feature count
## Recommendations for Future Development
### Short-term (v0.1.0)
- Monitor gitea-mcp for HTTP Streaming support confirmation
- Add configurable binary path (high priority from original roadmap)
- Add Docker support option
- Keep STDIO as default and primary mode
### Medium-term (v0.2.0)
- When gitea-mcp has HTTP Streaming support, evaluate implementation
- Create HTTP client support in Tendril
- Allow users to choose between STDIO and HTTP Streaming
- Document use cases for each transport
### Long-term (v1.0+)
- Full HTTP Streaming implementation
- Support for remote gitea-mcp servers
- Connection pooling for multiple Zed instances
- Load balancing for large teams
## Testing Checklist for Future Contributors
When testing Tendril:
- [ ] Verify STDIO mode with local gitea-mcp binary
- [ ] Confirm token-based authentication works
- [ ] Test self-hosted Gitea instance
- [ ] Test self-signed certificate handling
- [ ] Verify error messages are helpful
- [ ] Check Zed logs for any warnings
- [ ] Monitor gitea-mcp logs during operation
- [ ] Test with different Gitea instances if possible
When updating gitea-mcp version:
- [ ] Review gitea-mcp release notes for transport changes
- [ ] Test with new version before updating docs
- [ ] Check if new transport modes became available
- [ ] Update dependencies and CHANGELOG
- [ ] Run full test suite
## References
- **gitea-mcp Repository**: https://gitea.com/gitea/gitea-mcp
- **Commit that removed SSE**: https://gitea.com/gitea/gitea-mcp/commit/88471b5de048ee35e929a5c3e5789f50ba57a845
- **MCP Specification (Current)**: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
- **Streamable HTTP Spec**: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http
- **MCP Transport Overview**: https://docs.roocode.com/features/mcp/server-transports
## Conclusion
Testing revealed that SSE mode was already deprecated in gitea-mcp due to MCP specification evolution. This finding led to:
1. **Code Simplification**: Removed non-functional SSE code paths
2. **Configuration Improvement**: Reduced options from 5 to 3, removed confusing disabled mode
3. **Documentation Clarity**: Focused docs on what actually works
4. **Future Planning**: Identified HTTP Streaming as the next transport to support
The result is a cleaner, more maintainable extension with clearer user experience. STDIO mode remains robust and reliable, with a clear migration path documented for when HTTP Streaming support becomes desirable.
---
**Status**: v0.0.2 cleanup complete
**Next Steps**: Focus on binary path configuration and Docker support (v0.1.0)
**Verified By**: Live testing in Zed IDE, November 10, 2024