tendril/PROJECT_STATUS.md

Tendril Project Status & Setup Guide

🎯 Current Status: v0.1.0 - Feature Complete

Version: 0.1.0 (Development)
Last Updated: Current Session
Build Status: ✅ Compiling successfully
Features: ✅ Binary path resolution, Docker support, cross-platform detection

This document summarizes the current state of the Tendril project and provides setup instructions.

✅ What's Been Completed

Phase 1: Core Extension (v0.0.1)

• ✅ Recovered all source files from previous repository
• ✅ Reorganized project structure for clarity
• ✅ Renamed extension to "tendril-gitea-mcp"
• ✅ Updated branding to "The Mycelium Project"
• ✅ Code compiles to valid WASM without errors
• ✅ STDIO mode implementation complete

Phase 2: Flexible Binary Discovery (v0.1.0) - JUST COMPLETED

• ✅ Removed hardcoded binary path /usr/local/bin/gitea-mcp
• ✅ Implemented intelligent binary path resolution with fallbacks:
  • Explicit user configuration (gitea_mcp_binary_path)
  • /usr/local/bin/gitea-mcp
  • ~/.local/bin/gitea-mcp
  • ~/.cargo/bin/gitea-mcp
  • /opt/homebrew/bin/gitea-mcp (macOS M-series)
  • System PATH search
• ✅ Cross-platform support (Linux, macOS, Windows)
• ✅ Comprehensive error messages with troubleshooting steps

Phase 2: Docker Support (v0.1.0) - JUST COMPLETED

• ✅ Added use_docker configuration option
• ✅ Added docker_image configuration option (with sensible default)
• ✅ Implemented Docker command builder with proper argument passing
• ✅ Environment variable passing to Docker containers
• ✅ STDIN/STDOUT support through Docker
• ✅ Proper container cleanup (--rm flag)

Documentation (Updated for v0.1.0)

• ✅ README.md: Completely updated with binary path resolution and Docker examples
• ✅ DEVELOPMENT.md: Comprehensive developer guide with architecture and roadmap
• ✅ installation_instructions.md: Concise setup guide for Zed UI
• ✅ default_settings.jsonc: Well-documented configuration template with all new options
• ✅ PROJECT_STATUS.md: This file

📋 Project Files

tendril/
├── Cargo.toml                          # Rust project manifest
├── extension.toml                      # Zed extension manifest
├── src/
│   └── mcp_server_gitea.rs            # Extension implementation (~350 lines)
│                                       # - Binary path resolution
│                                       # - Docker support
│                                       # - Settings management
├── configuration/
│   ├── default_settings.jsonc         # Settings template with all options
│   └── installation_instructions.md   # Quick setup guide
├── README.md                           # Main documentation (500+ lines)
├── DEVELOPMENT.md                      # Dev guide & architecture (550+ lines)
├── PROJECT_STATUS.md                   # This file
├── LICENSE                             # Apache 2.0
└── ZedExtensions.md                    # Research notes

🚀 Getting Started (Dev Extension Setup)

Prerequisites

You need:

1. Zed IDE - Download from https://zed.dev
2. Rust - Installed via rustup (required for dev extensions)
3. Gitea Access Token - From your Gitea instance
4. gitea-mcp - Either:
   • Binary installed on your system, OR
   • Docker (to use containerized mode)

Step 1: Install Gitea MCP Binary (Choose One Method)

Option A: Download Pre-built Binary

# Linux x86_64
wget https://gitea.com/gitea/gitea-mcp/releases/download/v1.0.0/gitea-mcp-linux-amd64
sudo chmod +x gitea-mcp-linux-amd64
sudo mv gitea-mcp-linux-amd64 /usr/local/bin/gitea-mcp

# macOS Intel
wget https://gitea.com/gitea/gitea-mcp/releases/download/v1.0.0/gitea-mcp-darwin-amd64
sudo chmod +x gitea-mcp-darwin-amd64
sudo mv gitea-mcp-darwin-amd64 /usr/local/bin/gitea-mcp

# macOS M-series
wget https://gitea.com/gitea/gitea-mcp/releases/download/v1.0.0/gitea-mcp-darwin-arm64
sudo chmod +x gitea-mcp-darwin-arm64
sudo mv gitea-mcp-darwin-arm64 /usr/local/bin/gitea-mcp

Option B: Build from Source

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

Option C: Use Docker (Skip Binary Installation) If you have Docker installed, skip binary installation and configure Docker mode in step 4.

Verify installation:

/usr/local/bin/gitea-mcp --help

Or if using a different location, test it there instead.

Step 2: Generate Gitea Access Token

