MATLAB MCP Core Server v0.1.0

Author: agoldsbo

.copyright-ignore

@@ -0,0 +1,8 @@
+internal/adaptors/application/config/assets/version
+internal/adaptors/mcp/server/assets/**
+internal/wire/wire_gen.go
+licenses/**
+mocks/**
+go.sum
+SECURITY.md
+*.pem

.gitattributes

@@ -1,2 +1,3 @@
+# Copyright 2025 The MathWorks, Inc.
 # Auto detect text files and perform LF normalization
 * text=auto

.gitignore

@@ -0,0 +1,3 @@
+/.bin
+/cover.out
+/vendor

.golangci.yml

@@ -0,0 +1,77 @@
+# Copyright 2025 The MathWorks, Inc.
+version: "2"
+
+linters:
+  default: standard
+  enable:
+    - revive # Comprehensive Go linter with extensive rules
+    - gosec # Security scanner for Go code
+    - govet # Go static analyzer for common errors
+    - usetesting #  Static analysis for testing best practices
+    - testifylint # Linter for testify assertions and mocking
+    - unused
+    - inamedparam
+    - gochecknoglobals
+    - misspell
+    - tagalign
+    - errcheck
+    - bodyclose
+    - staticcheck
+    - nolintlint
+    - iface
+    - gomodguard
+    - testableexamples
+  disable:
+    # Maybe enable
+    - tagliatelle
+    - thelper
+    - ireturn
+    - exhaustruct
+    - lll
+    # Actually disable these ones
+    - depguard
+    - wsl
+    - wrapcheck
+    - paralleltest
+    - nlreturn
+    - godot
+  settings:
+    gomodguard:
+      allowed:
+        domains:
+          - golang.org
+          - github.com/google/jsonschema-go
+          - github.com/modelcontextprotocol
+          - github.com/stretchr/testify
+          - github.com/google/uuid
+          - github.com/spf13/pflag
+    nolintlint:
+      require-explanation: true
+    revive:
+      rules:
+        # Disable check which requires all packages exports to have documenting string 
+        - name: exported
+          disabled: true
+    usetesting:
+      context-background: true
+      os-temp-dir: true
+  exclusions:
+    generated: lax
+    rules:
+      # Allow underscores in test function names specifically
+      - path: tests/
+        linters:
+          - revive
+        text: "don't use underscores in Go names; method Test"
+
+formatters:
+  enable:
+    - gofmt
+    - goimports
+
+issues:
+  max-same-issues: 0
+  max-issues-per-linter: 0
+
+run:
+  relative-path-mode: gomod

.mockery.yml

@@ -0,0 +1,11 @@
+# Copyright 2025 The MathWorks, Inc.
+
+all: true
+filename: '{{.InterfaceName}}.go'
+pkgname: 'mocks'
+packages:
+  github.com/matlab/matlab-mcp-core-server/internal:
+    config:
+      dir: 'mocks/{{.InterfaceDirRelative | trimPrefix "internal" }}'
+      recursive: true
+      all: true

.vscode/.gitignore

@@ -0,0 +1,4 @@
+**/*
+
+!.gitignore
+!settings.json

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "gopls": {
+        "build.buildFlags": [
+            "-tags=wireinject"
+        ]
+    }
+}

LICENSE.md

@@ -0,0 +1,11 @@
+Copyright 2025 The MathWorks, Inc.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Makefile

