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
2025-11-10 16:43:11 -07:00
parent 83d9664f72
commit 6a8dfa8b66
13 changed files with 2761 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -1,3 +1,521 @@
-# tendril
+# Tendril: Gitea MCP for Zed

-A Zed IDE extension for Gitea and MCP integration.
+A Zed IDE extension that integrates with Gitea through the Model Context Protocol (MCP). Tendril is part of **The Mycelium Project** and provides seamless access to Gitea repositories, issues, pull requests, and more directly within your editor.
+
+## What is This?
+
+Tendril is a **Zed IDE extension** that acts as a bridge between Zed and a Gitea MCP server. The extension itself is lightweight - it's the glue that connects your editor to a Gitea MCP server running on your system (or in Docker). You'll need to have either the `gitea-mcp` binary installed or Docker available.
+
+Think of it as:
+- **Extension**: Tendril (this repository) - runs inside Zed
+- **Server**: gitea-mcp binary or Docker container - runs on your system, communicates with Gitea
+- **Result**: Full Gitea access from your editor through Zed's AI features
+
+## Requirements
+
+Before you can use Tendril, you need:
+
+1. **Zed IDE** - Download from https://zed.dev
+2. **Gitea MCP Server** - Either:
+   - Binary installed locally, OR
+   - Docker with gitea-mcp image available
+3. **Gitea Access Token** - Generated from your Gitea instance
+4. **Rust** (if installing as dev extension) - Installed via rustup
+
+## Quick Start
+
+### Option A: Using Local Binary
+
+#### 1. Install the Gitea MCP Binary
+
+The extension automatically searches for `gitea-mcp` in these locations:
+- `/usr/local/bin/gitea-mcp`
+- `~/.local/bin/gitea-mcp`
+- `~/.cargo/bin/gitea-mcp`
+- `/opt/homebrew/bin/gitea-mcp` (macOS M-series)
+- Anywhere in your PATH
+
+Choose an installation method:
+
+**Download Pre-built Binary:**
+```bash
+# Download from: https://gitea.com/gitea/gitea-mcp/releases
+# For example, Linux x64:
+wget https://gitea.com/gitea/gitea-mcp/releases/download/v1.0.0/gitea-mcp-linux-amd64
+chmod +x gitea-mcp-linux-amd64
+sudo mv gitea-mcp-linux-amd64 /usr/local/bin/gitea-mcp
+```
+
+**Build from Source:**
+```bash
+git clone https://gitea.com/gitea/gitea-mcp.git
+cd gitea-mcp
+make install
+```
+
+**Verify Installation:**
+```bash
+/usr/local/bin/gitea-mcp --help
+```
+
+#### 2. Generate a Gitea Access Token
+
+1. Log in to your Gitea instance
+2. Go to **Settings** → **Applications** → **Authorize New Application**
+3. Give it a name like "Zed MCP"
+4. Select required permissions (recommend repository-related scopes)
+5. Click **Authorize** and copy the token
+
+#### 3. Install Tendril as a Dev Extension
+
+1. Open Zed
+2. Go to **Extensions** panel (left sidebar or Cmd+K → "Extensions")
+3. Click **Install Dev Extension**
+4. Select the `tendril` directory
+5. Zed will compile and load the extension
+
+#### 4. Configure Zed Settings
+
+Open your Zed settings (`Cmd+,`) and add:
+
+```json
+{
+  "context_servers": {
+    "tendril-gitea-mcp": {
+      "settings": {
+        "gitea_access_token": "YOUR_GITEA_TOKEN_HERE"
+      }
+    }
+  }
+}
+```
+
+### Option B: Using Docker
+
+If you have Docker installed and prefer containerized deployment:
+
+#### 1. Generate a Gitea Access Token
+
+Same as Option A, step 2 above.
+
+#### 2. Install Tendril as a Dev Extension
+
+Same as Option A, steps 3-4, but with Docker settings:
+
+```json
+{
+  "context_servers": {
+    "tendril-gitea-mcp": {
+      "settings": {
+        "gitea_access_token": "YOUR_GITEA_TOKEN_HERE",
+        "use_docker": true
+      }
+    }
+  }
+}
+```
+
+The extension will automatically pull and run `gitea/gitea-mcp-server:latest` in Docker.
+
+Optionally, specify a different image:
+
+```json
+{
+  "context_servers": {
+    "tendril-gitea-mcp": {
+      "settings": {
+        "gitea_access_token": "YOUR_GITEA_TOKEN_HERE",
+        "use_docker": true,
+        "docker_image": "gitea/gitea-mcp-server:v1.0.0"
+      }
+    }
+  }
+}
+```
+
+#### 3. Test the Connection
+
+In Zed's Assistant panel, try:
+
+```
+list my repositories
+```
+
+### 5. Test the Connection
+
+In Zed's Assistant panel, try a command like:
+
+```
+list my repositories
+```
+
+The MCP server should respond with your Gitea repositories.
+
+## Configuration Reference
+
+### Basic Settings
+
+| Setting | Type | Required | Description |
+|---------|------|----------|-------------|
+| `gitea_access_token` | string | Yes | Your Gitea personal access token |
+| `gitea_host` | string | No | URL of your Gitea instance (for self-hosted) |
+| `gitea_insecure` | boolean | No | Allow self-signed certificates (default: false) |
+
+### Binary Path Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `gitea_mcp_binary_path` | string | (auto-detect) | Explicit path to gitea-mcp binary |
+
+If `gitea_mcp_binary_path` is not set, Tendril automatically searches standard locations. Use this setting if your binary is in a non-standard location.
+
+### Docker Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `use_docker` | boolean | false | Use Docker to run gitea-mcp instead of local binary |
+| `docker_image` | string | gitea/gitea-mcp-server:latest | Docker image to use |
+
+## Configuration Examples
+
+### Basic Setup (Auto-Detect Binary)
+
+```json
+{
+  "context_servers": {
+    "tendril-gitea-mcp": {
+      "settings": {
+        "gitea_access_token": "YOUR_GITEA_TOKEN_HERE"
+      }
+    }
+  }
+}
+```
+
+### Self-Hosted Gitea
+
+```json
+{
+  "context_servers": {
+    "tendril-gitea-mcp": {
+      "settings": {
+        "gitea_access_token": "YOUR_TOKEN",
+        "gitea_host": "https://git.example.com",
+        "gitea_insecure": false
+      }
+    }
+  }
+}
+```
+
+### Custom Binary Path
+
+```json
+{
+  "context_servers": {
+    "tendril-gitea-mcp": {
+      "settings": {
+        "gitea_access_token": "YOUR_TOKEN",
+        "gitea_mcp_binary_path": "/home/user/custom/location/gitea-mcp"
+      }
+    }
+  }
+}
+```
+
+### Docker Setup
+
+```json
+{
+  "context_servers": {
+    "tendril-gitea-mcp": {
+      "settings": {
+        "gitea_access_token": "YOUR_TOKEN",
+        "use_docker": true
+      }
+    }
+  }
+}
+```
+
+### Docker with Custom Image and Self-Hosted Gitea
+
+```json
+{
+  "context_servers": {
+    "tendril-gitea-mcp": {
+      "settings": {
+        "gitea_access_token": "YOUR_TOKEN",
+        "gitea_host": "https://git.internal.company.com",
+        "gitea_insecure": true,
+        "use_docker": true,
+        "docker_image": "my-registry.com/gitea-mcp:v1.0.0"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+Through the Gitea MCP server, you get access to:
+
+- **User Management**: Get user info, list organizations, search users
+- **Repository Management**: List repos, create repos, fork repos
+- **Branch Management**: Create/delete/list branches
+- **Release Management**: Create/list/delete releases
+- **Tag Management**: Create/list/delete tags
+- **File Operations**: View, create, update, delete files
+- **Issue Management**: Create/edit/list issues, add comments
+- **Pull Requests**: Create/list/manage pull requests
+- **Commits**: List and view commits
+
+See the [Gitea MCP documentation](https://gitea.com/gitea/gitea-mcp) for complete tool details.
+
+## Installation Methods
+
+### For Development (Recommended)
+
+Use the dev extension approach (see Quick Start above). This allows you to:
+- Test changes immediately
+- Reload the extension without restarting Zed
+- Contribute improvements back
+
+### For Production (When Published)
+
+Once Tendril is published to the Zed Extension Marketplace, you'll be able to install it like any other extension from within Zed's Extensions panel.
+
+## Troubleshooting
+
+### "Binary Not Found" Error
+
+If you get an error about gitea-mcp not being found:
+
+1. **Using binary mode:**
+   - Install gitea-mcp to `/usr/local/bin/gitea-mcp` or another standard location
+   - Or set `gitea_mcp_binary_path` to the full path in your settings
+   - Verify it's executable: `chmod +x /path/to/gitea-mcp`
+   - Test it: `/path/to/gitea-mcp --help`
+
+2. **Using Docker mode:**
+   - Ensure Docker is installed and running
+   - Set `use_docker: true` in settings
+   - Let Docker pull the image automatically
+
+### "Failed to Spawn Command" Error
+
+The binary exists but isn't executable:
+
+```bash
+chmod +x /usr/local/bin/gitea-mcp
+```
+
+Then restart Zed.
+
+### Authentication Issues
+
+- Verify your Gitea token has repository permissions
+- Ensure you've copied the entire token correctly (no extra spaces)
+- Check that the token hasn't expired
+- Log out and back in to your Gitea instance if using session-based auth
+
+### Self-Hosted Gitea with Self-Signed Certificates
+
+If you're getting SSL certificate errors with a self-hosted Gitea instance:
+
+```json
+{
+  "context_servers": {
+    "tendril-gitea-mcp": {
+      "settings": {
+        "gitea_access_token": "YOUR_TOKEN",
+        "gitea_host": "https://git.example.com",
+        "gitea_insecure": true
+      }
+    }
+  }
+}
+```
+
+**Security Note**: Only use `gitea_insecure: true` for trusted internal servers.
+
+### Docker Not Available
+
+If you see "docker: command not found":
+
+1. Install Docker from https://www.docker.com/products/docker-desktop
+2. Ensure Docker Desktop is running (macOS/Windows)
+3. Or install Docker on Linux: `sudo apt install docker.io` (Ubuntu) or equivalent for your distro
+4. Restart Zed after installing Docker
+
+### Dev Extension Not Loading
+
+Check the Zed log for errors:
+
+1. In Zed, run: `zed: open log`
+2. Look for errors related to "tendril"
+3. If you see build errors, try:
+   ```bash
+   cd tendril
+   cargo build --release
+   cargo clippy
+   ```
+4. Ensure Rust is installed via rustup: `rustup --version`
+5. Restart Zed completely
+
+## Binary Path Resolution
+
+When **not** using Docker, Tendril uses this search order:
+
+1. **Explicitly configured path** (if `gitea_mcp_binary_path` is set)
+2. **System standard locations**:
+   - `/usr/local/bin/gitea-mcp`
+   - `~/.local/bin/gitea-mcp`
+   - `~/.cargo/bin/gitea-mcp`
+   - `/opt/homebrew/bin/gitea-mcp` (macOS M-series)
+3. **PATH environment variable** (any location in your PATH)
+
+If the binary isn't found, you'll get a helpful error message with troubleshooting steps.
+
+## Debugging
+
+### View Gitea MCP Logs
+
+```bash
+tail -f ~/.gitea-mcp/gitea-mcp.log
+```
+
+### View Zed Logs
+
+1. In Zed, run: `zed: open log`
+2. Or check the system log location:
+   - macOS: `~/Library/Logs/Zed.log`
+   - Linux: `~/.local/share/zed/logs/Zed.log`
+   - Windows: `%APPDATA%\Zed\logs\Zed.log`
+
+### Debug with Verbose Logging
+
+Start Zed from the command line for more output:
+
+```bash
+zed --foreground
+```
+
+### Manual Binary Testing
+
+Test the binary directly (without Zed):
+
+```bash
+# STDIO mode
+export GITEA_ACCESS_TOKEN="your_token"
+/usr/local/bin/gitea-mcp -t stdio --host https://git.example.com
+
+# Type any command and press Ctrl+D when done
+# (This is a low-level test)
+```
+
+## Development
+
+### Building from Source
+
+Prerequisites:
+- Rust (installed via rustup)
+- Zed development environment
+
+Build the extension:
+
+```bash
+cd tendril
+cargo build --release
+```
+
+This generates the WASM module used by Zed.
+
+### Reloading During Development
+
+After making changes to the Rust code:
+
+1. Run `cargo build --release`
+2. Reload the extension in Zed (restart Zed or use extension reload if available)
+3. Changes take effect immediately
+
+### Project Structure
+
+```
+tendril/
+├── Cargo.toml                          # Rust project configuration
+├── extension.toml                      # Zed extension manifest
+├── src/
+│   └── mcp_server_gitea.rs            # Main extension logic (~350 lines)
+├── configuration/
+│   ├── default_settings.jsonc         # Default configuration with comments
+│   └── installation_instructions.md   # Quick setup guide for Zed UI
+├── README.md                           # This file
+├── DEVELOPMENT.md                      # Developer guide
+├── PROJECT_STATUS.md                   # Project status and roadmap
+└── LICENSE                             # Apache 2.0
+```
+
+### Code Overview
+
+**src/mcp_server_gitea.rs**:
+- `GiteaContextServerSettings`: Struct defining all configuration options
+- `build_binary_command()`: Creates command to run gitea-mcp binary
+- `build_docker_command()`: Creates Docker command to run gitea-mcp
+- `resolve_binary_path()`: Implements smart binary path discovery
+
+## Related Projects
+
+- **Gitea**: https://gitea.io - Lightweight Git service
+- **Gitea MCP**: https://gitea.com/gitea/gitea-mcp - MCP server for Gitea
+- **Model Context Protocol**: https://modelcontextprotocol.io
+- **The Mycelium Project**: https://git.parkingmeter.info/Mycelium
+- **Zed IDE**: https://zed.dev
+
+## License
+
+Licensed under the Apache License 2.0. See [LICENSE](./LICENSE) for details.
+
+## Support
+
+For issues or questions:
+
+1. **Check troubleshooting** above
+2. **Review logs** using `zed: open log`
+3. **Open an issue** on [Tendril repository](https://git.parkingmeter.info/Mycelium/tendril)
+4. **Consult documentation**:
+   - [Zed Extensions](https://zed.dev/docs/extensions)
+   - [Gitea MCP](https://gitea.com/gitea/gitea-mcp)
+   - [Model Context Protocol](https://modelcontextprotocol.io)
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Make your changes and test: `cargo build --release && cargo clippy`
+4. Submit a pull request with a clear description
+
+## Authors
+
+- Ryan Parmeter ([@parkingmeter](https://git.parkingmeter.info/parkingmeter))
+- The Mycelium Project Contributors
+
+## Changelog
+
+### v0.1.0 (Upcoming)
+
+- ✨ Configurable binary path with intelligent fallback search
+- ✨ Docker support for containerized deployment
+- ✨ Cross-platform binary discovery (Linux, macOS, Windows)
+- 🐛 Improved error messages with troubleshooting guidance
+- 📚 Enhanced documentation
+
+### v0.0.1 (Initial Development Release)
+
+- Initial development version
+- STDIO mode support
+- Basic configuration through Zed settings.json
+- Support for self-hosted Gitea instances
+- Hardcoded binary path to `/usr/local/bin/gitea-mcp`