Skip to main content
Glama
wzlwww

baltamatica.mcp

by wzlwww
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

baltamatica.mcp

PyPI License: MIT MCP Protocol Baltamatica

🔗 让 AI 代理（Claude Code / Cursor / Codex）直接驱动国产科学计算软件 北太天元（Baltamatica） 进行交互式数值计算。

📖 项目简介

baltamatica.mcp 是一个基于 Model Context Protocol (MCP) 的开源服务，为大语言模型提供与北太天元科学计算内核之间的双向通信桥梁。

通过本项目，AI 代理可以：

  • 🧮 执行代码：直接在北太天元中运行 .m 脚本或单行表达式，并取回控制台输出

  • 📊 读取变量：获取工作区中矩阵、向量、结构体、元胞等变量的值（BEX 后端二进制全保真）

  • ✍️ 写入变量：把标量/向量/矩阵注入工作区（set_variable）

  • 🔍 查询状态：列出当前工作区中所有变量的名称、类型和维度

  • 📂 管理脚本：运行本地 .m 脚本文件

  • 🧹 清空工作区：重置计算环境

当前状态：两套后端均可用。

  • CLI 后端：通过北太天元命令行入口执行代码，用 .mat 状态文件在多次 MCP 调用之间保持工作区变量。支持全部 6 个工具。

  • BEX 后端：在北太天元 GUI 进程内运行的 C 桥接（JSON-over-TCP），支持 execute_code、run_script、list_variables、get_variable、set_variable、clear_workspace：

    • get_variable 对数值/逻辑数组（实数和复数、任意大小）走 base64 二进制全保真回传，对字符/字符串/结构体/元胞走结构化 JSON；

    • set_variable 用 bxAddVariable 把标量/向量/矩阵注入工作区；

    • execute_code / run_script 用 evalc 捕获控制台输出并解析 BALTAMATICA_ARTIFACT= 文件产物；

    • 桥接生命周期健壮（可靠 stop、Ctrl-C 恢复、background 模式），并可触发 GUI Figure 弹窗（但北太天元本身无图形导出函数，见下）。

Related MCP server: jupyter-kernel-mcp

🏗️ 系统架构

项目提供两套后端。CLI 后端通过北太天元命令行入口执行代码，用 .mat 状态文件保持工作区变量，无需编译，适合快速上手。BEX 后端是一个在北太天元 GUI 进程内运行的 C 桥接，走 JSON-over-TCP，提供进程内低延迟长连接、二进制变量传输和变量注入。两者暴露相同的 MCP 工具集。

┌──────────────────────────────────────────────────────────┐
│            AI Agent (Claude Code / Cursor / Codex)         │
└─────────────────────────┬────────────────────────────────┘
                          │ MCP Protocol (stdio)
                          ▼
┌──────────────────────────────────────────────────────────┐
│               Python MCP Server (baltamatica-mcp)          │
│  execute_code / run_script / list_variables /              │
│  get_variable / set_variable / clear_workspace             │
│                     Engine Dispatcher                      │
└───────────────┬──────────────────────────┬───────────────┘
                │ (--backend cli)           │ (--backend bex)
                ▼                           ▼
     ┌────────────────────┐      ┌──────────────────────────┐
     │    CLI Backend     │      │       BEX Backend        │
     │ subprocess + .mat  │      │  JSON-over-TCP client    │
     └─────────┬──────────┘      └────────────┬─────────────┘
               ▼                               ▼
   baltamatica -nodesktop -s "…"    mcp_bridge (BEX in GUI, TCP 31415)

后端状态

特性

CLI 后端

BEX 后端

execute_code

✅

✅ evalc 捕获输出

run_script

✅

✅ evalc 捕获输出

list_variables

✅ whos 解析

✅ SDK 变量枚举

get_variable

✅ disp() 文本

✅ 二进制全保真 + 结构化 JSON

set_variable

✅ 字面量代码

✅ bxAddVariable（整数/浮点/复数/bool）

clear_workspace

✅

✅ clear

工作区状态保持

✅ .mat 状态文件

✅ BEX 进程长连接

文件产物反馈

✅ artifact marker

✅ 从捕获输出解析 marker

🚀 快速开始