@@ -0,0 +1,109 @@
+# Copyright 2025 The MathWorks, Inc.
+
+# Set shell based on OS
+ifeq ($(OS),Windows_NT)
+	SHELL = powershell.exe
+else
+	SHELL = sh
+endif
+
+SEMANTIC_VERSION=v0.1.0
+COMMIT_HASH := $(shell git rev-parse HEAD)
+
+# Append Git commit hash to version unless building a release
+ifeq ($(RELEASE),true)
+	VERSION := $(SEMANTIC_VERSION)
+else
+	VERSION := $(SEMANTIC_VERSION).$(COMMIT_HASH)
+endif
+
+ifeq ($(OS),Windows_NT)
+    RM_DIR = if (Test-Path "$(1)") { Remove-Item -Recurse -Force "$(1)" }
+	PATHSEP = ;
+	BIN_PATH = $(CURDIR)/.bin/win64
+else
+    RM_DIR = rm -rf $(1)
+	PATHSEP = :
+	BIN_PATH = $(CURDIR)/.bin/glnxa64
+endif
+
+# Go build flags
+LDFLAGS := -ldflags "-X 'github.com/matlab/matlab-mcp-core-server/internal/adaptors/application/config.version=$(VERSION)'"
+
+
+all: install wire mockery lint unit-tests build
+
+version:
+	@echo $(VERSION)
+
+mcp-inspector: build
+ifeq ($(OS),Windows_NT)
+	$$env:HOST='localhost'; $$env:PATH='$(BIN_PATH)$(PATHSEP)$(PATH)'; npx @modelcontextprotocol/inspector matlab-mcp-core-server
+else
+	HOST=localhost PATH="$(BIN_PATH)$(PATHSEP)$(PATH)" npx @modelcontextprotocol/inspector $(if $(DISPLAY),-e DISPLAY=$(DISPLAY)) matlab-mcp-core-server
+endif
+
+
+# File checks
+
+install:
+	go install github.com/google/wire/cmd/wire@latest
+	go install github.com/vektra/mockery/v3@latest
+	go install gotest.tools/gotestsum@latest
+	go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2
+
+wire:
+	wire github.com/matlab/matlab-mcp-core-server/internal/wire
+
+mockery:
+	@$(call RM_DIR,./mocks)
+	mockery
+
+lint:
+	golangci-lint run ./...
+
+fix-lint:
+	golangci-lint run ./... --fix
+
+# Building
+
+build: build-for-windows build-for-glnxa64 build-for-maci64 build-for-maca64
+
+build-for-windows:
+ifeq ($(OS),Windows_NT)
+	$$env:GOOS='windows'; $$env:GOARCH='amd64'; go build $(LDFLAGS) -o ./.bin/win64/matlab-mcp-core-server.exe ./cmd/matlab-mcp-core-server
+else
+	GOOS=windows GOARCH=amd64 go build $(LDFLAGS) -o ./.bin/win64/matlab-mcp-core-server.exe ./cmd/matlab-mcp-core-server
+endif
+
+build-for-glnxa64:
+ifeq ($(OS),Windows_NT)
+	$$env:GOOS='linux'; $$env:GOARCH='amd64'; go build $(LDFLAGS) -o ./.bin/glnxa64/matlab-mcp-core-server ./cmd/matlab-mcp-core-server
+else
+	GOOS=linux GOARCH=amd64 go build $(LDFLAGS) -o ./.bin/glnxa64/matlab-mcp-core-server ./cmd/matlab-mcp-core-server
+endif
+
+build-for-maci64:
+ifeq ($(OS),Windows_NT)
+	$$env:GOOS='darwin'; $$env:GOARCH='amd64'; go build $(LDFLAGS) -o ./.bin/maci64/matlab-mcp-core-server ./cmd/matlab-mcp-core-server
+else
+	GOOS=darwin GOARCH=amd64 go build $(LDFLAGS) -o ./.bin/maci64/matlab-mcp-core-server ./cmd/matlab-mcp-core-server
+endif
+
+build-for-maca64:
+ifeq ($(OS),Windows_NT)
+	$$env:GOOS='darwin'; $$env:GOARCH='arm64'; go build $(LDFLAGS) -o ./.bin/maca64/matlab-mcp-core-server ./cmd/matlab-mcp-core-server
+else
+	GOOS=darwin GOARCH=arm64 go build $(LDFLAGS) -o ./.bin/maca64/matlab-mcp-core-server ./cmd/matlab-mcp-core-server
+endif
+
+# Testing
+
+unit-tests:
+	gotestsum --packages ./internal/... -- -race -coverprofile cover.out
+
+ci-unit-tests:
+	go test -race -json -count=1 -coverprofile cover.out ./internal/...
+
+ci-system-tests:
+	go test -race -timeout 120m -json -count=1 ./tests/system/