1. Log in to your Gitea instance
2. Go to Settings → Applications → Authorize New Application
3. Give it a name (e.g., "Zed MCP")
4. Select repository-related permissions
5. Click Authorize and copy the token

Step 3: Install Tendril as Dev Extension

1. Open Zed
2. Go to Extensions
   • Press Cmd+K and type "Extensions"
   • Or click Extensions icon in left sidebar
3. Click "Install Dev Extension"
4. Select the tendril directory
   • Navigate to where you cloned this repository
5. Zed will compile and load the extension
   • You should see "Tendril: Gitea MCP" in your extensions list

Step 4: Configure Zed Settings

1. Open Settings
   • Press Cmd+, or go to Settings → Open Settings
2. Add to your settings.json:

Basic Setup (Auto-detects Binary):

{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_GITEA_TOKEN_HERE"
      }
    }
  }
}

Using Docker Instead:

{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_GITEA_TOKEN_HERE",
        "use_docker": true
      }
    }
  }
}

For Self-Hosted Gitea:

{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_GITEA_TOKEN_HERE",
        "gitea_host": "https://git.example.com",
        "gitea_insecure": false
      }
    }
  }
}

With Custom Binary Path:

{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_GITEA_TOKEN_HERE",
        "gitea_mcp_binary_path": "/path/to/gitea-mcp"
      }
    }
  }
}

Step 5: Test the Connection

1. Open Zed's Assistant panel
   • Press Cmd+K or click Assistant icon
2. Try a command:

   list my repositories
   

3. You should see your Gitea repositories listed

If it works, you're all set! ✨

🔄 What's New in v0.1.0

Major Features Added

1. Intelligent Binary Path Resolution

   • No longer hardcoded to /usr/local/bin/gitea-mcp
   • Automatically searches multiple common locations
   • Platform-aware (detects macOS M-series, Windows paths, etc.)
   • User-configurable via gitea_mcp_binary_path setting
   • Helpful error messages if binary not found

2. Docker Support

   • New use_docker setting to enable Docker mode
   • New docker_image setting for custom Docker images
   • Automatic Docker command generation
   • Environment variables properly passed to container
   • Works seamlessly with STDIO mode

3. Cross-Platform Support

   • Linux: Standard paths + ~/.local/bin + ~/.cargo/bin
   • macOS Intel: Standard paths + /opt/homebrew/bin consideration
   • macOS M-series: Optimized for /opt/homebrew/bin/gitea-mcp
   • Windows: Program Files paths (code ready, untested)

Configuration Enhancements

New settings available:

• gitea_mcp_binary_path - Explicit path to binary (optional)
• use_docker - Enable Docker mode (optional, default: false)
• docker_image - Custom Docker image (optional, default: gitea/gitea-mcp:latest)

All settings documented in configuration/default_settings.jsonc

Documentation Improvements

• README.md: 500+ lines with examples for all modes
• DEVELOPMENT.md: 550+ lines with complete architecture and roadmap
• installation_instructions.md: Concise UI-friendly guide
• default_settings.jsonc: Extensive inline documentation

⚠️ Known Issues & Limitations

Current Limitations (Before v1.0)

1. SSE Mode Not Supported

   • Only STDIO mode is currently supported
   • SSE mode would require Zed to support HTTP context servers
   • Future enhancement when Zed API adds this capability
   • See: https://github.com/zed-industries/zed/discussions/29370

2. Docker Image Management

   • No automatic image updates
   • Assumes Docker can pull from public registries
   • Custom registries require Docker authentication setup
   • Large images may take time to download on first use

3. Windows Testing

   • Code includes Windows paths but not tested on actual Windows
   • Binary path resolution should work but needs verification
   • Docker support should work but untested

4. No Configuration Wizard

   • Settings must be edited manually in settings.json
   • No interactive setup prompts yet
   • Goal for future version: add UI-based configuration

Troubleshooting

"gitea-mcp binary not found" Error

# Install to standard location
sudo mv gitea-mcp /usr/local/bin/gitea-mcp
sudo chmod +x /usr/local/bin/gitea-mcp

# Or configure explicit path in settings
"gitea_mcp_binary_path": "/path/to/gitea-mcp"

# Or use Docker
"use_docker": true

"Failed to spawn command" Error

# Make binary executable
chmod +x /usr/local/bin/gitea-mcp

# Test it manually
/usr/local/bin/gitea-mcp --help

# Restart Zed

Authentication/Token Issues

• Verify token has repository permissions
• Check token hasn't expired
• Copy entire token without extra spaces
• Restart Zed after changing settings

Docker Issues

