Skip to content

v0.1.1

Choose a tag to compare

View all tags
@ruslanmv ruslanmv released this 16 Aug 10:55
· 39 commits to master since this release
v0.1.1
c10e9c2

v0.1.1

Release date: 2025-08-16
Package: matrix-python-sdk
Tagline: Deep links, safe local installs, and a tiny runtime—SDK-first, CLI-light.

Highlights

  • Deep-link support (matrix://install)
    New matrix_sdk.deep_link module to parse & execute one-click install links safely.
  • Local installer (plan → files → artifacts → env)
    LocalInstaller materializes Hub install plans, fetches artifacts (HTTP/ZIP/TAR, Git), writes/infers runner.json, and prepares Python/Node environments.
  • Runtime helpers (no daemon)
    Start/stop/status/logs/doctor for locally installed MCP servers with simple lock files under ~/.matrix.
  • Hardened artifact fetchers
    HTTP fetcher with SHA-256 verification + safe extraction; Git fetcher with allow-listed hosts, shallow clones, optional LFS, and ref validation.
  • Typed schemas (Pydantic v2)
    Optional models for search results, entity details, and install outcomes.

This release is designed so a stable, UI-friendly CLI can do minimal orchestration while the SDK does all the heavy lifting.

What’s new (modules)

  • matrix_sdk/deep_link.py

    • parse(url) -> DeepLink
    • handle_install(url, client, *, target) -> HandleResult
    • Strict validation: requires id, optional alias (^[a-z0-9][a-z0-9._-]{0,63}$), forbids control/path chars.

  • matrix_sdk/installer.py

    • LocalInstaller.plan(id, target) – calls Hub install endpoint.
    • materialize(outcome, target) – writes files, fetches artifacts, emits/validates runner.json.
    • prepare_env(target, runner) – Python venv via venv (+ optional python_builder), Node via detected PM.
    • build(id, *, target=None, alias=None) – plan + materialize + env in one call.
    • Dataclasses: BuildReport, EnvReport, BuildResult.

  • matrix_sdk/runtime.py

    • start(target, *, alias=None, port=None) -> LockInfo (logs to ~/.matrix/logs/<alias>.log, lock at ~/.matrix/state/<alias>/runner.lock.json)
    • stop(alias), status() -> list[LockInfo], tail_logs(alias, follow=False, n=20), doctor(alias)
    • Requires runner.json with type (python/node) and entry. Python requires venv Python present.

  • matrix_sdk/archivefetch.py

    • fetch_http_artifact(url, target, dest=None, sha256=None, unpack=False, ...)
    • Safe ZIP/TAR extraction (no path traversal), optional checksum, optional unpack, flatten GH-style archives.

  • matrix_sdk/gitfetch.py

    • fetch_git_artifact(spec, target, *, allow_hosts=None, timeout=...)
    • Shallow clone, optional subdir sparse-checkout, optional LFS, optional verify_sha.
    • Security: HTTPS only by default, host allow-list required (env or param), ref validation.

  • matrix_sdk/schemas.py

    • Pydantic models for SearchItem, SearchResponse, EntityDetail, InstallStepResult, InstallOutcome.
    • MatrixAPIError (optional generic error wrapper).

  • matrix_sdk/cli/commands.py (optional CLI helper)

    • Typer command bulk-add leveraging BulkRegistrar for gateway registrations.

API surface (import paths)

from matrix_sdk import (
    MatrixClient, MatrixError,
    parse_deep_link, handle_deep_link_install,
)

from matrix_sdk.installer import LocalInstaller
from matrix_sdk.runtime import start as runtime_start, stop as runtime_stop

Note: previous MatrixHubClient/MatrixHubError naming has been unified as MatrixClient/MatrixError.

Quick start

Deep link → local install

from matrix_sdk import MatrixClient, handle_deep_link_install
from matrix_sdk.policy import default_install_target

client = MatrixClient(base_url="http://127.0.0.1:7300", token=None)
url = "matrix://install?id=mcp_server%3Ahello-sse-server%400.1.0&alias=hello-sse"
target = default_install_target("mcp_server:hello-sse-server@0.1.0", alias="hello-sse")
res = handle_deep_link_install(url, client, target=target)
print("installed to", res.target)

Programmatic build

from matrix_sdk import MatrixClient
from matrix_sdk.installer import LocalInstaller

client = MatrixClient(base_url="http://127.0.0.1:7300")
installer = LocalInstaller(client)
result = installer.build("mcp_server:hello-sse-server@0.1.0", alias="hello-sse")
print(result.target, result.env.python_prepared, result.env.node_prepared)

Run / stop / status

from matrix_sdk.runtime import start, stop, status, tail_logs, doctor

lock = start("/home/me/.matrix/runners/hello-sse/0.1.0", alias="hello-sse")
print(lock.pid, lock.port)

print(status())
print(doctor("hello-sse"))

stop("hello-sse")
for line in tail_logs("hello-sse", n=40):
    print(line, end="")

Configuration & env vars

  • General logging: MATRIX_SDK_DEBUG=1 (enables installer/runtime/archivefetch debug logs).

  • Git fetcher:

    • MATRIX_GIT_ALLOWED_HOSTS (CSV; defaults to github.com,gitlab.com,bitbucket.org if unset and you pass none via API).
    • MATRIX_GIT_ALLOW_INSECURE=1 to permit http (discouraged).
    • MATRIX_SDK_DEBUG_GIT=1 to see git debug logs.

  • Home override: MATRIX_HOME (default ~/.matrix) for logs/state locations.

Breaking changes / migration notes

  • Renamed client/error types

    • MatrixHubClient → MatrixClient
    • MatrixHubError → MatrixError
      Update imports accordingly.

  • Runtime (Python) now requires a venv python when runner.type == "python"; ensure your installer step creates it (handled by LocalInstaller.prepare_env) before calling runtime.start.

  • Deep link parsing lives in the SDK; your CLI/GUI should compute a target path and pass it to handle_deep_link_install (the SDK intentionally does not persist aliases).

For projects still on 0.1.1, the catalog methods are unchanged in behavior—only the class names moved. Most apps can update imports and continue.

Security & hardening

  • No shell expansion from user input; deep-link validation is strict.
  • HTTP artifacts: optional SHA-256 verification; safe ZIP/TAR extraction (prevents zip/tar-slip).
  • Git artifacts: HTTPS by default, allow-listed hosts, shallow clones, ref checks, optional verify_sha.
  • Runtime uses local files only; no background daemon or open server ports.

Known limitations

  • runtime.start assumes an SSE/HTTP-style runner; custom transports may need bespoke health checks.
  • If runner.json lacks type/entry, installer attempts to infer; otherwise env prep is skipped.
  • Manifest resolver lives in matrix_sdk.manifest (not changed in this drop); ensure you gate external hosts if you fetch manifests directly in apps.

Changelog

  • 0.1.1

    • Add installer, runtime, archivefetch, gitfetch, schemas, CLI bulk-add.
    • Unify client naming (MatrixClient, MatrixError).
    • Debug logging toggles + safer defaults.
    • Add deep_link with parse() and handle_install().

Install / Upgrade

pip install -U matrix-python-sdk

If you previously imported MatrixHubClient/MatrixHubError, update to:

from matrix_sdk import MatrixClient, MatrixError
Assets 4
Loading