前置条件

  • Python 3.10+

  • 北太天元 2025（社区版即可）

  • 北太天元命令行入口（macOS 通常是 /Applications/Baltamatica.app/Contents/MacOS/baltamatica）

  • C 编译器（仅使用 BEX 后端时需要；北太天元自带 bex 编译器会调用系统 clang/gcc）

安装

从 PyPI 安装（推荐）：

pip install baltamatica-mcp

或从源码安装（开发用）：

git clone https://github.com/wzlwww/baltamatica.mcp.git
cd baltamatica.mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

BEX 插件状态

BEX JSON 协议见 docs/bex-protocol.md，桥接使用与生命周期见 docs/bex-plugin.md 与 docs/bex-bridge.md。 当前 BEX 桥接已实现 execute_code、run_script、clear_workspace、list_variables 和 get_variable，返回结构化成功/错误结果。

获取桥接二进制 —— 三种方式,任选其一：

  • 一条命令安装（最简单）：

    baltamatica-mcp install-bridge

    自动下载对应平台的 mcp_bridge.bex* 到 ~/.baltamatica-mcp/,并打印要粘进北太天元的启动命令。

  • 手动下载：从 GitHub Releases 下对应平台的文件（macOS arm64 mcp_bridge.bexmaci64、Linux x86-64 mcp_bridge.bexa64、Windows x64 mcp_bridge.bexw64）。

  • 自行编译：scripts/build_bex.sh（自动定位北太天元 bex 编译器，Linux 上会回退到解释器内编译），或在北太天元 GUI 命令行手动编译：

clear mcp_bridge
cd '/path/to/baltamatica.mcp/bex'
bex 'mcp_bridge.c'                                   % 生成 mcp_bridge.bexmaci64 / .bexa64 / .bexw64

加载并常驻搜索路径（在北太天元 GUI 命令行）：

addpath('/path/to/mcp_bridge/所在目录'); savepath    % 让 mcp_bridge 常驻搜索路径

两种运行模式：

mcp_bridge()              % 前台：阻塞命令行，直到被停止
mcp_bridge('background')  % 后台：立即返回，命令行空着（推荐，可从同一 GUI 控制）

启动后让 Python MCP server 连接同一端口：

python -m baltamatica_mcp --backend bex --bex-host 127.0.0.1 --bex-port 31415

停止：

mcp_bridge('stop')        % 可靠停止；前台被 Ctrl-C 打断后也能释放端口

桥接把监听 socket 记在进程全局态里：stop 能在前台被 Ctrl-C 打断后直接关闭 socket 释放端口， 重跑 mcp_bridge() 会自动回收泄漏的 socket 而不是 bind 失败。若 mcp_bridge 不在搜索路径上 （例如重启后 addpath 丢失），可用纯 TCP 的兜底工具停止，完全不依赖路径：

PYTHONPATH=src python -m baltamatica_mcp.bex_shutdown

已知限制：

  • get_variable：数值/逻辑数组（实数和复数、任意大小）走 base64 二进制全保真回传；字符/字符串/结构体/元胞走结构化 JSON。极大的结构体/元胞会按上限截断（见 truncated 字段）；结构体/元胞里嵌套的数值目前是列主序扁平数组。

  • set_variable：支持整数（int8..uint64）、浮点（float32/float64）、复数（complex64/complex128，data={"real":...,"imag":...}）和 bool，二维以内。请求走缓冲读取 + 堆分配缓冲区，单条请求上限约 16 MB（约 100 万个 double）。

  • 屏幕绘图可用（figure/plot 等会在 GUI 弹窗），但图形导出到文件不可用——遍查北太天元全部 3736 个文档函数，均无 saveas/print/exportgraphics/getframe/imwrite 等图形导出函数（这是北太天元本身的能力缺失）。替代方案：用 get_variable 取回绘图数据由 AI 端渲染，或用 writematrix/writetable/save 把数据导出成文件 + BALTAMATICA_ARTIFACT= 标记回传（见下）。

  • CLI 后端无需编译、跨平台，适合快速上手；BEX 后端功能更全（二进制传输、变量注入、输出捕获）。

文件产物反馈(BEX 也支持):execute_code / run_script 现在捕获控制台输出,脚本用 fprintf('BALTAMATICA_ARTIFACT=text/csv:/tmp/x.csv\n') 声明的文件会被解析进返回的 artifacts 列表(路径、MIME、是否存在、大小)。

