alexchow/dialectic

dialectic: A Language Server Protocol (LSP) MCP Server

Feature: Find All References

You like to do Find References for symbols like this...

Now Cursor Agent can do it too like this!

With typechecker/LSP support (and without needing to get the line number perfectly right either, which LLMs aren't so good at)

Feature: Go To Definition

You like to "Cmd+Click" to "Go to Definition" of a Symbol like this

Now Cursor Agent can do it too!

Quick notes:

You can run the project either with

go install github.com/alexchow/dialectic@latest
go run github.com/alexchow/dialectic@latest

Or by cloning and building the binary

git clone github.com/alexchow/dialectic
cd dialectic
go build -o dialectic .
./dialectic

Simple setup

Prerequisite: Golang 1.24. Follow the install steps for your OS.

This assumes you're already using LSP tools (to navigate the code yourself) inside Cursor. If you're not, please make sure one of the LSPs is working.

Clone the project then make sure it can run:

git clone github.com/alexchow/dialectic
cd dialectic
go run .

Golang project

// .cursor/mcp.json
{
  "mcpServers": {
    "Golang LSP": {
      "command": "go",
      "args": [
        "run",
        "github.com/alexchow/dialectic@latest",
        "--workspace",
        "/Users/path/to/your/project",
        "--lsp",
        "~/go/bin/gopls", // Or wherever your "gopls" binary is
        "--",
        "-mode=stdio"
      ],
      "env": {
          "LOG_LEVEL": "INFO",
          "LOG_FILE": "/tmp/terraform-dialectic-lsp-golang.log"
      }
    }
  }
}

Pyright project:

// .cursor/mcp.json
{
  "mcpServers": {
    "Pyright LSP": {
      "command": "go",
      "args": [
        "run",
        "github.com/alexchow/dialectic@latest",
        "--workspace",
        "/Users/path/to/your/project",
        "--lsp",
        "/opt/homebrew/bin/pyright-langserver",
        "--",
        "--stdio"
      ],
      "env": {
        "LOG_LEVEL": "INFO",
        "LOG_FILE": "/tmp/python-mcp-server-example.log'
      }
    }
  }
}

Sorbet (ruby):

{
  "mcpServers": {
    "Sorbet LSP": {
      "command": "go",
      "args": [
        "run",
        "github.com/alexchow/dialectic@latest",
        "--workspace",
        "/Users/path/to/your/project",
        "--lsp",
        "bundle",
        "--",
        "exec srb typecheck --lsp"
      ],
      "env": {
        "LOG_LEVEL": "INFO",
        "LOG_FILE": "/tmp/python-mcp-server-example.log'
      }
    }
  }
}

Remote SSH setup

If you use Cursor on a remote machine via SSH, the setup is now much simpler since Cursor 0.50.

Important: Since Cursor 0.50, MCP servers run directly on the remote machine when you're in a remote SSH session. This means you can use the same configuration as you would locally.

1. Install dialectic on your remote machine: Follow the same install steps as above, but on your remote machine.

2. Configure Cursor on your remote project: Use the same configuration as you would locally:

// .cursor/mcp.json in your remote project
{
  "mcpServers": {
    "Golang LSP": {
      "command": "go",
      "args": [
        "run",
        "github.com/alexchow/dialectic@latest",
        "--workspace",
        "/path/to/your/project/on/remote",
        "--lsp",
        "~/go/bin/gopls", // Or wherever gopls is installed on your remote
        "--",
        "-mode=stdio"
      ],
      "env": {
        "LOG_LEVEL": "DEBUG",
        "LOG_FILE": "/tmp/dialectic-mcp-golang.log"
      }
    }
  }
}

That's it! The MCP server will run directly on your remote machine, so you don't need any SSH tunneling or complex setups anymore.

Available Tools

• Hover Information
• Find References
• Goto Definition
• Get Diagnostics
• Apply Text Edits (precise edits across your codebase with LSP accuracy)
• CodeLens (list and execute)

Full Build Install

You can also clone and build the binary yourself.

1. Install Go: Follow your OS-specific instructions at golang.org

2. Clone and build dialectic:

   git clone github.com/alexchow/dialectic
   cd dialectic
   go build -o dialectic .
   # Try to run
   ./dialectic
   

3. Install Your Language Server: You need the LSP for your specific language installed separately (e.g., gopls, pyright, rust-analyzer, tsserver, sorbet, etc.). Find instructions for your language.

4. Configure Cursor: Add dialectic as an MCP Server in Cursor's settings (usually mcp.json in your project's .cursor directory. Or globally for all your Cursor windows, tho this is not ideal):

   // Example for Cursor's mcp.json (adapt key if necessary)
   "mcpServers": [
     {
       "name": "dialectic-mcp-lsp", // Or any name you like. Keep it short since there is a 60-char limit of MCP server name + tool.
       "command": "dialectic", // Assumes 'dialectic' is in your system PATH, or use the path to the built binary
       "args": [
         "--workspace", "/path/to/your/project",       // <<< ABSOLUTE path to your code
         "--lsp", "/path/to/your/language-server", // <<< ABSOLUTE path to LSP binary (use `which <lsp_command>`)
         "--", // Arguments below are passed directly to the LSP
         "--stdio" // Example LSP argument, check your LSP's docs
       ],
       "env": {
         "LOG_LEVEL": "INFO", // Optional: Use "DEBUG" for verbose logs
         "LOG_FILE": "/tmp/path/to/dialectic-mcp-server-your-lsp.log"
         // Add other ENV vars your LSP might need (e.g., GOPATH for gopls)
       }
     }
   ]
   

   • Important: Replace placeholders with absolute paths.
   • Use which your-language-server (e.g., which gopls) in your terminal to find the LSP path.
   • Check your specific LSP's documentation for required command-line arguments (after --) and environment variables (env).

