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

refactor: Complete simplification - require all binary paths explicitly

Browse Source 
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
This commit is contained in:
Ryan Parmeter
2025-11-10 21:45:08 -07:00
parent 0627ebe404
commit e6e1ef2144
4 changed files with 385 additions and 365 deletions
Download Patch File Download Diff File Expand all files Collapse all files

573
README.md
View File

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

85
configuration/default_settings.jsonc
View File

@@ -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)
//
// ============================================================================
}

49
configuration/installation_instructions.md
View File

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

43
src/mcp_server_gitea.rs
View File

@@ -39,6 +39,8 @@ struct GiteaContextServerSettings {
#[serde(default)]
use_docker: Option<bool>,
#[serde(default)]
docker_binary_path: Option<String>,
#[serde(default)]
docker_image: Option<String>,
}
@@ -188,8 +190,8 @@ fn build_binary_command(settings: &GiteaContextServerSettings) -> Result<Command
/// Build a command to run gitea-mcp in Docker
fn build_docker_command(settings: &GiteaContextServerSettings) -> Result<Command> {
// 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<Command
}
/// Find the docker binary
/// Returns "docker" and relies on the system's PATH to find it
/// This is more reliable across platforms than trying to detect docker location in WASM
fn find_docker_binary() -> Result<String> {
// 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<String> {
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