Skip to content

v0.1.3

Choose a tag to compare

View all tags
@ruslanmv ruslanmv released this 29 Aug 18:22
· 26 commits to master since this release
v0.1.3
fc339cc
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Matrix CLI v0.1.3 — Release Notes

Date: 2025-08-29
Project: agent-matrix/matrix-cli
PyPI: https://pypi.org/project/matrix-cli/

The Matrix CLI is the developer-focused interface for MatrixHub, aiming to become the pip of agents & MCP servers. This release brings first‑class connector runner support and smoother MCP interactions.

🎯 Highlights

  • Connector runner (attach mode) — first‑class support

    • Use runner.json with { "type": "connector", "url": "http://…/sse" } to attach to an existing MCP server.
    • matrix run records the URL; no local process is spawned.
    • matrix stop is a no‑op (unlocks only) for connectors.

  • MCP reliability & ergonomics

    • Probe/call now tolerates /sse ↔ /messages/ endpoint mismatches with a one‑time retry.
    • On tool call errors, CLI surfaces the advertised tool names (e.g., chat).

  • Safer locks & idempotent flows
    Reduced stale‑lock surprises when re‑running components.

  • Security parity
    Consistent TLS verification (env CA / OS trust / certifi) maintained.

✨ New

  • Connector-aware runtime: matrix run, ps, stop, and doctor recognize connector runners (pid 0, URL recorded, no local spawn).
  • MCP endpoint tolerance: One retry swap between /sse and /messages/ for smoother interoperability across servers.

🛠️ Improvements

  • Clearer error messages for MCP calls, including the tools the server actually exposes.
  • Small UX polish in run/stop flows and lock handling.

✅ Fixes

  • Reduced false negatives during repeated runs caused by stale lock files.
  • More robust behavior when probing endpoints that respond with partial/atypical SSE headers.

📦 Compatibility & Requirements

  • Python: 3.11+
  • SDK: matrix-python-sdk ≥ 0.1.6
  • Optional MCP utilities: pip install "matrix-cli[mcp]" (SSE; websockets for WS)

🔼 Upgrade

# pipx
pipx upgrade matrix-cli

# or pip (inside a virtualenv)
pip install -U matrix-cli

If you maintain a local development environment with custom SDK wheels, install the SDK first:

pip install /path/to/wheelhouse/matrix_python_sdk-0.1.6-py3-none-any.whl
pip install -U matrix-cli

🔗 Quick start (unchanged)

matrix search "hello" --type mcp_server --limit 5
matrix install hello-sse-server --alias hello-sse-server --force --no-prompt
matrix run hello-sse-server
matrix ps
matrix mcp probe --alias hello-sse-server
matrix mcp call hello --alias hello-sse-server --args '{}'

🔌 Connector runner example

~/.matrix/runners/watsonx-chat/0.1.0/runner.json

{
  "type": "connector",
  "name": "watsonx-chat",
  "description": "Connector to Watsonx MCP over SSE",
  "integration_type": "MCP",
  "request_type": "SSE",
  "url": "http://127.0.0.1:6289/sse",
  "endpoint": "/sse",
  "headers": {}
}

Then:

matrix run watsonx-chat         # attaches (pid=0), does not spawn a process
matrix mcp probe --alias watsonx-chat
matrix mcp call chat --alias watsonx-chat --args '{"query":"Hello"}'

🧩 MCP (probe/call) tips

  • If the call fails, the CLI prints the tools the server advertises (e.g., chat).
  • The CLI automatically retries once with the alternate endpoint (/sse vs /messages/).
  • For WebSocket endpoints, install websockets in addition to the mcp extra.

🧪 Troubleshooting

  • ExceptionGroup on probe/call: Ensure the server is reachable at the URL and that the tool name exists (check matrix mcp probe --url … --json).
  • Connector mode shows PID=0: Expected. You’re attached to a remote/local server; stop only clears the lock.
  • TLS/CA: Set SSL_CERT_FILE or REQUESTS_CA_BUNDLE when behind corporate proxies.

🙌 Thanks

Huge thanks to everyone kicking the tires on connector mode and reporting edge cases around /sse vs /messages/. Your feedback directly shaped this release.

🔗 Links

Assets 4
Loading