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

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