在 Claude Desktop 中配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "baltamatica": {
      "command": "/path/to/baltamatica.mcp/.venv/bin/python",
      "args": ["-m", "baltamatica_mcp"]
    }
  }
}

在 Claude Code 中配置

claude mcp add baltamatica -- /path/to/baltamatica.mcp/.venv/bin/python -m baltamatica_mcp

CLI Fallback 模式（无需编译）

CLI 后端会自动探测标准安装位置（macOS /Applications/Baltamatica.app/...、 Linux /opt/Baltamatica/bin/baltamatica.sh、Windows C:\Program Files\Baltamatica\...）， 标准安装下零配置即可：

baltamatica-mcp --backend cli

装在非标准位置时，用环境变量或参数指定：

BALTAMATICA_CLI=/path/to/baltamatica baltamatica-mcp --backend cli

不同平台的命令行入口不一样（后端会自动识别）：macOS 是 /Applications/Baltamatica.app/Contents/MacOS/baltamatica，Linux 是 baltamatica.sh（会自动设置库路径并透传 -s 参数）。在无显示器的 Linux（SSH/服务器）上，后端会自动设 QT_QPA_PLATFORM=offscreen。

也可以显式指定入口和单次执行超时：

baltamatica-mcp --backend cli --cli-executable /path/to/baltamatica.sh --timeout 30

CLI 后端会用 .mat 状态文件在多次 MCP 调用之间保存工作区变量。默认使用临时状态文件， 也可以显式指定：

python -m baltamatica_mcp --backend cli --state-file /tmp/baltamatica-mcp-state.mat

在 Codex 中配置

codex mcp add baltamatica \
  --env PYTHONPATH=/path/to/baltamatica.mcp/src \
  --env BALTAMATICA_CLI=/Applications/Baltamatica.app/Contents/MacOS/baltamatica \
  -- python3 -m baltamatica_mcp --backend cli --timeout 30

配置后可通过 MCP 工具调用 execute_code、run_script、list_variables、 get_variable、set_variable 和 clear_workspace。

开发测试

运行不依赖北太天元安装的单元测试：

PYTHONPATH=src pytest -q -m "not integration"
PYTHONPATH=src python3 -m compileall -q src tests

如果本机已安装北太天元 CLI，可以启用真实集成测试：

BALTAMATICA_CLI=/Applications/Baltamatica.app/Contents/MacOS/baltamatica \
  PYTHONPATH=src pytest -q -m integration

📁 项目结构

baltamatica.mcp/
├── README.md
├── LICENSE
├── pyproject.toml
├── .github/workflows/ci.yml
├── src/baltamatica_mcp/
│   ├── __init__.py
│   ├── __main__.py
│   ├── server.py           # MCP Server & Tool 注册
│   ├── engine.py           # 后端协议与结果类型
│   ├── backend_cli.py      # CLI 后端：subprocess + .mat 状态文件
│   ├── backend_bex.py      # BEX JSON-over-TCP 客户端
│   ├── serializer.py       # 变量二进制解码/编码与结构化呈现
│   └── bex_shutdown.py     # 纯 TCP 关闭 BEX 桥接的兜底工具
├── bex/
│   ├── CMakeLists.txt      # BEX CMake 构建配置
│   ├── mcp_protocol.h      # BEX JSON 协议常量
│   ├── mcp_bridge.c        # BEX TCP 桥接源码（主体）
│   └── bex_plot_probe.c    # 绘图能力探针
├── tests/
│   ├── test_backend_cli.py
│   ├── test_backend_bex.py
│   ├── test_serializer.py
│   ├── test_bex_sources.py
│   ├── test_bex_shutdown.py
│   ├── test_server.py
│   ├── test_integration_cli.py   # 标记 integration
│   ├── test_integration_bex.py   # 标记 integration
│   └── fixtures/sample_script.m
├── docs/
│   ├── contributing.md
│   ├── bex-protocol.md
│   ├── bex-plugin.md
│   ├── bex-bridge.md
│   ├── bex-plot-probe.md
│   ├── releasing.md
│   └── pr-plan.md
├── scripts/
│   └── build_bex.sh        # 用北太天元 bex 编译器编译本平台桥接二进制
└── examples/
    ├── monte_carlo_pi.m
    ├── numerical_pipeline_demo.m
    ├── artifact_export_demo.m
    └── bex_plot_probe_demo.m

