Add Experimental MCP Support

[st0012]

Add Model Context Protocol (MCP) support to Ruby LSP

This PR adds support for the Model Context Protocol (MCP), enabling AI assistants to programmatically access Ruby project indexes and file contents that Ruby LSP already collects.

Connection Mechanism

The implementation uses a hybrid approach:

1. Ruby LSP runs an HTTP-based MCP server powered by WEBrick on a dynamically assigned local port
2. A lightweight stdio-to-HTTP bridge script (ruby-mcp-bridge) connects the editor's MCP client to our HTTP server
3. Communication flows bidirectionally between AI assistants and the Ruby project's metadata

Architecture Diagram

Editor Setup

VS Code Configuration

Add to .vscode/mcp.json:

{
  "inputs": [],
  "servers": {
    "rubyMcp": {
      "type": "stdio",
      "command": "${workspaceFolder}/.ruby-lsp/ruby-mcp-bridge"
    }
  }
}

See VS Code MCP documentation for more details.

Cursor Configuration

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "rubyMcp": {
      "command": "./.ruby-lsp/ruby-mcp-bridge"
    }
  }
}

See Cursor MCP documentation for more details.

Notes For Manual Testing

This feature requires both the extension and server changes to work. So for testing:

1. Run the extension with the subject project
2. Update the subject project's Gemfile to have gem "ruby-lsp", github: "Shopify/ruby-lsp", branch: "mcp"
3. Make sure the server is connected to the respective editors. When connected, the editor should display what tools are available
4. In both editors, MCP servers are only used in "Agent" mode
5. For VS Code, tool usage needs to be selected manually at each prompt

Known Issues

⚠️ Cursor-specific issue: We've identified that Cursor's MCP/LSP client implementation can occasionally cause hangs in the Ruby LSP process. The main thread gets stuck waiting on gets in the LSP communication channel. This issue may be specific to Cursor as it doesn't occur (or occurs much less frequently) in VS Code, and more often in certain projects (e.g. ruby/irb) than others. The cause may be related to how Cursor handles MCP/LSP requests and requires more investigation.

Supported Tools (TBD)

The MCP server provides four tools:

1. get_classes_and_modules - Browse all indexed classes and modules in your project, with optional query filtering
2. read_ruby_files - Access file contents, including from dependencies
   • I removed this because clients usually would ask additional permission to read files outside of the workspace, and Ruby MCP should not provide a way to get around that.
3. get_methods_details - Get comprehensive information about methods (documentation, parameters, location, visibility)
4. get_class_module_details - See class/module details including documentation, ancestry chains, and available methods

These tools enable AI assistants to understand Ruby code structure, navigate dependencies, and access relevant documentation that are not accessible through the editor's simple codebase indexing.

[graphite-app]

How to use the Graphite Merge Queue

Add the label graphite-merge to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

[andyw8]

Some early notes on how to try this with Zed:

• Check out this branch locally (as a small modification is needed) and point your project's Gemfile to it.

• Manually copy ruby-mcp-bridge into .ruby-lsp in your project (ensure it retains the +x permission) since we can't rely on the VS Code extension (a Zed extension should be fairly easy though).

• Configure the project settings:

  // .zed/settings.json
  {
    "context_servers": {
      "mcp-servers-ruby-lsp": {
        "command": {
          "path": "/path/to/project/.ruby-lsp/ruby-mcp-bridge", // seems to need an absolute path
          "args": []
        },
      }
    }

Modify global_state.rb in Ruby LSP to make it Zed-aware:

def detects_ruby_mcp
  check_mcp_file(".vscode/mcp.json", ["servers", "rubyMcp"]) ||
    check_mcp_file(".cursor/mcp.json", ["mcpServers", "rubyMcp"]) ||
    check_mcp_file(".zed/settings.json", ["context_servers", "mcp-servers-ruby-lsp"])
end

Reload Zed, choose Tools in the Agent panel and if all well you should see get_classes_and_modules etc. listed:

[Prajjwal]

Nit: Do we want to use #!/bin/sh instead? Not a huge problem, almost everyone will have bash and then you don't need to worry about compatibility across shells.

[Prajjwal]

At the very least, I would set -eu here to make the script safer.

[Prajjwal]

A bit hard to read and the && introduces an extra failure mode. Maybe SCRIPT_DIR=$(realpath $(dirname ${BASH_SOURCE[0]}))?

[Prajjwal]

LOG_FILE for name consistency with PORT_FILE?

[Prajjwal]

Should this be "http://127.0.0.1:$PORT/mcp" 2>$LOG_PATH) || {, my understanding is that 2> would clobber the file and erase old logs.

[Prajjwal]

We should wrap this in an ensure, or we're skipping cleanup on errors.