tendril/ZedExtensions.md

# Zed Extensions for BCOS

This document provides information about developing Zed extensions, with specific focus on Model Context Protocol (MCP) server extensions that will be used in the BCOS project.

## Extension Capabilities

Extensions can add the following capabilities to Zed:
- Languages
- Debuggers
- Themes
- Icon Themes
- Slash Commands
- MCP Servers (primary focus for BCOS)
## Developing an Extension Locally
Before starting to develop an extension for Zed, be sure to install Rust via rustup.

Rust must be installed via rustup. If you have Rust installed via homebrew or otherwise, installing dev extensions will not work.

When developing an extension, you can use it in Zed without needing to publish it by installing it as a dev extension.

From the extensions page, click the Install Dev Extension button (or the zed: install dev extension action) and select the directory containing your extension.

If you need to troubleshoot, you can check the Zed.log (zed: open log) for additional output. For debug output, close and relaunch zed with the zed --foreground from the command line which show more verbose INFO level logging.

If you already have a published extension with the same name installed, your dev extension will override it.

After installing the Extensions page will indicate that that the upstream extension is "Overridden by dev extension".

Pre-installed extensions with the same name have to be uninstalled before installing the dev extension. See #31106 for more.

## Directory Structure of a Zed Extension
A Zed extension is a Git repository that contains an extension.toml. This file must contain some basic information about the extension:

```
id = "my-extension"
name = "My extension"
version = "0.0.1"
schema_version = 1
authors = ["Your Name <you@example.com>"]
description = "My cool extension"
repository = "https://github.com/your-name/my-zed-extension"
```

In addition to this, there are several other optional files and directories that can be used to add functionality to a Zed extension. An example directory structure of an extension that provides all capabilities is as follows:
```
my-extension/
  extension.toml
  Cargo.toml
  src/
    lib.rs
  languages/
    my-language/
      config.toml
      highlights.scm
  themes/
    my-theme.json
```

## WebAssembly
Procedural parts of extensions are written in Rust and compiled to WebAssembly. To develop an extension that includes custom code, include a Cargo.toml like this:

```
[package]
name = "my-extension"
version = "0.0.1"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
zed_extension_api = "0.1.0"
```

Use the latest version of the zed_extension_api available on crates.io. Make sure it's still compatible with Zed versions you want to support.

In the src/lib.rs file in your Rust crate you will need to define a struct for your extension and implement the Extension trait, as well as use the register_extension! macro to register your extension:

```
use zed_extension_api as zed;

struct MyExtension {
    // ... state
}

impl zed::Extension for MyExtension {
    // ...
}

zed::register_extension!(MyExtension);
```

stdout/stderr is forwarded directly to the Zed process. In order to see println!/dbg! output from your extension, you can start Zed in your terminal with a --foreground flag.

# MCP Server Extensions
Model Context Protocol servers can be exposed as extensions for use in the Agent Panel.

## Defining MCP Extensions
A given extension may provide one or more MCP servers. Each MCP server must be registered in the extension.toml:

```
[context_servers.my-context-server]
```

Then, in the Rust code for your extension, implement the context_server_command method on your extension:

```
impl zed::Extension for MyExtension {
    fn context_server_command(
        &mut self,
        context_server_id: &ContextServerId,
        project: &zed::Project,
    ) -> Result<zed::Command> {
        Ok(zed::Command {
            command: get_path_to_context_server_executable()?,
            args: get_args_for_context_server()?,
            env: get_env_for_context_server()?,
        })
    }
}
```

This method should return the command to start up an MCP server, along with any arguments or environment variables necessary for it to function.

If you need to download the MCP server from an external source—like GitHub Releases or npm—you can also do that in this function.

## Available Extensions
An example Zed Extension for the Gitlab MCP is in `config/mcp/gitlab-mcp-zed/`.

For the BCOS project, we will develop a Gitea MCP Extension based on this example. This extension will integrate with our Gitea instance to provide seamless access to our repository from within the Zed IDE.

## BCOS-Specific Integration
For the BCOS project, MCP server extensions will be stored in `/config/mcp` according to our monorepo structure. This ensures proper versioning and access control for our development environment.

When developing MCP server extensions for BCOS, ensure they follow the project's security and automation guidelines documented in the technical specifications.

## Testing
To test the new MCP server extension, the user can install it as a dev extension in the Zed client application.