🛠️ MCP Tools（暴露给 AI 的工具接口）

Tool 名称

参数

描述

CLI 后端

BEX 后端

execute_code

code: string

执行代码并返回控制台输出

✅

✅ evalc 捕获输出

run_script

file_path: string

运行 .m 脚本文件

✅

✅ evalc 捕获输出

list_variables

—

列出工作区所有变量（名称、类型、维度）

✅ whos 解析

✅ SDK 变量枚举

get_variable

name: string

获取变量值

✅ disp() 文本

✅ 二进制全保真 + 结构化 JSON

set_variable

name, data, dtype?

创建/覆盖工作区变量

✅ 字面量代码

✅ bxAddVariable（整数/浮点/复数/bool）

clear_workspace

—

清空工作区状态

✅

✅ clear

文件产物反馈

脚本可以通过标准输出声明生成的文件产物：

fprintf('BALTAMATICA_ARTIFACT=text/csv:/tmp/result.csv\n');

MCP 返回值会包含 artifacts 列表，记录文件路径、MIME 类型、是否存在和文件大小。若省略 MIME 类型：

fprintf('BALTAMATICA_ARTIFACT=/tmp/plot.png\n');

服务会根据扩展名推断常见类型，例如 image/png、application/pdf、text/csv。示例见 examples/artifact_export_demo.m。

🗺️ 开发路线图 (Roadmap)

详细 PR 拆分和实现方案见 docs/pr-plan.md。

已完成

  • MCP Server 骨架（FastMCP）

  • CLI 后端（subprocess + baltamatica -nodesktop -s）

  • execute_code / run_script

  • .mat 状态文件保持 CLI 工作区

  • list_variables / get_variable / clear_workspace

  • 可选真实集成测试与 GitHub Actions CI

  • 数值计算示例：examples/numerical_pipeline_demo.m

  • 文件产物反馈：BALTAMATICA_ARTIFACT=...

  • BEX JSON 协议设计与 Python TCP 客户端骨架

  • BEX 插件最小可用版

  • BEX list_variables / get_variable 文本变量读取

  • BEX 小型实数数值/逻辑数组结构化 JSON 读取

  • BEX 生命周期健壮化：可靠 stop / Ctrl-C 恢复 / 自愈重绑 / background 模式 / 状态返回值

  • BEX get_variable 存在性预检查（避免不存在变量在 GUI 里回显 evalin 错误）

  • BEX 数值/逻辑二进制全保真传输（含复数）+ 字符/字符串/结构体/元胞结构化序列化

  • BEX set_variable：从标量/向量/矩阵注入工作区变量（bxAddVariable）

  • BEX execute_code / run_script 控制台输出捕获（evalc + try/catch，成功返回 stdout、失败返回错误信息）

  • BEX 文件产物反馈：从捕获输出解析 BALTAMATICA_ARTIFACT= 标记

  • 绘图导出调研：确认北太天元无任何图形导出函数（3736 个函数全查），改走数据侧回传

  • background 模式线程安全评估：桥接串行化所有请求（800 顺序 + 并发双连接零错误）；唯一风险是后台模式下手动同时操作 GUI（见 docs/bex-bridge.md 线程与并发一节）

  • 自动化 BEX 集成测试（bex 编译校验 + 运行中桥接往返，标记 integration）

  • 发布体验：baltamatica-mcp 控制台入口、项目 URL、set_variable 工具与文档

  • BEX set_variable 扩展：整数（int8..uint64）/浮点（float32/64）/复数（complex64/128）类型 + 缓冲读取大 payload（上限约 16 MB）

  • 打包就绪：python -m build 可出 sdist/wheel、控制台入口、scripts/build_bex.sh 编译桥接二进制、发布流程见 docs/releasing.md

  • 发布 v0.2.0：PyPI（pip install baltamatica-mcp）+ GitHub Release（含 macOS/Linux/Windows 三平台预编译二进制）

  • v0.2.1 安装简化：CLI 后端零配置自动探测北太天元 + baltamatica-mcp install-bridge 一键下载桥接二进制

  • v0.2.2 Linux 修复：CLI 后端改用 baltamatica.sh（baltamaticaC.sh 会吞掉 -s）+ 无显示器时自动 QT_QPA_PLATFORM=offscreen（mac/Linux 均实测通过）