Supported Languages

Actively tested with:

• gopls (Go)
• pyright (Python)
• tsserver (TypeScript)
• rust-analyzer (Rust)
• srb (Ruby Sorbet)

It should work with most other standard Language Servers too. File an issue if you encounter problems!

Status

⚠️ Pre-beta Quality ⚠️

This tool is under active development. Expect potential bugs and breaking changes. Feedback and contributions welcome!

Development

Interested in contributing?

1. Clone: git clone https://github.com/alexchow/dialectic.git && cd dialectic
2. Setup: ./setup.sh (Installs Go dependencies & required dev tools like gopls)
3. Test: go test ./... (Requires gopls in PATH, setup script handles this)
4. Build: go build
5. Run Locally: Configure Cursor (see Quick Start) to use the absolute path to your locally built dialectic binary instead of just dialectic. Remember to rebuild after changes.

Logging & Debugging

For debugging, set LOG_LEVEL to DEBUG in the env configuration. To see raw LSP JSON messages, add wire:DEBUG to the LOG_COMPONENT_LEVELS env variable (e.g., "LOG_LEVEL": "INFO", "LOG_COMPONENT_LEVELS": "wire:DEBUG").

Adding LOG_FILE with a path will write logs to that file while still printing to stderr.

Please include relevant logs when opening issues.

Roadmap

• Find references (find_references)
• Go to definition (goto_definition)
• Apply edit (apply_text_edit)
• Get diagnostics (get_diagnostics)
• Code lens (get_codelens, execute_codelens)
• Hover info (hover)
• Code actions / Quick Fixes
• Symbol Rename Tool
• Add LSP server configuration presets for common languages
• Make a more consistent and scalable API for tools (pagination, etc.)
• Create higher-level composite tools (e.g., "get info" combining diagnostics, hover, definition)

Attribution

This project is a fork of mcp-language-server by Phil Isaac. Thank you for your work.

This project utilizes edited code from Go Tools (gopls) for LSP protocol handling. See ATTRIBUTION file. It uses mcp-go for MCP communication.