From e6e1ef214475f69277501fad4bca7c32f91b1a5d Mon Sep 17 00:00:00 2001 From: Ryan Parmeter Date: Mon, 10 Nov 2025 21:45:08 -0700 Subject: [PATCH] refactor: Complete simplification - require all binary paths explicitly MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit BREAKING CHANGE: All binary paths must now be explicitly configured. Changes to code: - Added docker_binary_path setting to GiteaContextServerSettings - Updated find_docker_binary() to require explicit docker path - Clear error messages with platform-specific examples - Consistent approach: no auto-detection for any binaries Changes to documentation: - Updated README.md with docker_binary_path requirement - Rewrote default_settings.jsonc with explicit configuration examples - Shortened installation_instructions.md to fit Zed UI - Added 'which' command instructions to find binary paths - Documented common paths for macOS, Linux, Windows - Explained WASM limitations clearly Why this approach: - WASM cannot access PATH reliably (especially on macOS) - WASM cannot detect host OS - WASM cannot check file existence - Explicit configuration is reliable and works everywhere - Users have full control over which binaries are used - Configuration is done once and works consistently This completes the simplification: ✅ No auto-detection attempts ✅ Clear, actionable error messages ✅ Comprehensive documentation ✅ Works reliably on Linux, macOS, and Windows ✅ Tested on Linux x86_64 and macOS M4 --- README.md | 573 ++++++++++----------- configuration/default_settings.jsonc | 85 ++- configuration/installation_instructions.md | 49 +- src/mcp_server_gitea.rs | 43 +- 4 files changed, 385 insertions(+), 365 deletions(-) diff --git a/README.md b/README.md index a07b17f..3771875 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,11 @@ A Zed IDE extension that integrates with Gitea through the Model Context Protoco ## 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. +Tendril is a **Zed IDE extension** that acts as a bridge between Zed and a Gitea MCP server. The extension is lightweight - it connects your editor to a Gitea MCP server running on your system (or in Docker). 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 +- **Server**: gitea-mcp binary or Docker container - communicates with Gitea - **Result**: Full Gitea access from your editor through Zed's AI features ## Requirements @@ -18,96 +18,68 @@ 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 + - Docker with gitea-mcp image 3. **Gitea Access Token** - Generated from your Gitea instance -4. **Rust** (if installing as dev extension) - Installed via rustup +4. **Rust** (for dev installation) - Installed via rustup ## Quick Start -### Option A: Using Local Binary +### Step 1: Install Gitea MCP Server -#### 1. Install the Gitea MCP Binary +Choose one method: -The extension automatically searches for `gitea-mcp` (and `gitea-mcp-server`) in these locations: -- `/usr/local/bin/gitea-mcp` or `gitea-mcp-server` -- `~/.local/bin/gitea-mcp` or `gitea-mcp-server` -- `~/.cargo/bin/gitea-mcp` or `gitea-mcp-server` -- `/opt/homebrew/bin/gitea-mcp` or `gitea-mcp-server` (macOS) -- Anywhere in your PATH +#### Option A: macOS (Homebrew - Recommended) -Choose an installation method: - -**macOS (Recommended - Homebrew):** ```bash -# Install via Homebrew (handles binary verification and updates) brew install gitea/tap/gitea-mcp-server ``` -This installs to `/opt/homebrew/bin/gitea-mcp-server` and is the easiest method for macOS users. -**Download Pre-built Binary:** +The binary will be installed at `/opt/homebrew/bin/gitea-mcp-server`. + +#### Option B: Linux (Pre-built Binary) + ```bash # Download from: https://gitea.com/gitea/gitea-mcp/releases -# For example, Linux x64: +# Example for 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:** +#### Option C: 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 -``` +#### Option D: Use Docker -#### 2. Generate a Gitea Access Token +If you prefer Docker, skip the binary installation - we'll configure Docker mode in Step 3. + +### Step 2: Generate a Gitea Access Token 1. Log in to your Gitea instance -2. Go to **Settings** → **Applications** → **Authorize New Application** +2. Go to **Settings** → **Applications** → **Generate New Token** 3. Give it a name like "Zed MCP" -4. Select required permissions (recommend repository-related scopes) -5. Click **Authorize** and copy the token +4. Select repository-related permissions +5. Copy the token -#### 3. Install Tendril as a Dev Extension +### Step 3: Install Tendril 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 +1. Clone this repository +2. Open Zed +3. Go to **Extensions** panel (Cmd/Ctrl + Shift + X) +4. Click **Install Dev Extension** +5. Select the `tendril` directory +6. Zed will compile and load the extension -#### 4. Configure Zed Settings +### Step 4: Configure Zed Settings -Open your Zed settings (`Cmd+,`) and add: +Open your Zed settings (Cmd/Ctrl + ,) and add one of the following configurations: -```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: +#### For Local Binary (macOS with Homebrew): ```json { @@ -115,16 +87,29 @@ Same as Option A, steps 3-4, but with Docker settings: "tendril-gitea-mcp": { "settings": { "gitea_access_token": "YOUR_GITEA_TOKEN_HERE", - "use_docker": true + "gitea_mcp_binary_path": "/opt/homebrew/bin/gitea-mcp-server" } } } } ``` -The extension will automatically pull and run `gitea/gitea-mcp-server:latest` in Docker. +#### For Local Binary (Linux): -Optionally, specify a different image: +```json +{ + "context_servers": { + "tendril-gitea-mcp": { + "settings": { + "gitea_access_token": "YOUR_GITEA_TOKEN_HERE", + "gitea_mcp_binary_path": "/usr/local/bin/gitea-mcp" + } + } + } +} +``` + +#### For Docker: ```json { @@ -133,14 +118,16 @@ Optionally, specify a different image: "settings": { "gitea_access_token": "YOUR_GITEA_TOKEN_HERE", "use_docker": true, - "docker_image": "gitea/gitea-mcp-server:v1.0.0" + "docker_binary_path": "/usr/bin/docker" } } } } ``` -#### 3. Test the Connection +**Note**: Find your docker path with `which docker` and use that full path. + +### Step 5: Test the Connection In Zed's Assistant panel, try: @@ -148,58 +135,45 @@ 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. +You should see your Gitea repositories! ## Configuration Reference -### Basic Settings +### Required 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) | +| Setting | Type | Description | +|---------|------|-------------| +| `gitea_access_token` | string | Your Gitea personal access token | -### Binary Path Settings +### Binary Configuration (choose one) + +| Setting | Type | Description | +|---------|------|-------------| +| `gitea_mcp_binary_path` | string | Full path to gitea-mcp binary (e.g., `/opt/homebrew/bin/gitea-mcp-server`) | +| `use_docker` | boolean | Set to `true` to use Docker instead of local binary | +| `docker_binary_path` | string | Full path to docker binary (required when `use_docker: true`) | + +**Important**: Due to WebAssembly sandbox limitations, you **must** explicitly configure: +- Either `gitea_mcp_binary_path` for local binary +- Or `use_docker: true` + `docker_binary_path` for Docker mode + +Auto-detection is not possible. + +### Optional Settings | Setting | Type | Default | Description | |---------|------|---------|-------------| -| `gitea_mcp_binary_path` | string | (auto-detect) | Explicit path to gitea-mcp binary | +| `gitea_host` | string | (none) | URL of your Gitea instance (for self-hosted) | +| `gitea_insecure` | boolean | false | Allow self-signed certificates | +| `docker_image` | string | gitea/gitea-mcp-server:latest | Docker image to use (when `use_docker: true`) | -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 | +**Finding binary paths:** +- gitea-mcp: `which gitea-mcp` or `which gitea-mcp-server` +- docker: `which docker` ## Configuration Examples -### Basic Setup (Auto-Detect Binary) - -```json -{ - "context_servers": { - "tendril-gitea-mcp": { - "settings": { - "gitea_access_token": "YOUR_GITEA_TOKEN_HERE" - } - } - } -} -``` - -### Self-Hosted Gitea +### Self-Hosted Gitea with Binary ```json { @@ -208,14 +182,14 @@ If `gitea_mcp_binary_path` is not set, Tendril automatically searches standard l "settings": { "gitea_access_token": "YOUR_TOKEN", "gitea_host": "https://git.example.com", - "gitea_insecure": false + "gitea_mcp_binary_path": "/usr/local/bin/gitea-mcp" } } } } ``` -### Custom Binary Path +### Self-Hosted Gitea with Docker ```json { @@ -223,29 +197,16 @@ If `gitea_mcp_binary_path` is not set, Tendril automatically searches standard l "tendril-gitea-mcp": { "settings": { "gitea_access_token": "YOUR_TOKEN", - "gitea_mcp_binary_path": "/home/user/custom/location/gitea-mcp" + "gitea_host": "https://git.example.com", + "use_docker": true, + "docker_binary_path": "/usr/bin/docker" } } } } ``` -### 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 +### Self-Signed Certificates ```json { @@ -255,98 +216,7 @@ If `gitea_mcp_binary_path` is not set, Tendril automatically searches standard l "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: - -**For macOS:** -- Install via Homebrew: `brew install gitea/tap/gitea-mcp-server` -- Or set `gitea_mcp_binary_path` to the full path in your settings -- Verify it works: `/opt/homebrew/bin/gitea-mcp-server --help` - -**For Linux:** -- Download from https://gitea.com/gitea/gitea-mcp/releases to `/usr/local/bin/gitea-mcp` -- Or build from source and run `make install` -- Or set `gitea_mcp_binary_path` to your custom location - -**For all platforms:** -- Verify the binary is executable: `chmod +x /path/to/gitea-mcp` -- Test it manually: `/path/to/gitea-mcp --help` -- If you've installed it in a non-standard location, use the `gitea_mcp_binary_path` setting - -**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 + "gitea_mcp_binary_path": "/usr/local/bin/gitea-mcp" } } } @@ -355,93 +225,156 @@ If you're getting SSL certificate errors with a self-hosted Gitea instance: **Security Note**: Only use `gitea_insecure: true` for trusted internal servers. -### Docker Not Available +### Custom Docker Image -If you see "docker: command not found": +```json +{ + "context_servers": { + "tendril-gitea-mcp": { + "settings": { + "gitea_access_token": "YOUR_TOKEN", + "use_docker": true, + "docker_binary_path": "/usr/bin/docker", + "docker_image": "my-registry.com/gitea-mcp:v1.0.0" + } + } + } +} +``` -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 +## Available Features -### Dev Extension Not Loading +Through the Gitea MCP server, you get access to: -Check the Zed log for errors: +- **User Management**: Get user info, list organizations, search users +- **Repository Management**: List, create, fork repositories +- **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 -1. In Zed, run: `zed: open log` -2. Look for errors related to "tendril" -3. If you see build errors, try: +See the [Gitea MCP documentation](https://gitea.com/gitea/gitea-mcp) for complete tool details. + +## Why Explicit Configuration? + +Tendril runs as a WebAssembly (WASM) extension inside Zed. The WASM sandbox has important security restrictions: + +- ❌ Cannot detect the host operating system +- ❌ Cannot access PATH environment variable reliably (especially on macOS) +- ❌ Cannot check if files exist on the filesystem +- ❌ Cannot spawn commands like `which` + +These limitations mean automatic binary discovery is unreliable and platform-dependent. Explicit configuration ensures the extension works reliably across all platforms. + +**The upside**: Once configured, it just works! And you have full control over which binary/Docker image is used. + +**Note on Docker**: Docker mode also requires explicit `docker_binary_path` for the same reasons. + +## Troubleshooting + +### "Binary path not configured" Error + +You'll see this if neither `gitea_mcp_binary_path` nor `use_docker` is set. + +**Solution**: Add one of these to your Zed settings: + +```json +"gitea_mcp_binary_path": "/opt/homebrew/bin/gitea-mcp-server" +``` + +or + +```json +"use_docker": true, +"docker_binary_path": "/usr/bin/docker" +``` + +### Finding Your Binary Path + +If you're not sure where your binary is installed: + +**macOS (Homebrew):** +```bash +which gitea-mcp-server +# Output: /opt/homebrew/bin/gitea-mcp-server +``` + +**Linux:** +```bash +which gitea-mcp +# Output: /usr/local/bin/gitea-mcp +``` + +Use the output path in your `gitea_mcp_binary_path` setting. + +### "Failed to spawn command" Error + +The path is configured but Zed can't execute the binary: + +1. **Verify the path is correct:** ```bash - cd tendril - cargo build --release - cargo clippy + ls -la /opt/homebrew/bin/gitea-mcp-server ``` -4. Ensure Rust is installed via rustup: `rustup --version` -5. Restart Zed completely -## Binary Path Resolution +2. **Ensure it's executable:** + ```bash + chmod +x /opt/homebrew/bin/gitea-mcp-server + ``` -When **not** using Docker, Tendril uses this search order: +3. **Test it manually:** + ```bash + /opt/homebrew/bin/gitea-mcp-server --help + ``` -1. **Explicitly configured path** (if `gitea_mcp_binary_path` is set) - - User configuration takes priority - - Example: `"gitea_mcp_binary_path": "/opt/homebrew/bin/gitea-mcp-server"` +4. **Restart Zed** after fixing permissions -2. **System standard locations** (searches for both `gitea-mcp` and `gitea-mcp-server`): - - `/usr/local/bin/gitea-mcp` or `gitea-mcp-server` - - `/usr/bin/gitea-mcp` or `gitea-mcp-server` - - `~/.local/bin/gitea-mcp` or `gitea-mcp-server` - - `~/bin/gitea-mcp` or `gitea-mcp-server` - - `~/.cargo/bin/gitea-mcp` or `gitea-mcp-server` - - `/opt/homebrew/bin/gitea-mcp` or `gitea-mcp-server` (macOS - installed via Homebrew) +### Authentication Issues -3. **PATH environment variable** (any location in your system PATH) +- Verify your token has the correct permissions +- Check for extra spaces when copying the token +- Ensure the token hasn't expired +- Try generating a new token -If the binary isn't found, you'll get a helpful error message with troubleshooting steps. +### Docker Issues -### macOS Homebrew Note +If using `use_docker: true` and seeing errors: -If you installed via Homebrew (`brew install gitea/tap/gitea-mcp-server`), the binary will be at: -- `/opt/homebrew/bin/gitea-mcp-server` (M-series/ARM64 Macs) +1. **Find your docker binary path:** + ```bash + which docker + # Output: /usr/bin/docker (use this in docker_binary_path) + ``` -This location is automatically searched, so no configuration needed! +2. **Check Docker is running:** + ```bash + docker ps + ``` -## Debugging +3. **Verify Docker can pull images:** + ```bash + docker pull gitea/gitea-mcp-server:latest + ``` -### View Gitea MCP Logs +4. **On Linux, check permissions:** + ```bash + sudo usermod -aG docker $USER + # Log out and back in + ``` -```bash -tail -f ~/.gitea-mcp/gitea-mcp.log -``` +**Common Docker paths:** +- Linux: `/usr/bin/docker` +- macOS: `/usr/local/bin/docker` or `/Applications/Docker.app/Contents/Resources/bin/docker` -### View Zed Logs +### View 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` +Check Zed logs for detailed error messages: -### 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) -``` +1. In Zed, run command: `zed: open log` +2. Look for errors related to "tendril" or "gitea-mcp" +3. The error messages will show the exact path that was attempted ## Development @@ -449,25 +382,16 @@ export GITEA_ACCESS_TOKEN="your_token" Prerequisites: - Rust (installed via rustup) -- Zed development environment +- WASM target: `rustup target add wasm32-unknown-unknown` Build the extension: ```bash cd tendril -cargo build --release +cargo build --target wasm32-unknown-unknown --release +cp target/wasm32-unknown-unknown/release/mcp_server_gitea.wasm extension.wasm ``` -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 ``` @@ -475,10 +399,10 @@ tendril/ ├── Cargo.toml # Rust project configuration ├── extension.toml # Zed extension manifest ├── src/ -│ └── mcp_server_gitea.rs # Main extension logic (~350 lines) +│ └── mcp_server_gitea.rs # Main extension logic ├── configuration/ -│ ├── default_settings.jsonc # Default configuration with comments -│ └── installation_instructions.md # Quick setup guide for Zed UI +│ ├── default_settings.jsonc # Default configuration template +│ └── installation_instructions.md # Setup guide for Zed UI ├── README.md # This file ├── DEVELOPMENT.md # Developer guide ├── PROJECT_STATUS.md # Project status and roadmap @@ -487,11 +411,27 @@ tendril/ ### 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 +The extension is ~300 lines of clean Rust code: + +- `GiteaContextServerSettings`: Configuration structure +- `build_binary_command()`: Creates command for local binary +- `build_docker_command()`: Creates command for Docker +- `resolve_binary_path()`: Validates explicit configuration + +## Common Binary Paths + +For reference, here are the typical installation paths: + +| Platform | Package Manager | Path | +|----------|----------------|------| +| macOS | Homebrew | `/opt/homebrew/bin/gitea-mcp-server` | +| macOS (Intel) | Homebrew | `/usr/local/bin/gitea-mcp-server` | +| Linux | Manual install | `/usr/local/bin/gitea-mcp` | +| Linux | User install | `~/.local/bin/gitea-mcp` | +| Source build | Cargo | `~/.cargo/bin/gitea-mcp` | +| Windows | Manual install | `C:\Program Files\gitea-mcp\gitea-mcp.exe` | + +Use `which gitea-mcp` or `which gitea-mcp-server` to find your actual path. ## Related Projects @@ -509,8 +449,8 @@ Licensed under the Apache License 2.0. See [LICENSE](./LICENSE) for details. For issues or questions: -1. **Check troubleshooting** above -2. **Review logs** using `zed: open log` +1. **Check troubleshooting section** above +2. **Review Zed 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) @@ -522,8 +462,8 @@ For issues or questions: 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` +2. Create a feature branch +3. Make your changes and test thoroughly 4. Submit a pull request with a clear description ## Authors @@ -533,18 +473,23 @@ Contributions are welcome! Please: ## Changelog -### v0.1.0 (Upcoming) +### v0.2.0 (Current) -- ✨ 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 +- 🔧 **BREAKING**: Removed automatic binary path detection (WASM limitations) +- ✨ Explicit configuration required: `gitea_mcp_binary_path` or `use_docker: true` + `docker_binary_path` +- ✨ Docker mode now requires explicit `docker_binary_path` (consistent with binary requirement) +- 📚 Simplified documentation and clearer error messages +- 🐛 Fixed macOS M4 compatibility issues +- ✅ Tested on Linux (x86_64) and macOS (M4) -### v0.0.1 (Initial Development Release) +### v0.1.0 (Previous) + +- ✨ Attempted automatic binary path detection +- ✨ Docker support +- 🐛 Issues with PATH detection in WASM on macOS + +### v0.0.1 (Initial) - 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` +- Basic configuration through Zed settings \ No newline at end of file diff --git a/configuration/default_settings.jsonc b/configuration/default_settings.jsonc index 790ef78..99671c6 100644 --- a/configuration/default_settings.jsonc +++ b/configuration/default_settings.jsonc @@ -4,41 +4,63 @@ // ============================================================================ // Required: Your Gitea personal access token - // Generated in Gitea at: Settings > Applications > Authorize New Application + // Generated in Gitea at: Settings > Applications > Generate New Token // This token is used to authenticate with your Gitea instance "gitea_access_token": "YOUR_GITEA_TOKEN", // ============================================================================ - // BINARY PATH RESOLUTION + // BINARY CONFIGURATION (Choose ONE option) // ============================================================================ - // Optional: Explicit path to gitea-mcp binary - // Leave commented to use automatic discovery - // If set, this path must point to the gitea-mcp executable - // Examples: - // - "/usr/local/bin/gitea-mcp" - // - "/home/user/.local/bin/gitea-mcp" - // - "C:\\Program Files\\gitea-mcp\\gitea-mcp.exe" (Windows) - // "gitea_mcp_binary_path": "path/to/gitea-mcp", + // Option 1: Local Binary Path + // Required if not using Docker + // Specify the full path to the gitea-mcp binary on your system + // + // Find your binary path with: + // macOS/Linux: which gitea-mcp-server (or: which gitea-mcp) + // Windows: where gitea-mcp.exe + // + // Common paths: + // macOS (Homebrew): "/opt/homebrew/bin/gitea-mcp-server" + // macOS (Intel): "/usr/local/bin/gitea-mcp-server" + // Linux: "/usr/local/bin/gitea-mcp" + // Windows: "C:\\Program Files\\gitea-mcp\\gitea-mcp.exe" + // + "gitea_mcp_binary_path": "/opt/homebrew/bin/gitea-mcp-server", + + // Option 2: Docker Mode + // Use Docker to run gitea-mcp in a container + // Requires Docker to be installed and running + // + // When using Docker, you must also specify docker_binary_path below + // + // "use_docker": true, // ============================================================================ - // DOCKER SUPPORT + // DOCKER CONFIGURATION (Only if use_docker is true) // ============================================================================ - // Optional: Use Docker to run gitea-mcp instead of local binary - // Set to true if: - // 1. You prefer containerized deployment - // 2. The binary is not available on your system - // 3. You want consistent behavior across platforms - // Requires: Docker or Docker Desktop to be installed and running - // "use_docker": false, + // Required when use_docker is true + // Full path to the docker binary + // + // Find your docker path with: + // macOS/Linux: which docker + // + // Common paths: + // Linux: "/usr/bin/docker" + // macOS: "/usr/local/bin/docker" + // "/Applications/Docker.app/Contents/Resources/bin/docker" + // + // "docker_binary_path": "/usr/bin/docker", // Optional: Docker image to use for gitea-mcp // Only used if use_docker is true - // Default: "gitea/gitea-mcp:latest" - // You can specify a different version or tag: + // Default: "gitea/gitea-mcp-server:latest" + // + // Examples: // - "gitea/gitea-mcp-server:v1.0.0" (specific version) // - "my-registry.com/gitea-mcp-server:custom" (custom registry) + // // "docker_image": "gitea/gitea-mcp-server:latest", // ============================================================================ @@ -46,16 +68,37 @@ // ============================================================================ // Optional: URL of your Gitea instance (for self-hosted Gitea) - // Leave commented out to use the default Gitea instance + // Leave commented out to use the default public Gitea instance + // // Examples: // - "https://git.example.com" // - "https://gitea.internal.company.com" // - "http://localhost:3000" (for local development) + // // "gitea_host": "https://your-gitea-instance.com", // Optional: Allow insecure/self-signed certificates // Set to true ONLY if using self-signed certificates + // // Security warning: This disables certificate verification // Only use this for trusted internal servers + // // "gitea_insecure": false + + // ============================================================================ + // IMPORTANT NOTES + // ============================================================================ + // + // Why explicit paths are required: + // This extension runs in a WebAssembly (WASM) sandbox which cannot: + // - Access PATH environment variable reliably + // - Detect the host operating system + // - Check if files exist on the filesystem + // - Auto-discover binary locations + // + // Therefore, you MUST explicitly configure either: + // 1. gitea_mcp_binary_path (for local binary), OR + // 2. use_docker: true + docker_binary_path (for Docker mode) + // + // ============================================================================ } diff --git a/configuration/installation_instructions.md b/configuration/installation_instructions.md index 2686a42..2a9f6d8 100644 --- a/configuration/installation_instructions.md +++ b/configuration/installation_instructions.md @@ -1,28 +1,33 @@ # Tendril: Gitea MCP for Zed -## Quick Start +### 1. Install Gitea MCP Binary -1. **Get a Gitea Token** - - Log in to your Gitea instance - - Settings → Applications → Authorize New Application - - Copy the token +**macOS (Homebrew):** +```bash +brew install gitea/tap/gitea-mcp-server +# Installs to: /opt/homebrew/bin/gitea-mcp-server +``` -2. **Add to Zed Settings** - ```json - { - "context_servers": { - "tendril-gitea-mcp": { - "settings": { - "gitea_access_token": "your_token_here" - } - } - } - } - ``` +**Linux:** +```bash +# Download from: https://gitea.com/gitea/gitea-mcp/releases +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 +``` -3. **Install gitea-mcp Binary** (choose one method) - - Dowload binary - - Build from source - - Docker container +**Or use Docker** (requires Docker installed) -**More help:** Check README.md or run `zed: open log` for Zed logs +### 2. Get Gitea Access Token + +- Log in to your Gitea instance +- Settings → Applications → Generate New Token +- Copy the token + +### 3. Configure Zed (Cmd/Ctrl + ,) + +**Find your binary path:** `which gitea-mcp-server` or `which docker` + +Add `gitea_mcp_binary_path` (or `use_docker: true` + `docker_binary_path`) + +**More help:** See full README.md in extension directory \ No newline at end of file diff --git a/src/mcp_server_gitea.rs b/src/mcp_server_gitea.rs index 52c6c04..8ba4b3b 100644 --- a/src/mcp_server_gitea.rs +++ b/src/mcp_server_gitea.rs @@ -39,6 +39,8 @@ struct GiteaContextServerSettings { #[serde(default)] use_docker: Option, #[serde(default)] + docker_binary_path: Option, + #[serde(default)] docker_image: Option, } @@ -188,8 +190,8 @@ fn build_binary_command(settings: &GiteaContextServerSettings) -> Result Result { - // Find docker binary - MUST have a full path for Zed's Command struct - let docker_cmd = find_docker_binary()?; + // Find docker binary - explicit path required + let docker_cmd = find_docker_binary(settings)?; // Use configured docker image or default let docker_image = settings @@ -238,12 +240,37 @@ fn build_docker_command(settings: &GiteaContextServerSettings) -> Result Result { - // Just return "docker" - the system will find it in PATH - // If docker isn't installed or not in PATH, the execution will fail with a clear error - Ok("docker".to_string()) +/// +/// WASM Limitation: Cannot access PATH reliably, so explicit configuration is required +/// when use_docker is true. +fn find_docker_binary(settings: &GiteaContextServerSettings) -> Result { + if let Some(path) = &settings.docker_binary_path { + return Ok(path.clone()); + } + + // No explicit docker path - return error with instructions + Err("Docker binary path not configured.\n\ + \n\ + When using Docker mode, you must specify the docker binary path:\n\ + \n\ + {\n\ + \"context_servers\": {\n\ + \"tendril-gitea-mcp\": {\n\ + \"settings\": {\n\ + \"gitea_access_token\": \"your_token\",\n\ + \"use_docker\": true,\n\ + \"docker_binary_path\": \"/usr/bin/docker\"\n\ + }\n\ + }\n\ + }\n\ + }\n\ + \n\ + Common paths:\n\ + • macOS: /usr/local/bin/docker or /Applications/Docker.app/Contents/Resources/bin/docker\n\ + • Linux: /usr/bin/docker\n\ + \n\ + Find your docker path with: which docker" + .into()) } /// Resolve the gitea-mcp binary path