下一步

  • BEX 图形导出到文件：受限于北太天元本身缺少 saveas/print/exportgraphics 等函数，需厂商侧支持

🔧 核心依赖的北太天元 SDK API

本项目依赖北太天元 BEX SDK (bex.h, API v3.9) 提供的以下关键接口：

API 函数

功能

bxEvalString(expr)

执行一条字符串命令

bxEvalIn(ws, expr, plhs)

在指定工作区执行表达式并捕获返回值

bxCallBaltamatica(...)

通过函数名调用北太天元内置/自定义函数

bxGetVariableNames(result, num)

获取当前工作区所有变量名

bxAddVariable(name, value, mode)

向工作区注入变量

bxRemoveVariable(name)

删除工作区变量

bxGetDoublesRO/bxGetComplexDoublesRO/...(ba)

只读获取各类型矩阵数据指针（二进制回传）

bxCreateDoubleMatrix/bxCreateLogicalMatrix(...)

创建矩阵（set_variable 注入）

bxGetDoublesRW/bxGetLogicalsRW(ba)

读写数据指针（写入注入的数据）

bxGetString / bxGetFieldByNumberRO / bxGetCellRO

读取字符串/结构体字段/元胞元素（结构化序列化）

bxGetDimensions(ba)

获取数组维度信息

bxGetClassID(ba)

获取变量的数据类型

bxArrayToCStr(ba, ...) / bxAsCStr(ba, ...)

将变量格式化/转换为字符串

bxPrintf(...)

向命令行窗口输出（桥接状态信息）

execute_code / run_script 通过 bxCallBaltamatica 调用内置的 evalc 函数捕获控制台输出。

🤝 贡献指南

欢迎贡献代码！请参阅 CONTRIBUTING.md。

分支模型

  • main：稳定发布分支，始终保持可用

  • develop：开发主分支，所有 feature 合入此处

  • feature/<name>：功能分支，从 develop 拉出

  • fix/<name>：Bug 修复分支

提交规范

使用 Conventional Commits 规范：

feat: 添加 execute_code 工具实现
fix: 修复控制台输出截断问题
docs: 更新 README 安装说明
refactor: 重构引擎通信模块
test: 添加变量序列化单元测试
chore: 更新 CI 配置

📄 License

MIT License © 2026 wzlwww

Available Tools

6 tools
clear_workspaceB

Clear variables from the Baltamatica workspace state.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It only states the generic clearing action, without disclosing whether clearing is irreversible, affects all variables or only non-persistent ones, or triggers side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words. It is appropriately concise for a simple parameterless tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite lacking behavioral details, the description adequately explains the tool's core purpose for a straightforward action. An output schema exists but is not shown; the description does not need to detail return values per rubric.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and schema description coverage is 100%. The description adds no parameter meaning beyond the schema, meeting the baseline of 3 for 0-param tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (clear) and the resource (variables from the Baltamatica workspace). It distinguishes itself from siblings like set_variable and list_variables by indicating a removal operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives (e.g., set_variable to clear a single variable, or list_variables to inspect before clearing). The description does not specify prerequisites or context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

execute_codeC

Execute a Baltamatica code snippet and return output from the backend.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behaviors. It only states execution and output, omitting side effects, safety concerns, timeouts, or error handling for a potentially risky code execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single concise sentence that communicates the core functionality without waste. However, it could be front-loaded with more critical information first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description fails to address important aspects like error messages, execution limits, or impact on workspace state. For a code execution tool, this is insufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%. The description adds minimal context by specifying 'Baltamatica code snippet', but does not describe the expected format, limits, or behavior of the code parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool executes a Baltamatica code snippet and returns output, with a specific verb and resource. It is distinct from sibling tools like clear_workspace or get_variable, which handle workspace management and variables.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like run_script, nor any conditions or prerequisites. The description lacks context for appropriate use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_variableB

