tendril/README.md

# Tendril: Gitea MCP for Zed

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 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 - 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
3. **Gitea Access Token** - Generated from your Gitea instance
4. **Rust** (for dev installation) - Installed via rustup

## Quick Start

### Step 1: Install Gitea MCP Server

Choose one method:

#### Option A: macOS (Homebrew - Recommended)

```bash
brew install gitea/tap/gitea-mcp-server
```

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
# 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
```

#### Option C: Build from Source

```bash
git clone https://gitea.com/gitea/gitea-mcp.git
cd gitea-mcp
make install
```

#### Option D: Use Docker

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** → **Generate New Token**
3. Give it a name like "Zed MCP"
4. Select repository-related permissions
5. Copy the token

### Step 3: Install Tendril 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

### Step 4: Configure Zed Settings

Open your Zed settings (Cmd/Ctrl + ,) and add one of the following configurations:

#### For Local Binary (macOS with Homebrew):

```json
{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_GITEA_TOKEN_HERE",
        "gitea_mcp_binary_path": "/opt/homebrew/bin/gitea-mcp-server"
      }
    }
  }
}
```

#### For Local Binary (Linux):

```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
{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_GITEA_TOKEN_HERE",
        "use_docker": true,
        "docker_binary_path": "/usr/bin/docker"
      }
    }
  }
}
```

**Note**: Find your docker path with `which docker` and use that full path.

### Step 5: Test the Connection

In Zed's Assistant panel, try:

```
list my repositories
```

You should see your Gitea repositories!

## Configuration Reference

### Required Settings

| Setting | Type | Description |
|---------|------|-------------|
| `gitea_access_token` | string | Your Gitea personal access token |

### 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_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`) |

**Finding binary paths:**
- gitea-mcp: `which gitea-mcp` or `which gitea-mcp-server`
- docker: `which docker`

## Configuration Examples

### Self-Hosted Gitea with Binary

```json
{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_TOKEN",
        "gitea_host": "https://git.example.com",
        "gitea_mcp_binary_path": "/usr/local/bin/gitea-mcp"
      }
    }
  }
}
```

### Self-Hosted Gitea with Docker

```json
{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_TOKEN",
        "gitea_host": "https://git.example.com",
        "use_docker": true,
        "docker_binary_path": "/usr/bin/docker"
      }
    }
  }
}
```

### Self-Signed Certificates

```json
{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_TOKEN",
        "gitea_host": "https://git.internal.company.com",
        "gitea_insecure": true,
        "gitea_mcp_binary_path": "/usr/local/bin/gitea-mcp"
      }
    }
  }
}
```

**Security Note**: Only use `gitea_insecure: true` for trusted internal servers.

### Custom Docker Image

```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"
      }
    }
  }
}
```

## Available Features

Through the Gitea MCP server, you get access to:

- **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

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
   ls -la /opt/homebrew/bin/gitea-mcp-server
   ```

2. **Ensure it's executable:**
   ```bash
   chmod +x /opt/homebrew/bin/gitea-mcp-server
   ```

3. **Test it manually:**
   ```bash
   /opt/homebrew/bin/gitea-mcp-server --help
   ```

4. **Restart Zed** after fixing permissions

### Authentication Issues

- 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

### Docker Issues

If using `use_docker: true` and seeing errors:

1. **Find your docker binary path:**
   ```bash
   which docker
   # Output: /usr/bin/docker (use this in docker_binary_path)
   ```

2. **Check Docker is running:**
   ```bash
   docker ps
   ```

3. **Verify Docker can pull images:**
   ```bash
   docker pull gitea/gitea-mcp-server:latest
   ```

4. **On Linux, check permissions:**
   ```bash
   sudo usermod -aG docker $USER
   # Log out and back in
   ```

**Common Docker paths:**
- Linux: `/usr/bin/docker`
- macOS: `/usr/local/bin/docker` or `/Applications/Docker.app/Contents/Resources/bin/docker`

### View Logs

Check Zed logs for detailed error messages:

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

### Building from Source

Prerequisites:
- Rust (installed via rustup)
- WASM target: `rustup target add wasm32-unknown-unknown`

Build the extension:

```bash
cd tendril
cargo build --target wasm32-unknown-unknown --release
cp target/wasm32-unknown-unknown/release/mcp_server_gitea.wasm extension.wasm
```

### Project Structure

```
tendril/
├── Cargo.toml                          # Rust project configuration
├── extension.toml                      # Zed extension manifest
├── src/
│   └── mcp_server_gitea.rs            # Main extension logic
├── configuration/
│   ├── 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
└── LICENSE                             # Apache 2.0
```

### Code Overview

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

- **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 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)
   - [Gitea MCP](https://gitea.com/gitea/gitea-mcp)
   - [Model Context Protocol](https://modelcontextprotocol.io)

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on:

- Development workflow
- Branch management
- Documentation standards
- Code quality requirements
- Pull request process

**Quick Start:**
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/your-feature-name`
3. Make your changes and test thoroughly
4. Submit a pull request with a clear description

For full details, see [CONTRIBUTING.md](CONTRIBUTING.md).

## Authors

- Ryan Parmeter ([@parkingmeter](https://git.parkingmeter.info/parkingmeter))
- The Mycelium Project Contributors

## Changelog

### v0.2.0 (Current)

- 🔧 **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.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