Skip to content

v0.1.7

Choose a tag to compare

View all tags
@ruslanmv ruslanmv released this 31 Aug 21:43
· 24 commits to master since this release
v0.1.7
80ea7a2

Matrix Python SDK v0.1.7

Date: 2025-08-31

A small but important release focused on manifest ingestion, runner materialization, and more reliable Python environment setup. If you’re installing MCP servers from manifests (v2) and want the SDK to “just work” without a hand-crafted runner.json, this one’s for you.

✨ Highlights

  • v2 manifest ingestion: understands embedded runner definitions and pulls runner data from the manifest/provenance when available.
  • Deterministic runner materialization: a clear, prioritized set of strategies to find, fetch, or synthesize runner.json.
  • Smarter Python env setup: integrates an optional python_builder pathway with a robust pip fallback.
  • New environment switches to make CI/CD repeatable and easier to debug.

🔧 Changes

Runner materialization (installer)

The SDK now attempts runner discovery using a predictable priority order (first match wins):

  1. Embedded base-64 runner
  2. Explicit runner URL
  3. Runner object provided in the plan
  4. Embedded v2 manifest runner (or v1 synth)
  5. Known file locations
  6. Shallow search
  7. Synthesize from manifest_url / provenance.source_url
  8. Fallback connector synthesis

This means many installs no longer require a local runner.json. If your manifest embeds a valid runner (or points to one), the SDK will use it automatically.

Python environment preparation

  • Attempts python_builder first (when available), then falls back to a standard pip flow.
  • Always ensures pip, setuptools, and wheel are up to date before installing.
  • Honors optional indexes via environment variables (see below).

New / documented environment variables

  • MATRIX_SDK_ALLOW_MANIFEST_FETCH=1
    Allow the installer to fetch and use runner details from the provided manifest URL/provenance.
  • MATRIX_SDK_RUNNER_SEARCH_DEPTH=3
    Control how far the SDK will look for a runner file when doing shallow searches.
  • MATRIX_SDK_PIP_INDEX_URL and MATRIX_SDK_PIP_EXTRA_INDEX_URL
    Point installs at private indexes/mirrors in CI.

Logging & UX

  • Clearer log messages for each runner-discovery strategy.
  • More explicit warnings when a runner cannot be found or synthesized.

⚠️ Notes & compatibility

  • Behavioral change: the refined priority order can cause the SDK to pick a different runner source than previous versions if multiple options were available. If you rely on an older inference path, pin a runner explicitly (embedded, URL, or runner.json).
  • Connector vs process/python runners: if your manifest declares a connector that points to a local SSE URL, the SDK will honor that. If you intend to launch a server, prefer a python/process runner in the manifest or ship a runner.json.

✅ Recommended usage

  • Prefer v2 manifests with an embedded runner (or a provenance.source_url) so installs are reproducible.

  • In CI, set:

    export MATRIX_SDK_ALLOW_MANIFEST_FETCH=1
export MATRIX_SDK_RUNNER_SEARCH_DEPTH=3
# Optional:
export MATRIX_SDK_PIP_INDEX_URL=...
export MATRIX_SDK_PIP_EXTRA_INDEX_URL=...

🐞 Fixes & reliability

  • More resilient venv creation across platforms (retries without symlinks when needed).
  • Better error surfaces when no dependency files are present (skips gracefully instead of failing silently).

🙏 Thanks

Thanks to everyone testing manifest-based installs and sharing feedback around runner discovery and env setup—this release folds many of those lessons into the default flow.

📦 Installing / upgrading

If published to your index:

pip install -U matrix-python-sdk==0.1.7

Or install from source in editable mode:

pip install -e .

🔗 Changelog

  • Compare: v0.1.6...v0.1.7
  • Key modules touched: matrix_sdk/installer.py (runner strategies & env setup)
Assets 4
Loading