Return a display representation of one Baltamatica variable.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries full burden. It implies a read-only operation by saying 'Return a display representation', but does not explicitly state it is safe, idempotent, or has no side effects. The transparency is adequate but leaves room for uncertainty.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence of 8 words, with no wasted information. It is front-loaded and directly states the core function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, the description need not detail return values. It adequately indicates the output type ('display representation'). For a simple retrieval tool with one parameter, the description covers the essential behavior, though it could mention error handling or variable existence checks.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds no meaning beyond the input schema. The single required parameter 'name' is not explained (e.g., 'name of the variable'). With 0% schema description coverage, the description fails to compensate, leaving the agent to infer the parameter's purpose from the tool name alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Return' and the resource 'display representation of one Baltamatica variable'. It distinguishes from sibling tools like list_variables (which returns all variables) and set_variable (which modifies), making the tool's specific purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention contexts where list_variables or execute_code might be more appropriate, nor does it state prerequisites or constraints.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_variablesA

List variables in the Baltamatica workspace state.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description should disclose behavioral traits. It states the operation is listing, but doesn't mention ordering, output format, or side effects. Adequate but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. Every word contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with no parameters and has an output schema. The description fully explains the tool's purpose, and no additional information is needed for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so the schema coverage is trivially 100%. The description correctly implies no input is needed, earning the baseline of 4 for zero params.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'variables' in the 'Baltamatica workspace state', distinguishing it from sibling tools like get_variable (single variable) and set_variable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives like get_variable. The description lacks explicit context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_scriptB

Run a local Baltamatica .m script file.

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and the description fails to disclose behavioral traits such as side effects (workspace mutation), error handling, or output behavior beyond the existence of an output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single clear sentence with no unnecessary words, effectively communicating the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the tool has only one parameter and an output schema, the description omits important context such as side effects, return value structure, and relationship to sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description does not add meaning beyond the parameter name 'file_path', missing details like format, path patterns, or allowed extensions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Run' and the specific resource 'local Baltamatica .m script file', distinguishing it from sibling tools like execute_code which likely runs code snippets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus siblings like execute_code, or when not to use it. The description lacks context about prerequisites or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_variableA

Create or overwrite a workspace variable.

data may be a number, a boolean, a 1-D list (row vector), or a 2-D nested list (matrix). Without dtype, numbers become double and booleans become logical. dtype may request an integer type (int8..uint64), float32/float64, or a complex type (complex64/complex128, with data={"real": <array>, "imag": <array>}).

ParametersJSON Schema
NameRequiredDescriptionDefault
dataYes
nameYes
dtypeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It explains data types and dtype options, including complex numbers, but lacks details on side effects (e.g., overwriting behavior), permissions, or error handling. The 'create or overwrite' phrasing is helpful but incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the core action. It uses bullet-like formatting for details, but could be more structured (e.g., separating parameter descriptions). No irrelevant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the input schema and lack of annotations, the description covers data types and dtype comprehensively. It does not explain return values, but an output schema exists (context signal), so this is acceptable for a variable-setting tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description adds significant value by explaining valid data formats (number, boolean, list, matrix) and dtype options. However, it does not explain the 'name' parameter beyond the schema's type string, missing an opportunity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action: 'Create or overwrite a workspace variable.' The verb 'set' and resource 'variable' are explicit, and the purpose is distinct from siblings like get_variable (read) and list_variables (list).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for storing data but does not explicitly state when to use this tool over alternatives. No guidance on prerequisites or context is provided, though the purpose is clear from sibling tool names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv0.2.2
    • First observedclear_workspace
    • First observedexecute_code
    • First observedget_variable
    • First observedlist_variables
    • First observedrun_script
    • First observedset_variable
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 6 tools

Disambiguation5/5

Each tool has a distinct purpose: workspace management (clear, list, get, set) and code execution (snippet vs script). No overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern (e.g., clear_workspace, execute_code, set_variable). No deviations.

Tool Count5/5

6 tools is well-scoped for a MATLAB-like environment, covering workspace operations and code execution without unnecessary bloat.

Completeness4/5

Covers core workspace CRUD (create via set, read via get/list, delete via clear) and execution. Missing a per-variable delete, but overall sufficient for typical use.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers