matlab-lsp-server 0.2.9

Lightweight Language Server Protocol implementation for MATLAB

LSP MATLAB Server

A lightweight, fast, and cross-platform Language Server Protocol (LSP) implementation for MATLAB files.

Version: 0.2.3 | License: MIT | Python: 3.10+

📖 See INTEGRATION.md for detailed editor configuration guides and advanced options.

---

Quick Install

pip install matlab-lsp-server

That's it! The server is now ready to use.

For detailed editor integration guides and advanced configuration, see INTEGRATION.md.

Command-Line Options

# Run in stdio mode (for LSP clients)
matlab-lsp --stdio

# Run in TCP mode (for debugging)
matlab-lsp --tcp --port 4389

# Enable verbose logging
matlab-lsp --stdio --verbose

# Disable automatic config creation
matlab-lsp --stdio --no-init-config

Options:

• --stdio - Run in stdio mode (default for LSP clients)
• --tcp - Run in TCP mode (for debugging)
• --port PORT - Port for TCP mode (default: 4389)
• --host HOST - Host for TCP mode (default: 127.0.0.1)
• -v, --verbose - Enable verbose logging
• --no-init-config - Disable automatic .matlab-lsprc.json creation
• --version - Show version information

Configuration Methods

You can configure the server in multiple ways (priority order):

1. Editor Settings (highest) - Pass settings via LSP client
2. Config File - .matlab-lsprc.json in project root
3. Environment Variables - MATLAB_PATH
4. Auto-Discovery - Automatically finds MATLAB in standard locations

Quick Editor Configuration

VS Code (.vscode/settings.json):

{
  "languageserver": {
    "matlab": {
      "command": "python",
      "args": ["matlab-lsp", "--stdio"],
      "filetypes": ["matlab", "m"],
      "rootPatterns": [".git", ".matlab-lsprc.json"]
    }
  }
}

Neovim (nvim-lspconfig):

require('lspconfig').matlab_lsp_server.setup({
  cmd = {'matlab-lsp'},
  filetypes = {'matlab', 'm'},
  root_dir = require('lspconfig.util').root_pattern('.git', '.matlab-lsprc.json', 'project.m')
})

Vim (vim-lsp):

" .vimrc
autocmd BufRead,BufNewFile *.m set filetype=matlab

if executable('python')
  au User lsp_setup call lsp#register_server({
    \ 'name': 'matlab-lsp',
    \ 'cmd': {'matlab-lsp'},
    \ 'whitelist': ['matlab', 'm']
    \ })
endif

Emacs (lsp-mode):

;; init.el
(use-package lsp-mode
  :config
  (lsp-register-client
    (make-lsp-client
      :new-connection (lsp-stdio-connection "matlab-lsp")
      :major-modes '(matlab-mode)
      :server-id 'matlab-lsp)))

(use-package matlab-mode
  :config
  (add-hook 'matlab-mode-hook #'lsp))

TUI Crush (.crush.json):

{
  "lsp": {
    "matlab": {
      "command": "matlab-lsp",
      "args": ["--stdio"],
      "filetypes": ["matlab", "m"],
      "root_markers": [".git", ".matlab-lsprc.json", "project.m"]
    }
  }
}

OpenCode CLI (.opencode.json):

{
  "lsp": {
    "matlab": {
      "command": "matlab-lsp",
      "args": ["--stdio"],
      "extensions": [".m"]
    }
  }
}

Claude Code LSP / cclsp (cclsp.json):

{
  "servers": [
    {
      "extensions": ["m"],
      "command": "matlab-lsp",
      "args": ["--stdio"],
      "rootDir": "."
    }
  ]
}

See INTEGRATION.md for detailed configuration and advanced options.

---

Why This Over Official MathWorks LSP?

Feature	This Server	MathWorks LSP
Lightweight	Pure Python, no Java required	Java-based, heavy
Startup Time	< 1 second	5-10 seconds
Memory Usage	~50MB	500MB+
MATLAB Required	Optional (standalone analyzer)	Required
Configuration	Simple JSON file	Complex JSON/registry
Cross-Platform	Windows, Linux, macOS	Windows only
Customization	Fully configurable	Limited

Key Advantages:

1. Fast & Lightweight - Starts instantly, uses minimal resources
2. No MATLAB Dependency - Works with standalone analyzer when MATLAB isn't installed
3. Cross-Platform - Works on Windows, Linux, and macOS
4. Simple Setup - One pip install and you're done
5. Flexible - Highly configurable with JSON config file
6. Open Source - MIT licensed, community-driven

---

Features

Core LSP Features

• Code Completion - Smart suggestions for functions, variables, and classes
• Hover Documentation - Show function signatures and documentation inline
• Go to Definition - Jump to function/class definitions instantly
• Find References - Locate all usages of symbols
• Document Symbols - Outline view of your code structure
• Workspace Symbols - Search symbols across entire project
• Code Formatting - Auto-format MATLAB code with configurable style
• Diagnostics - Real-time error and warning detection
• Quick Fixes - Automatic suggestions for common issues

MATLAB Support

• Regex Parser - Fast and robust MATLAB syntax parsing
• Function Extraction - Extract all function definitions
• Class Parsing - Support for classdef, properties, methods
• Nested Functions - Handle nested and local functions
• Variable Tracking - Track global and persistent variables
• Comment Extraction - Parse documentation from comments

Performance

• LRU Caching - Fast symbol lookups with O(1) complexity
• Debouncing - Optimized document analysis
• In-Memory Index - Quick project-wide symbol search
• Async Operations - Non-blocking diagnostics and analysis

For complete feature documentation and configuration options, see INTEGRATION.md.

---

Quick Start

1. Install

# Using pip (recommended)
pip install matlab-lsp-server

# Or from source
git clone https://github.com/yourusername/matlab_lsp_server.git
cd matlab_lsp_server
pip install -e .

2. Configure Your Editor

TUI Crush

Create or edit ~/.crush.json:

{
  "lsp": {
    "matlab": {
      "command": "matlab-lsp",
      "args": ["--stdio"],
      "filetypes": ["m"],
      "root_markers": [".git", ".matlab-lsprc.json"]
    }
  }
}

VS Code

Create .vscode/settings.json:

{
  "languageserver": {
    "matlab": {
      "command": "python",
      "args": ["-m", "matlab_lsp_server.server", "--stdio"],
      "filetypes": ["matlab", "m"],
      "rootPatterns": [".git", ".matlab-lsprc.json"]
    }
  }
}

Or install the MATLAB extension and configure it to use this server.

Neovim

Add to init.lua or init.vim:

require('lspconfig').matlab_lsp.setup({
  cmd = {"matlab-lsp", "--stdio"},
  filetypes = {"matlab", "m"},
  root_dir = require('lspconfig.util').root_pattern(
    ".git", ".matlab-lsprc.json"
  ),
})

3. Open a MATLAB File

Open any .m file in your editor. The LSP server will automatically start and provide:

• Syntax error highlighting
• Code completion
• Hover documentation
• Go-to-definition
• And more!

For more editor configurations (Emacs, Vim, OpenCode, cclsp), see INTEGRATION.md.

---

Configuration

Copy the example configuration file to your project root:

cp .matlab-lsprc.json.example .matlab-lsprc.json

Note: The server automatically creates .matlab-lsprc.json with default settings on first run if it doesn't exist. You can skip this step and edit the auto-generated file later.

Then edit .matlab-lsprc.json with your settings:

What happens if matlabPath stays empty?

• Server starts normally without errors
• Basic LSP features work (completion, hover, go to definition, etc.)
• Diagnostics from MATLAB's mlint analyzer will be unavailable
• Server tries to find MATLAB in standard locations
• Server logs a warning: "MlintAnalyzer is NOT available!"

Auto-Discovery on First Run: On first startup, the server automatically searches for MATLAB in:

1. System PATH (recursive search, finds even in bin/win64/)
2. Standard installation paths:
   • Windows: C:/Program Files/MATLAB, D:/Program Files/MATLAB, etc.
   • macOS: /Applications/MATLAB_R*.app
   • Linux: /usr/local/MATLAB, /opt/MATLAB, ~/MATLAB
3. If found, matlabPath is auto-filled in .matlab-lsprc.json

To enable full diagnostics:

1. Set matlabPath in .matlab-lsprc.json
2. Or set MATLAB_PATH environment variable
3. Or ensure MATLAB is in system PATH

Handling MATLAB Reinstallation: If you reinstall MATLAB to a different location:

• Server will detect the old path is invalid
• Automatically searches for new MATLAB location
• Falls back to basic LSP features if MATLAB not found
• Update matlabPath in config to specify new location

{
  "matlabPath": "C:/Program Files/MATLAB/R2023b"
}

That's it! All other settings use sensible defaults. For more configuration options, see INTEGRATION.md.

Environment Variables

You can also configure using environment variables:

# MATLAB installation path
export MATLAB_PATH="C:/Program Files/MATLAB/R2023b"

---

Installation Methods

Method 1: pip install (Recommended)

pip install matlab-lsp-server
matlab-lsp --stdio

Method 2: Install from Source

git clone https://github.com/yourusername/matlab_lsp_server.git
cd matlab_lsp_server
pip install -e .
python server.py --stdio

Method 3: Download Release

1. Download from Releases
2. Extract the archive
3. Run: python server.py --stdio

---

Platform-Specific Notes

Windows

• Requires Python 3.10+
• MATLAB R2020b or later recommended for mlint integration
• Works with PowerShell, Command Prompt, Git Bash

Linux

• Requires Python 3.10+
• Tested on Ubuntu, Debian, Fedora
• MATLAB R2020b or later recommended
• Works with Octave's mlint alternative (experimental)

macOS

• Requires Python 3.10+ (from python.org or Homebrew)
• MATLAB R2020b or later recommended
• Tested on macOS 11+ (Big Sur and later)

---

Running the Server

stdio Mode (for LSP clients)

python server.py --stdio
# or
matlab-lsp --stdio

TCP Mode (for debugging)

python server.py --tcp --port 4389
# Connect with telnet or nc
telnet localhost 4389

Verbose Logging

python server.py --stdio --verbose

Show Version

python server.py --version
# Output: MATLAB LSP Server v0.2.3

---

Troubleshooting

"mlint not found"

1. Install MATLAB R2020b or later
2. Set MATLAB_PATH environment variable
3. Or configure in .matlab-lsprc.json
4. Server will use standalone analyzer (limited features)

"No diagnostics shown"

1. Check log level is set to INFO or DEBUG
2. Verify MATLAB path is correct
3. Try running server with --verbose

"Slow performance"

1. Enable caching (default: enabled)
2. Reduce maxSuggestions in config
3. Close unused documents
4. Use a fast disk (SSD recommended)

Get Debug Logs

# Use the --verbose flag
matlab-lsp --stdio --verbose

# Or from source
python server.py --stdio --verbose

For more troubleshooting tips and configuration options, see INTEGRATION.md.

---

Development

Project Structure

matlab_lsp_server/
├── server.py              # Main entry point
├── requirements.txt        # Dependencies
├── pyproject.toml        # Package config
├── src/
│   ├── protocol/         # LSP lifecycle handlers
│   ├── handlers/         # LSP method handlers
│   ├── parser/           # MATLAB parser
│   ├── analyzer/         # Code analyzers
│   ├── features/         # Feature management
│   └── utils/           # Utilities
└── tests/              # Unit and integration tests

Contributing

See CONTRIBUTING.md for guidelines.

Running Tests

# Install dev dependencies
pip install -r requirements-dev.txt

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test
pytest tests/unit/test_parser.py::test_parse_function

---

Documentation

• Installation Guide - Detailed installation instructions
• Architecture - Design decisions and structure
• Development - Developer guide
• Contributing - How to contribute
• CHANGELOG - Version history
• FAQ - Common issues and solutions

---

Version: 0.2.3

What's Included

• ✅ Full LSP implementation (9+ features)
• ✅ MATLAB parser (regex-based)
• ✅ Code completion with ranking
• ✅ Hover documentation
• ✅ Go-to-definition with cross-file support
• ✅ Find references
• ✅ Document symbols with hierarchy
• ✅ Workspace symbols with fuzzy search
• ✅ Code formatting with configurable style
• ✅ Diagnostics via mlint
• ✅ Quick fixes for common errors
• ✅ Cross-platform support (Windows, Linux, macOS)
• ✅ Standalone analyzer (no MATLAB required)
• ✅ LRU caching for performance
• ✅ Configurable via JSON or environment

Known Limitations

• .mlx files (Live Scripts) not supported
• Octave compatibility is experimental
• Some advanced MATLAB features may not be parsed correctly
• mlint required for full diagnostics (standalone analyzer is limited)

---

Requirements

Minimum

• Python 3.10 or higher
• 50MB RAM
• 10MB disk space

Recommended (for full features)

• MATLAB R2020b or later
• 100MB RAM
• 50MB disk space
• SSD drive for better performance

Optional

• MATLAB R2023b (for latest features)
• Git (for installation from source)

---

License

MIT License - See LICENSE file for details.

Author

Vladimir M. Funtikov

Links

• GitHub: https://github.com/vmfu/matlab_lsp_server
• PyPI: https://pypi.org/project/matlab-lsp-server/
• Issues: https://github.com/vmfu/matlab_lsp_server/issues

---

LSP MATLAB Server v0.2.3 Fast. Lightweight. Cross-Platform.