• Ensure Docker is installed and running
• Try pulling image manually: docker pull gitea/gitea-mcp:latest
• Check Docker logs for errors

🔍 What's Next (High Priority for v0.2.0)

Testing & Validation

• Test with actual Gitea instances (various versions)
• Test binary discovery on multiple systems
• Test Docker mode on Linux, macOS, Windows
• Test with self-hosted Gitea instances
• Test with different token permissions
• Validate error messages are helpful
• Performance testing with large repositories

User Experience Improvements

• Interactive configuration wizard
• Settings validation with helpful errors
• Status diagnostic commands
• Better error messages with context
• Optional configuration UI helpers

Documentation & Release

• Troubleshooting video
• FAQ section
• Contributing guidelines
• Version bump to 1.0.0 when stable
• Submit to Zed marketplace

Platform Testing Matrix

✓ Linux (expected to work - most tested during development)
? macOS Intel (needs testing)
? macOS M-series (code ready, needs testing with actual M4 Mac)
? Windows (code ready, needs testing)

✓ Binary mode (expected to work)
✓ Docker mode (needs testing across platforms)

📊 Build & Development

Building the Extension

# Full release build
cargo build --release

# Quick debug build
cargo build

# Check for issues without building
cargo check

# Lint code
cargo clippy

Development Workflow

1. Make changes to src/mcp_server_gitea.rs or configuration files
2. Run cargo build --release
3. Reload extension in Zed (or restart Zed)
4. Test changes in Assistant panel

Debug Logging

# Start Zed with verbose logging
zed --foreground

# Watch gitea-mcp server logs
tail -f ~/.gitea-mcp/gitea-mcp.log

# View Zed logs
# In Zed: zed: open log

📚 Documentation

All documentation has been updated for v0.1.0:

• README.md - Main user guide with all configuration options
• DEVELOPMENT.md - Developer guide, architecture, and roadmap
• installation_instructions.md - Quick setup guide (shown in Zed UI)
• configuration/default_settings.jsonc - Configuration template with comments
• PROJECT_STATUS.md - This file (status and getting started)

🔗 Resources

• Zed Extension Docs: https://zed.dev/docs/extensions
• Gitea MCP Repository: https://gitea.com/gitea/gitea-mcp
• Model Context Protocol: https://modelcontextprotocol.io
• The Mycelium Project: https://git.parkingmeter.info/Mycelium
• Gitea Docs: https://docs.gitea.io
• Docker Docs: https://docs.docker.com

📞 Support & Contributing

For Issues

1. Check troubleshooting sections in README.md or DEVELOPMENT.md
2. Check Zed logs: zed: open log
3. Check gitea-mcp logs: tail -f ~/.gitea-mcp/gitea-mcp.log
4. Open an issue on the repository

For Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes and test locally
4. Run cargo build --release && cargo clippy
5. Submit a pull request with a clear description

📋 Testing Checklist Before v1.0.0 Release

Platform Testing

• Test on Linux x86_64
• Test on macOS Intel
• Test on macOS M-series (ARM64)
• Test on Windows (if possible)

Feature Testing

• Binary auto-discovery works
• Custom binary path works
• Docker mode works
• Custom Docker image works
• Self-hosted Gitea works
• Self-signed certificates work
• Token validation works
• All error messages are clear and helpful

Error Scenarios

• Binary not found → helpful error with options
• Invalid token → clear error message
• Docker not installed → suggestion to install or use binary
• Wrong binary path → error with suggestion
• Network issues → clear error with context

Documentation

• README covers all common scenarios
• DEVELOPMENT guide is comprehensive
• Configuration examples are clear
• Troubleshooting section is helpful
• All new features are documented

👥 Version History

v0.1.0 (Current - Just Released)

• ✨ Flexible binary path resolution with intelligent fallbacks
• ✨ Docker support for containerized deployment
• ✨ Cross-platform binary detection
• 🐛 Improved error messages with troubleshooting guidance
• 📚 Comprehensive documentation updates

v0.0.1 (Previous)

• Initial development version
• Hardcoded binary path to /usr/local/bin/gitea-mcp
• STDIO mode support
• Basic configuration through settings.json

📄 License

Licensed under the Apache License 2.0. See LICENSE file for full details.

👥 Authors

• Ryan Parmeter (@parkingmeter)
• The Mycelium Project Contributors

---

✨ Quick Links

• Get Started: Follow "Getting Started" section above
• Main Documentation: See README.md
• Developer Guide: See DEVELOPMENT.md
• Configuration Help: See configuration/default_settings.jsonc
• Issues/Questions: Open an issue on the repository

To get started right now: Follow the "Getting Started" section above to install the dev extension!