matrix-python-sdk 0.1.5

Python SDK for Matrix Hub — catalog search, entity detail, install, and remote management for agents, tools, and MCP servers.

Matrix Python SDK

matrix-python-sdk is the official Python SDK for the Matrix Hub — the open catalog and installer for agents, tools, and MCP servers.

Built for teams that need fast discovery, reproducible installs, and safe runtime operations at scale.

---

What’s new in 0.1.2

• Search helpers (matrix_sdk.search): on-top of /catalog/search with filter normalization, tiny retries, and automatic mode fallbacks (semantic → hybrid → keyword).
• Client search parity: MatrixClient.search supports with_rag (fit reasons) and rerank (none | llm).
• Quality & docs updates across installer/runtime/bulk.

---

Why teams choose this SDK

• One interface for a messy ecosystem — consistent search/install across agents, tools, and MCP servers.
• Reproducible installs — Hub-backed plans, adapters, and lockfiles you can ship to CI and prod.
• Production guardrails — safe archive extraction, Git host allow-lists, ETag-aware caching, typed models.
• Performance at scale — lean client, server-side indexing/scoring, normalized params to maximize cache hits.

---

Install

pip install matrix-python-sdk

Python 3.11+ supported.

---

Quickstart

1) Search

from matrix_sdk.client import MatrixClient

hub = MatrixClient("https://api.matrixhub.io")

res = hub.search(
    q="extract pdf tables",
    type="any",
    mode="hybrid",       # "keyword" | "semantic" | "hybrid"
    limit=5,
    with_snippets=True,
    with_rag=False,
    include_pending=False,
    rerank="none",
)

for it in res.get("items", []):
    print(it.get("id"), "→", it.get("manifest_url"))

Prefer the high-level helper for resilience and typed results:

from matrix_sdk.search import search, SearchOptions
res = search(hub, "chat with PDFs", type="agent",
             options=SearchOptions(as_model=True, max_attempts=3))
print(res.total, [i.id for i in res.items])

2) Install

from matrix_sdk.client import MatrixClient

hub = MatrixClient("https://api.matrixhub.io")

hub.install(
    id="mcp_server:hello-sse-server@0.1.0",
    target="./.matrix/runners/demo",
    # alias="hello-sse",         # optional
    # options={"force": True},   # optional
)

3) Run locally (no daemon)

from matrix_sdk.client import MatrixClient
from matrix_sdk.installer import LocalInstaller
from matrix_sdk import runtime

hub = MatrixClient("https://api.matrixhub.io")
result = LocalInstaller(hub).build("mcp_server:hello-sse-server@0.1.0", alias="hello-sse")

lock = runtime.start(result.target, alias="hello-sse")
print("PID:", lock.pid, "PORT:", lock.port)
runtime.stop("hello-sse")

4) Bulk register (optional)

Register servers (ZIP/dir/Git) into an MCP Gateway with concurrency, idempotency keys, and capability probing.

import os, asyncio
from matrix_sdk.bulk.bulk_registrar import BulkRegistrar

sources = [{"kind":"git","url":"https://github.com/ruslanmv/hello-mcp","ref":"main","probe":True}]

registrar = BulkRegistrar(
    gateway_url=os.getenv("GATEWAY_URL", "http://127.0.0.1:4444"),
    token=os.getenv("ADMIN_TOKEN"),
    concurrency=50,
    probe=True,
)

results = asyncio.run(registrar.register_servers(sources))
print(results)

---

API surface (snapshot)

• matrix_sdk.client.MatrixClient: search, entity, install, list_remotes, add_remote, delete_remote, trigger_ingest
• matrix_sdk.search: search, search_try_modes, SearchOptions
• matrix_sdk.installer.LocalInstaller: plan, materialize, prepare_env, build
• matrix_sdk.runtime: start, stop, status, tail_logs, doctor, log_path
• matrix_sdk.bulk.* (optional): discovery, gateway client, registrar

Pydantic models (v1/v2 compatible) in matrix_sdk.schemas: SearchItem, SearchResponse, EntityDetail, InstallOutcome, etc.

---

Reliability, Security, Performance

• Reliability: strict error types, small safe retries, idempotent bulk writes, optional ETag cache.
• Security: safe ZIP/TAR extraction, Git host allow-lists, deny-by-default where sensible.
• Performance: minimal client overhead, normalized search params, server-side scoring and indexing.

---

Links

• Docs: see docs/ (MkDocs) — Usage, API Reference, Bulk
• Source: https://github.com/agent-matrix/matrix-python-sdk
• Matrix Hub: https://github.com/agent-matrix/matrix-hub
• License: Apache 2.0

---

Contributing

We welcome issues and PRs. Please read CONTRIBUTING.md before submitting changes. Join us in shaping a fast, safe, and open ecosystem for AI agents, tools, and MCP servers.