README.md

@@ -0,0 +1,130 @@
+# MATLAB MCP Core Server
+
+Run MATLAB® using AI applications. The MATLAB MCP Core Server allows your AI applications to:
+
+- Start and quit MATLAB.
+- Write and run MATLAB code.
+- Assess your MATLAB code for style and correctness.
+  
+## Table of Contents
+  - [Setup](#setup)
+    - [Claude Code](#claude-code) 
+    - [Claude Desktop](#claude-desktop)
+    - [GitHub Copilot in Visual Studio Code](#github-copilot-in-visual-studio-code)
+  - [Arguments](#arguments)
+  - [Tools](#tools)
+  - [Data Collection](#data-collection)
+  - [Disclaimer](#disclaimer)
+
+## Setup
+
+1. Install [MATLAB (MathWorks)](https://www.mathworks.com/help/install/ug/install-products-with-internet-connection.html) 2020b or later and add it to the system PATH.
+2. Download the [Latest Release](https://github.com/matlab/matlab-mcp-core-server/releases/latest) from GitHub®. Alternatively, you can install [Go](https://go.dev/doc/install) and build the binary from source using `go install github.com/matlab/matlab-mcp-core-server/cmd/matlab-mcp-core-server`. 
+3. Add the MATLAB MCP Core Server to your AI application. You can find instructions for adding MCP servers in the documentation of your AI application. For example instructions on using Claude Code®, Claude Desktop®, and GitHub Copilot in Visual Studio® Code, see below. Note that you can customize the server by specifying optional [arguments](#arguments).
+
+#### Claude Code
+
+In your terminal, run the following, remembering to insert the full path to the server binary you acquired in the setup:
+```sh
+claude mcp add --transport stdio matlab /fullpath/to/matlab-mcp-core-server-binary [arguments...]
+```
+You can customize the server by specifying [arguments](#arguments):
+```sh
+claude mcp add --transport stdio matlab /fullpath/to/matlab-mcp-core-server-binary --initial-working-folder=/home/username/myproject
+```
+
+For details on adding MCP servers in Claude Code, see [Add a local stdio server (Claude Code)](https://docs.claude.com/en/docs/claude-code/mcp#option-3%3A-add-a-local-stdio-server). To remove the server later, run:
+```sh
+claude mcp remove matlab
+```
+
+#### Claude Desktop
+
+Follow the instructions on the page [Connect to local MCP servers (MCP)](https://modelcontextprotocol.io/docs/develop/connect-local-servers) to install Node.js and the Filesystem Server. In your Claude Desktop configuration file, you need to add the configuration for the MATLAB MCP Core Server as well as the Filesystem Server. You can use the combined JSON below. In the Filesystem `args`, remember to specify which paths the server can access. In the MATLAB `args`, remember to insert the full path to the server binary you acquired, as well as any other arguments:
+
+```json
+{
+   "mcpServers": {
+      "filesystem": {
+         "command": "npx",
+         "args": [
+            "-y",
+            "@modelcontextprotocol/server-filesystem",
+            "C:\\Users\\username"
+         ]
+      },
+      "matlab": {
+         "command": "fullpath\\to\\matlab-mcp-core-server-binary",
+         "args": [
+            "--initial-working-folder=C:\\Users\\username\\Documents"
+         ]
+      }
+   }
+}
+```
+After saving the configuration file, quit and restart Claude Desktop. 
+
+#### GitHub Copilot in Visual Studio Code
+
+VS Code provides different methods to [Add an MCP Server (VS Code)](https://code.visualstudio.com/docs/copilot/customization/mcp-servers?wt.md_id=AZ-MVP-5004796#_add-an-mcp-server). MathWorks recommends you follow the steps in the section **"Add an MCP server to a workspace `mcp.json` file"**. In your `mcp.json` configuration file, add the following, remembering to insert the full path to the server binary you acquired in the setup, as well as any arguments:
+```json
+{
+    "servers": {
+        "matlab": {
+            "type": "stdio",
+            "command": "/fullpath/to/matlab-mcp-core-server-binary",
+            "args": []
+        }
+    }
+}
+```
+
+## Arguments
+
+Customize the behavior of the server by providing arguments in the `args` array when configuring your AI application.
+
+| Argument | Description | Example |
+| ------------- | ------------- | ------------- |
+| matlab-root | Full path specifying which MATLAB to start. Do not include `/bin` in the path. By default, the server tries to find the first MATLAB on the system PATH. | `"--matlab-root=/home/usr/MATLAB/R2025a"` |
+| initial-working-folder | Specify the folder where MATLAB starts and where the server generates any MATLAB scripts. If you do not provide the argument, MATLAB starts in the folder specified by the last entry in your list of [Roots (MCP)](https://modelcontextprotocol.io/specification/2025-06-18/client/roots). If you do not specify a root, MATLAB starts in these locations: <br><br> <ul><li>Linux: `/home/username` </li><li> Windows: `C:\Users\username\Documents`</li><li>Mac: `/Users/username/Documents`</li></ul> | `"--initial-working-folder=C:\\Users\\name\\MyProject"` |  
+| disable-telemetry | To disable anonymized data collection, set this argument to `true`. For details, see [Data Collection](#data-collection). | `"--disable-telemetry=true"`  |
+
+## Tools
+
+1. `detect_matlab_toolboxes`
+   - Lists installed MATLAB toolboxes with version information.
+ 
+2. `check_matlab_code`
+   - Performs static code analysis on a MATLAB script. Returns warnings about coding style, potential errors, deprecated functions, performance issues, and best practice violations. This is a non-destructive, read-only operation that helps identify code quality issues without executing the script.
+   - Inputs:
+     - `script_path` (string): Absolute path to the MATLAB script file to analyze. Must be a `.m` file within an allowed directory. The file is not modified during analysis. Example: `C:\Users\username\matlab\myFunction.m` or `/home/user/scripts/analysis.m`.
+ 
+3. `evaluate_matlab_code`
+   - Evaluates a string of MATLAB code and returns the output.
+   - Inputs:
+     - `code` (string): MATLAB code to evaluate.
+     - `project_path` (string): Absolute path to an allowed project directory. MATLAB sets this directory as the current working folder. Example: `C:\Users\username\matlab-project` or `/home/user/research`.
+ 
+4. `run_matlab_file`
+   - Executes a MATLAB script and returns the output. The script must be a valid `.m file`.
+   - Inputs:
+     - `script_path` (string): Absolute path to the MATLAB script file to execute. Must be a valid `.m` file within an allowed directory. Example: `C:\Users\username\projects\analysis.m` or `/home/user/matlab/simulation.m`.
+ 
+5. `run_matlab_test_file`
+   - Executes a MATLAB test script and returns comprehensive test results. Designed specifically for MATLAB unit test files that follow MATLAB testing framework conventions.
+   - Inputs:
+     - `script_path` (string): Absolute path to the MATLAB test script file. Must be a valid `.m` file containing MATLAB unit tests, within an allowed directory. Example: `C:\Users\username\tests\testMyFunction.m` or `/home/user/matlab/tests/test_analysis.m`.
+
+## Data Collection
+
+The MATLAB MCP Core Server may collect fully anonymized information about your usage of the server and send it to MathWorks. This data collection helps MathWorks improve products and is on by default. To opt out of data collection, set the argument `--disable-telemetry` to `true`.
+
+## Disclaimer
+
+The MATLAB MCP Core Server is provided "as is" without warranties of any kind, expressed or implied. By using this server, you acknowledge and accept that you are solely responsible for any actions taken and any consequences arising from its use. It is your responsibility to thoroughly review and validate all tool calls before execution. The developers and providers of this server disclaim any liability for loss, damage, or injury resulting from its use.
+
+---
+
+Copyright 2025 The MathWorks, Inc.
+
+----