data/kb.jsonl

{"text":"MatrixHub is the API and registry for Matrix apps, tracking health and LKG metadata.","source":"kb:matrixhub"}
{"text":"Matrix Guardian coordinates probes, writes /status to MatrixHub, and asks matrix-ai for plans.","source":"kb:guardian"}
{"text":"Matrix System 1.0 turns a static registry into an alive, policy-governed, self-healing platform (observe → plan → approve/execute → audit).","source":"kb:overview"}
{"text": "⚡️ Matrix CLI\n*The command-line interface for **Matrix Hub** — search, inspect, install, run, probe MCP servers, manage remotes, check connectivity, and safely uninstall.*\n[](https://pypi.org/project/matrix-cli/)\n[](https://pypi.org/project/matrix-cli/)\n[](https://github.com/agent-matrix/matrix-cli)\n[](https://agent-matrix.github.io/matrix-cli/)\n[](./LICENSE) <a href=\"https://github.com/agent-matrix/matrix-hub\"><img src=\"https://img.shields.io/badge/Powered%20by-matrix--hub-brightgreen\" alt=\"Powered by matrix-hub\"></a>\nRequires **Python 3.11+** and **matrix-python-sdk ≥ 0.1.9**.\n🌍 Why Matrix CLI\nMatrix CLI gets you from **discovery → install → run → interact** with agents, tools, and MCP servers — fast. Built to be secure by default, delightful for developers, and friendly for automation w", "source": "github:agent-matrix/matrix-cli/README.md"}
{"text": ", tools, and MCP servers — fast. Built to be secure by default, delightful for developers, and friendly for automation worldwide.\n🚀 What’s new in v0.1.6\nAligned with **matrix-python-sdk 0.1.9** (backwards-compatible refactor) and introduces a faster way to talk to your agents.\n• **✨ New:** matrix do <alias> <prompt> — the quickest way to interact with a running agent.\n• **Smarter runner discovery:** Auto-materializes runner.json from embedded b64/URL/object, embedded manifests (v1/v2), on-disk search, or inference (server.py, package.json). Synthesizes connector runners if an MCP URL is present.\n• **Safer materialization:** Writes only under your target; supports base64 files, git/http artifacts; robust logging.\n• **Faster environment prep:** Python: fresh venv + upgraded pip/setuptools/wh", "source": "github:agent-matrix/matrix-cli/README.md"}
{"text": "iles, git/http artifacts; robust logging.\n• **Faster environment prep:** Python: fresh venv + upgraded pip/setuptools/wheel, then requirements.txt or editable pyproject.toml / setup.py. Node: auto-detects **pnpm > yarn > npm**.\n• **Connector-aware run (attach mode):** If runner.json is a connector with an MCP SSE URL, matrix run attaches (no local process). matrix stop becomes a no-op (clears the lock).\n• **Better MCP probing & calls:** Tolerates /sse vs /messages/, clearer errors, --json for scripts.\n• **Idempotent installs:** Re-install same alias with --force --no-prompt without surprises.\nTip: export MATRIX_SDK_DEBUG=1 for verbose installer logs.\n🎬 A 5-Minute End-to-End Demo\nExperience the full lifecycle with a Watsonx agent — from search to results.\n0) Setup\nCreate a local .env with y", "source": "github:agent-matrix/matrix-cli/README.md"}
{"text": "nd Demo\nExperience the full lifecycle with a Watsonx agent — from search to results.\n0) Setup\nCreate a local .env with your credentials:\n1) 🔍 Discover\n2) 📦 Install\n3) 🚀 Run\n4) ✨ Ask with **matrix do**\n5) ⚙️ Advanced call\n6) 📋 Manage & clean up\n📦 Install\nOptional extras\n⚙️ Configuration\nThe CLI reads, in order: **environment variables**, ~/.config/matrix/cli.toml (optional), then built-ins.\nEnvironment\nOptional TOML (~/.config/matrix/cli.toml)\n🏁 Quick start\n**Demo GIFs**\n🔍 Search tips\nUseful filters:\n• --type {agent|tool|mcp_server}\n• --mode {keyword|semantic|hybrid}\n• --capabilities rag,sql\n• --frameworks langchain,autogen\n• --providers openai,anthropic\n• --with-snippets\n• --certified (registered/certified only)\n• --json for programmatic output\n• --exact to fetch a specific ID\nExamples:\nIf", "source": "github:agent-matrix/matrix-cli/README.md"}
{"text": "• --certified (registered/certified only)\n• --json for programmatic output\n• --exact to fetch a specific ID\nExamples:\nIf the public Hub is unreachable, some operations try a **local dev Hub** once and tell you.\n🧩 Install behavior (safer by design)\n• Accepts name, name@ver, ns:name, ns:name@ver.\n• If ns missing, prefers **mcp_server**.\n• If @version missing, picks **latest** (stable > pre-release).\n• Uses a small cache under ~/.matrix/cache/resolve.json (per-hub, short TTL).\n• **No absolute paths sent to the Hub** — the CLI sends a safe <alias>/<version> label, then **materializes locally**.\n• Preflight checks ensure your local target is **writable** before network calls.\nExamples:\n▶️ Run, interact, and probe\nmatrix run <alias> prints a click-ready **URL** and **Health** link, plus a logs h", "source": "github:agent-matrix/matrix-cli/README.md"}
{"text": "Examples:\n▶️ Run, interact, and probe\nmatrix run <alias> prints a click-ready **URL** and **Health** link, plus a logs hint.\n🔗 Connector mode (attach to a remote/local MCP)\nIf you already have an MCP server listening (e.g. on http://127.0.0.1:6289/sse), **attach** to it without starting a local process by using a **connector runner**:\n~/.matrix/runners/<alias>/<version>/runner.json:\nThen:\nIn connector mode, matrix stop simply clears the lock (no local process to kill).\n🧪 MCP utilities (SSE/WS)\nProbe and call tools on MCP servers.\nNotes:\n• SSE works with mcp>=1.13.1 (installed via the mcp extra).\n• WebSocket URLs (ws:///wss://) require the websockets package.\n• If a call fails, the CLI helps by listing tools and tolerates /sse vs /messages/ endpoints.\n🧭 Process management\nmatrix ps shows a ", "source": "github:agent-matrix/matrix-cli/README.md"}
{"text": "ails, the CLI helps by listing tools and tolerates /sse vs /messages/ endpoints.\n🧭 Process management\nmatrix ps shows a **URL** column built from the runner’s port and endpoint (default /messages/).\nCopy the URL directly into:\nScript-friendly output:\nOther commands:\n🌐 Hub health & TLS\nTLS policy:\n• Respects REQUESTS_CA_BUNDLE / SSL_CERT_FILE.\n• Tries OS trust (when available).\n• Falls back to certifi.\n• Never throws on network errors in health checks — returns a structured status with exit codes.\n🧹 Safe uninstall\nRemove one or many aliases, and optionally purge local files.\nSafety features:\n• Only purges targets under ~/.matrix/runners by default.\n• Skips deleting files still referenced by other aliases.\n• --force-files allows deleting outside the safe path (⚠️ **dangerous**; off by defaul", "source": "github:agent-matrix/matrix-cli/README.md"}
{"text": "till referenced by other aliases.\n• --force-files allows deleting outside the safe path (⚠️ **dangerous**; off by default).\n• --stopped-only to avoid touching running aliases.\nExit codes: **0** success, **2** partial/failed.\n🧰 Scripting & CI examples\n🐞 Troubleshooting\n• **“Missing 'mcp' package”** — Install the optional extra: pip install \"matrix-cli[mcp]\" (and pip install websockets for WS).\n• **TLS / certificate errors** — Set SSL_CERT_FILE or REQUESTS_CA_BUNDLE to your CA bundle.\n• **Alias not found when probing** — Use the alias shown by matrix ps (case-insensitive), or pass --url directly.\n• **Connector mode shows PID=0** — Expected in attach mode; ensure the remote server is running.\n🛠️ Development\n🌍 About MatrixHub\nMatrixHub aims to be the **pip of agents & MCP servers** — a secure,", "source": "github:agent-matrix/matrix-cli/README.md"}
{"text": "server is running.\n🛠️ Development\n🌍 About MatrixHub\nMatrixHub aims to be the **pip of agents & MCP servers** — a secure, open, and developer-friendly registry and runtime that scales from personal laptops to global enterprises. If you’re building agents, tools, or MCP services, Matrix CLI gets you from idea to running in seconds.\n📄 License\nApache License 2.0\n✉️ Feedback\nIssues and PRs welcome! If you hit rough edges with install/probing/health, the new **connector** flow, or ps --plain/--json and uninstall, please open an issue with your command, output, and environment.\n• GitHub: https://github.com/agent-matrix/matrix-cli\n• PyPI: https://pypi.org/project/matrix-cli/", "source": "github:agent-matrix/matrix-cli/README.md"}
{"text": "<!-- docs/changelog.md -->\nChangelog\nv0.1.3\n• **Connector runner** supported end‑to‑end (pid=0; URL only)\n• MCP client: one‑retry tolerance between /sse and /messages/\n• Better error messages: show advertised tool names on call failure\n• Runtime: stop is a no‑op for connectors; doctor acknowledges remote URL\nv0.1.2\n• matrix connection (human/JSON; exit code 0/2)\n• matrix mcp (probe/call; SSE; WS optional)\n• Safer installs (no absolute paths leaked to the Hub)\n• matrix ps shows URL; --plain & --json\n• matrix uninstall with optional --purge\n• TLS hardening", "source": "github:agent-matrix/matrix-cli/docs/changelog.md"}
{"text": "do — One‑shot MCP Call\nA fast, zero‑JSON way to call an MCP tool exposed by a running server. You give an **alias** (or a full **URL**) and optional **text** or a **file path**; do selects a sensible tool and builds the arguments for you.\nPrefer do for quick ad‑hoc prompts. If you need structured input, use matrix mcp call with --args, --kv, --text, or --wizard.\nSynopsis\n**Positional arguments**\n• TARGET  — Optional alias or catalog name you installed earlier (same as --alias).\n• TEXT    — Optional plain‑text input mapped to the tool’s default input field.\n**Options**\n• --alias ALIAS  — Alias shown by matrix ps. Auto‑discovers host/port/endpoint.\n• --url URL      — Full SSE/WebSocket endpoint (e.g., http://127.0.0.1:52305/messages/).\n• --in PATH      — Path‑like input. If the schema define", "source": "github:agent-matrix/matrix-cli/docs/do.md"}
{"text": "SE/WebSocket endpoint (e.g., http://127.0.0.1:52305/messages/).\n• --in PATH      — Path‑like input. If the schema defines path/file fields, it maps there; otherwise it uses the default input key.\n• --timeout SEC  — Connect/read timeout (default: 10.0).\n• --json         — Emit structured JSON instead of human text.\nExit codes: 0 success · 2 user/guidance error · 130 interrupted\nWhat do infers for you\nURL / endpoint (from alias)\n• Reuses the same discovery helpers as matrix mcp:\n• Finds the running row for the alias via matrix_sdk.runtime.status().\n• If you did **not** provide an endpoint, it reads <target>/runner.json and falls back to \"/messages/\" when unspecified.\n• Builds http://{host}:{port}/{endpoint}/ and picks **SSE** automatically for HTTP(S) URLs.\n• If you pass --url, it is used **", "source": "github:agent-matrix/matrix-cli/docs/do.md"}
{"text": "ds http://{host}:{port}/{endpoint}/ and picks **SSE** automatically for HTTP(S) URLs.\n• If you pass --url, it is used **as‑is**. Many MCP servers require a **trailing slash** (e.g., /sse/).\nTool selection\n• Picks a *default* tool by name preference: **default → main → run → chat**.\n• If none match, uses the **first** tool exposed by the server.\nInput mapping\n• If you provided **TEXT**, do maps it to a default input key inferred from the tool’s input schema:\n1. x-default-input\n2. first of query | prompt | text | input | message\n3. a single **required** string property\n4. the only **string** property\n• If you provided **--in PATH**, do prefers common path keys (path, file, filepath, filename, input_path); otherwise it maps PATH to the default input key (above).\n• If the schema requires struc", "source": "github:agent-matrix/matrix-cli/docs/do.md"}
{"text": "filepath, filename, input_path); otherwise it maps PATH to the default input key (above).\n• If the schema requires structured input and do can’t infer it safely, it will guide you to use matrix mcp call --wizard.\nOutput rendering\n• Prints text content blocks directly. Non‑text blocks are shown as - <type>: <repr>. Use --json for machine‑readable output.\nExamples\n1) Quick chat‑style prompt (alias)\n2) Using TARGET positional instead of --alias\n3) Explicit URL (note the trailing slash)\n4) File path mapping\n5) JSON output (pipe into jq)\nTroubleshooting\n**“Provide --url OR --alias (optionally with --port).”**\nYou didn’t supply a way to connect. Add --alias <name> (preferred) or --url http://host:port/path/.\n**404 or route error**\nIf you passed --url without a trailing slash (e.g., /sse), many s", "source": "github:agent-matrix/matrix-cli/docs/do.md"}
{"text": "r --url http://host:port/path/.\n**404 or route error**\nIf you passed --url without a trailing slash (e.g., /sse), many servers expect /sse/.\n**“Multiple inputs or no clear default input detected.”**\nThe tool needs structured arguments. Use the guided mode:\n**“No tools exposed by the server.”**\nVerify the server is healthy and actually exposes tools. Try:\n**Unsupported URL scheme**\nWebSocket requires ws:// or wss://. HTTP(S) uses SSE by default.\nWhen to use do vs mcp call\n• Use **do** for quick one‑shot prompts where a single text or file path is enough.\n• Use **mcp call** when you need full control over arguments (--args JSON, --kv, --text, or interactive --wizard).\nSee also\n• mcp command\n• quickstart\n• matrix ps, matrix run, matrix logs, matrix stop", "source": "github:agent-matrix/matrix-cli/docs/do.md"}
{"text": "<!-- docs/index.md -->\nMatrix CLI (v0.1.3)\n**MatrixHub** is building the *pip of agents & MCP servers* — search, install, run, and connect.\nThe **Matrix CLI** is a thin, fast UX over the Matrix Python SDK. It works with public and private Matrix Hubs.\nWhy MatrixHub?\n• **Discoverability** — Search a global catalog of agents, tools, and MCP servers.\n• **One‑line installs** — Clean install plans; local materialization stays on your machine.\n• **Runtime built‑in** — Start/stop processes, tail logs, and health‑check.\n• **MCP‑native** — Probe and call tools over SSE/WS with zero boilerplate.\n• **Enterprise‑grade TLS** — Honors corporate CAs via SSL_CERT_FILE / REQUESTS_CA_BUNDLE.\nCLI highlights\n• matrix search — rich filters, JSON output for scripting\n• matrix install — safe planning; no absolut", "source": "github:agent-matrix/matrix-cli/docs/index.md"}
{"text": "E.\nCLI highlights\n• matrix search — rich filters, JSON output for scripting\n• matrix install — safe planning; no absolute paths sent to the Hub\n• matrix run, matrix ps, matrix logs, matrix stop\n• matrix mcp probe / matrix mcp call — attach to **local** or **remote** MCP\n• matrix connection — Hub health (human + JSON)\n• matrix uninstall — safe, scriptable removal\nExample (end‑to‑end)\nEnvironment variables\nProject links\n• Website: https://matrixhub.io\n• CLI: published as matrix-cli (PyPI/pipx)\n• SDK: matrix-python-sdk", "source": "github:agent-matrix/matrix-cli/docs/index.md"}
{"text": "<!-- docs/install.md -->\nInstall\n**Requirements**: Python **3.11+**.\nRecommended\nVirtualenv\nOptional extras\nUpgrading\nUsing local wheels (offline/dev)\nIf you built local wheels (e.g. the SDK: matrix-python-sdk-0.1.6), install them before the CLI:", "source": "github:agent-matrix/matrix-cli/docs/install.md"}
{"text": "MCP (Probe & Call)\nMatrix CLI speaks **Model Context Protocol** (MCP) over **SSE** and optionally WebSocket.\nTwo ways to attach\n• **Process runner** — CLI starts a local server from runner.json (type python/node).\n• **Connector runner** — CLI records a **remote** url (pid=0) and does **not** spawn a process.\nBoth are supported and non‑breaking.\nProbe\nCLI will automatically retry **once** if /sse vs /messages/ is mismatched.\n**Gotcha:** When you pass --url, the CLI uses it **as‑is**. Many MCP servers require a **trailing slash** (e.g., /sse/). If you see 404s or route errors, add the trailing /.\nCall a tool\n**Tip:** If a call fails, the CLI prints the tool list advertised by the server (e.g., chat).\nArgument forms (choose one)\nPick any of these equivalent ways to pass inputs to a tool. Thes", "source": "github:agent-matrix/matrix-cli/docs/mcp.md"}
{"text": "by the server (e.g., chat).\nArgument forms (choose one)\nPick any of these equivalent ways to pass inputs to a tool. These are especially handy for simple chat‑style tools that expect a query string.\n**Simplest (let the CLI infer the argument name):**\n**KV style (no JSON):**\n**Proper JSON (quote the whole object):**\n**With URL (note the trailing slash):**\n**From stdin:**\n**Bash/WSL tip:** Wrap JSON in **single quotes** so you don’t have to escape the inner double quotes.\nExample: connector runner\nCreate ~/.matrix/runners/watsonx-chat/0.1.0/runner.json:\nThen:", "source": "github:agent-matrix/matrix-cli/docs/mcp.md"}
{"text": "<!-- docs/quickstart.md -->\nQuickstart\n1) Check the Hub\n2) Search the catalog\n3) Install safely\n4) Run + inspect\n5) MCP probe & call\nBy alias (auto‑discovers URL/endpoint)\nBy explicit URL\n**Tip (bash/WSL):** Wrap JSON in **single quotes** so you don’t have to escape the inner double quotes.\n6) Stop & uninstall", "source": "github:agent-matrix/matrix-cli/docs/quickstart.md"}
{"text": "<!-- docs/runtime.md -->\nRuntime (run / ps / logs / stop)\nRun\n• For **process** runners, CLI launches the server and writes a lock with real PID/port.\n• For **connector** runners, CLI writes a lock with pid=0, port=null, url=<runner.url>.\nList\nLogs\nHealth\n• Process: probes /health at http://127.0.0.1:<port>/health.\n• Connector: returns **ok** with a message like *configured remote SSE url …* (may perform a short HEAD).\nStop\n• Process: sends SIGTERM and removes the lock.\n• Connector: **no‑op** (removes the lock only).", "source": "github:agent-matrix/matrix-cli/docs/runtime.md"}
{"text": "<!-- docs/troubleshooting.md -->\nTroubleshooting\n\"ExceptionGroup: unhandled errors in a TaskGroup\"\nUsually means the CLI couldn’t establish an MCP session.\n**Checklist**\n1. **Is the server running?**\n• Probe the URL directly: curl -I http://127.0.0.1:6288/sse (look for 200 OK).\n• Try matrix mcp probe --url ... --json and inspect the error.\n2. **Endpoint mismatch**\n• Your server exposes /sse, older code might use /messages/.\n• The CLI retries once with the alternate path automatically.\n3. **Tool name mismatch**\n• Server exposes chat, but you called watsonx-chat.\n• The CLI now prints tool names on failures.\n4. **Stale lock**\n• If matrix run says locked, run matrix stop <alias> or remove ~/.matrix/state/<alias>/runner.lock.json.\n5. **TLS / corporate CA**\n• Set SSL_CERT_FILE *or* REQUESTS_CA_B", "source": "github:agent-matrix/matrix-cli/docs/troubleshooting.md"}
{"text": "as> or remove ~/.matrix/state/<alias>/runner.lock.json.\n5. **TLS / corporate CA**\n• Set SSL_CERT_FILE *or* REQUESTS_CA_BUNDLE to your CA bundle.\nGateway 401 during install\nSet MCP_GATEWAY_TOKEN or pass --gw-token in your PoC scripts.\nLocal wheels\nEnsure your virtualenv resolves your dev wheels first, e.g. install matrix-python-sdk-*.whl before matrix-cli.", "source": "github:agent-matrix/matrix-cli/docs/troubleshooting.md"}
{"text": "Matrix Python SDK\n[](https://pypi.org/project/matrix-python-sdk/)\n[](https://pypi.org/project/matrix-python-sdk/)\n[](https://github.com/agent-matrix/matrix-python-sdk/actions/workflows/ci.yml)\n[](https://github.com/agent-matrix/matrix-python-sdk/blob/master/LICENSE)\n**matrix-python-sdk** is the official Python SDK for the Matrix Hub — the open catalog and installer for **agents**, **tools**, and **MCP servers**.\nBuilt for teams that need **fast discovery**, **reproducible installs**, and **safe runtime** operations at scale.\nWhat’s new in 0.1.9\nA focused, compatibility-preserving refresh.\n• **Modular installer** with legacy import preserved:\nInternals split into installer/core.py, runner_schema.py, runner_discovery.py, envs.py, util.py.\n• **Runner discovery** restored to legacy strategy or", "source": "github:agent-matrix/matrix-python-sdk/README.md"}
{"text": "/core.py, runner_schema.py, runner_discovery.py, envs.py, util.py.\n• **Runner discovery** restored to legacy strategy order with modern safeguards:\nb64 → URL → object → embedded manifest → file → shallow search → manifest URL (opt-in) → infer by structure → **connector** fallback.\n• **Connector synthesis** (attach mode): auto-generates minimal\n{\"type\":\"connector\",\"url\":\"…/sse\"} when an MCP/SSE endpoint is found. Gate via MATRIX_SDK_ENABLE_CONNECTOR=1 (default **on**).\n• **Windows venv reliability**: venv creation retries without symlinks when required.\n• **Shared utilities**: env toggles, timeouts, runner search depth, safe FS checks in installer/util.py.\n• **Docs**: updated install/usage/API pages; clearer examples.\nRequires Python **3.11–3.12**.\nWhy teams choose this SDK\n• **One interfac", "source": "github:agent-matrix/matrix-python-sdk/README.md"}
{"text": "ted install/usage/API pages; clearer examples.\nRequires Python **3.11–3.12**.\nWhy teams choose this SDK\n• **One interface** for a messy ecosystem — consistent search/install across agents, tools, and MCP servers.\n• **Reproducible installs** — Hub-backed plans, adapters, and lockfiles you can ship to CI and prod.\n• **Production guardrails** — safe archive extraction, Git host allow-lists, ETag-aware caching, typed models.\n• **Performance at scale** — lean client, server-side indexing/scoring, normalized params to maximize cache hits.\nInstall\nPython **3.11+** supported.\nQuickstart\n1) Search\nPrefer the high-level helper for resilience and typed results:\n2) Install\n3) Run locally (no daemon)\nConnector / attach mode (new in 0.1.6)\nIf runner.json has {\"type\":\"connector\",\"url\":\"http://127.0.0.1:6", "source": "github:agent-matrix/matrix-python-sdk/README.md"}
{"text": "ally (no daemon)\nConnector / attach mode (new in 0.1.6)\nIf runner.json has {\"type\":\"connector\",\"url\":\"http://127.0.0.1:6288/sse\"}, runtime.start(...) **does not** start a process. Instead it stores the URL in the lock (with pid=0). Use the URL directly with your MCP client.\n4) Bulk register (optional)\nRegister servers (ZIP/dir/Git) into an MCP Gateway with concurrency, idempotency keys, and capability probing.\nAPI surface (snapshot)\n• matrix_sdk.client.MatrixClient: search, entity, install, list_remotes, add_remote, delete_remote, trigger_ingest\n• matrix_sdk.search: search, search_try_modes, SearchOptions\n• matrix_sdk.installer.LocalInstaller: plan, materialize, prepare_env, build\n• matrix_sdk.runtime: start, stop, status, tail_logs, doctor, log_path\n*(Lock files now include an optional ur", "source": "github:agent-matrix/matrix-python-sdk/README.md"}
{"text": "nv, build\n• matrix_sdk.runtime: start, stop, status, tail_logs, doctor, log_path\n*(Lock files now include an optional url for connector runners; stop() is a no-op for connectors.)*\n• matrix_sdk.bulk.* (optional): discovery, gateway client, registrar\nPydantic models (v1/v2 compatible) in matrix_sdk.schemas: SearchItem, SearchResponse, EntityDetail, InstallOutcome, etc.\nReliability, Security, Performance\n• **Reliability**: strict error types, small safe retries, idempotent bulk writes, optional ETag cache.\n• **Security**: safe ZIP/TAR extraction, Git host allow-lists, deny-by-default where sensible.\n• **Performance**: minimal client overhead, normalized search params, server-side scoring and indexing.\nLinks\n• Docs: see docs/ (MkDocs) — Usage, API Reference, Bulk\n• Source: https://github.com/", "source": "github:agent-matrix/matrix-python-sdk/README.md"}
{"text": "r-side scoring and indexing.\nLinks\n• Docs: see docs/ (MkDocs) — Usage, API Reference, Bulk\n• Source: https://github.com/agent-matrix/matrix-python-sdk\n• Matrix Hub: https://github.com/agent-matrix/matrix-hub\n• License: Apache 2.0\nContributing\nWe welcome issues and PRs. Please read **CONTRIBUTING.md** before submitting changes.\nJoin us in shaping a fast, safe, and open ecosystem for AI agents, tools, and MCP servers.", "source": "github:agent-matrix/matrix-python-sdk/README.md"}
{"text": "API Reference\nSDK version: **0.1.9**\nScope: Hub catalog client • local installer (files, artifacts, env, runner discovery) • lightweight runtime\nThis SDK provides three pillars:\n1. **MatrixClient** — search the Hub, read entities, request install plans.\n2. **LocalInstaller** — materialize a plan locally (files, artifacts, env, runner.json).\n3. **runtime** — start/stop/list/tail/doctor local MCP servers (no daemon).\nNew in **0.1.9**\n* The installer has been refactored into a proper subpackage: matrix_sdk/installer/.\n* Backwards-compatible import: **from matrix_sdk.installer import LocalInstaller still works**.\n* More robust runner discovery (URLs, embedded manifests, shallow search, structural inference).\n* Environment prep parity with the legacy installer (Python venv + pip indices, Node P", "source": "github:agent-matrix/matrix-python-sdk/docs/api.md"}
{"text": "ow search, structural inference).\n* Environment prep parity with the legacy installer (Python venv + pip indices, Node PM autodetect).\n* New/expanded env toggles (see **Environment variables**).\nMatrixClient\n**Location**: matrix_sdk.client.MatrixClient\n**Errors**: raises matrix_sdk.client.MatrixError(status, detail) on non-2xx.\n**Notes**\n• entity(id) URL-encodes id internally.\n• install(id, target) calls Hub /catalog/install and returns the Hub payload (plan/results/etc).\n• Treat type=\"any\" (or None) as “no filter”.\nDeep links\n**Location**: matrix_sdk.deep_link\n**Errors**: InvalidMatrixUri for bad/unsupported URIs.\nRules:\n• Only matrix://install is supported.\n• id is **required**; alias must match ^[a-z0-9][a-z0-9._-]{0,63}$.\nLocalInstaller\n**Location**: matrix_sdk.installer.LocalInstaller", "source": "github:agent-matrix/matrix-python-sdk/docs/api.md"}
{"text": "quired**; alias must match ^[a-z0-9][a-z0-9._-]{0,63}$.\nLocalInstaller\n**Location**: matrix_sdk.installer.LocalInstaller\n**Data classes**: BuildReport, EnvReport, BuildResult\n**Other errors**: matrix_sdk.manifest.ManifestResolutionError, ArchiveFetchError, GitFetchError.\nPublic dataclasses (exact fields)\nLifecycle\n1. **plan(id, target)** → ask Hub for an install plan\n*Sends a server-safe target label by default (e.g. alias/version). Use MATRIX_INSTALL_SEND_ABS_TARGET=true to send the absolute path.*\n2. **materialize(outcome, target)** → write declared files, fetch artifacts, ensure/validate runner.json\n*Scans plan.files, results[].files, and top-level files. Supports content (text) and content_b64 (binary).*\n3. **prepare_env(target, runner)** → create .venv (Python) and/or run pnpm|yarn|np", "source": "github:agent-matrix/matrix-python-sdk/docs/api.md"}
{"text": "ent (text) and content_b64 (binary).*\n3. **prepare_env(target, runner)** → create .venv (Python) and/or run pnpm|yarn|npm install (Node)\n*Python: upgrades pip/setuptools/wheel; respects pip index envs; installs from runner.python.requirements, requirements.txt, or local project (pyproject.toml / setup.py) with optional editable mode. Node: auto-detects package manager from lockfiles unless overridden.*\n4. **build(id, …)** → runs all three steps and returns BuildResult.\nMethods (signatures & behavior)\nRunner discovery (strategy order)\nThe installer uses a deterministic chain and stops at the first valid result:\n1. plan.runner_b64 → decode → validate → write\n2. plan.runner_url (relative resolved against provenance) → fetch JSON → validate → write\n3. plan.runner (object) → validate → write\n4.", "source": "github:agent-matrix/matrix-python-sdk/docs/api.md"}
{"text": "url (relative resolved against provenance) → fetch JSON → validate → write\n3. plan.runner (object) → validate → write\n4. Embedded manifest (v2): manifest.runner → validate → write\n5. Embedded manifest (v1): extract server URL → synthesize **connector** runner (/sse) → write\n6. Local file: runner_file or runner.json\n7. Shallow BFS for runner.json (depth = MATRIX_SDK_RUNNER_SEARCH_DEPTH, default **2**)\n8. Manifest URL (plan.manifest_url or provenance.source_url), when MATRIX_SDK_ALLOW_MANIFEST_FETCH=true: fetch → parse → synthesize connector → write\n9. Structural inference: infer minimal python/node runner from files (e.g., server.py, package.json) → write\n10. Last-ditch: if *any* MCP/SSE URL hint is present, synthesize a minimal connector\nA valid **process** runner must include \"entry\" and ", "source": "github:agent-matrix/matrix-python-sdk/docs/api.md"}
{"text": "f *any* MCP/SSE URL hint is present, synthesize a minimal connector\nA valid **process** runner must include \"entry\" and \"type\": \"python\"|\"node\".\nA valid **connector** runner must include \"type\": \"connector\" and \"url\".\nruntime\n**Location**: matrix_sdk.runtime\n**State/Logs**: ~/.matrix/state/<alias>/runner.lock.json, ~/.matrix/logs/<alias>.log\n**Model**: LockInfo(pid:int, port:int|None, alias:str, target:str, started_at:float, runner_path:str)\n**Requirements**\n• runner.json must define at least: {\"type\": \"python\"|\"node\", \"entry\": \"…\"}\n• Python runners: venv Python must exist (created during prepare_env).\nArtifact fetchers\nHTTP archives\n**Location**: matrix_sdk.archivefetch\n**API**:\n• Safe ZIP/TAR extraction (no path traversal).\n• Optional flatten of GitHub-style single-folder archives.\nGit r", "source": "github:agent-matrix/matrix-python-sdk/docs/api.md"}
{"text": "**API**:\n• Safe ZIP/TAR extraction (no path traversal).\n• Optional flatten of GitHub-style single-folder archives.\nGit repos\n**Location**: matrix_sdk.gitfetch\n**API**:\n• HTTPS by default; host allow-list enforced (deny-by-default if none given).\n• Shallow clone, optional sparse subdir, optional LFS, optional commit verification.\nSchemas (Pydantic)\n**Location**: matrix_sdk.schemas\nModels mirror Hub responses; unknown fields are allowed.\n• SearchItem, SearchResponse\n• EntityDetail (extra fields allowed; includes manifest-ish + computed fields)\n• InstallStepResult, InstallOutcome\n• MatrixAPIError (generic error wrapper)\nExceptions\n• matrix_sdk.client.MatrixError(status, detail) — Hub non-2xx.\n• matrix_sdk.deep_link.InvalidMatrixUri — deep-link parse/validation errors.\n• matrix_sdk.manifest.Ma", "source": "github:agent-matrix/matrix-python-sdk/docs/api.md"}
{"text": "il) — Hub non-2xx.\n• matrix_sdk.deep_link.InvalidMatrixUri — deep-link parse/validation errors.\n• matrix_sdk.manifest.ManifestResolutionError — manifest/artifact integrity/host violations.\n• matrix_sdk.archivefetch.ArchiveFetchError — download/unpack errors.\n• matrix_sdk.gitfetch.GitFetchError — git materialization errors.\nEnvironment variables\nGeneral\n| Variable                         | Meaning                                                                           | Default   |\n| MATRIX_SDK_DEBUG               | Enables verbose DEBUG logging for installer/runtime/archivefetch.                 | off       |\n| MATRIX_HOME                    | Base dir for ~/.matrix (state/logs).                                            | user home |\n| MATRIX_INSTALL_SEND_ABS_TARGET | Send absolute ins", "source": "github:agent-matrix/matrix-python-sdk/docs/api.md"}
{"text": "ate/logs).                                            | user home |\n| MATRIX_INSTALL_SEND_ABS_TARGET | Send absolute install path to Hub during plan() (instead of server-safe label). | off       |\nInstaller — runner discovery\n| Variable                          | Meaning                                                             | Default     |\n| MATRIX_SDK_RUNNER_SEARCH_DEPTH  | Depth for shallow runner.json search.                             | 2         |\n| MATRIX_SDK_ALLOW_MANIFEST_FETCH | Permit fetching a remote manifest to synthesize a connector runner. | 1         |\n| MATRIX_SDK_MANIFEST_DOMAINS     | CSV allow-list of domains allowed for remote manifest fetches.      | (allow all) |\n| MATRIX_SDK_ENABLE_CONNECTOR     | Allow synthesizing connector runners from URL hints.          ", "source": "github:agent-matrix/matrix-python-sdk/docs/api.md"}
{"text": "      | (allow all) |\n| MATRIX_SDK_ENABLE_CONNECTOR     | Allow synthesizing connector runners from URL hints.                | 1         |\n| MATRIX_SDK_HTTP_TIMEOUT         | Network timeout (seconds) for installer fetches.                    | 15        |\nInstaller — Python deps\n| Variable                         | Meaning                                                 | Default     |\n| MATRIX_SDK_PIP_INDEX_URL       | Primary pip index URL.                                  | pip default |\n| MATRIX_SDK_PIP_EXTRA_INDEX_URL | Extra pip index URL.                                    | none        |\n| MATRIX_SDK_PIP_EDITABLE        | Install local project as editable (pip install -e .). | 1         |\nGit fetcher\n| Variable                    | Meaning                             | Default   ", "source": "github:agent-matrix/matrix-python-sdk/docs/api.md"}
{"text": "nstall -e .). | 1         |\nGit fetcher\n| Variable                    | Meaning                             | Default      |\n| MATRIX_GIT_ALLOWED_HOSTS  | CSV allow-list for git clone hosts. | common hosts |\n| MATRIX_GIT_ALLOW_INSECURE | Allow http:// git (discouraged).  | off          |\n| MATRIX_SDK_DEBUG_GIT      | Extra git logs.                     | off          |\nSearch\n**Location**: matrix_sdk.search\n**Purpose**: Thin, defensive wrappers around GET /catalog/search with normalization, small retries, and optional mode fallbacks.\nsearch(...)\n**Behavior**\n• Normalizes filters (lists/sets → CSV), clamps limit.\n• Retries transient 5xx/network errors with exponential backoff.\n• Optional **fallback chain** across modes (e.g., semantic → hybrid → keyword) when no results.\n• Returns a dict by", "source": "github:agent-matrix/matrix-python-sdk/docs/api.md"}
{"text": "off.\n• Optional **fallback chain** across modes (e.g., semantic → hybrid → keyword) when no results.\n• Returns a dict by default, or a typed SearchResponse if options.as_model=True.\n**Example**\nSearchOptions\nDefaults:\n• If fallback_order is not provided, the helper picks a sensible chain based on the initial mode.\n• max_attempts applies to each HTTP attempt (initial + each fallback).\nsearch_try_modes(...)\nEnd-to-end example\nCompatibility notes (0.1.9)\n• The legacy matrix_sdk/installer.py module has been split into the **matrix_sdk/installer/** package.\n• Import **compatibility is preserved**: from matrix_sdk.installer import LocalInstaller (and the dataclasses) still works.\n• A few helpers are also re-exported for downstream compatibility:\n_is_valid_runner_schema, _ensure_sse_url, _url_fro", "source": "github:agent-matrix/matrix-python-sdk/docs/api.md"}
{"text": "s.\n• A few helpers are also re-exported for downstream compatibility:\n_is_valid_runner_schema, _ensure_sse_url, _url_from_manifest, _extract_mcp_sse_url, _coerce_runner_to_legacy_process.\nRequirements\n• Python **3.11 – 3.12** (per pyproject.toml).", "source": "github:agent-matrix/matrix-python-sdk/docs/api.md"}
{"text": "Bulk Registration\nThe SDK includes a tiny, async **Bulk Registrar** that discovers MCP servers in a repo (or ZIP) and registers them into an **MCP Gateway Admin API** (e.g., http://localhost:4444). It’s optional and independent of the Hub.\n!!! note\nThe registrar **does not** modify your local project. It discovers manifests and calls your **Gateway Admin API** to create/update server entries.\nWhat it does (in one picture)\n1. **Discovery (matrix-first)**\n• If a matrix/ folder exists, read:\n• matrix/index.json (list of servers **or** list of manifest paths), and/or\n• matrix/*.manifest.json\n• Else, fall back to pyproject.toml → [tool.mcp_server].\n2. **Normalize → Manifest**\n• Convert discovery into a canonical ServerManifest (Pydantic v1/v2 compatible).\n3. **Register (upsert)**\n• POST to your", "source": "github:agent-matrix/matrix-python-sdk/docs/bulk.md"}
{"text": "• Convert discovery into a canonical ServerManifest (Pydantic v1/v2 compatible).\n3. **Register (upsert)**\n• POST to your Gateway’s Admin endpoint:\n• Try **JSON** first.\n• If the gateway rejects JSON with 422/400/415 (e.g. “Missing required field: 'name'”), auto-fallback to **form URL-encoded** with a sanitized name.\n4. **Resilience**\n• Idempotency key (SHA256 of manifest payload).\n• Concurrency + exponential backoff.\n• Optional **capability probe** (best-effort GET ${endpoint}/capabilities).\nQuickstart (Python)\nTypical successful result item from the gateway:\nCLI usage (module)\nYou can invoke the registrar via the module entrypoint:\n**Alternate sources**\n**Optional flags**\n• --concurrency 20 – number of parallel registrations\n• --no-probe – disable capability probing\n• --env-file .env.loca", "source": "github:agent-matrix/matrix-python-sdk/docs/bulk.md"}
{"text": "*\n• --concurrency 20 – number of parallel registrations\n• --no-probe – disable capability probing\n• --env-file .env.local – load env first (KEY=VALUE lines)\nSource descriptor schema\nA **source** describes where to discover manifests.\n| Field   | Type | Required        | Example                                           |\n| kind  | enum | yes             | \"zip\" \\| \"git\" \\| \"dir\"                     |\n| path  | str  | for zip/dir | /abs/path/repo.zip or /abs/path/repo          |\n| url   | str  | for git       | https://github.com/IBM/docling-mcp.git          |\n| ref   | str  | optional (git)  | main / tag / SHA                                |\n| probe | bool | optional        | true (default) – try ${endpoint}/capabilities |\nYou can pass **multiple** sources; the registrar handles each (wit", "source": "github:agent-matrix/matrix-python-sdk/docs/bulk.md"}
{"text": "    | true (default) – try ${endpoint}/capabilities |\nYou can pass **multiple** sources; the registrar handles each (with overall concurrency control).\nHow discovery works\n1. **Matrix folder (preferred)**\n• matrix/index.json can be:\n• An **array of strings** (each a path to *.manifest.json under matrix/), or\n• An **array of objects** with \"type\": \"mcp_server\" and server fields.\n• Any matrix/*.manifest.json is also read.\n2. **Fallback: pyproject.toml**\n• [tool.mcp_server] block is mapped to a ServerManifest.\n• Endpoint is normalized to:\nRegistration behavior\n• **JSON first**, then **auto-fallback to form** if the gateway says your JSON is invalid for the legacy “create” route:\n• Common signal: HTTP 422 with \"Missing required field: 'name'\" or \"Invalid name\".\n• **Name sanitization** (for the", "source": "github:agent-matrix/matrix-python-sdk/docs/bulk.md"}
{"text": "ute:\n• Common signal: HTTP 422 with \"Missing required field: 'name'\" or \"Invalid name\".\n• **Name sanitization** (for the form fallback):\n• Allowed: letters, digits, underscore (_), dot (.), hyphen (-), spaces.\n• Disallowed chars are removed, whitespace is collapsed, and result is trimmed to 255 chars.\n• If empty after cleaning, a stable fallback like server-<hash> is used.\n**Idempotency**\n• For each manifest, the registrar computes a SHA256 idempotency key from the JSON payload (sorted keys).\n• You can safely re-run without creating duplicates (server-side must support idempotency).\n**Concurrency & backoff**\n• Overall concurrency is bound by a semaphore (configurable).\n• Each upsert uses exponential backoff with jitter (defaults: max_retries=5, base_delay=1.0s).\n**Capability probe (optiona", "source": "github:agent-matrix/matrix-python-sdk/docs/bulk.md"}
{"text": "Each upsert uses exponential backoff with jitter (defaults: max_retries=5, base_delay=1.0s).\n**Capability probe (optional)**\n• If enabled, for HTTP/SSE endpoints the registrar **GETs** ${endpoint.url}/capabilities and merges the returned list into capabilities.\nEnvironment variables\nYou can control the CLI/script by env vars (all optional):\n| Variable                   | Meaning                                                           | Default                 |\n| GATEWAY_URL              | Admin API base URL                                                | http://localhost:4444 |\n| ADMIN_TOKEN              | Bearer token (alternates: GATEWAY_TOKEN, GATEWAY_ADMIN_TOKEN) | *(none)*                |\n| ZIP_PATH                 | Path to local ZIP                                              ", "source": "github:agent-matrix/matrix-python-sdk/docs/bulk.md"}
{"text": "| *(none)*                |\n| ZIP_PATH                 | Path to local ZIP                                                 | *(none)*                |\n| DIR_PATH                 | Path to local directory                                           | *(none)*                |\n| GIT_URL                  | Git repo URL                                                      | *(none)*                |\n| GIT_REF                  | Git ref                                                           | main                  |\n| CONCURRENCY              | Parallel registrations                                            | 10 (CLI)              |\n| PROBE                    | true/false capability probing                                 | true                  |\n| ENV_FILE / DOTENV_FILE | Path to .env to l", "source": "github:agent-matrix/matrix-python-sdk/docs/bulk.md"}
{"text": "apability probing                                 | true                  |\n| ENV_FILE / DOTENV_FILE | Path to .env to load first                                      | .env.local            |\nReturn shape\nBulkRegistrar.register_servers(sources) returns a **flat list** of results (one per discovered manifest). Each item is either:\nor an error wrapper, e.g.:\nTroubleshooting\n**HTTP 401/403 (Unauthorized/Forbidden)**\n→ Set ADMIN_TOKEN (or GATEWAY_TOKEN / GATEWAY_ADMIN_TOKEN).\n**HTTP 422 “Missing required field: 'name'” or “Invalid name”**\n→ Your gateway expects **form fields** and a sanitized name. The client will fallback to form automatically and clean the name. If you still see the error, your original name/id may be empty; discovery will synthesize a safe fallback.\n**AnyUrl is not JSON se", "source": "github:agent-matrix/matrix-python-sdk/docs/bulk.md"}
{"text": "ll see the error, your original name/id may be empty; discovery will synthesize a safe fallback.\n**AnyUrl is not JSON serializable**\n→ You’re likely bypassing the provided models. The registrar already serializes models into JSON-safe dicts; don’t send raw Pydantic types to httpx.\n**RuntimeWarning: 'matrix_sdk.bulk.cli' in sys.modules…**\n→ Ensure matrix_sdk/bulk/__init__.py doesn’t import cli. Keep it minimal:\n**Git clone failures**\n→ Prefer a local ZIP (ZIP_PATH) to avoid any network/git issues.\nSecurity notes\n• Only run against Gateways you control. The registrar sends **Bearer tokens** to the URL you provide.\n• If you store tokens in .env files, protect those files (e.g., don’t commit them).\n• The registrar does **not** execute arbitrary code in the repo; it reads manifests and TOML/JSO", "source": "github:agent-matrix/matrix-python-sdk/docs/bulk.md"}
{"text": "g., don’t commit them).\n• The registrar does **not** execute arbitrary code in the repo; it reads manifests and TOML/JSON files.\nMinimal API reference\nclass BulkRegistrar\n• register_servers(sources: Iterable[dict]) -> list[Any]\nDiscovers manifests for each source and upserts them concurrently, returning a flat list of results/errors.\nSource kinds\n• {\"kind\": \"zip\", \"path\": \"/path/repo.zip\", \"probe\": true}\n• {\"kind\": \"dir\", \"path\": \"/path/repo\", \"probe\": true}\n• {\"kind\": \"git\", \"url\": \"https://...\", \"ref\": \"main\", \"probe\": true}\nWorked examples\n**Register a local ZIP**\n**Register docling-mcp (Git)**\n**Script example**\nCompatibility\n• **Python**: 3.10+\n• **Pydantic**: v1 *or* v2 (the models handle both)\n• **httpx**: 0.27+\nIf your Gateway’s Admin API only supports form POSTs, the registrar wil", "source": "github:agent-matrix/matrix-python-sdk/docs/bulk.md"}
{"text": "* v2 (the models handle both)\n• **httpx**: 0.27+\nIf your Gateway’s Admin API only supports form POSTs, the registrar will **automatically switch** after a JSON attempt fails with a recognizable error.\nSee Usage for more scenarios.", "source": "github:agent-matrix/matrix-python-sdk/docs/bulk.md"}
{"text": "Configuration\nYou configure the SDK by **passing options at construction time**. We recommend keeping secrets/URLs in environment variables and reading them in your app.\nEnvironment variables (recommended)\nCreate a .env or export variables in your shell:\nThen load them in Python (e.g., with os.getenv or python-dotenv) and pass to the client.\nMatrixClient (Hub)\nUsed for search, detail, install, and (optionally) remote/ingest admin.\nCommon usage\nBulk Registrar (Gateway) — optional\nIf you also manage a Gateway, the SDK can **bulk-register** MCP servers you host. This is independent of the Hub client.\nRequired env\nOptional env (source + behavior)\nMinimal Python setup\n**Notes**\n• **Discovery (matrix-first):** the registrar looks for matrix/index.json or matrix/*.manifest.json. If none are prese", "source": "github:agent-matrix/matrix-python-sdk/docs/config.md"}
{"text": "*\n• **Discovery (matrix-first):** the registrar looks for matrix/index.json or matrix/*.manifest.json. If none are present, it falls back to [tool.mcp_server] in pyproject.toml.\n• **Gateway compatibility:** the client POSTs **JSON** first; if your gateway expects form data on /admin/servers, it **auto-falls back** to URL-encoded form and **sanitizes name** to match gateway rules.\n• **Idempotency & resilience:** a stable idempotency key (SHA-256 of the manifest) prevents duplicates; requests use concurrency and exponential backoff with jitter.\nAdvanced configuration\nTimeouts and sessions\nMatrixClient accepts a timeout (seconds) and an optional pre-configured httpx.Client session:\nIf you pass token=..., the client sets Authorization: Bearer <token> automatically.\nRoute overrides (if your Hub", "source": "github:agent-matrix/matrix-python-sdk/docs/config.md"}
{"text": "ession:\nIf you pass token=..., the client sets Authorization: Bearer <token> automatically.\nRoute overrides (if your Hub paths differ)\nCaching (ETag-aware)\nThe SDK ships a tiny in-memory cache that honors ETags for /catalog/search. It avoids re-downloading unchanged results and can speed up repeated queries.\n**Notes**\n• The cache stores response bodies and ETags keyed by request parameters.\n• If the server returns **304 Not Modified**, the SDK serves the cached body.\n• You can swap in your own cache implementation as long as it provides:\n• make_key(path: str, params: dict) -> str\n• get_etag(key: str) -> str | None\n• get_body(key: str) -> dict | None\n• save(key: str, *, etag: str | None, body: dict) -> None\nProxies and TLS\nhttpx honors HTTP_PROXY / HTTPS_PROXY / NO_PROXY. Example:\nOr pass p", "source": "github:agent-matrix/matrix-python-sdk/docs/config.md"}
{"text": "ag: str | None, body: dict) -> None\nProxies and TLS\nhttpx honors HTTP_PROXY / HTTPS_PROXY / NO_PROXY. Example:\nOr pass proxies to your httpx.Client.\nError handling\nThe client raises MatrixError on non-2xx responses or network errors:\n• HTTP errors → MatrixError(status=<http code>, detail=<server message>)\n• Timeouts / connection issues → MatrixError(status=0, detail=\"timeout\" or similar)\nServer-side tip (Hub admins)\nTo produce absolute links (e.g., manifest_url, install_url) behind a proxy/CDN, set the Hub’s environment variable:\nThis is **not** an SDK setting, but it affects the links you receive from the Hub.", "source": "github:agent-matrix/matrix-python-sdk/docs/config.md"}
{"text": "Contributing\nThank you for your interest!\n• Please submit issues/feature requests on GitHub.\n• See CONTRIBUTING.md for coding standards, branch policy, and more.\n• All contributions require tests and clear documentation.\nCode of Conduct\nWe follow the Contributor Covenant.\nDev setup\n• Install pre-commit hooks:\n• Run tests:", "source": "github:agent-matrix/matrix-python-sdk/docs/contributing.md"}
{"text": "matrix-python-sdk\n**matrix-python-sdk** is the official Python SDK for \\[Matrix Hub] — the open catalog and installer for **agents**, **tools**, and **MCP servers**.\nIt gives teams a *single, dependable path* to **discover**, **evaluate**, **install**, and **run** AI components. Whether you’re curating a marketplace, wiring up internal tools, or shipping end-user assistants, this SDK helps you move from *“I think I need X”* to *“X is installed, configured, and running”* in minutes.\nWhy it matters\n• **One interface for many ecosystems.** Agents, tools, and MCP servers are published in different places and formats. Matrix Hub normalizes them; this SDK makes them easy to query and install.\n• **Reproducible installs.** The Hub returns concrete install plans and lockfiles; the SDK materializes ", "source": "github:agent-matrix/matrix-python-sdk/docs/index.md"}
{"text": "ry and install.\n• **Reproducible installs.** The Hub returns concrete install plans and lockfiles; the SDK materializes them safely and consistently.\n• **Built for production.** Secure archive extraction, Git host allow-lists, optional ETag caching, typed models, and careful retries mean fewer surprises in CI and prod.\n• **Scales as your catalog grows.** Efficient search helpers (keyword/semantic/hybrid) with normalization and fallback keep UX fast even as catalogs reach millions of entries (the heavy lifting stays server-side).\nWhat this package offers\n• **Ergonomic client** (MatrixClient) to call Hub APIs: search, entity, install, and catalog remotes.\n• **Search helpers** (matrix_sdk.search) with filter normalization, small retries, and *mode fallbacks* (semantic → hybrid → keyword).\n• *", "source": "github:agent-matrix/matrix-python-sdk/docs/index.md"}
{"text": "** (matrix_sdk.search) with filter normalization, small retries, and *mode fallbacks* (semantic → hybrid → keyword).\n• **Local installer** (matrix_sdk.installer.LocalInstaller) to fetch artifacts, write adapters, and prepare runtime environments.\n• **Lightweight runtime** (matrix_sdk.runtime) to start/stop/list/tail/doctor local MCP servers—no daemon required.\n• **Bulk registrar** (matrix_sdk.bulk.*, optional) to discover manifests (ZIP/dir/Git) and register MCP servers into a Gateway with idempotency and capability probing.\nInstall\nQuickstart — Search & install\nQuickstart — Run locally\nAdvanced search (helper)\nPrefer the high-level helper when you want resilience and typed results.\n**Why use the helper?**\n• Normalizes filters (lists/sets → CSV), clamps limits, and retries transient errors", "source": "github:agent-matrix/matrix-python-sdk/docs/index.md"}
{"text": "ed results.\n**Why use the helper?**\n• Normalizes filters (lists/sets → CSV), clamps limits, and retries transient errors with jittered backoff.\n• Smart mode fallbacks avoid user-visible “empty” results when semantic indices aren’t available in dev.\n• Optional typed responses (SearchResponse) for ergonomic, safe code.\nBulk registration (optional)\nDiscover MCP server manifests and register them into a Gateway Admin API.\n**Highlights**\n• **Matrix-first discovery:** looks for matrix/index.json or matrix/*.manifest.json; falls back to pyproject.toml.\n• **Gateway compatibility:** JSON first; auto-fallback to form with safe name sanitization.\n• **Resilience:** concurrency control, idempotency keys, exponential backoff with jitter.\nDesign values\n• **Reliability:** strict error types, small safe re", "source": "github:agent-matrix/matrix-python-sdk/docs/index.md"}
{"text": "l, idempotency keys, exponential backoff with jitter.\nDesign values\n• **Reliability:** strict error types, small safe retries, idempotent bulk writes, ETag-aware client cache.\n• **Security by default:** safe archive extraction, Git host allow-lists, deny-by-default where sensible.\n• **Performance:** lightweight client, normalized query params, and server-side scoring/indexing.\n• **Compatibility:** Pydantic v1/v2 models, tolerant schema (unknown fields allowed), portable runtime.\nDocs\n• Installation\n• Configuration\n• Usage\n• API Reference\n• Bulk Registration\n*matrix-python-sdk* helps you move faster from **idea → discovery → install → run** with production-grade guardrails and a clean, Pythonic API.", "source": "github:agent-matrix/matrix-python-sdk/docs/index.md"}
{"text": "Installation\nFrom PyPI\nRequires Python 3.10+.\nFrom source\nUpgrade\nOptional extras\n• httpx (installed): HTTP client used by the SDK.\n• pydantic (installed): typed models for responses.\n• pyyaml (optional): enables fetch_manifest() to parse YAML manifests.", "source": "github:agent-matrix/matrix-python-sdk/docs/install.md"}
{"text": "Reference (v0.1.9)\nA quick map of the primary modules and entry points.\nCore\n• matrix_sdk.client.MatrixClient — Hub API client\nMethods: search(), entity(), install(), list_remotes(), add_remote(), delete_remote(), trigger_ingest()\n• matrix_sdk.installer.LocalInstaller — local install orchestration\nReturns: BuildReport, EnvReport, BuildResult\n• matrix_sdk.runtime — run local MCP servers\nFunctions: start(), stop(), status(), doctor(), tail_logs(), log_path()\nInstaller helpers\n• Runner schema & discovery (re-exported):\n• _is_valid_runner_schema(runner, logger)\n• _coerce_runner_to_legacy_process(obj)\n• _ensure_sse_url(url)\n• _url_from_manifest(manifest)\n• _extract_mcp_sse_url(node)\nArtifact fetchers\n• matrix_sdk.archivefetch — fetch_http_artifact, ArchiveFetchError\n• matrix_sdk.gitfetch — fetc", "source": "github:agent-matrix/matrix-python-sdk/docs/reference.md"}
{"text": "(node)\nArtifact fetchers\n• matrix_sdk.archivefetch — fetch_http_artifact, ArchiveFetchError\n• matrix_sdk.gitfetch — fetch_git_artifact, GitFetchError\nModels\n• matrix_sdk.schemas — Pydantic models for Hub responses\n(SearchItem, SearchResponse, EntityDetail, InstallOutcome, etc.)\nExceptions\n• matrix_sdk.client.MatrixError\n• matrix_sdk.manifest.ManifestResolutionError\n• matrix_sdk.archivefetch.ArchiveFetchError\n• matrix_sdk.gitfetch.GitFetchError\nEnv toggles (common)\n• MATRIX_SDK_DEBUG=1\n• MATRIX_SDK_HTTP_TIMEOUT=15\n• MATRIX_SDK_RUNNER_SEARCH_DEPTH=2\n• MATRIX_SDK_ALLOW_MANIFEST_FETCH=1\n• MATRIX_SDK_ENABLE_CONNECTOR=1", "source": "github:agent-matrix/matrix-python-sdk/docs/reference.md"}
{"text": "Usage (v0.1.9)\nQuick, copy-pasteable examples for searching the Hub, installing locally, and (optionally) running a server.\nRequires **Python 3.11+**.\n1) Quick search\n**Tip:** prefer the high-level helper below for tiny retries and optional fallbacks.\n2) Install & build locally\nThe build step: 1) requests a plan, 2) writes files/artifacts, 3) ensures runner.json, 4) prepares envs.\n3) Run locally (no daemon)\n**Connector / attach mode:** if runner.json contains {\"type\":\"connector\",\"url\":\"http://127.0.0.1:6288/sse\"}, runtime.start(...) **does not** spawn a process; it records the URL in the lock (pid=0). Use your MCP client to talk to that endpoint directly.\n4) Advanced search helper\n5) Manage catalog remotes\n6) Bulk registration (Gateway, optional)\n7) Error handling\nEnvironment variables (qu", "source": "github:agent-matrix/matrix-python-sdk/docs/usage.md"}
{"text": "ch helper\n5) Manage catalog remotes\n6) Bulk registration (Gateway, optional)\n7) Error handling\nEnvironment variables (quick reference)\n• MATRIX_SDK_DEBUG=1 — verbose logs (installer/runtime/search/etc.).\n• MATRIX_HOME — base dir for state/logs (default: ~/.matrix).\n• MATRIX_SDK_ENABLE_CONNECTOR=1 — allow connector runner synthesis (default **on**).\n• MATRIX_SDK_HTTP_TIMEOUT — network timeout (seconds; default **15**).", "source": "github:agent-matrix/matrix-python-sdk/docs/usage.md"}
{"text": "⚡️ MatrixLink Suite\n*Production toolkit for **MatrixHub** — discover, select, and run MCP servers (orchestrators) and A2A agents across any cloud.*\n<p align=\"left\">\n<a href=\"https://pypi.org/project/matrixlink/\"><img alt=\"PyPI Version\" src=\"https://img.shields.io/pypi/v/matrixlink.svg\"></a>\n<a href=\"https://pypi.org/project/matrixlink/\"><img alt=\"Python Versions\" src=\"https://img.shields.io/pypi/pyversions/matrixlink.svg\"></a>\n<a href=\"https://github.com/agent-matrix/matrixlink\"><img alt=\"GitHub\" src=\"https://img.shields.io/badge/github-matrixlink--suite?logo=github\"></a>\n<a href=\"https://agent-matrix.github.io/matrixlink/\"><img alt=\"Docs (MkDocs)\" src=\"https://img.shields.io/badge/docs-mkdocs--material-blue?logo=mkdocs\"></a>\n<a href=\"./LICENSE\"><img alt=\"License: Apache-2.0\" src=\"https://", "source": "github:agent-matrix/matrixlink/README.md"}
{"text": "s.io/badge/docs-mkdocs--material-blue?logo=mkdocs\"></a>\n<a href=\"./LICENSE\"><img alt=\"License: Apache-2.0\" src=\"https://img.shields.io/badge/license-Apache%202.0-blue\"></a>\n<a href=\"https://github.com/agent-matrix/matrix-hub\"><img alt=\"Powered by matrix-hub\" src=\"https://img.shields.io/badge/Powered%20by-matrix--hub-brightgreen\"></a>\nRequires **Python 3.11+**. Library published as **matrixlink** on PyPI. BFF/UI run on **:8080**.\nMatrixLink Suite gives you a production-ready base to run **MCP Gateway + Orchestrators (MCP Servers) + A2A Agents** on any modern platform (IBM Code Engine, Google Cloud Run, AWS App Runner, Azure Container Apps, Knative/K8s, Local). It includes:\n• libs/matrixlink/ — PyPI-ready client for MCP discovery, A2A messaging, and Orchestrator invocation\n• apps/bff/ — Fron", "source": "github:agent-matrix/matrixlink/README.md"}
{"text": "\n• libs/matrixlink/ — PyPI-ready client for MCP discovery, A2A messaging, and Orchestrator invocation\n• apps/bff/ — Front Door (FastAPI) exposing a clean /api/* surface with admin & MCP proxy\n• ui/matrixhub-admin/ — Minimal React admin (read-only) for MCP servers & agents\n• infra/ce/ — IBM Code Engine scripts for apps + secrets\n• Makefile — Dev & ops targets (make help)\nAll services bind to port **8080**. East–west calls use **Bearer service tokens** (optionally mTLS).\n**Default provider = local**. No external services are required to run BFF + UI locally.\nWhat are MatrixHub and MatrixLink?\n**MatrixHub** is an *internet-scale hub* and search engine (think **PyPI for AI agents & MCP servers**). You use it to discover high-quality agents/orchestrators by **capability** (skills, flows), **tru", "source": "github:agent-matrix/matrixlink/README.md"}
{"text": "ents & MCP servers**). You use it to discover high-quality agents/orchestrators by **capability** (skills, flows), **trust** (publisher, SBOM/attestation), and **fitness** (success rate, latency, region). Import chosen entries into your org’s private catalog with the right **visibility** and **policy**.\n**MatrixLink** is the runtime connector: a tiny client library plus an optional BFF that makes **discovery and invocation portable** across clouds. It lets your code:\n• Discover agents by **skill** via your **MCP Gateway**\n• Call agents with a simple **A2A** contract (/message/send, optional SSE)\n• Invoke orchestrators (/invoke/<flow>) with tenancy headers & bearer auth\n• Auto-resolve service endpoints via environment variables (no code edits per provider)\n**Together**: *discover globally, ", "source": "github:agent-matrix/matrixlink/README.md"}
{"text": "Auto-resolve service endpoints via environment variables (no code edits per provider)\n**Together**: *discover globally, run locally*. You pick building blocks from MatrixHub; MatrixLink wires them into your environment safely and repeatably.\nArchitecture\n**Public API (edge):**\n| Path                                        | Target       | Notes                              |\n| GET /api/health                           | BFF          | liveness                           |\n| GET /api/ready                            | BFF          | readiness (+ MCP health)           |\n| POST /api/chat / /api/flows/*         | Orchestrator | main chat/flow entrypoint          |\n| /api/mcp/*                                | BFF → MCP    | proxied, secured                   |\n| /api/admin/*                    ", "source": "github:agent-matrix/matrixlink/README.md"}
{"text": "                                | BFF → MCP    | proxied, secured                   |\n| /api/admin/*                              | BFF          | agents CRUD/run, secured           |\nRepository layout\nRequirements\n• Python 3.10+\n• Node 18+ (UI)\n• Docker (for container builds)\n• Optional: IBM Cloud CLI for Code Engine deploys\nQuickstart (local)\n**1) Run the BFF (Front Door)**\n**2) Run the Admin UI**\nFor local testing, set export ADMIN_BEARER=changeme-admin-bearer-token and use the same in the UI Settings.\nWhen do I need an MCP Gateway?\nMatrixLink’s BFF and UI run fine **without** MCP for basic health/admin. You’ll want an **MCP Gateway** when you need:\n• **Runtime discovery** of agents/orchestrators by skill/tags\n• **Central registry** + **RBAC** and **visibility** per team/tenant\n• **Heal", "source": "github:agent-matrix/matrixlink/README.md"}
{"text": "ry** of agents/orchestrators by skill/tags\n• **Central registry** + **RBAC** and **visibility** per team/tenant\n• **Health & fitness** signals (route only to healthy entries)\n• **Controlled rollouts** (blue/green, canary via tags)\n**Local dev:** you can run a lightweight MCP Gateway on http://localhost:4444. In cloud, point MCP_BASE_URL to your managed MCP instance (or resolve via DOMAIN_SUFFIX+MCP_SERVICE_NAME).\nEnvironment variables\n**BFF**\n• ADMIN_BEARER — token to guard /api/admin/* and /api/mcp/*\n• MCP_BASE_URL — MCP Gateway URL (defaults to http://localhost:4444 for CLOUD_PROVIDER=local)\n• MCP_BEARER_TOKEN — service token to call MCP Gateway\n• AGENTS_BASE_URL — optional static base for agents (fan-in host)\n• AGENTS_API_TOKEN — east–west bearer for agent invocations\n**MatrixLink lib**", "source": "github:agent-matrix/matrixlink/README.md"}
{"text": "onal static base for agents (fan-in host)\n• AGENTS_API_TOKEN — east–west bearer for agent invocations\n**MatrixLink lib**\n• CLOUD_PROVIDER — local (default), ce, gcrun, apprunner, aca, knative\n• DOMAIN_SUFFIX — e.g. proj.region.codeengine.appdomain.cloud\n• MCP_SERVICE_NAME — default mcp-gateway\n• ORCH_SERVICE_NAME — default orchestrator\n• AGENTS_DOMAIN_PREFIX — default agents\n• MCP_BASE_URL, ORCH_BASE_URL, AGENTS_BASE_URL — explicit overrides\n• MCP_BEARER_TOKEN, A2A_SERVICE_TOKEN, TENANT_HEADER, REQUEST_TIMEOUT\nUsing MatrixLink (Python)\nInstall locally from repo:\nOr from PyPI (after you publish):\n**Discover an agent by skill (via MCP Gateway)**\n**Send data to an A2A agent**\n**Invoke an orchestrator (MCP Server) flow**\nAdmin API (BFF)\n| Method | Path | Secured? | Purpose |\n| GET | /api/healt", "source": "github:agent-matrix/matrixlink/README.md"}
{"text": "*\n**Invoke an orchestrator (MCP Server) flow**\nAdmin API (BFF)\n| Method | Path | Secured? | Purpose |\n| GET | /api/health | ❌ | Liveness |\n| GET | /api/ready | ❌ | Readiness (+ MCP health) |\n| GET | /api/mcp/servers | ✅ | MCP servers list (proxy) |\n| GET | /api/mcp/tools | ✅ | MCP tools list (proxy) |\n| POST | /api/mcp/servers | ✅ | Create MCP server (proxy) |\n| GET | /api/admin/agents | ✅ | List agents |\n| POST | /api/admin/agents | ✅ | Create agent |\n| POST | /api/admin/agents/{id}/bind | ✅ | Bind agent → catalog URL |\n| POST | /api/admin/agents/{id}/run | ✅ | Invoke an agent by name |\nSecure = requires Authorization: Bearer ${ADMIN_BEARER}.\nDocker\n**BFF**\n**Admin UI**\nDeploy on IBM Code Engine (example)\n1.  **Create secrets** (fill tokens first):\n./infra/secrets/create-secrets.sh\n2.  **", "source": "github:agent-matrix/matrixlink/README.md"}
{"text": "Deploy on IBM Code Engine (example)\n1.  **Create secrets** (fill tokens first):\n./infra/secrets/create-secrets.sh\n2.  **Build & push images**:\nmake docker-build-bff docker-build-ui\nmake docker-push-bff docker-push-ui\n3.  **Create apps**:\nmake ce-create-bff\nmake ce-create-ui\n4.  **API Gateway routes**:\n• /api/health|/api/ready|/api/admin/*|/api/mcp/* -> BFF\n• /api/chat (or /api/flows/<flow>)               -> Orchestrator (separate repo/app)\nOther providers (env presets)\n**Google Cloud Run** (custom domains recommended)\n**AWS App Runner**\n**Azure Container Apps**\n**Knative / K8s**\n**Local / Docker Compose + Traefik**\nSecurity & Ops\n• **Secrets**: store tokens in provider secret stores; never in images\n• **Auth**: OIDC/JWT at edge for /api/chat; ADMIN_BEARER for admin proxy; service Bearer fo", "source": "github:agent-matrix/matrixlink/README.md"}
{"text": "cret stores; never in images\n• **Auth**: OIDC/JWT at edge for /api/chat; ADMIN_BEARER for admin proxy; service Bearer for east–west\n• **Observability**: structured logs with X-Request-ID / X-Tenant-Id; add OTEL exporters if desired\n• **SSE**: ensure the API Gateway does not buffer /stream responses\n• **Scaling**: BFF & MCP Gateway minScale=1; Orchestrators/Agents can scale to 0\n• **DB**: BFF uses SQLite for dev; switch to a managed DB in prod via DATABASE_URL\nMake targets\nTroubleshooting\n• **ModuleNotFoundError: matrixlink** when running BFF locally → run make install.\n• **MCP base URL not set** → set MCP_BASE_URL or use CLOUD_PROVIDER + DOMAIN_SUFFIX + MCP_SERVICE_NAME.\n• **CORS** → set CORS_ALLOW_ORIGINS in BFF (e.g., http://localhost:3000).\n• **401 on admin routes** → set ADMIN_BEARER a", "source": "github:agent-matrix/matrixlink/README.md"}
{"text": "• **CORS** → set CORS_ALLOW_ORIGINS in BFF (e.g., http://localhost:3000).\n• **401 on admin routes** → set ADMIN_BEARER and pass Authorization: Bearer <token> from the UI.\nLicense\nApache 2.0 — see LICENSE.", "source": "github:agent-matrix/matrixlink/README.md"}
{"text": "API\nPublic endpoints (via BFF & Orchestrator)\n| Method | Path | Description |\n| GET | /api/health | Liveness |\n| GET | /api/ready | Readiness (+ MCP health) |\n| POST | /api/chat | Main chat entrypoint (edge → orchestrator) |\nAdmin endpoints (BFF)\n| Method | Path | Secured | Description |\n| GET | /api/mcp/servers | ✅ | Proxy list MCP servers |\n| GET | /api/mcp/tools | ✅ | Proxy list MCP tools |\n| POST | /api/mcp/servers | ✅ | Create MCP server (proxy) |\n| GET | /api/admin/agents | ✅ | List agents (local DB) |\n| POST | /api/admin/agents | ✅ | Create agent |\n| POST | /api/admin/agents/{id}/bind | ✅ | Bind agent → catalog URL |\n| POST | /api/admin/agents/{id}/run | ✅ | Invoke agent by name |", "source": "github:agent-matrix/matrixlink/docs/api.md"}
{"text": "Configuration\nEnvironment variables (BFF)\n• ADMIN_BEARER\n• MCP_BASE_URL\n• MCP_BEARER_TOKEN\n• AGENTS_BASE_URL\n• AGENTS_API_TOKEN\nEnvironment variables (MatrixLink)\n• CLOUD_PROVIDER — local|ce|gcrun|apprunner|aca|knative\n• DOMAIN_SUFFIX — e.g. proj.region.codeengine.appdomain.cloud\n• MCP_SERVICE_NAME — default mcp-gateway\n• ORCH_SERVICE_NAME — default orchestrator\n• AGENTS_DOMAIN_PREFIX — default agents\n• MCP_BASE_URL, ORCH_BASE_URL, AGENTS_BASE_URL\n• MCP_BEARER_TOKEN, A2A_SERVICE_TOKEN, TENANT_HEADER, REQUEST_TIMEOUT\nProvider presets", "source": "github:agent-matrix/matrixlink/docs/configuration.md"}
{"text": "Deploy\nIBM Code Engine\n1. Create secrets:\n2. Build & push images:\n3. Create apps:\n4. Configure API Gateway routes:\n• /api/health|/api/ready|/api/admin/*|/api/mcp/* -> BFF\n• /api/chat (or /api/flows/<flow>)               -> Orchestrator\nOther providers\nUse env presets from **Configuration**. Endpoints resolve via either explicit *_BASE_URL or DOMAIN_SUFFIX + SERVICE_NAME.", "source": "github:agent-matrix/matrixlink/docs/deploy.md"}
{"text": "FAQ\n**Do I need MCP Gateway to start?**\nNo. You can run BFF + UI locally without MCP. Add MCP when you need discovery, health-based routing, and policy/RBAC.\n**How does MatrixLink find URLs?**\nEither via explicit *_BASE_URL envs, or by composing https://<SERVICE>.<DOMAIN_SUFFIX> using provider hints.\n**Can I run agents/orchestrators at scale-to-zero?**\nYes. Keep MCP and BFF warm (minScale=1) and let agents/orchestrators scale to 0/∞.\n**What about multi-cloud?**\nMatrixLink is provider-agnostic. Move workloads between CE/Run/App Runner/ACA/Knative with env changes only.", "source": "github:agent-matrix/matrixlink/docs/faq.md"}
{"text": "MatrixLink Suite\nMatrixLink Suite = **MatrixLink (PyPI client)** + **Front Door (BFF)** + **Admin UI** + **infra** to run **MCP Gateway + Orchestrators + A2A Agents**.\n• All services bind **:8080** (host/path routing).\n• East–west calls use **Bearer service tokens** (optional mTLS).\n• Default provider = **local**.\nSee **Quickstart** to run locally in minutes.", "source": "github:agent-matrix/matrixlink/docs/index.md"}
{"text": "MatrixHub × MatrixLink — internet hub + portable runtime\n**MatrixHub** is an internet-scale hub and search engine (like PyPI, but for agents and MCP servers). It indexes capability cards, trust, health and fitness so your teams can **find and import** the best candidates.\n**MatrixLink** is the portable, production-safe client + BFF that your apps use to **discover** and **invoke** those candidates at runtime with consistent contracts and env-based endpoints.\nWhat MatrixHub provides\n• Open catalog & search by skill (e.g. report.generate), tags (domain:finance), modes, license, region\n• Trust/quality: uptime, success rate, latency, verified publisher, SBOM/attestation\n• Governance: visibility (private|team|global), policy filtering, team tagging\n• One-click import to your org’s tenant (mirro", "source": "github:agent-matrix/matrixlink/docs/matrixhub-matrixlink.md"}
{"text": "ernance: visibility (private|team|global), policy filtering, team tagging\n• One-click import to your org’s tenant (mirrored into your MCP Gateway)\nHow MatrixLink consumes it\n• MCPClient.discover_agents(skill=..., input_mode=..., output_mode=...)\n• MCPClient.discover_servers(role=\"orchestrator\", tags=[...])\n• A2AClient.send_message(endpoint, data) and optional SSE stream\n• OrchestratorClient.invoke(flow, arguments)\n• Provider-aware resolution via CLOUD_PROVIDER, DOMAIN_SUFFIX, or explicit *_BASE_URL\nTypical workflow\n1. Search on public MatrixHub → pick candidate(s)\n2. Import into your org tenant → tagged, governed entries\n3. Deploy/attach endpoints → heartbeat into MCP\n4. Use MatrixLink from orchestrators/edge → discover and invoke at runtime\n5. Operate rollouts (canary/blue-green) without ", "source": "github:agent-matrix/matrixlink/docs/matrixhub-matrixlink.md"}
{"text": "MCP Gateway — when and how to use it\n**When you need it**\n• Runtime discovery by skill/tags across many agents\n• A registry with visibility, RBAC, health and fitness scoring\n• Traffic shaping via tags (canary, tier) and safe rollouts\n**Local dev**\n• Run a lightweight MCP instance at http://localhost:4444\n• Point BFF/clients with MCP_BASE_URL=http://localhost:4444\n**Cloud**\n• Deploy/consume a managed MCP; set MCP_BASE_URL (or use DOMAIN_SUFFIX + MCP_SERVICE_NAME)\n• Use MCP_BEARER_TOKEN for service-to-service auth\n**Discovery APIs (typical)**\n• GET /discover/agents?skill=...&inputMode=...&outputMode=...&healthyOnly=true\n• GET /discover/servers?role=orchestrator&tags=...\n**Best practices**\n• Keep MCP warm (minScale=1) for low latency discovery\n• Enforce RBAC + tenancy headers end-to-end\n• Emi", "source": "github:agent-matrix/matrixlink/docs/mcpgateway.md"}
{"text": "Security & Ops\nAuthentication & Authorization\n• Edge: verify user OIDC/JWT for /api/chat and user-facing routes\n• East–west: service bearer tokens; optionally mTLS between internal services\n• Admin plane: ADMIN_BEARER for /api/admin/* and /api/mcp/*\nTenancy & Headers\n• Propagate X-Tenant-Id from edge → orchestrator → agents\n• Enforce visibility in MCP (private|team|global) and team tags\nObservability\n• Use X-Request-Id for correlation; structured logs\n• Add OTEL exporters if desired; ensure SSE endpoints are not buffered by edge\nSLO Guidance\n• Discovery P99 < 50 ms\n• Agent success rate > 99.5% (ex-upstream)\n• First SSE event < 250 ms\nLifecycle & Rollouts\n• Blue/green with tags (canary, stable)\n• Traffic shaping in MCP; deprecate with policy windows\nData & Secrets\n• Store secrets in provide", "source": "github:agent-matrix/matrixlink/docs/security.md"}
{"text": "Troubleshooting\n**ModuleNotFoundError: matrixlink when running BFF locally**\n• Run make install to install the library into the BFF venv.\n**MCP base URL not set**\n• Set MCP_BASE_URL or configure CLOUD_PROVIDER + DOMAIN_SUFFIX + MCP_SERVICE_NAME.\n**CORS errors in the Admin UI**\n• Set CORS_ALLOW_ORIGINS in BFF (e.g., http://localhost:3000).\n**401 on admin routes**\n• Set ADMIN_BEARER and pass Authorization: Bearer <token> from the UI Settings.\n**SSE not streaming**\n• Ensure your API Gateway does **not buffer** text/event-stream responses.", "source": "github:agent-matrix/matrixlink/docs/troubleshooting.md"}
{"text": "<p align=\"center\">\n<img src=\"./assets/logo.png\" alt=\"Matrix Hub Logo\" width=\"300\">\nMatrix Hub\n[](https://hub.docker.com/r/ruslanmv/matrix-hub)\n[](https://www.python.org/downloads/release/python-3100/)\n[](https://github.com/agent-matrix/matrix-hub/actions/workflows/ci.yml)\n[](https://agent-matrix.github.io/matrix-hub/)\n[](LICENSE) <a href=\"https://github.com/ruslanmv/agent-generator\"><img src=\"https://img.shields.io/badge/Powered%20by-agent--generator-brightgreen\" alt=\"Powered by agent-generator\"></a>\nWelcome to Matrix Hub, your all‑in‑one AI agent marketplace and installer!\n**Matrix Hub** is your production‑ready catalog & installer for AI agents, custom tools, and MCP servers.\nIt ingests well‑structured manifests from remote catalogs (e.g., GitHub), offers lightning‑fast **search** (lexic", "source": "github:agent-matrix/matrix-hub/README.md"}
{"text": "rvers.\nIt ingests well‑structured manifests from remote catalogs (e.g., GitHub), offers lightning‑fast **search** (lexical + semantic hybrid), safely computes and executes **install plans** (pip/uv, Docker, Git, ZIP), and can automatically **register** everything with your MCP Gateway.\n• **API**: FastAPI on port **443**\n• **DB**: PostgreSQL (SQLite supported for lightweight/dev use)\n• **Ingest**: Pull index.json from one or more remotes, validate & enrich manifests, optional chunk+embed\n• **Install**: Idempotent steps, project adapters, lockfile generation\n• **Auth**: Optional bearer‑token for admin endpoints\n• **Logs**: Structured JSON with correlation IDs\nWhat is Matrix Hub?\nImagine PyPI for intelligent agents and custom tools—Matrix Hub ingests curated manifests from GitHub (or any remo", "source": "github:agent-matrix/matrix-hub/README.md"}
{"text": " Hub?\nImagine PyPI for intelligent agents and custom tools—Matrix Hub ingests curated manifests from GitHub (or any remote catalog), lets you find the perfect agent in seconds using hybrid text + semantic search, and then safely installs everything into your project (pip, Docker, Git, or ZIP) with a single command. It even auto‑registers new services with your MCP Gateway, writes scaffolding adapters, and produces a lockfile so your builds are rock‑solid.\nReady to discover, install, and manage enterprise‑grade AI skills?\nExplore the full documentation to get started!\nOfficial Search API\nMatrix Hub exposes a stable, public endpoint that returns the **Top‑5** best matches for a query across agents, tools, and MCP servers. This contract is additive and safe for production.\nEndpoint\n**Common p", "source": "github:agent-matrix/matrix-hub/README.md"}
{"text": "or a query across agents, tools, and MCP servers. This contract is additive and safe for production.\nEndpoint\n**Common parameters**\n• q *(string, required)* – user intent, e.g. summarize pdfs\n• type *(enum: agent|tool|mcp\\_server|any, default any)* – filter by type; any searches all.\n• limit *(int, default 5)* – maximum items returned. Public API caps to **5**.\n• with_snippets *(bool, default false)* – include a short snippet (first \\~200 chars of summary/description) when available.\nAdvanced parameters (optional): mode (keyword|semantic|hybrid), with_rag (bool), rerank (none|llm), and CSV filters capabilities, frameworks, providers.\nResponse\nEach item includes ranking scores and convenience links for import/install:\nQuick start (curl)\nTo install a selected item:\nSee the full API doc: Top‑", "source": "github:agent-matrix/matrix-hub/README.md"}
{"text": "ores and convenience links for import/install:\nQuick start (curl)\nTo install a selected item:\nSee the full API doc: Top‑5 Search API.\n**Deployment notes**\n• Set PUBLIC_BASE_URL in your environment (e.g., https://api.example.com).\n• The optional helper route GET /catalog/manifest/{id} can redirect to external manifests when source_url is set.\n• No database migrations required.\nQuick start (docker compose)\nRequirements: Docker 24+, docker compose plugin.\nYou should see:\nThe app container waits for Postgres to be healthy, then starts the API. Ingest is scheduled (see INGEST\\_INTERVAL\\_MIN in .env).\nEnvironment\nAll configuration is via environment variables; see .env.example for a documented template.\nKey settings (common):\n| Variable                 | Purpose                                  ", "source": "github:agent-matrix/matrix-hub/README.md"}
{"text": "for a documented template.\nKey settings (common):\n| Variable                 | Purpose                                      | Example                                                                  |\n| DATABASE_URL           | SQLAlchemy URL                               | postgresql+psycopg://matrix:matrix@db:5432/matrixhub                   |\n| HOST / PORT          | Bind address/port                            | 0.0.0.0 / 443                                                       |\n| MATRIX_REMOTES         | CSV/JSON list of index.json URLs to ingest | https://raw.githubusercontent.com/agent-matrix/catalog/main/index.json |\n| INGEST_INTERVAL_MIN    | Background ingest interval (minutes)         | 15                                                                     |\n| API_TOKEN       ", "source": "github:agent-matrix/matrix-hub/README.md"}
{"text": "interval (minutes)         | 15                                                                     |\n| API_TOKEN              | Bearer token for admin/protected endpoints   | set_me                                                                 |\n| MCP_GATEWAY_URL        | MCP Gateway base URL                         | http://mcpgateway:7200                                                 |\n| MCP_GATEWAY_TOKEN      | Bearer for Gateway admin API                 | supersecret                                                            |\n| SEARCH_LEXICAL_BACKEND | pgtrgm or none                           | pgtrgm                                                                 |\n| SEARCH_VECTOR_BACKEND  | pgvector / none                          | none                                        ", "source": "github:agent-matrix/matrix-hub/README.md"}
{"text": "    |\n| SEARCH_VECTOR_BACKEND  | pgvector / none                          | none                                                                   |\n| SEARCH_HYBRID_WEIGHTS  | sem:0.6,lex:0.4,rec:0.1,q:0.1              |                                                                          |\n| RAG_ENABLED            | false                                      |                                                                          |\n| EMBED_MODEL            | Embedder identifier (informational)          | sentence-transformers/all-MiniLM-L6-v2                                 |\n**Security:** If you set API_TOKEN, pass Authorization: Bearer <token> on protected endpoints (e.g., manual ingest). Without it, admin endpoints are disabled or open depending on route configuration.\nAPI walk‑t", "source": "github:agent-matrix/matrix-hub/README.md"}
{"text": "nts (e.g., manual ingest). Without it, admin endpoints are disabled or open depending on route configuration.\nAPI walk‑through\nBase URL defaults to http://localhost:443.\nGET /health\nLiveness/readiness. Optional DB probe:\nReturns:\nGET /catalog/search\nHybrid search over the catalog with optional filters.\n**Query params**\n• q (required) — free text query\n• type — agent | tool | mcp_server\n• capabilities — CSV, e.g. pdf,summarize\n• frameworks — CSV, e.g. langgraph,watsonx_orchestrate\n• providers — CSV, e.g. openai,watsonx\n• mode — keyword | semantic | hybrid (default from settings)\n• limit — default 20\n• with_rag — true to enrich results with a short “fit\\_reason”\n• rerank — none | llm (default from settings)\n**Example**\n**Response (truncated)**\nGET /catalog/entities/{id}\nFetch full entity det", "source": "github:agent-matrix/matrix-hub/README.md"}
{"text": "none | llm (default from settings)\n**Example**\n**Response (truncated)**\nGET /catalog/entities/{id}\nFetch full entity details for a specific catalog ID.\n**Example**\nPOST /catalog/install\nCompute and execute an install plan (pip/uv, docker, git, zip), write adapters into your project, and (optionally) register tools/servers with MCP‑Gateway. Emits matrix.lock.json.\n**Body**\n**Example**\n**Response (truncated)**\nManifests & Schemas\nCatalog authors publish manifests in a separate content repo (e.g., agent-matrix/catalog) and generate an index.json.\nMatrix Hub ingests those manifests on a schedule or via an admin trigger.\nSupported schemas (JSON Schema Draft 2020‑12):\n• Agent: schemas/agent.manifest.schema.json\n• Tool:  schemas/tool.manifest.schema.json\n• MCP Server: schemas/mcp-server.manifest.", "source": "github:agent-matrix/matrix-hub/README.md"}
{"text": "schemas/agent.manifest.schema.json\n• Tool:  schemas/tool.manifest.schema.json\n• MCP Server: schemas/mcp-server.manifest.schema.json\nMinimal index.json formats accepted:\nExample agent manifest (excerpt):\nLocal development\n**Quality & tests**\n**Where things live**\nMigrations\nThis project includes Alembic scaffolding. To create and apply migrations:\nIn production, run migrations as part of your deploy step (e.g., init container or CI job) before starting new app instances.\nProduction notes\n**Container image:** See Dockerfile (multi‑stage). Run with:\n**Database:** Use PostgreSQL in production. SQLite is supported for quick local trials only.\n**Scaling:** The API is stateless; scale horizontally behind a reverse proxy/load balancer. Ensure a single writer for migrations.\n**Observability:** Logs", "source": "github:agent-matrix/matrix-hub/README.md"}
{"text": " scale horizontally behind a reverse proxy/load balancer. Ensure a single writer for migrations.\n**Observability:** Logs are JSON‑formatted with correlation IDs (see src/utils/logging.py). Forward stdout/stderr to your log stack (e.g., Loki/ELK). Add metrics/tracing as needed.\n**Security:**\n• Set API_TOKEN to protect admin routes.\n• Place the service behind TLS (e.g., NGINX/Envoy) and enforce client auth if needed.\n• Configure outbound access policies for pip, docker, and git if your environment restricts egress.\n**MCP Gateway:** Expose MCP_GATEWAY_URL and MCP_GATEWAY_TOKEN. The installer will register tools/servers after artifacts are installed.\nTroubleshooting\n**API returns 500 on /catalog/search**\n• Check DB connectivity (/health?check_db=true).\n• Ensure the entity table is populated (i", "source": "github:agent-matrix/matrix-hub/README.md"}
{"text": "urns 500 on /catalog/search**\n• Check DB connectivity (/health?check_db=true).\n• Ensure the entity table is populated (ingest logs).\n• If running SQLite, semantic/vector search is disabled by default.\n**No results after ingest**\n• Verify MATRIX_REMOTES points to a valid index.json.\n• Review container logs for validation errors (schema mismatches).\n**Install fails on pip/docker/git**\n• See the results array in the install response for command stdout/stderr.\n• Check that the container has network access and the artifact references are valid.\n**Gateway registration errors**\n• Confirm MCP_GATEWAY_URL is reachable and token is correct.\n• Some gateways perform discovery automatically; our client handles transport normalization.\nLicense\nApache‑2.0. See LICENSE.\nSee also\n**Schemas:**\n• Agent — sch", "source": "github:agent-matrix/matrix-hub/README.md"}
{"text": "ically; our client handles transport normalization.\nLicense\nApache‑2.0. See LICENSE.\nSee also\n**Schemas:**\n• Agent — schemas/agent.manifest.schema.json\n• Tool — schemas/tool.manifest.schema.json\n• MCP Server — schemas/mcp-server.manifest.schema.json\n**Tests:** tests/ — smoke tests and examples; run with make test.", "source": "github:agent-matrix/matrix-hub/README.md"}
{"text": "Installing Agents/Tools via Matrix Hub\nYou can install through the **CLI** or the **API**. Installation computes a plan, executes artifacts (pip/uv, docker, git, zip), writes adapters, registers to MCP Gateway, and emits matrix.lock.json.\nCLI\nAPI\nArtifacts Supported\n• pypi → uv pip install … (fallback to pip)\n• oci → docker pull …\n• git → git clone … (+ optional checkout)\n• zip → curl + unzip\nAdapters\nFramework glue written to your project (e.g., LangGraph node).\nPath defaults can be overridden per adapter spec.\nFiles added to matrix.lock.json under adapters_files.\nLockfile\nmatrix.lock.json records installed entities, artifacts, digests, and adapters for reproducibility.\nRollback (manual)\nRemove adapters and revert project changes.\nRe-run install with a known-good version (@version).", "source": "github:agent-matrix/matrix-hub/docs/agent-installation.md"}
{"text": "Registration with MCP Gateway\nAfter installing, Matrix Hub can register entities with MCP Gateway via its admin API.\nWhat Gets Registered\n• **Tools**: POST /tools with name, integration_type (REST|MCP), request_type, url, input_schema, and optional headers/annotations.\n• **MCP Servers**: POST /gateways with name, url, transport (HTTP/SSE/STDIO/STREAMABLEHTTP), and optional auth.\n• Discovery of tools is **automatic** after registration; no separate endpoint needed.\n• **Resources / Prompts** (optional): added via POST /resources / POST /prompts.\nIdempotency & Conflicts\n• Re-registration with identical payloads may yield 409 Conflict; Matrix Hub surfaces this in the install results.\n• Admin token is required; set MCP_GATEWAY_TOKEN.\nSecurity\n• Use Gateway over TLS.\n• Store auth tokens outside ", "source": "github:agent-matrix/matrix-hub/docs/agent-registration.md"}
{"text": "Agents, Tools, and MCP Servers (Concepts)\nMatrix Hub catalogs three entity types:\n• **Agent**: an orchestrated capability (often a service with /invoke).\n• **Tool**: a callable function/tool (often REST or MCP tool).\n• **MCP Server**: a server that exposes MCP protocol endpoints and tools.\nManifests\nEach entity has a manifest describing:\n• Identity: type, id, name, version\n• Metadata: summary, description, license, homepage\n• Capabilities/tags; compatibility (frameworks/providers)\n• Artifacts: pypi | oci | git | zip with specs\n• Adapters: framework glue to drop into your project\n• mcp_registration: how to register with MCP Gateway", "source": "github:agent-matrix/matrix-hub/docs/agents.md"}
{"text": "API — Endpoints\nBase URL defaults to http://localhost:443.\nThis Hub stores a catalog of manifests (agents/tools/mcp\\_servers), installs artifacts, and syncs MCP servers into **MCP-Gateway**. Mutating endpoints require an admin token if API_TOKEN is set.\nAuth\nWhen API_TOKEN is configured in the Hub:\nAdmin-only endpoints below are marked accordingly.\nGET /health\nCheck service health.\n**Query params**\n• check_db (bool, optional): also checks DB connectivity.\n**200 Response**\nGET /catalog/search\nHybrid search with filters (keyword/semantic/hybrid). Also handy for listing ingested items.\n**Query params**\n• q (string, optional): text query\n• type (string, optional): agent | tool | mcp_server\n• capabilities (CSV, optional)\n• frameworks (CSV, optional)\n• providers (CSV, optional)\n• mode (string, o", "source": "github:agent-matrix/matrix-hub/docs/api.md"}
{"text": "l | mcp_server\n• capabilities (CSV, optional)\n• frameworks (CSV, optional)\n• providers (CSV, optional)\n• mode (string, optional): keyword | semantic | hybrid (default: hybrid)\n• limit (int, default: 20)\n• with_rag (bool, optional): include a brief fit explanation\n**200 Response (truncated)**\n**Useful scripts**\nGET /catalog/entities/{id}\nReturn full metadata for an entity (resolved from the ingested manifests).\n**Example**\n**404** if not found.\nPOST /catalog/install  *(admin)*\nExecute an install plan (artifacts/adapters) and best-effort **MCP-Gateway** registration when mcp_registration is present.\n**Body**\n**Notes**\n• id must be <type>:<slug>@<version> and match the manifest.\n• If manifest is provided inline:\n• It is persisted as a catalog Entity.\n• mcp_registration is saved on the entity ", "source": "github:agent-matrix/matrix-hub/docs/api.md"}
{"text": "est.\n• If manifest is provided inline:\n• It is persisted as a catalog Entity.\n• mcp_registration is saved on the entity (used later by sync).\n• A matrix.lock.json is written under target.\n• Best-effort gateway registration is attempted; errors are recorded in results and entity.gateway_error.\n**200 Response (truncated)**\nRemotes (catalog sources)\nThese endpoints manage remote catalog indexes (each is an index.json URL). When no remotes are stored, the Hub seeds them from MATRIX_REMOTES (CSV or JSON array) the first time you call GET /remotes or POST /remotes/sync.\nGET /remotes\nList configured remotes. If DB is empty, this call seeds from MATRIX_REMOTES.\n**200 Response**\nPOST /remotes  *(admin)*\nAdd a remote index URL.\n**Body**\n**201 Response**\nDELETE /remotes  *(admin)*\nRemove a remote ind", "source": "github:agent-matrix/matrix-hub/docs/api.md"}
{"text": "OST /remotes  *(admin)*\nAdd a remote index URL.\n**Body**\n**201 Response**\nDELETE /remotes  *(admin)*\nRemove a remote index URL.\n**Body**\n**200 Response**\nIngest & Sync\nPOST /ingest  *(admin)*\nManually trigger ingestion for one or all remotes.\n**Body**\n**200 Response (truncated)**\nPOST /remotes/sync  *(admin)*\nEnd-to-end sync:\n1. Ensure remotes exist (seed from MATRIX_REMOTES if empty).\n2. Ingest each remote.\n3. Register **new** MCP servers into MCP-Gateway (Tool → Resources → Prompts → Gateway).\n**200 Response**\nGateways (pending → registered)\nThese endpoints help you see what’s ingested but **not yet** registered in MCP-Gateway, and clean them up if needed.\nGET /gateways/pending  *(admin)*\nList ingested MCP servers with gateway_registered_at IS NULL.\n**Query params**\n• limit (int, default", "source": "github:agent-matrix/matrix-hub/docs/api.md"}
{"text": "/pending  *(admin)*\nList ingested MCP servers with gateway_registered_at IS NULL.\n**Query params**\n• limit (int, default: 100, max 1000)\n• offset (int, default: 0)\n**200 Response**\n**Tip:** This is exactly what scripts/list_pending_gateways.sh displays.\nDELETE /gateways/pending/{uid}  *(admin)*\nDelete a **pending** mcp_server by UID (does nothing if it’s already registered).\n**200 Response**\n**404** is not used; if the row can’t be deleted you get:\nPOST /gateways/pending/delete  *(admin)*\nBulk delete pending MCP servers.\n**Body**\n• Provide either uids **or** set all=true.\n• With error_only=true, only entities with gateway_error are deleted.\n**200 Response**\nScripts (helpers)\n• scripts/list_ingested.sh\nLists all ingested mcp_server rows from the DB (falls back to /gateways/pending if DB is ", "source": "github:agent-matrix/matrix-hub/docs/api.md"}
{"text": "rs)\n• scripts/list_ingested.sh\nLists all ingested mcp_server rows from the DB (falls back to /gateways/pending if DB is unavailable). Shows status: PENDING vs REGISTERED.\n• scripts/list_pending_gateways.sh\nCalls GET /gateways/pending and prints a table. Exits with non-zero if any pending exist (useful in CI).\n• scripts/verify_token.sh\nVerifies your Hub → Gateway auth and lists /servers and /gateways on MCP-Gateway.\n• examples/register_watsonx_local_via_hub.sh\nPushes an inline mcp_server manifest to the Hub and triggers /remotes/sync (which registers the server into MCP-Gateway).\nBehavior notes\n• **Inline install parity**: an inline manifest in POST /catalog/install is now persisted in the DB, including mcp_registration. The same fields drive /remotes/sync.\n• **Gateway registration flow** (", "source": "github:agent-matrix/matrix-hub/docs/api.md"}
{"text": " persisted in the DB, including mcp_registration. The same fields drive /remotes/sync.\n• **Gateway registration flow** (on sync):\nTool → Resources → Prompts → Gateway. SSE endpoints are normalized to /messages/ when appropriate.\n• **Error visibility**: sync errors are recorded in entity.gateway_error and surfaced by GET /gateways/pending.\nOptional: Gateway pass-throughs\nIf you run the Gateway locally, use the Gateway’s own API (auth header from scripts/verify_token.sh):\n• GET /health\n• GET /servers\n• GET /gateways\n• POST /gateways (register a federated server)\nThese are **not** Hub endpoints; they belong to MCP-Gateway.\nStatus codes\n• 200  OK\n• 201  Created (POST /remotes)\n• 400  Bad request (invalid body or params)\n• 401  Unauthorized (missing/invalid token when required)\n• 404  Not found", "source": "github:agent-matrix/matrix-hub/docs/api.md"}
{"text": ")\n• 400  Bad request (invalid body or params)\n• 401  Unauthorized (missing/invalid token when required)\n• 404  Not found (for entity lookups; delete-pending returns a soft reason instead)\n• 409  Conflict (idempotent creates may translate to OK upstream)\n• 500  Internal server error\nEnvironment\n• API_TOKEN — enables admin protection on mutating routes.\n• MATRIX_REMOTES — CSV or JSON array of index URLs; used to seed remotes when empty.\n• DATA_DIR / DB_PATH — where catalog.sqlite is stored (deployment-specific).\n• Gateway auth used by the Hub (for sync): MCP_GATEWAY_URL, JWT_SECRET_KEY, BASIC_AUTH_USERNAME, MCP_GATEWAY_TOKEN.", "source": "github:agent-matrix/matrix-hub/docs/api.md"}
{"text": "Matrix Hub — Top‑5 Search API\nThis document defines the **public, production‑safe** search endpoint that powers the Matrix Hub meta search for agents, tools, and MCP servers. The contract is **additive** and **backward‑compatible** with existing deployments.\nEndpoint\nGET /catalog/search\nPurpose\nReturn the **Top‑5** best matches for a user query across agent, tool, and mcp_server entities.\nQuery Parameters\n| Name            | Type                                  | Default        | Description                                                                                      |\n| q             | string                                | **required**   | The user intent. Example: summarize pdfs                                                       |\n| type          | enum (agent\\|tool\\|mcp_se", "source": "github:agent-matrix/matrix-hub/docs/api/search-api.md"}
{"text": "mple: summarize pdfs                                                       |\n| type          | enum (agent\\|tool\\|mcp_server\\|any) | any          | Filter by entity type. any means no filter.                                                    |\n| limit         | integer (1–100)                       | 5            | Maximum results returned. Public API caps to **5** even if larger is requested.                  |\n| with_snippets | boolean                               | false        | Include a short snippet (first \\~200 chars of summary/description) in each item, when available. |\n| mode          | enum (keyword\\|semantic\\|hybrid)    | server default | Advanced: controls which backends participate.                                                   |\n| with_rag      | boolean              ", "source": "github:agent-matrix/matrix-hub/docs/api/search-api.md"}
{"text": " which backends participate.                                                   |\n| with_rag      | boolean                               | false        | Advanced: include an optional fit_reason field per item.                                       |\n| rerank        | enum (none\\|llm)                    | server default | Advanced: apply an LLM reranker to the merged results.                                           |\n**Note:** Additional filtering parameters exist (capabilities, frameworks, providers). They accept CSV values.\nResponse Shape\nField Notes\n• manifest_url comes from the entity’s source_url when present; otherwise it may point to a local resolver GET /catalog/manifest/{id}.\n• install_url is a convenience link; clients should still POST /catalog/install under the hood.\n• snippe", "source": "github:agent-matrix/matrix-hub/docs/api/search-api.md"}
{"text": "/manifest/{id}.\n• install_url is a convenience link; clients should still POST /catalog/install under the hood.\n• snippet appears only if with_snippets=true and summary/description text exists.\n• total is a conservative estimate of distinct entities matched by the underlying backends.\nExample\nSearch for the top‑5 items related to extracting tables from PDFs, across all types:\nInstall\nOnce you select an item from the results, install it via the canonical install endpoint:\nYou may also install from an inline manifest by providing a manifest object in the body.\nCompatibility & Stability\n• This API is **additive**; existing clients continue to work.\n• No database migrations are required for this feature.\n• Works in SQLite (dev) and Postgres (prod). Semantic search via pgvector can be enabled l", "source": "github:agent-matrix/matrix-hub/docs/api/search-api.md"}
{"text": "Architecture\nComponents\n• **API** (FastAPI): search, entities, install, remotes, ingest trigger.\n• **DB** (PostgreSQL): normalized entity metadata, artifacts, tags, capabilities.\n• **Ingestor**: pulls index.json, validates manifests, upserts entities.\n• **Installer**: executes artifact steps, writes adapters, updates lockfile, registers with MCP Gateway.\n• **Scheduler**: periodic ingestion via APScheduler.\nData model (high level)\n• entity — (uid, type, name, version, summary, description, capabilities[], frameworks[], providers[], source_url, created_at, updated_at, provenance)\n• artifact — (entity_id, kind, uri, hash, size, install_hint)\n• tag & entity_tag, capability & entity_capability (many-to-many)\n• optional embedding_chunk (when using vector search)\nDiagram\nScaling\n• Swap lexical ba", "source": "github:agent-matrix/matrix-hub/docs/architecture.md"}
{"text": "entity_capability (many-to-many)\n• optional embedding_chunk (when using vector search)\nDiagram\nScaling\n• Swap lexical backend to OpenSearch and vector backend to Milvus without changing the public API.\n• Keep Matrix Hub stateless; scale horizontally.", "source": "github:agent-matrix/matrix-hub/docs/architecture.md"}
{"text": "Blob Storage\nStores long text artifacts (READMEs, examples) for retrieval-augmented generation (RAG).\nBackends\n• **Local disk** (default): ${BLOB_DIR:-./data/blobs}\n• **Object storage (later)**: S3/MinIO with lifecycle policies\nKeys & Paths\n• Key format: \"{entity_uid}/{section}/{position}\" → sanitized to a flat path\n• Files are UTF-8 text\n• Checksums stored in DB to detect changes\nRetention\n• Keep last N versions per entity (configurable).\n• GC job prunes orphan blobs after successful re-indexing.\nSecurity\n• No secrets in blob content.\n• If private catalogs are used, ensure the object store is private and accessed via presigned URLs.", "source": "github:agent-matrix/matrix-hub/docs/blob-storage.md"}
{"text": "Changelog\n0.1.0 — Initial Release\n• **API**: /health, /catalog/search, /catalog/entities/{id}, /catalog/install, /catalog/remotes, /catalog/ingest\n• **Ingest**: index.json pull + schema validation\n• **Search**: lexical (pg_trgm), semantic (pgvector optional), hybrid ranking\n• **Install**: pip/uv, docker, git, zip; adapters; lockfile\n• **MCP Gateway**: tool/server registration via admin API\n• **Docs**: MkDocs site (Material)", "source": "github:agent-matrix/matrix-hub/docs/changelog.md"}
{"text": "Chunking\nPrepares text for semantic search & RAG.\nInputs\n• name, summary, description\n• README/excerpts referenced by manifest or repository\n• Examples / usage snippets (if provided)\nStrategy\n• **Hierarchical splitting**:\n1. Headings (#, ##) → paragraphs → sentences\n2. Target chunk size ~ **300–600 tokens** (configurable)\n• **Metadata** per chunk:\n• entity_uid, section, position, weight, source_uri, checksum\nWeights\n• Title/name: higher prior (e.g., 1.3×)\n• Summary: 1.2×\n• README/body: 1.0×\n• Examples/code: 1.1×\nOutput\n• A list of (chunk_id, entity_uid, text, weight, meta) ready for embedding.", "source": "github:agent-matrix/matrix-hub/docs/chunking.md"}
{"text": "Configuration\nMatrix Hub is configured entirely via environment variables (see .env.example).\n| Key | Description | Example |\n| DATABASE_URL | SQLAlchemy URL | postgresql+psycopg://matrix:matrix@db:5432/matrixhub |\n| HOST / PORT | Bind address & port | 0.0.0.0 / 443 |\n| API_TOKEN | Bearer token for admin/protected routes | supersecret |\n| MATRIX_REMOTES | CSV/JSON list of index.json URLs to ingest | https://raw.githubusercontent.com/.../index.json |\n| INGEST_INTERVAL_MIN | Background ingestion interval (minutes) | 15 |\n| SEARCH_LEXICAL_BACKEND | pgtrgm or none | pgtrgm |\n| SEARCH_VECTOR_BACKEND | pgvector or none | none |\n| EMBED_MODEL | Embedder model id (informational; pluggable) | all-MiniLM-L6-v2 |\n| MCP_GATEWAY_URL | MCP Gateway base URL | http://mcpgateway:7200 |\n| MCP_GATEWAY_TOKEN ", "source": "github:agent-matrix/matrix-hub/docs/configuration.md"}
{"text": "pluggable) | all-MiniLM-L6-v2 |\n| MCP_GATEWAY_URL | MCP Gateway base URL | http://mcpgateway:7200 |\n| MCP_GATEWAY_TOKEN | Bearer for gateway admin API | supersecret |\nNotes\n• If API_TOKEN is set, pass Authorization: Bearer <token> on admin calls (/catalog/ingest, /catalog/remotes).\n• For local SQLLite quick trials, you can use sqlite+pysqlite:///./data/catalog.sqlite. Some search features (pg_trgm/pgvector) won’t be available.", "source": "github:agent-matrix/matrix-hub/docs/configuration.md"}
{"text": "Container Notes (Matrix Hub + MCP‑Gateway)\nThis document explains how the Docker image is built and run for **Matrix Hub** together with the **MCP‑Gateway**, and how to operate it in production.\nWhat’s inside the image\n• **Two isolated Python virtualenvs**:\n• **Matrix Hub venv:** /app/.venv\n• **MCP‑Gateway venv:** /app/mcpgateway/.venv\n• **Code & scripts:**\n• App code under /app/src\n• Gateway project under /app/mcpgateway\n• Entrypoint supervisor: /app/scripts/run_prod.sh\n• Helper scripts: /app/scripts/build_container.sh, /app/scripts/run_container.sh\n• **Default exposed ports:**\n• **Hub:** 443\n• **Gateway:** 4444\n• **Healthcheck:** probes Hub at http://127.0.0.1:${PORT:-443}/.\nThe entrypoint (scripts/run_prod.sh) launches **Gateway first**, waits for its port, then launches **Matrix Hub**.", "source": "github:agent-matrix/matrix-hub/docs/container.md"}
{"text": "43}/.\nThe entrypoint (scripts/run_prod.sh) launches **Gateway first**, waits for its port, then launches **Matrix Hub**. Both are supervised: if one exits, the other is stopped gracefully.\nEnvironment files\n• **Matrix Hub:** root .env (copied from .env.example if missing).\n• **Gateway:** /app/mcpgateway/.env (copied from repo’s .env.gateway.local during build if present via setup script).\n**Important variables:**\n• **Hub bind:** HOST=0.0.0.0, PORT=443\n• **Hub → Gateway integration:** MCP_GATEWAY_URL=http://127.0.0.1:4444 (or external URL if you skip the embedded gateway)\n• **Gateway bind:** HOST=0.0.0.0, PORT=4444\nBuilding the image\nUse the helper script (recommended):\nDirect docker build (if preferred):\nRunning the container\nUse the run helper (recommended):\nKey flags:\n• --app-port PORT →", "source": "github:agent-matrix/matrix-hub/docs/container.md"}
{"text": "rect docker build (if preferred):\nRunning the container\nUse the run helper (recommended):\nKey flags:\n• --app-port PORT → host port for Hub (container 443)\n• --gw-port PORT → host port for Gateway (container 4444)\n• --skip-gateway → do not start the embedded Gateway (sets GATEWAY_SKIP_START=1)\n• --env-file PATH → pass a .env for Matrix Hub\n• --data-volume NAME → persist /app/data (Hub data/SQLite)\n• --gw-volume NAME → persist /app/mcpgateway/.state (Gateway state).\nIf used, set in Gateway env:\nDirect docker run example:\nSupervisor behavior (scripts/run_prod.sh)\n• Starts **MCP‑Gateway** first, waits for :4444 (or gateway’s PORT) to listen.\n• Starts **Matrix Hub** next on :443 (or Hub’s PORT).\n• Uses **gunicorn + uvicorn workers** when available; falls back to uvicorn.\n• **Workers** auto‑calc", "source": "github:agent-matrix/matrix-hub/docs/container.md"}
{"text": "43 (or Hub’s PORT).\n• Uses **gunicorn + uvicorn workers** when available; falls back to uvicorn.\n• **Workers** auto‑calculated as 2*CPU+1 (override via env).\n• Graceful shutdown on exit; kills the sibling process if one dies.\n• Runs Alembic migrations for Hub if alembic and alembic.ini are present.\n**Tuning via env (override at runtime):**\n• **Hub:** HUB_WORKERS, HUB_TIMEOUT, HUB_GRACEFUL_TIMEOUT, HUB_KEEPALIVE, HUB_MAX_REQUESTS, HUB_MAX_REQUESTS_JITTER, HUB_PRELOAD=true|false, HUB_LOG_LEVEL\n• **Gateway:** GW_WORKERS, GW_TIMEOUT, GW_GRACEFUL_TIMEOUT, GW_KEEPALIVE, GW_MAX_REQUESTS, GW_MAX_REQUESTS_JITTER, GW_PRELOAD=true|false, GW_LOG_LEVEL\n• **Skip gateway:** GATEWAY_SKIP_START=1\n• **Override gateway app path (fallback mode):** GW_APP_MODULE=mcp_gateway.app:app\nUsing an **external** MCP‑Ga", "source": "github:agent-matrix/matrix-hub/docs/container.md"}
{"text": "_START=1\n• **Override gateway app path (fallback mode):** GW_APP_MODULE=mcp_gateway.app:app\nUsing an **external** MCP‑Gateway\n• Run with --skip-gateway (or GATEWAY_SKIP_START=1).\n• Set **Matrix Hub** .env:\n• Do **not** publish container’s 4444 in that scenario.\nVolumes & persistence\n• **Hub data:** /app/data → mount a named volume (e.g., matrixhub_data).\n• **Gateway state (optional):** /app/mcpgateway/.state → mount a volume (e.g., mcpgw_data) and point gateway DATABASE_URL at a file in that mount.\nLogs\n• Both services log to **stdout/stderr** (12‑factor friendly).\n• View logs:\nHealth / readiness\n• Dockerfile healthcheck pings Hub at http://127.0.0.1:${PORT:-443}/.\n• scripts/run_container.sh waits for Hub after start and prints the URLs.\nUpdating\n1. Pull latest code (or update submodules).", "source": "github:agent-matrix/matrix-hub/docs/container.md"}
{"text": "pts/run_container.sh waits for Hub after start and prints the URLs.\nUpdating\n1. Pull latest code (or update submodules).\n2. Rebuild image:\n3. Restart container:\nTroubleshooting\n• **Port already in use**\n• Change host mapping: --app-port / --gw-port, or free the port.\n• **Gateway module path error** (fallback mode):\nSet GW_APP_MODULE to the correct ASGI path (e.g., my_gateway.main:app).\n• **Hub import errors (e.g., SQLAlchemy)**\nRebuild image to ensure deps are installed: scripts/build_container.sh.\nLocally (non‑container) run make setup.\n• **Hub cannot reach gateway**\nCheck MCP_GATEWAY_URL and that gateway is reachable from the Hub container.\nIf using embedded gateway, ensure :4444 is listening inside the container (docker exec -it matrix-hub sh then lsof -nP -i :4444).\n• **Migrations fail", "source": "github:agent-matrix/matrix-hub/docs/container.md"}
{"text": "sure :4444 is listening inside the container (docker exec -it matrix-hub sh then lsof -nP -i :4444).\n• **Migrations failing**\nConfirm alembic.ini exists and DB URL is reachable. Disable migrations by removing alembic or the alembic.ini file from the image if not used.\nSecurity & ops recommendations\n• Run behind a reverse proxy/ingress with **TLS termination**.\n• Inject secrets (tokens, DB creds) through **orchestrator secrets** (K8s/Swarm), not baked into images.\n• Restrict exposed ports; if using external gateway, **do not expose 4444** from the Hub container.\n• Use non‑root (already configured). For stricter profiles, consider:\n• Read‑only root filesystem, tmpfs for /tmp\n• Drop capabilities (--cap-drop=ALL) if feasible\n• Resource limits (CPU/memory) and ulimit adjustments as needed\nKuber", "source": "github:agent-matrix/matrix-hub/docs/container.md"}
{"text": "p\n• Drop capabilities (--cap-drop=ALL) if feasible\n• Resource limits (CPU/memory) and ulimit adjustments as needed\nKubernetes / Compose (high‑level)\n• **Kubernetes:** Prefer **separate deployments** for Hub and Gateway. Point the Hub’s MCP_GATEWAY_URL at the Gateway service DNS.\n• **Docker Compose:** Either use this single image (both processes) or two services (one for Hub, one for Gateway). The latter is recommended for clearer lifecycle and scaling.\nQuick references\n• **Build:** scripts/build_container.sh\n• **Run:** scripts/run_container.sh\n• **Entrypoint:** scripts/run_prod.sh\n• **Default ports:** Hub 443, Gateway 4444\n• **Hub env:** .env (copied from .env.example if missing)\n• **Gateway env:** mcpgateway/.env (from gateway setup)\n• **Volumes:** /app/data, optional /app/mcpgateway/.sta", "source": "github:agent-matrix/matrix-hub/docs/container.md"}
{"text": "missing)\n• **Gateway env:** mcpgateway/.env (from gateway setup)\n• **Volumes:** /app/data, optional /app/mcpgateway/.state\nProduction\nThis section shows a **simple, repeatable** way to build and run Matrix Hub + MCP‑Gateway for production using Postgres, split API/Worker roles, and the new prod build script.\n1) Build a production image\nUse the new helper (recommended):\nPush to your registry (optional):\n2) Prepare environment files\n• **Hub (.env)** — copy from .env.example, then set at least:\n• **Gateway (.env.gateway)** — copy from .env.gateway.example. You can keep the default SQLite or point to Postgres:\n3) Bring up the production stack (Compose)\nA production compose file typically defines four services: db (Postgres), api (Hub HTTP), worker (ingest scheduler), and gateway. Once your doc", "source": "github:agent-matrix/matrix-hub/docs/container.md"}
{"text": "le typically defines four services: db (Postgres), api (Hub HTTP), worker (ingest scheduler), and gateway. Once your docker-compose.prod.yml is in place:\n• **API** listens on :443 with INGEST_SCHED_ENABLED=false.\n• **Worker** runs the same app with INGEST_SCHED_ENABLED=true (no public port required).\n• **Gateway** listens on :4444 (optional if you use an external gateway).\nCheck health:\n4) Scale and upgrade safely\n• Scale API (stateless) for more throughput/HA:\n• Rolling upgrade:\n5) Expectations in production\n• **Database**: Postgres is required for real concurrency; dev SQLite is fine with WAL+timeouts.\n• **Migrations**: Hub applies Alembic migrations on startup (already wired). Ensure DB connectivity.\n• **Split roles**: Keep search responsive by running API and Worker as **separate proce", "source": "github:agent-matrix/matrix-hub/docs/container.md"}
{"text": " wired). Ensure DB connectivity.\n• **Split roles**: Keep search responsive by running API and Worker as **separate processes/containers**.\n• **Secrets**: Provide DB/Gateway tokens via environment or orchestrator secrets (do not bake into images).\n• **Proxy/TLS**: Place API and Gateway behind a reverse proxy/ingress that handles TLS, timeouts, and health checks.\n*End of document.*", "source": "github:agent-matrix/matrix-hub/docs/container.md"}
{"text": "Deployment\nDocker Compose (reference)\n• See docker-compose.yaml included in the repo.\n• Exposes the API on :443 and Postgres on :5432.\nContainer image\nKubernetes (guidance)\n• Use a Deployment with 2+ replicas.\n• Configure a Secret for API_TOKEN and gateway tokens.\n• Add a Job or init container to run Alembic migrations before rollout.\n• Use a Readiness probe on /health.\nPersistence\n• Postgres should be backed by persistent volumes.\n• The API is stateless (no local writes beyond ephemeral temp files).", "source": "github:agent-matrix/matrix-hub/docs/deployment.md"}
{"text": "Development\nPrerequisites\n• Python 3.11 or 3.12\n• Postgres (optional — SQLite works for unit tests)\n• make for convenience\nSetup\nMake targets\n• make dev — uvicorn with auto-reload\n• make run — foreground server\n• make lint / make fmt — Ruff static checks & formatting\n• make test — pytest test suite\n• make migrate m=\"msg\" — Alembic revision\n• make upgrade — apply migrations to head\nTests\n• Unit tests use SQLite by default.\n• CI runs on Python 3.11/3.12 (see .github/workflows/ci.yml).\nStyle\n• Ruff enforces formatting and lint rules.\n• Prefer type hints and small, composable functions.\n• Keep external network operations behind service boundaries.", "source": "github:agent-matrix/matrix-hub/docs/development.md"}
{"text": "Embedding\nEncodes chunks into vectors for semantic search & hybrid ranking.\nEmbedder\n• Default: lightweight sentence transformer (config: EMBED_MODEL).\n• Batch size & concurrency tuned to avoid memory spikes.\nFailure & Retries\n• If the model fails, the chunk is marked **pending**; the scheduler retries later.\n• We never block ingestion of the catalog on embedding failures.\nStored Fields\n• entity_uid\n• chunk_id\n• vector (list of floats / DB-specific binary)\n• dim, model_id, created_at\nReplacement Policy\n• Re-embedding occurs only when:\n• Chunk text or weight changed, or\n• Embedder model_id changed, or\n• Admin forced re-embed.", "source": "github:agent-matrix/matrix-hub/docs/embedding.md"}
{"text": "FAQ\n**Q: Can I run Matrix Hub without Postgres?** Yes, for local development and tests. Some search features (pg_trgm/pgvector) are unavailable on SQLite.\n**Q: Where do adapter files go?** They’re written under your target project directory (e.g., src/flows/...) and referenced in matrix.lock.json.\n**Q: How do I add my agents/tools to the catalog?** Publish manifests in your catalog repo and ensure they’re listed in its index.json. Then configure that index URL in MATRIX_REMOTES.\n**Q: Does Matrix Hub modify MCP Gateway code?** No. It uses gateway admin APIs to register tools/servers.\n**Q: How do I update an installed agent?** Re-run POST /catalog/install with the new id@version. Your lockfile is updated and registrations are refreshed.", "source": "github:agent-matrix/matrix-hub/docs/faq.md"}
{"text": "Matrix Hub\n**Matrix Hub** is a central **catalog & installer** for AI **agents**, **tools**, and **MCP servers**.\nIt ingests manifests from remote catalogs (e.g., GitHub), powers **search** (lexical & semantic), computes and executes **install plans** (pip/uv, docker, git, zip), writes **adapters** into your project, and optionally registers assets with an **MCP Gateway**.\nHow it works?\nMatrix Hub makes managing your AI agents, tools, and MCP servers as simple as browsing a package registry and running installs—you point it at one or more “catalog” URLs (like GitHub-hosted index.json files), it automatically pulls in and validates each manifest, enriches and indexes them for lightning-fast hybrid search (text + vector), then when you run an install it computes an idempotent plan (pip/uv, D", "source": "github:agent-matrix/matrix-hub/docs/index.md"}
{"text": "for lightning-fast hybrid search (text + vector), then when you run an install it computes an idempotent plan (pip/uv, Docker pull, Git clone, ZIP extract), writes any framework adapters into your project, registers the new services with your MCP Gateway via its normal admin API, and emits a lockfile so you—and your CI—know exactly what’s installed.\nHighlights\n• **Reuse-first**: find existing agents/tools before generating new code.\n• **Search**: lexical (pg_trgm), semantic (pgvector), **hybrid ranking**.\n• **Install**: uv/pip, docker, git, zip with safe defaults & lockfile.\n• **MCP Gateway**: register tools/servers using the gateway’s admin API.\n• **Governance-ready**: schema validation, basic policy hooks.\nHigh-level architecture\nAPI: FastAPI on :443\nDB: PostgreSQL (SQLite supported for ", "source": "github:agent-matrix/matrix-hub/docs/index.md"}
{"text": "chema validation, basic policy hooks.\nHigh-level architecture\nAPI: FastAPI on :443\nDB: PostgreSQL (SQLite supported for local dev)\nScheduler: periodic ingestion of remote catalogs\nWhat’s in this release\n• Core API: /health, /catalog/search, /catalog/entities/{id}, /catalog/install, /catalog/remotes, /catalog/ingest\n• Ingestor: index.json pull + schema validation\n• Installer: pip/uv + docker + git + zip\n• MCP Gateway integration: tools & servers (gateway registration)\n• Adapters: example templates (LangGraph node, WXO skill stub)", "source": "github:agent-matrix/matrix-hub/docs/index.md"}
{"text": "Indexing Architecture\nMatrix Hub ingests **manifests** (agents, tools, MCP servers) from remote catalogs (e.g., GitHub), validates them, normalizes metadata into a relational **Catalog DB**, optionally chunks & embeds long text, and updates a **Vector Index** plus a **Blob Store** for RAG.\nGoals\n• **Reuse-first**: one canonical entry per (type, id, version).\n• **Idempotent**: re-ingesting the same content is safe.\n• **Provable**: provenance stored (remote@commit, ETag, timestamps).\n• **Composable**: lexical, vector, and RAG layers are pluggable.\nData Flow (high level)\n1. **Discover**: pull index.json (or walk repo ZIP/tree).\n2. **Validate**: JSON Schema + optional signatures/SBOM checks.\n3. **Normalize**: map to entity, capabilities, artifacts, adapters, compatibility.\n4. **Persist**: upse", "source": "github:agent-matrix/matrix-hub/docs/indexing-architecture.md"}
{"text": "res/SBOM checks.\n3. **Normalize**: map to entity, capabilities, artifacts, adapters, compatibility.\n4. **Persist**: upsert into DB; record provenance and checksums.\n5. **Chunk & Embed** (optional): split long text → vectors → upsert vector index.\n6. **Blob Store**: persist large text (READMEs, examples) for RAG retrieval.\nSLOs & Operational Notes\n• **Freshness**: default ingest every 15 minutes (configurable).\n• **Back-pressure**: batch size and rate limits to avoid API throttling.\n• **Consistency**: write DB first, then vectors/blobs; retries are safe.\n• **Observability**: structured logs; ingest counters; rejection reasons.", "source": "github:agent-matrix/matrix-hub/docs/indexing-architecture.md"}
{"text": "Ingestion\nMatrix Hub ingests manifests from one or more remotes and stores normalized metadata in the catalog DB.\nSources\n• **index.json** files published by your catalog (e.g., GitHub Pages or raw Git URLs).\n• Each index entry points at a *.manifest.yaml (agent, tool, or mcp-server).\nValidation\n• Manifests are validated against JSON Schemas:\n• schemas/agent.manifest.schema.json\n• schemas/tool.manifest.schema.json\n• schemas/mcp-server.manifest.schema.json\nInvalid manifests are **skipped** and logged.\nScheduling\n• Background job polls remotes every INGEST_INTERVAL_MIN minutes (default 15).\n• Manual trigger via POST /catalog/ingest?remote=<name> (admin).\nProvenance\n• The DB stores the manifest URL and optional commit/hash, enabling traceability.", "source": "github:agent-matrix/matrix-hub/docs/ingestion.md"}
{"text": "Matrix Hub — Quick Start (Local Ingest & Install)\nThis is the **definitive, step-by-step** guide to add MCP servers/tools/agents to **Matrix-Hub** on your local machine.\nNo prior knowledge is required — we explain every step and show **copy-paste ready** commands.\nYou’ll learn **two ways** to get content into Matrix-Hub:\n• **A) Catalog flow (recommended for scale)**\nYou publish an index.json (and your manifests) over **HTTP**. The Hub **downloads** that URL, parses it, writes entities into the **database**, and then you “install” (register into the **MCP-Gateway**).\n• **B) Direct install (quick local test)**\nYou call /catalog/install with an ID (and optionally an inline manifest), skipping catalog/ingest.\n### Why do I need python3 -m http.server 8001?\nMatrix-Hub must **download** your matr", "source": "github:agent-matrix/matrix-hub/docs/ingestion_local.md"}
{"text": "anifest), skipping catalog/ingest.\n### Why do I need python3 -m http.server 8001?\nMatrix-Hub must **download** your matrix/index.json and manifests via **HTTP** — it can’t read local files directly.\nFor local dev, the easiest way is:\nThis serves your repo over HTTP at http://127.0.0.1:8001/.\nIf your files are already published (GitHub raw, S3/CDN), **you don’t need** this local server.\n0) Start Matrix-Hub locally\nFrom the **Matrix-Hub repo root**:\nVerify it’s alive:\n**.env note**: If you use .env, it’s loaded by make dev.\n**Auth note**: For protected endpoints, set API_TOKEN=<token> in .env and pass -H \"Authorization: Bearer <token>\" in curl calls.\n1) Get an admin token & set HUB_URL (the **right** way)\nUse the helper to get an admin token and endpoint:\nIt prints something like:\nNow **expo", "source": "github:agent-matrix/matrix-hub/docs/ingestion_local.md"}
{"text": " set HUB_URL (the **right** way)\nUse the helper to get an admin token and endpoint:\nIt prints something like:\nNow **export** those values (copy/paste exactly):\nNormalize HUB_URL for curl:\n**Why not 0.0.0.0?** That’s a **bind** address on the server. Clients should use 127.0.0.1:443 (or your LAN IP/hostname).\n2) Choose a flow\nOption A — Catalog flow (recommended for scale)\nYou **host**:\nMatrix-Hub **fetches** your index.json, parses it, then fetches each manifest_url and writes **Entity** rows into the Hub DB.\nFor **local dev**, host matrix/ via:\nYour **index** will be at: http://127.0.0.1:8001/matrix/index.json\nOption B — Direct install (quick test)\nYou skip index.json and ingestion. You call /catalog/install with:\n• \"id\": \"mcp_server:your-id@version\"\n• Optionally with an inline \"manifest\"", "source": "github:agent-matrix/matrix-hub/docs/ingestion_local.md"}
{"text": "d ingestion. You call /catalog/install with:\n• \"id\": \"mcp_server:your-id@version\"\n• Optionally with an inline \"manifest\": {...}\nThis is great for quick tests and avoids needing DB or ingestion.\n3A) Catalog flow — Create a correct index & serve it\nThe ingestor supports **one** of these top-level keys in index.json:\n* **Form A**: \"manifests\"\n{\"manifests\": [\"https://.../x.manifest.json\", ...]}\n* **Form B**: \"items\"\n{\"items\": [{\"manifest_url\": \"https://.../x.manifest.json\"}, ...]}\n* **Form C**: \"entries\"\n{\"entries\": [{\"path\":\"x.manifest.json\",\"base_url\":\"https://host/matrix/\"}]}\nIf you use entities or something else, you will see:\n**“No compatible ingest function found in src.services.ingest”.**\n3A.1) Create **supported** index shape: items\nFrom the Matrix-Hub repo root:\n3A.2) Add your manifes", "source": "github:agent-matrix/matrix-hub/docs/ingestion_local.md"}
{"text": ".services.ingest”.**\n3A.1) Create **supported** index shape: items\nFrom the Matrix-Hub repo root:\n3A.2) Add your manifest URL to the index\nThis produces matrix/index.json like:\n3A.3) Serve your repo folder\nIn the **same repo root** (the folder containing your matrix/ directory):\nOpen a **new terminal**, and check your files are reachable:\nExport your index URL:\n**Critical sanity check**: If the JSON printed by curl does **not** show \"items\" or shows unexpected URLs, you are **serving the wrong folder** — cd to the folder that contains your matrix/ and run python3 -m http.server 8001 **there**.\n4A) Register your index & ingest\nMake sure HUB_URL and ADMIN_TOKEN are set (Step 1).\n4A.1) Register the remote\nYou should see an idempotent response like:\nIf you get URL using bad/illegal format or m", "source": "github:agent-matrix/matrix-hub/docs/ingestion_local.md"}
{"text": "p 1).\n4A.1) Register the remote\nYou should see an idempotent response like:\nIf you get URL using bad/illegal format or missing URL, your $HUB_URL is empty. Go back to **Step 1** and export it correctly.\n4A.2) Ingest\nExpected outcome:\n• \"ok\": true for your index, with stats (manifests processed)\n• Your Entity row (mcp_server:hello-sse-server@0.1.0) upserted in the DB\n**If you see** No compatible ingest function found:\n* Your index shape is wrong or\n* Hub fetched a non-JSON page (like HTML error)\n**Fix**:\nThen run /remotes and /ingest again.\n4A.3) Install (register into MCP-Gateway)\nNow that the Entity exists in the DB from ingest, install by UID:\nThis reads the manifest via the Entity’s source_url and, if it has:\n…it will call MCP-Gateway to **register** that server.\n**Gateway env**: In you", "source": "github:agent-matrix/matrix-hub/docs/ingestion_local.md"}
{"text": "a the Entity’s source_url and, if it has:\n…it will call MCP-Gateway to **register** that server.\n**Gateway env**: In your Hub .env, set:\nRestart the Hub after setting env. Without these, registration will fail (401). Check Hub logs (make dev terminal) for details.\n3B) Direct install (skip catalog/ingest)\nFor quick testing (no index required), send the **inline manifest**:\nIf you still get **500** on direct install:\n* Make sure the DB schema exists (for SQLite dev: INIT_DB=true in .env or run make upgrade).\n* Ensure MCP_GATEWAY_URL and MCP_GATEWAY_TOKEN are set **in the Hub process** (restart after changing).\n* Check the logs from the terminal where make dev is running — tracebacks point to the exact cause.\n5) Make sure your MCP server is reachable\nIf your manifest specifies \"url\": \"http://", "source": "github:agent-matrix/matrix-hub/docs/ingestion_local.md"}
{"text": "racebacks point to the exact cause.\n5) Make sure your MCP server is reachable\nIf your manifest specifies \"url\": \"http://127.0.0.1:8000/messages/\", **run the server**:\n**Docker note**: If Hub or Gateway runs in Docker, 127.0.0.1 refers to the container. Use http://host.docker.internal:8000/ (Docker Desktop) or a LAN IP/compose service DNS so the container can reach your server.\n6) Quick connectivity test (optional helper)\nYou can validate **Hub health** and **index/manifest reachability & shape** with:\nIf it shows 200 for both and recognizes the index shape (items, manifests, or entries), /ingest will work.\n7) Common pitfalls (and precise fixes)\n• **“URL using bad/illegal format or missing URL”**\nYou didn’t set HUB_URL. Do **Step 1** (make gateway-token), export ADMIN_TOKEN & HUB_ENDPOINT, ", "source": "github:agent-matrix/matrix-hub/docs/ingestion_local.md"}
{"text": "format or missing URL”**\nYou didn’t set HUB_URL. Do **Step 1** (make gateway-token), export ADMIN_TOKEN & HUB_ENDPOINT, then normalize HUB_URL.\nSanity check:\n• **“No compatible ingest function found in src.services.ingest”**\nYour index.json is not in items/manifests/entries form **or** Hub fetched a non-JSON page.\nFix:\nAnd ensure you're serving the correct folder with python3 -m http.server 8001 in that directory.\n• **422 on /catalog/install**\nYour API expects \"id\" in the body. Include \"id\": \"mcp_server:<name>@<version>\" even when sending inline manifest.\n• **500 on /catalog/install**\nUsually happens if:\n• The Entity isn’t in DB (when doing UID-only install) → fix by ingesting first.\n• Gateway env isn’t set or reachable (MCP_GATEWAY_URL, MCP_GATEWAY_TOKEN).\n• DB schema not initialized (SQL", "source": "github:agent-matrix/matrix-hub/docs/ingestion_local.md"}
{"text": "sting first.\n• Gateway env isn’t set or reachable (MCP_GATEWAY_URL, MCP_GATEWAY_TOKEN).\n• DB schema not initialized (SQLite dev: INIT_DB=true or run make upgrade).\n• **Serving the wrong folder**\nYou must run python3 -m http.server 8001 **in the same directory** that contains your matrix/ folder and the index.json you created. Recheck with:\n8) When Hub is online (e.g., https://www.matrixhub.io)\n• Set:\n• Publish your matrix/index.json and manifests on public URLs (GitHub raw, S3).\n• Run the same /remotes → /ingest → /catalog/install flow with those public URLs.\n9) TL;DR (copy-paste)\nStart Hub & set token\nCatalog (local)\nDirect install\nQuick reality checks\n• **Is my index served?**\ncurl -sS http://127.0.0.1:8001/matrix/index.json | jq .\n*Must show proper JSON with \"items\":[{\"manifest_url\":\"..", "source": "github:agent-matrix/matrix-hub/docs/ingestion_local.md"}
{"text": "rved?**\ncurl -sS http://127.0.0.1:8001/matrix/index.json | jq .\n*Must show proper JSON with \"items\":[{\"manifest_url\":\"...\"}].*\n• **Is my Hub URL set?**\necho \"$HUB_URL\" → *must be http://127.0.0.1:443.*\n• **Do I have logs?**\nThe terminal running make dev shows detailed errors if something fails (DB, Gateway registration, schema mismatch, etc.).\nWith these steps — **supported index** (items), **correctly served folder**, **HUB\\_URL + ADMIN\\_TOKEN set**, **DB initialized**, and **inline manifest** available when needed — you will reliably ingest and install locally. Later, switch to public URLs and https://www.matrixhub.io with the **same workflow**.", "source": "github:agent-matrix/matrix-hub/docs/ingestion_local.md"}
{"text": "Ingestors\nThe ingestor discovers manifests from remote catalogs and feeds the validator + normalizer.\nSources\n• **Mode A — index.json** (preferred): a single file listing manifest URLs (and optional checksums).\n• **Mode B — tree/ZIP**: list repo trees via API or download a ZIP and scan *.manifest.yaml.\nSample index.json\nScheduling\nDefault: every 15 minutes via APScheduler (INGEST_INTERVAL_MIN).\nManual trigger: POST /catalog/ingest?remote=name (if admin token enabled).\nHTTP Etiquette\nUse ETag/Last-Modified to avoid re-downloading.\nRespect 429/5xx with exponential backoff.\nTimeouts tuned (connect/read) to keep the scheduler responsive.\nProvenance & Idempotency\nEach upsert stores remote.name, commit/etag, and last_sync_ts.\nUpsert key: (type, id, version); replays are safe.\nOn validation failu", "source": "github:agent-matrix/matrix-hub/docs/ingestors.md"}
{"text": "Install & Registration\nInstall steps\n• **pypi** — uv pip install (with pip fallback)\n• **oci** — docker pull\n• **git** — git clone and optional checkout\n• **zip** — download & extract (hash-checked when digest is provided)\nEach step is **idempotent** where possible (e.g., docker pull, git checkout).\nAdapters\n• Manifest adapters entries instruct Matrix Hub to write glue code/templates into your project:\n• Example: LangGraph node in src/flows/...\n• Example: WatsonX Orchestrate skill.yaml\n• Files are listed under files_written and referenced in matrix.lock.json.\nLockfile\nmatrix.lock.json captures:\n• Entity ID & version\n• Artifacts resolved\n• Adapters written\n• Provenance (manifest URL, optional commit)\nMCP Gateway registration\nIf the manifest contains mcp_registration:\n• **tool** — POST /tool", "source": "github:agent-matrix/matrix-hub/docs/install-and-registration.md"}
{"text": "nifest URL, optional commit)\nMCP Gateway registration\nIf the manifest contains mcp_registration:\n• **tool** — POST /tools (integration_type: REST/MCP, request_type, url, input_schema)\n• **server** — POST /gateways (transport: SSE/HTTP/STDIO/STREAMABLEHTTP)\n• **resources/prompts** — POST /resources, /prompts\nSome gateways perform discovery automatically after registration. Matrix Hub’s gateway client supports this by design.", "source": "github:agent-matrix/matrix-hub/docs/install-and-registration.md"}
{"text": "Catalog Manifests\nMatrix Hub consumes **manifests** stored in your catalog repo and indexed by an index.json.\nTypes\n• **Agent** — agent.manifest.yaml\n• **Tool** — tool.manifest.yaml\n• **MCP Server** — mcp-server.manifest.yaml\nCore fields\n• schema_version, type, id, name, version, description, license\n• capabilities, compatibility (frameworks/providers)\n• artifacts — list of { kind: pypi|oci|git|zip, spec: {...} }\n• endpoints (optional)\n• mcp_registration (optional)\n• adapters (optional)\nExample — Agent\nSchemas\n• schemas/agent.manifest.schema.json\n• schemas/tool.manifest.schema.json\n• schemas/mcp-server.manifest.schema.json\nDuring ingestion, schemas are validated; invalid manifests are skipped with warnings.", "source": "github:agent-matrix/matrix-hub/docs/manifests.md"}
{"text": "MCP Gateway Overview\nThe MCP Gateway (also known as Context Forge) is the central hub for the Model Context Protocol (MCP), providing:\n• **Service registry & discovery:** Agents register themselves and advertise their “tools” (capabilities).\n• **Request routing:** All requests go through a single HTTP gateway, which dispatches them to the correct service.\n• **Security & authentication:** Supports Basic Auth for user/admin access, and JWTs for fine‑grained, time‑limited tokens.\n• **Health monitoring:** Built‑in /health endpoint for readiness checks.\n• **Local & production modes:** Can run locally in a Python virtualenv or be containerized.\nKey Components\n| Component                | Location                        |\n| Makefile targets         | top‑level Makefile            |\n| Setup script", "source": "github:agent-matrix/matrix-hub/docs/mcp-gateway.md"}
{"text": "         | Location                        |\n| Makefile targets         | top‑level Makefile            |\n| Setup script             | scripts/setup-mcp-gateway.sh  |\n| Start/stop scripts       | scripts/start-mcp-gateway.sh, scripts/stop-mcp-gateway.sh |\n| Verification script      | scripts/verify_servers.sh     |\n| Core code                | mcpgateway/ directory         |\n| Default config template  | .env.example                  |\nGetting Started (Local Python Mode)\n1. **Setup environment**\nThis runs scripts/setup-mcp-gateway.sh to:\n• Check OS compatibility (Ubuntu 22.04 recommended)\n• Install Python 3.11 if missing\n• Install OS packages: git, curl, jq, etc.\n• Clone or update the IBM/mcp-context-forge repo at a pinned commit\n• Create (or recreate) a Python 3.11 virtualenv\n• Install Pyt", "source": "github:agent-matrix/matrix-hub/docs/mcp-gateway.md"}
{"text": "r update the IBM/mcp-context-forge repo at a pinned commit\n• Create (or recreate) a Python 3.11 virtualenv\n• Install Python dependencies in editable (.[dev]) mode\n• Copy .env.example → .env if needed\n2. **Start the gateway**\nInvokes scripts/start-mcp-gateway.sh, which:\n• Activates virtualenv\n• Loads .env vars\n• Initializes the SQLite (or configured) database\n• Launches mcpgateway on $HOST:$PORT (default 0.0.0.0:4444)\n• Waits (up to 2 minutes) for /health to return {\"status\":\"ok\"}\n3. **Verify it’s running**\nRuns scripts/verify_servers.sh, which checks:\n• HTTP /health endpoint\n• Admin /servers list (using JWT‑based admin token)\n• Any additional smoke tests\n4. **Stop the gateway**\nRuns scripts/stop-mcp-gateway.sh to kill any running mcpgateway processes.", "source": "github:agent-matrix/matrix-hub/docs/mcp-gateway.md"}
{"text": "Normalization\nConverts validated manifests into relational rows and auxiliary tables used by search & install.\nCanonical Identity\n• **UID**: \"{type}:{id}@{version}\" (e.g., agent:pdf-summarizer@1.4.2)\n• **Type**: agent | tool | mcp_server\n• **Name** (display), **Summary**, **Description**, **License**, **Homepage**, **Source URL**\nField Hygiene\n• **Capabilities / Tags**: lowercase slug tokens, deduplicated.\n• **Compatibility**: frameworks, providers, runtime, version ranges.\n• **Artifacts**: pypi | oci | git | zip with spec JSON.\n• **Adapters**: framework + template_key + optional path/params.\n• **mcp_registration**: tool/server/resources/prompts blocks.\nVersioning\n• Versions are strings; sorting is lexical unless catalog provides SemVer hints.\n• We do **not** infer \"latest\" at write time; ", "source": "github:agent-matrix/matrix-hub/docs/normalization.md"}
{"text": "ons are strings; sorting is lexical unless catalog provides SemVer hints.\n• We do **not** infer \"latest\" at write time; the **client** decides at read time.\nRejection Reasons (examples)\n• Schema violation: missing required fields.\n• Policy violation: denied license.\n• Unresolvable artifact: missing package or invalid image.", "source": "github:agent-matrix/matrix-hub/docs/normalization.md"}
{"text": "Observability\nLogging\n• JSON logs with correlation IDs via middleware.\n• Standard fields: timestamp, level, logger, message, request_id (when available).\nMetrics & Tracing\n• (Roadmap) Expose Prometheus metrics: ingest latency, search latency, install success rate.\n• (Roadmap) OpenTelemetry tracing around install steps and gateway calls.\nAudit\n• Record ingestion attempts and install steps in application logs.\n• Consider forwarding logs to ELK/Loki for retention and analysis.", "source": "github:agent-matrix/matrix-hub/docs/observability.md"}
{"text": "Querying Architecture\nSearch blends **lexical** and **semantic** signals with quality & recency, then optionally performs RAG to produce a “fit reason”.\nScoring\nscore_final = w_sem*sem + w_lex*lex + w_q*quality + w_r*recency\nWeights configured at runtime (e.g., sem=0.6, lex=0.4 by default).\nCaching\n• **ETag/Last-Modified** per query/filter tuple.\n• Clients should respect 304 Not Modified.\nFailure Modes\n• If vector backend is unavailable, we fall back to lexical only.\n• If lexical backend is unavailable, semantic only.\n• Results include which modes contributed to the final score.", "source": "github:agent-matrix/matrix-hub/docs/querying-architecture.md"}
{"text": "Querying API\nMatrix Hub exposes GET /catalog/search for discovery with optional hybrid ranking and RAG.\nEndpoint\nGET /catalog/search\nQuery Parameters\n• q *(required)*: free-text query\n• type: agent | tool | mcp_server\n• capabilities: CSV (pdf,summarize)\n• frameworks: CSV (langgraph,watsonx_orchestrate)\n• providers: CSV (openai,watsonx)\n• mode: keyword | semantic | hybrid (default from settings)\n• limit: default 20\n• offset: default 0\n• with_rag: true|false\n• rerank: none | llm (future)\n• etag: handled via If-None-Match header\nResponse (shape)\nExamples", "source": "github:agent-matrix/matrix-hub/docs/querying.md"}
{"text": "Quickstart\nRequirements\n• Docker 24+ with docker compose\n• Or Python 3.11/3.12 for local dev\n1) Clone and configure\nEdit .env as needed (e.g., MATRIX_REMOTES to your catalog’s index.json).\n2) Run with compose\nExpected:\n3) Search the catalog\n4) Install into your project\nThis writes project adapters and apps/pdf-bot/matrix.lock.json.\nIf the manifest includes mcp_registration, the installer also registers the tool/server with MCP Gateway.\n5) Local development (no Docker)\nopen http://localhost:443/health", "source": "github:agent-matrix/matrix-hub/docs/quickstart.md"}
{"text": "Python SDK (matrix-python-sdk)\nThe SDK provides a small client for Matrix Hub APIs, used by both the CLI and the agent generator.\nInstall\nUsage\nTimeouts & Retries\nDefault timeout: 20s (configurable per client).\nRetries handled by the CLI for network hiccups; the server is idempotent.\nAuth\nIf API_TOKEN is set on the server, pass a Bearer token:", "source": "github:agent-matrix/matrix-hub/docs/sdk.md"}
{"text": "Search & Indexing Architecture\nThe diagram below shows the “Ingest & Index Pluggable” → “Query & Rank Stable API” flow, and the table that follows maps each piece to the matrix-hub modules that implement it (as well as the native client and SDK).\nImplementation Mapping\n| Flow Node                                              | Package / Module                 | File(s)                                              |\n| **GitHub Ingestor**<br/>(manifests + READMEs)          | matrix-hub (Companion service) | src/services/ingest.py                             |\n| **Normalizer**<br/>(validate + enrich + version)       | matrix-hub                     | src/services/validate.py + parts of ingest.py    |\n| **Catalog DB**<br/>(Postgres or SQLite)                | matrix-hub                     | s", "source": "github:agent-matrix/matrix-hub/docs/search-diagram.md"}
{"text": " + parts of ingest.py    |\n| **Catalog DB**<br/>(Postgres or SQLite)                | matrix-hub                     | src/db.py, src/models.py                         |\n| **Chunker**<br/>(name/desc/README/examples)            | matrix-hub (search internals)  | src/services/search/chunking.py                    |\n| **Embedder**<br/>(MiniLM model; workers)               | matrix-hub (search backends)   | src/services/search/backends/embedder.py           |\n| **Vector Index**<br/>(pgvector → Milvus)               | matrix-hub (search backends)   | src/services/search/backends/vector.py             |\n| **BlobStore**<br/>(local disk → S3/MinIO)              | matrix-hub (search backends)   | src/services/search/backends/blobstore.py          |\n| **GET /catalog/search**<br/>(Stable API)        ", "source": "github:agent-matrix/matrix-hub/docs/search-diagram.md"}
{"text": "ch backends)   | src/services/search/backends/blobstore.py          |\n| **GET /catalog/search**<br/>(Stable API)               | matrix-hub (API routes)        | src/routes/catalog.py                              |\n| **Lexical Search**<br/>(pg\\_trgm BM25 → OpenSearch)    | matrix-hub (search backends)   | src/services/search/backends/lexical.py            |\n| **Hybrid Ranker**<br/>(weights in config)              | matrix-hub (search logic)      | src/services/search/ranker.py                      |\n| **RAG (optional)**<br/>(fetch best chunks + summarize) | matrix-hub (search logic)      | src/services/search/rag.py                         |\n| **Python SDK**<br/>(client library)                    | matrix-python-sdk              | matrix_sdk/client.py, cache.py, types.py       |\n| **Agent", "source": "github:agent-matrix/matrix-hub/docs/search-diagram.md"}
{"text": "ibrary)                    | matrix-python-sdk              | matrix_sdk/client.py, cache.py, types.py       |\n| **Agent Creator**<br/>(native CLI client)              | matrix-cli                     | matrix_cli/__main__.py, matrix_cli/commands/*.py |\n| **Agent Generator Plugin**<br/>(reuse‑first)           | agent-generator-matrix         | agent_generator_matrix/plugin.py                   |\n**Note:**\n• All ingestion, indexing, embedding and search‑and‑rank logic lives in **matrix-hub** under its services/ and routes/ directories.\n• The **Python SDK** (matrix-python-sdk) and **CLI** (matrix-cli aka “agent‑creator”) are the native clients of the platform.\n• The **agent-generator-matrix** plugin hooks your planning_agent.py to call Matrix Hub first (reuse‑first), then fall back to code g", "source": "github:agent-matrix/matrix-hub/docs/search-diagram.md"}
{"text": "Search\nMatrix Hub supports **lexical**, **semantic**, and **hybrid** ranking.\nLexical (keyword)\n• Backend: **pg_trgm** (PostgreSQL trigram), using BM25-ish scoring.\n• Fields: name, summary, description, tags/capabilities (flattened).\nSemantic (vector)\n• Backend: **pgvector** (optional).\n• Embedding: pluggable; the default build exposes a dummy embedder for local trials.\nHybrid ranking\nScore is a weighted blend:\nscore_final = w_sem * semantic + w_lex * lexical + w_q * quality + w_r * recency\nWeights are configurable via SEARCH_HYBRID_WEIGHTS (e.g., sem:0.6,lex:0.4,rec:0.1,q:0.1).\nRAG fit reasoning (optional)\nWhen with_rag=true, the service can fetch top README/manifest chunks and produce a short “fit_reason” string for each hit.\nLimits\n• On SQLite, only **keyword** mode is available.\n• For ", "source": "github:agent-matrix/matrix-hub/docs/search.md"}
{"text": "nks and produce a short “fit_reason” string for each hit.\nLimits\n• On SQLite, only **keyword** mode is available.\n• For large scale, consider migrating to **Milvus/Weaviate** for ANN and **OpenSearch** for lexical, keeping the same public API.", "source": "github:agent-matrix/matrix-hub/docs/search.md"}
{"text": "Security\nAPI authentication\n• If API_TOKEN is set, admin routes require Authorization: Bearer <token>.\nSupply chain\n• Prefer oci artifacts with signed images and digests.\n• Prefer pinned Python versions (e.g., ==1.4.2) or upper bounds.\nPolicies (extensible)\n• License allow/deny lists at ingest and install time.\n• Optional signature and SBOM validation hooks (stubs in current release).\nNetwork egress\n• Installer performs pip, docker, and git operations.\n• Use allowlists/proxies as required by your environment.\nSecrets\n• Do not commit .env. Provide tokens via Secret managers where possible.", "source": "github:agent-matrix/matrix-hub/docs/security.md"}
{"text": "MCP Gateway Setup\nThis document describes how to install and prepare the MCP Gateway for local development.\nPrerequisites\n• Ubuntu 22.04 (other Linux distros may work with small adjustments)\n• Internet access to GitHub\n• sudo privileges to install system packages\nInstallation Steps\nWhat the setup script does\n1. **OS check**\nWarns if not running Ubuntu 22.04.\n2. **Python 3.11**\n• Checks python3.11 on PATH\n• If missing, runs scripts/install_python.sh (must exist)\n3. **System packages**\n4. **Clone or update repo**\n• On first run: clones at commit 1a37247c21cbeed212cbbd525376292de43a54bb\n• On subsequent runs: git fetch && git pull --ff-only and optionally resets to that commit.\n5. **Virtualenv**\n• Creates (or optionally recreates) .venv using python3.11 -m venv\n• Activates venv and upgrades pi", "source": "github:agent-matrix/matrix-hub/docs/setup-mcp-gateway.md"}
{"text": "t.\n5. **Virtualenv**\n• Creates (or optionally recreates) .venv using python3.11 -m venv\n• Activates venv and upgrades pip, setuptools, wheel\n6. **Python dependencies**\n• Installs editable dev extras: pip install -e '.[dev]' (or falls back to -e .)\n• If present, falls back to requirements.txt\n7. **Environment file**\n• Copies .env.example → .env if no .env exists\n• You must review and edit .env for credentials, ports, etc.", "source": "github:agent-matrix/matrix-hub/docs/setup-mcp-gateway.md"}
{"text": "Vector Indexing\nMatrix Hub supports a pluggable vector layer:\n• **Day-1**: pgvector (PostgreSQL extension)\n• **Later**: Milvus/FAISS/Weaviate (adapter interface is already isolated)\npgvector (recommended to start)\n• Table: embedding_chunk\n• entity_uid, chunk_id, vector, weight, model_id, timestamps\n• Index type: IVF/Flat/HNSW (choose based on your pgvector version and dataset size)\n• Tunables:\n• IVF lists / probes for recall vs. latency\n• HNSW m, ef_search if available\n• Filter strategy: apply filters on entity first (type, caps), then join candidates to ANN results.\nExample (conceptual)\nAlternatives (future)\nMilvus: stand-alone ANN with collections per model_id.\nAPI contracts for vector search remain the same: search(query_vec, filters, k) → hits.", "source": "github:agent-matrix/matrix-hub/docs/vector-indexing.md"}
{"text": "MCP Gateway Verification\nAfter setup and starting the gateway, run a few checks to ensure it’s operational.\nUsing the provided script\nThis will:\n1. **Check health endpoint**\n2. **List registered servers**\n3. **(Optional) Additional smoke tests**\n• Probe any custom agent endpoints you may have registered\n• Tail logs: tail -f mcpgateway/logs/mcpgateway.log for errors/warnings\nManual Verification\n1. **Open browser**\nNavigate to http://localhost:4444/admin/, log in with your Basic Auth user (default admin/changeme).\n2. **Inspect Dashboard**\n• No agents listed initially\n• Check “Servers” tab to confirm the gateway itself is registered\n3. **API calls**\nTry a few calls with curl or Postman to /health, /servers, etc.", "source": "github:agent-matrix/matrix-hub/docs/verify-mcp-gateway.md"}
{"text": "WatsonX Agent Creator\nThe **WatsonX Agent Creator** project provides a simple and interactive way to generate agents on watsonx.ai on the fly.\nIt uses a wizard that collects user requirements and configures a new agent automatically based on a selected framework.\nThis tool supports multiple base frameworks and offers the option to customize the agent code using AI-powered logic.\nSupported Frameworks\nWhen generating a new agent, you can choose from the following frameworks:\n| # | Framework | Notes |\n| 1 | **watsonx sdk** | Adds ibm-watsonx-ai + Python < 3.13 constraint |\n| 2 | **beeai** | Adds beeai-framework |\n| 3 | **langraph** | Adds langgraph + langchain-ibm |\n| 4 | **crewai** | Adds crewai starter code (soon) |\n| 5 | **langflow** | Adds langflow playground |\n| 6 | **no framework**| Use", "source": "github:agent-matrix/watsonx-agent-creator/README.md"}
{"text": "crewai** | Adds crewai starter code (soon) |\n| 5 | **langflow** | Adds langflow playground |\n| 6 | **no framework**| Uses the *base* template only |\nChoosing a framework stores its extra requirements in\nassets/frameworks/<framework>/pyproject.fragment.toml.\nIf you select **no framework**, the wizard uses assets/frameworks/base.\nAgent Customization\nAfter selecting a framework and setting up the base model files, the wizard offers an optional customization step.\n• **YES** ⇒ you describe a new task → agent_creator/generator.py rewrites the original agent.py with help of Granite LLM → result saved as **agent_custom.py**.\n• **NO** ⇒ the default agent.py remains unchanged.\n▶ **NEW – Dependency & Lock-file Handling**\n• Each generated agent is a standalone **Poetry** project (pyproject.toml + poet", "source": "github:agent-matrix/watsonx-agent-creator/README.md"}
{"text": "NEW – Dependency & Lock-file Handling**\n• Each generated agent is a standalone **Poetry** project (pyproject.toml + poetry.lock) under app/.\n• The generator now builds the file in **PEP 621** format **and** keeps a legacy [tool.poetry] section for full compatibility.\n• **Framework fragments** are merged automatically — caret (^) versions are converted to PEP 508 ranges for the [project] list but retained in the legacy table.\n• The wizard calls poetry lock, guaranteeing a reproducible environment before you ever cd into the agent.\nPipeline Overview\nThe complete pipeline of the agent-creation process works as follows:\n1. **Framework Selection**\n• The system prompts you to choose a framework (or no framework) from a list of supported options.\n• Based on your selection, the corresponding model", "source": "github:agent-matrix/watsonx-agent-creator/README.md"}
{"text": "hoose a framework (or no framework) from a list of supported options.\n• Based on your selection, the corresponding model folder is created under assets/frameworks.\n2. **Base Model Setup**\n• The default agent code is copied from assets/model/agent.py to the newly created framework folder.\n3. **Agent Customization (Optional)**\n• You are asked if you wish to customize the agent.\n• If yes, the system loads the agent code, requests a new task description, and calls the generator in agent_creator/generator.py to produce a customized version.\n• The customized code is saved as **agent_custom.py**.\n4. **Project Generation**\n• The remaining project components such as the Dockerfile, compose file, README, Git configuration, etc., are generated.\n5. **Dependency Resolution & Lock-file creation** ▶ **NE", "source": "github:agent-matrix/watsonx-agent-creator/README.md"}
{"text": ", compose file, README, Git configuration, etc., are generated.\n5. **Dependency Resolution & Lock-file creation** ▶ **NEW**\n6. **Registration in agents.json / optional Git push**\n• A new repository is optionally created and pushed to the watsonx-agents GitHub organization.\n• The project’s metadata is updated in agents.json.\nExample of Usage\n1. **Clone the Repository**\n2.  **Create and Activate a Python Virtual Environment**\n3.  **Create a New Agent**\nFrom the project’s main directory, run the following script:\n• You will be prompted to select a framework.\n• Next, the system will set up the corresponding model files.\n• Optionally, you can choose to customize your agent by providing a new task description.\nIf you do, an updated agent code will be generated in **agent\\_custom.py**.\nA new repo", "source": "github:agent-matrix/watsonx-agent-creator/README.md"}
{"text": "providing a new task description.\nIf you do, an updated agent code will be generated in **agent\\_custom.py**.\nA new repository will be created under the GitHub organization (with a name such as agent_<agent_name>),\nand the agents.json file will be updated with your new agent details.\n▶ **NEW – Quick “inside the agent” tour**\nAfter generation:\nVisit http://localhost:\\<agent\\_port\\>/docs to poke the FastAPI endpoint.\nAll environment variables live in the agent’s .env; secrets never leak into git.\nExample of a Generated Agent Structure\nAfter generating a new agent, the directory structure might look like this:\nExample Without a Framework\nIf you choose **no framework**, the project will create the assets/frameworks/base/model folder with the default agent code.\nYou can later update the **model", "source": "github:agent-matrix/watsonx-agent-creator/README.md"}
{"text": "roject will create the assets/frameworks/base/model folder with the default agent code.\nYou can later update the **model/agent.py** file as needed for further customizations.\n**model/agent.py Example:**\nTo test the agent without a framework:\n1.  Navigate to the app folder:\n2.  Install the dependencies:\n3.  Activate the poetry shell:\n4.  Run the agent's main script:\nYou can then access the API documentation and test endpoints via http://localhost:2001/docs (port 2001 is used as specified during setup).\n▶ **NEW – Contributing / Extending**\nAdd a new framework\n1.  Create assets/frameworks/<your_fw>/model/agent.py\n2.  Add pyproject.fragment.toml with any extra dependencies.\n3.  Update select_framework() list in the generator script.\nUpgrade dependencies\nEdit the fragment files or the generic b", "source": "github:agent-matrix/watsonx-agent-creator/README.md"}
{"text": ".  Update select_framework() list in the generator script.\nUpgrade dependencies\nEdit the fragment files or the generic bundle list in agent_creator/main.py; the generator will propagate the changes to every new agent.\nSummary\n• **Interactive Wizard:** Select a framework and optionally customize the agent task.\n• **AI-Powered Customization:** Use agent_creator/generator.py to generate an updated version of the agent code based on user-provided task descriptions.\n• **Automated Repository Management:** Optionally push the newly created agent to GitHub and update agents.json.\n• **Modular Design:** The agent’s core logic is encapsulated in the **model/agent.py** file (or **agent\\_custom.py** if customized), so developers can easily update or extend the functionality.\n• **Automatic pyproject + l", "source": "github:agent-matrix/watsonx-agent-creator/README.md"}
{"text": "nt\\_custom.py** if customized), so developers can easily update or extend the functionality.\n• **Automatic pyproject + lock-file with framework-specific deps.** ▲ **NEW**\n• **Modular assets:** edit a single file to support new frameworks. **NEW**\n• **One-command bootstrap:** bash create_agent.sh. **NEW**\nStart creating and customizing your agents with the WatsonX Agents Hub, and empower your applications with dynamic, AI-powered agents\\!", "source": "github:agent-matrix/watsonx-agent-creator/README.md"}
{"text": "<p align=\"center\">\n<img src=\"https://github.com/agent-matrix/.github/blob/main/profile/logo.png\" alt=\"Agent-Matrix Logo\" width=\"200\">\n<h1 align=\"center\">\nAgent-Matrix Catalog\n<p align=\"center\">\n<a href=\"https://github.com/ruslanmv/agent-generator\"><img src=\"https://img.shields.io/badge/Powered%20by-agent--generator-brightgreen\" alt=\"Powered by agent-generator\"></a>\n<a href=\"./LICENSE\"><img src=\"https://img.shields.io/badge/License-Apache%202.0-blue\" alt=\"License\"></a>\nOverview\nThe **Agent-Matrix Catalog** is a public, versioned registry of **MCP servers** (agents/tools) used by MatrixHub.\nIt publishes one canonical index.json with **absolute RAW URLs** to each server’s manifest.json, plus per-server folders containing a manifest.json and a per-folder index.json.\n• 🔗 **Top-level RAW index (", "source": "github:agent-matrix/catalog/README.md"}
{"text": "nifest.json, plus per-server folders containing a manifest.json and a per-folder index.json.\n• 🔗 **Top-level RAW index (main branch):**\nThis repo is designed for **high-volume**, **append-only** publishing: add new servers via Pull Request; CI refreshes the top index.\nRepository layout\n• **index.json** at the repo root contains **absolute** raw URLs to every manifest in servers/**/manifest.json.\n• Each **servers/<folder>/index.json** lists the manifest(s) in that folder, typically:\nbash\ncurl -s https://raw.githubusercontent.com/agent-matrix/catalog/refs/heads/main/index.json\njson\n\"manifests\": [\n\"https://raw.githubusercontent.com/agent-matrix/catalog/refs/heads/main/servers/<folder-a>/manifest.json\",\n\"https://raw.githubusercontent.com/agent-matrix/catalog/refs/heads/main/servers/<folder-b>/", "source": "github:agent-matrix/catalog/README.md"}
{"text": "s/<folder-a>/manifest.json\",\n\"https://raw.githubusercontent.com/agent-matrix/catalog/refs/heads/main/servers/<folder-b>/manifest.json\"\nbash\npip install mcp-ingest\nbash\nEmits manifest.json + index.json\nmcp-ingest pack ./path/to/server --out ./dist\nCredits\n• **Lead developer:** *Ruslan Magana Vsevolodovna* — https://ruslanmv.com\n• **Model Context Protocol** community for the protocol and reference servers.\n• Maintainers and contributors across the Agent-Matrix ecosystem.\n“Powered by agent-generator and mcp-ingest.”\nLicense\nThis catalog is released under the **Apache License 2.0**.\nSee LICENSE for details.", "source": "github:agent-matrix/catalog/README.md"}
{"text": "🦾 MCP Ingest\n*Discover, describe, and register AI agents with ease.*\n<p align=\"center\">\n<a href=\"https://pypi.org/project/mcp-ingest/\"><img src=\"https://img.shields.io/pypi/v/mcp-ingest?color=blue\" alt=\"PyPI\"></a>\n<a href=\"https://pypi.org/project/mcp-ingest/\"><img src=\"https://img.shields.io/pypi/pyversions/mcp-ingest.svg?logo=python\" alt=\"Python Versions\"></a>\n<a href=\"https://github.com/agent-matrix/mcp_ingest/actions/workflows/ci.yml\">\n<img src=\"https://github.com/agent-matrix/mcp_ingest/actions/workflows/ci.yml/badge.svg?branch=master\" alt=\"CI\">\n<a href=\"https://agent-matrix.github.io/matrix-hub/\"><img src=\"https://img.shields.io/static/v1?label=docs&message=mkdocs&color=blue&logo=mkdocs\" alt=\"Docs\"></a>\n<a href=\"https://github.com/agent-matrix/mcp_ingest/blob/master/LICENSE\"><img src", "source": "github:agent-matrix/mcp_ingest/README.md"}
{"text": "olor=blue&logo=mkdocs\" alt=\"Docs\"></a>\n<a href=\"https://github.com/agent-matrix/mcp_ingest/blob/master/LICENSE\"><img src=\"https://img.shields.io/badge/License-Apache%202.0-blue\" alt=\"License: Apache-2.0\"></a>\n<a href=\"https://github.com/ruslanmv/agent-generator\"><img src=\"https://img.shields.io/badge/Powered%20by-agent--generator-brightgreen\" alt=\"Powered by agent-generator\"></a>\n**mcp-ingest** is a tiny SDK + CLI that turns *any* MCP server/agent/tool into a **MatrixHub‑ready** artifact. It lets you:\n• **Discover** servers from a folder, Git repo, or ZIP — even whole registries (harvester).\n• **Describe** them offline → emit manifest.json + index.json (SSE normalized).\n• **Validate** in a sandbox or container (handshake, ListTools, one CallTool).\n• **Publish** to S3/GitHub Pages and **Reg", "source": "github:agent-matrix/mcp_ingest/README.md"}
{"text": " **Validate** in a sandbox or container (handshake, ListTools, one CallTool).\n• **Publish** to S3/GitHub Pages and **Register** to MatrixHub (/catalog/install).\nBuilt for **Python 3.11**, packaged for **PyPI**, with strict lint/type/test gates.\nYou can catalog **millions** of MCP candidates offline and install on demand per tenant/workspace — the fastest path to building **the Matrix** of interoperable agents and tools.\nInstall\nFor contributors:\nQuickstart\nSDK (authors)\nCLI (operators)\nHarvest a whole repo\nHarvest a multi-server repository (e.g., the official MCP servers collection):\nOutputs one manifest.json per detected server and a **repo-level index.json** that lists them all. Optionally --publish s3://… and/or --register.\nMatrixHub integration\n• Preferred path: **POST /catalog/install", "source": "github:agent-matrix/mcp_ingest/README.md"}
{"text": "them all. Optionally --publish s3://… and/or --register.\nMatrixHub integration\n• Preferred path: **POST /catalog/install** with the **inline manifest** (what autoinstall() and mcp-ingest register do). And when is installed and running the mcp server can be later imported in MCP Gateway for future use.\n• **Idempotent** by design: HTTP **409** is treated as success; safe to re-run.\n• **SSE normalization**: we auto-fix URLs to end in /sse unless the manifest explicitly requests /messages or a different transport.\n**Deferred install**: You can *describe* millions of candidates offline, then install only when a tenant wants them.\nTransports\nMCP Ingest supports three server transports when building manifests:\n• **SSE** (default): URL is normalized to /sse if needed.\n• **STDIO**: provide an exec ", "source": "github:agent-matrix/mcp_ingest/README.md"}
{"text": "nsports when building manifests:\n• **SSE** (default): URL is normalized to /sse if needed.\n• **STDIO**: provide an exec block with cmd (e.g. Node servers via npx).\n• **WS**: WebSocket endpoints are preserved as provided.\nExample STDIO snippet:\nProject layout\nMkDocs documentation lives under docs/ (Material theme). CI builds lint/type/tests and wheels.\nDevelopment\nUse the Makefile helpers:\nLocal harvester API:\nCI & Quality\n• **Ruff** (lint), **Black** (format), **Mypy** (types), **Pytest** (coverage)\n• GitHub Actions workflow in .github/workflows/ci.yml\n• Package is built and uploaded as CI artifact; PyPI publishing via Twine is supported.\nSecurity & Safety\n• Idempotent HTTP and retries with exponential backoff (409 → success).\n• Sandboxes (process & container) with timeouts and memory caps", "source": "github:agent-matrix/mcp_ingest/README.md"}
{"text": "TP and retries with exponential backoff (409 → success).\n• Sandboxes (process & container) with timeouts and memory caps.\n• No secrets stored at rest; inject via environment only.\n• Logs are structured; per-job trace IDs in the harvester path.\nRoadmap\n• More detectors (framework coverage), stronger schema inference.\n• Richer validation (multiple tool calls, golden tests), SBOM/provenance by default.\n• Global public index shards (CDN) fed by the harvester.\nLicense\nmcp-ingest is licensed under the Apache License 2.0. See the LICENSE file for more details.\nAcknowledgements\nThis project is part of the **Agent‑Matrix** ecosystem and is inspired by the Model Context Protocol community work.", "source": "github:agent-matrix/mcp_ingest/README.md"}
{"text": "API Reference\nCLI Commands\nPython SDK\ndescribe(...)\nBuilds manifest.json and index.json without running the server. SSE URLs are normalized to /sse unless the transport indicates otherwise.\nautoinstall(...)\nRegisters a manifest by POSTing inline JSON to MatrixHub /catalog/install.\nHarvest Orchestrators\nmcp_ingest.harvest.repo.harvest_repo(source, *, out_dir, publish=None, register=False, matrixhub_url=None) -> HarvestResult\nHarvests a single repository (local dir | git URL | zip URL), finds subservers, emits per-server manifests, and writes a repo-level index.json.\n**Return:** HarvestResult { manifests: list[Path], index_path: Path, errors: list[str], summary: dict }\nmcp_ingest.harvest.source.harvest_source(repo_url, out_dir, *, yes=False, max_parallel=4, only_github=True, register=False, ", "source": "github:agent-matrix/mcp_ingest/docs/api.md"}
{"text": "ingest.harvest.source.harvest_source(repo_url, out_dir, *, yes=False, max_parallel=4, only_github=True, register=False, matrixhub=None, log_file=None) -> dict\nReads a GitHub repo’s README, extracts all GitHub candidates (including /tree/<ref>/<subdir>), harvests each, merges into one index.json, and optionally registers all manifests.\n**Return (dict):** {\"index_path\": str, \"manifests\": [...], \"manifests_count\": int, \"errors\": [...], \"by_detector\": {...}, \"transports\": {...}}\nExtractor Utilities\nmcp_ingest.utils.extractor.fetch_readme_markdown(repo_url: str) -> str | None\nFetch the README (default branch with fallbacks) for a GitHub repo URL.\nmcp_ingest.utils.extractor.extract_urls_from_markdown(md: str) -> list[str]\nExtract and dedupe all HTTP/HTTPS URLs from a README’s markdown.\nmcp_inges", "source": "github:agent-matrix/mcp_ingest/docs/api.md"}
{"text": "ract_urls_from_markdown(md: str) -> list[str]\nExtract and dedupe all HTTP/HTTPS URLs from a README’s markdown.\nmcp_ingest.utils.extractor.extract_github_repo_links_from_readme(repo_url: str) -> list[RepoTarget]\nReturn GitHub repo candidates (including /tree/<ref>/<subdir>) as RepoTarget items.\nTesting extraction\nGood happy coding..", "source": "github:agent-matrix/mcp_ingest/docs/api.md"}
{"text": "Architecture\nCore modules:\n• **detect/** — AST/regex detectors for FastMCP, LangChain, LlamaIndex, AutoGen, CrewAI, Semantic Kernel.\n• **emit/** — manifest & index emitters; MatrixHub adapters (optional).\n• **register/** — MatrixHub /catalog/install (preferred) and gateway fallback.\n• **validate/** — local & container sandboxes; MCP probe.\n• **publishers/** — S3/GH Pages static publishing + global index shards.\n• **services/harvester/** — internet‑scale discovery, workers, and persistence.\nDataflow", "source": "github:agent-matrix/mcp_ingest/docs/architecture.md"}
{"text": "API Reference\nCLI\n• mcp-ingest detect <source> → DetectReport\n• mcp-ingest describe <name> <url> [--tools ...] [--resource ...] [--out dir]\n• mcp-ingest register --matrixhub URL [--manifest path] [--entity-uid ...] [--target ./]\n• mcp-ingest pack <source> [--out dir] [--register] [--matrixhub URL]\nSDK\n• describe(name, url, tools=None, resources=None, description=\"\", version=\"0.1.0\", out_dir=\".\") -> {paths}\n• autoinstall(matrixhub_url, manifest=None, manifest_path=None, entity_uid=None, target=\"./\", token=None)\nHarvester (service)\n• POST /jobs {source, options} → {id}\n• GET  /jobs/{id} → status, artifacts\n• GET  /catalogs → list entries (filters)", "source": "github:agent-matrix/mcp_ingest/docs/backup/api.md"}
{"text": "Changelog\n0.1.0 — Initial release\n• SDK: describe, autoinstall\n• CLI: detect, describe, register, pack, harvest-repo\n• Detectors: FastMCP + heuristics; LangChain\n• Emitters: manifest/index/adapters\n• Harvester: minimal jobs API & worker integration", "source": "github:agent-matrix/mcp_ingest/docs/changelog.md"}
{"text": "Contributing\nWe welcome issues and PRs! Please:\n• Run make ci before submitting.\n• Keep changes small and well-tested.\n• Discuss large features in an issue first.\nBy contributing, you agree your work is licensed under the project license.", "source": "github:agent-matrix/mcp_ingest/docs/contributing.md"}
{"text": "Development\nPrereqs\n• Python 3.11\n• Docker (for container validation)\n• Make (optional)\nSetup\nUseful targets\nTests\n• Unit tests for emit/detect/utils.\n• E2E tests for CLI pack and harvest-repo (with small fixtures).\nVersioning\n• SemVer; stamp artifacts with tool versions and git SHA.", "source": "github:agent-matrix/mcp_ingest/docs/development.md"}
{"text": "FAQ\n**Do I have to run servers to generate manifests?**\nNo. describe(...) and harvest-repo generate manifests offline.\n**Can I validate tools automatically?**\nYes. Use container validation to handshake, list tools, and call one tool.\n**What about Node MCP servers?**\nUse transport=STDIO with an exec.cmd like npx -y @modelcontextprotocol/server-filesystem.", "source": "github:agent-matrix/mcp_ingest/docs/faq.md"}
{"text": "Harvest MCP Servers in a Repo **and** All Servers Linked in its README\nThis tutorial shows how to extract links from a repo’s README, harvest/describe every server found (both in the repo and linked externally), and optionally register the results to MatrixHub.\nExample target: https://github.com/modelcontextprotocol/servers\nPrerequisites\n• **Python 3.11**\n• **Virtualenv** (recommended)\n• *(Optional)* **MatrixHub** at http://127.0.0.1:7300\n• *(Optional)* **Docker** (only if you plan to validate in containers)\n• *(Recommended)* GITHUB_TOKEN to avoid GitHub rate limits\n1) Install mcp-ingest\n2) One command: Extract README → Harvest/Describe → (Optional) Register\nWhat this does\n1. **Reads the README** on the default branch (with fallbacks).\n2. **Identifies GitHub candidates**, including /tree/<", "source": "github:agent-matrix/mcp_ingest/docs/harvest-source.md"}
{"text": "s\n1. **Reads the README** on the default branch (with fallbacks).\n2. **Identifies GitHub candidates**, including /tree/<ref>/<subdir> links.\n3. **Plans** each candidate (repo vs. subdir-of-ref).\n4. **Detects & describes** with existing detectors (FastMCP, LangChain, LlamaIndex, AutoGen, CrewAI, Semantic Kernel; fallback to raw).\n5. **Emits** one manifest.json per server and **merges** all into a single index.json.\n6. **(Optional)** Registers each manifest to MatrixHub (/catalog/install, 409 is OK).\n**Useful flags**\n• --yes / -y Skip the confirmation prompt.\n• --max-parallel N Process multiple candidates concurrently.\n• --register --matrixhub URL Register results to MatrixHub.\n• --only-github Ignore non-GitHub links in the README.\n• --log-file FILE Write structured logs to disk.\n3) Inspect ", "source": "github:agent-matrix/mcp_ingest/docs/harvest-source.md"}
{"text": "Hub.\n• --only-github Ignore non-GitHub links in the README.\n• --log-file FILE Write structured logs to disk.\n3) Inspect results\nAll artifacts are written to dist/servers/:\n• Per-server **manifest.json**\n• A single **index.json** listing them all\nQuick checks:\nOpen a manifest:\n4) Register later (optional)\nRegistration is **idempotent**; HTTP 409 counts as success.\nTips & Troubleshooting\n• **Performance:** --max-parallel speeds things up when harvesting many candidates.\n• **Rate limits:** set GITHUB_TOKEN to avoid anonymous throttling.\n• **Safety:** the fetcher uses size/time limits and safe extraction (ZipSlip guards).\n• **Transports:** SSE is normalized unless /messages is explicitly used.\n• **STDIO:** Manifests include an exec block where applicable (Node MCP servers).\n• **Compare:** harv", "source": "github:agent-matrix/mcp_ingest/docs/harvest-source.md"}
{"text": "s explicitly used.\n• **STDIO:** Manifests include an exec block where applicable (Node MCP servers).\n• **Compare:** harvest-repo handles a single source; harvest-source expands to README-linked repos too.\nWhy this matters\nCurated READMEs often link to dozens of independent MCP servers. harvest-source turns a single entrypoint into a wide crawl, scaling your MatrixHub catalog with one command.", "source": "github:agent-matrix/mcp_ingest/docs/harvest-source.md"}
{"text": "Harvester Service\nThe harvester discovers sources, queues jobs, runs ingest in sandboxes, scores results, and (optionally) registers high‑quality servers into MatrixHub.\nAPI\n• POST /jobs {mode, source, options} → {id}\n• GET /jobs/{id} → status + artifacts\n• POST /harvest/repo {source, options} → shortcut for mode=harvest_repo\nJob payload\nRunning locally\nSee also: services/harvester/workers/runner.py and store/* modules.", "source": "github:agent-matrix/mcp_ingest/docs/harvester.md"}
{"text": "MCP Ingest\n*A tiny SDK + CLI to **discover, describe, validate, and register** MCP servers, agents, and tools into MatrixHub at planet scale.*\n• **SDK for authors** → describe(...) emits manifest.json/index.json; optional autoinstall(...) posts to MatrixHub.\n• **CLI for operators** → mcp-ingest harvest-repo <source> and pack <source> for end‑to‑end ingest.\n• **Harvester service** → internet‑scale discovery, scoring, and deferred install; keeps the catalog fresh.\nRequires **Python 3.11**. Works without MatrixHub, but integrates best with /catalog/install.\nInstall\nWhy MCP Ingest?\n• **Mass ingest**: Catalog millions of MCP endpoints offline, install on demand.\n• **Idempotent**: Safe re-runs; HTTP 409 is success; exponential backoff everywhere.\n• **Standards-aware**: Normalizes SSE endpoints; ", "source": "github:agent-matrix/mcp_ingest/docs/index.md"}
{"text": "MatrixHub Integration\nMCP Ingest integrates primarily via **POST /catalog/install** with an inline manifest. This is idempotent: HTTP 409 is treated as success.\nSSE normalization\n• If transport is SSE, manifests enforce the endpoint ends with /sse.\n• If a server uses /messages, keep it explicitly.\nSTDIO & WS\n• STDIO servers must provide an exec.cmd array (e.g., Node MCP servers via npx).\n• WS URLs are preserved.\nRegistration flow\n1. Detect → Describe → (optional) Validate/Publish.\n2. **Register** when a tenant wants the tool (runtime costs happen on demand).\nEnsure Matrix Hub is running and reachable at HUB_URL in your .env (or pass as arg)\nIf protected, set API_TOKEN in .env.\n1) Harvest\nmcp-ingest harvest-repo https://github.com/zazencodes/random-number-mcp --out dist/servers-first\n2) Reg", "source": "github:agent-matrix/mcp_ingest/docs/matrixhub.md"}
{"text": ".env.\n1) Harvest\nmcp-ingest harvest-repo https://github.com/zazencodes/random-number-mcp --out dist/servers-first\n2) Register\nchmod +x tests/test_register.sh\ntests/test_register.sh dist/servers-first/index.json", "source": "github:agent-matrix/mcp_ingest/docs/matrixhub.md"}
{"text": "Quickstart\nSDK (author)\nCLI (operator)\nHarvest a whole repo (many servers)\n**Result:** one manifest.json per subserver + a repo-level index.json.\nHarvest README-linked servers too\nUse the new integrated command to extract GitHub candidates from a repo’s README, harvest each, and (optionally) register them:\nThis first reads the README, finds all GitHub repo (and /tree/<ref>/<subdir>) links, then processes each candidate. See the full tutorial in **Tutorials → Harvest README-linked servers**.", "source": "github:agent-matrix/mcp_ingest/docs/quickstart.md"}
{"text": "SDK\ndescribe(...)\nBuilds manifest.json and index.json without running the server. SSE URLs are normalized to /sse unless the transport indicates otherwise.\nautoinstall(...)\nRegisters a manifest by POSTing inline JSON to MatrixHub /catalog/install.\nManifest transports\n• SSE → URL auto-normalized to /sse.\n• STDIO → requires exec: { cmd: [...] } block.\n• WS → keep URL as provided.", "source": "github:agent-matrix/mcp_ingest/docs/sdk.md"}
{"text": "Troubleshooting\nDocker not found\nInstall Docker and ensure it is on PATH. Container validation requires a local Docker daemon.\nSSE preflight fails\nCheck that your server listens on /sse and reachable on the expected port. Try curl -N http://127.0.0.1:6288/sse.\nGit clone errors\nPublic repos should work without tokens. For private repos, provide credentials or use ZIP archives.\nMatrixHub 404 on /catalog/install\nVerify MatrixHub is running and your --matrixhub URL is correct.", "source": "github:agent-matrix/mcp_ingest/docs/troubleshooting.md"}
{"text": "Harvest MCP Servers\nThis tutorial walks you through extracting links from a repository’s **README**, harvesting and describing **every MCP server** found (both inside the repo and **externally linked** from the README), and optionally **registering** them to MatrixHub.\n**Example target:** https://github.com/modelcontextprotocol/servers\nPrerequisites\n• **Python 3.11**\n• **Virtualenv** (recommended)\n• *(Optional)* **MatrixHub** running at http://127.0.0.1:7300\n• *(Optional)* **Docker** (only if you plan to run container validation)\n• *(Recommended)* GITHUB_TOKEN exported in your environment to avoid GitHub API rate limits\n1) Install mcp-ingest\nThe tools target prints versions for Python, ruff, black, mypy, pytest, and mkdocs to confirm your environment.\n2) One Command: README ➜ Harvest/Descr", "source": "github:agent-matrix/mcp_ingest/docs/tutorials/harvest-source.md"}
{"text": "ns for Python, ruff, black, mypy, pytest, and mkdocs to confirm your environment.\n2) One Command: README ➜ Harvest/Describe ➜ (Optional) Register\nWhat happens under the hood\n1. **Extracts** all URLs from the repo’s README (default branch with fallbacks).\n2. **Identifies GitHub candidates**, including links like /tree/<ref>/<subdir>.\n3. **Plans and processes** each candidate:\n• **Repo links** → analyze the repo root.\n• **/tree/<ref>/<subdir>** → fetch that ref and analyze just the subfolder.\n4. **Detects & describes** servers using built‑in detectors (FastMCP, LangChain, LlamaIndex, AutoGen, CrewAI, Semantic Kernel; fallback to a raw heuristic).\n5. **Emits** one manifest.json per server and writes a **single merged index.json** for the run.\n6. **(Optional)** **Registers** each manifest to M", "source": "github:agent-matrix/mcp_ingest/docs/tutorials/harvest-source.md"}
{"text": "son per server and writes a **single merged index.json** for the run.\n6. **(Optional)** **Registers** each manifest to MatrixHub (idempotent; HTTP 409 counts as success).\n7. **Prints a JSON summary** with counts by detector, transports, errors, and artifact paths.\nCommon flags\n• --yes / -y Skip the confirmation prompt.\n• --max-parallel N Process multiple candidates concurrently.\n• --register --matrixhub URL Register results to MatrixHub.\n• --only-github Ignore non‑GitHub links in the README.\n• --log-file FILE Write structured logs to disk.\n!!! note\nharvest-source is **read‑only and offline‑first** by default. It does not execute foreign code. Container validation is a separate step.\n3) Inspect Results\nArtifacts are written to dist/servers/:\n• Per‑server **manifest.json** (and a local index", "source": "github:agent-matrix/mcp_ingest/docs/tutorials/harvest-source.md"}
{"text": "arate step.\n3) Inspect Results\nArtifacts are written to dist/servers/:\n• Per‑server **manifest.json** (and a local index.json per server directory)\n• A single **repo‑level index.json** listing **all** manifests (in‑repo and README‑linked)\nQuick checks:\nOpen a specific manifest:\n4) Register Later (Optional)\nYou can register any manifest after the fact:\nRegistration is **idempotent**. If the entity already exists, HTTP **409** is treated as success.\n5) Tips & Troubleshooting\n• **Performance:** Use --max-parallel to process more candidates concurrently.\n• **Rate limits:** Set GITHUB_TOKEN to avoid anonymous throttling by GitHub.\n• **Safety:** The fetcher uses size/time limits and **ZipSlip**‑safe extraction.\n• **Transports:** SSE is normalized to /sse unless /messages is explicitly used.\n• **", "source": "github:agent-matrix/mcp_ingest/docs/tutorials/harvest-source.md"}
{"text": "s and **ZipSlip**‑safe extraction.\n• **Transports:** SSE is normalized to /sse unless /messages is explicitly used.\n• **STDIO:** Manifests include an exec block where applicable (e.g., Node servers via npx).\nIf you see GitHub 429/403 errors, wait or provide a GITHUB_TOKEN. If a candidate fails, the run continues and the error is included in the final summary.\n6) How This Differs From harvest-repo\n• harvest-repo scans **one source** (a git URL, zip URL, or local folder).\n• **harvest-source** first **extracts candidates from the README** and then calls the **harvest/describe** engine for **each** candidate, **merging everything** into a single catalog.\n7) How This Grows the MatrixHub Network\nRunning harvest-source across popular repos (and their README‑linked ecosystems) continuously **expan", "source": "github:agent-matrix/mcp_ingest/docs/tutorials/harvest-source.md"}
{"text": " MatrixHub Network\nRunning harvest-source across popular repos (and their README‑linked ecosystems) continuously **expands your MatrixHub catalog**:\n• **More coverage:** pulls in servers that live outside monorepos.\n• **Richer metadata:** standardized manifests improve discovery, ranking, and governance.\n• **Faster onboarding:** idempotent registration lets operators sync new servers with a single flag.\n• **Network effects:** more manifests → better discovery → more usage → more contributions → even richer catalogs.\n8) At Scale (Illustrative Summary)\n9) Non‑Interactive Script (Example)\nA minimal wrapper script is provided for repeatable runs:\nSet MATRIXHUB_URL to register as part of the run:\n10) See Also\n• Quickstart\n• CLI Reference\n• Harvester Service\n• MatrixHub Integration\n**Pro tip:** ", "source": "github:agent-matrix/mcp_ingest/docs/tutorials/harvest-source.md"}
{"text": " as part of the run:\n10) See Also\n• Quickstart\n• CLI Reference\n• Harvester Service\n• MatrixHub Integration\n**Pro tip:** For large scheduled runs, wire this into the **Harvester** service to queue jobs and persist artifacts/scoring automatically.", "source": "github:agent-matrix/mcp_ingest/docs/tutorials/harvest-source.md"}
{"text": "Matrix-Hub Admin (Next.js + MUI + NextAuth)\nA lightweight, modern admin UI to operate **Matrix-Hub** and **MCP Gateway** from your browser implemented with **custom Next.js Pages**, **MUI** for UI, **NextAuth** for authentication, and **axios** clients for Hub/Gateway APIs.\n✨ Features\n• **Authentication**\n• NextAuth **Credentials** provider (configurable admin user/password)\n• Protected routes by default; **/login** is public\n• **Login/Logout** buttons in the top bar\n• **Dark / Light mode**\n• One-click toggle in the navbar, persisted in localStorage\n• **Unified layout & navigation**\n• Top AppBar with active-page highlighting\n• Breadcrumb slot on each page\n• **Remotes**\n• Add/List/Delete remote index URLs\n• **Sync** (ingest + gateway re-affirm)\n• **Ingest All** (trigger hub ingest across al", "source": "github:agent-matrix/matrix-hub-admin/README.MD"}
{"text": "Add/List/Delete remote index URLs\n• **Sync** (ingest + gateway re-affirm)\n• **Ingest All** (trigger hub ingest across all remotes)\n• **Catalog**\n• **Search** with filters (type, capabilities, frameworks, providers)\n• Modes: **keyword / semantic / hybrid**, **rerank**: none / llm, optional **RAG fit reason**\n• One-click **Install** to target path\n• **Entities** (DB-backed list) and **Entity details** view with install\n• **Gateway**\n• Register an MCP server (name, URL, transport: SSE | HTTP | STREAMABLEHTTP | STDIO)\n• **Health**\n• Status cards for Hub and Gateway with **OK/DOWN**, latency, last-checked timestamp\n• **Settings**\n• Configure **Hub/Gateway tokens** (masked input, show/hide, clear)\n• Read-only Hub/Gateway URLs from env\n🧩 Tech stack\n• **Next.js (Pages Router)**\n• **MUI** (Material", "source": "github:agent-matrix/matrix-hub-admin/README.MD"}
{"text": "t, show/hide, clear)\n• Read-only Hub/Gateway URLs from env\n🧩 Tech stack\n• **Next.js (Pages Router)**\n• **MUI** (Material UI)\n• **NextAuth** (Credentials)\n• **axios** (API clients)\n• **TypeScript**\n• **Makefile** & **Dockerfile** (Next.js standalone build)\n🚀 Quick start\nRequires Node.js 18+ and npm.\n1 ) Clone the reepo\n2) Configure environment\nCopy the template and edit values:\n./.env.local:\n3) Run\nOpen http://localhost:3000 → you’ll be redirected to **/login**.\nUse the credentials from .env.local (default: admin / admin123).\n🗂 Project structure (high level)\n🔐 Auth & security\n• **Auth**: NextAuth with **Credentials** (JWT sessions).\nConfigure ADMIN_USER, ADMIN_PASS, and NEXTAUTH_SECRET in .env.local.\nThe app protects all pages by default; only **/login** is public.\n• **Tokens**\n• Hub/Gatewa", "source": "github:agent-matrix/matrix-hub-admin/README.MD"}
{"text": "XTAUTH_SECRET in .env.local.\nThe app protects all pages by default; only **/login** is public.\n• **Tokens**\n• Hub/Gateway tokens are **not** secrets in this UI and are stored in the browser’s localStorage (for convenience in dev).\n• For **production**, prefer a small Next.js **API route proxy** that reads tokens from secure **httpOnly cookies** and forwards to Hub/Gateway. That way, tokens never reach the browser.\n• Ensure **CORS** settings on Hub/Gateway allow your frontend origin for the endpoints you call.\n🔗 API assumptions\n**Matrix-Hub** (examples):\n• GET  /health\n• GET  /remotes\n• POST /remotes { url }\n• DELETE /remotes { url } (JSON body)\n• POST /remotes/sync {}\n• POST /ingest { url?: string | null }\n• GET  /catalog (DB-backed list)\n• GET  /catalog/search (filters/modes/rerank/with\\_", "source": "github:agent-matrix/matrix-hub-admin/README.MD"}
{"text": "OST /ingest { url?: string | null }\n• GET  /catalog (DB-backed list)\n• GET  /catalog/search (filters/modes/rerank/with\\_rag)\n• GET  /catalog/entities/:uid (details)\n• POST /catalog/install { id, target, version?, manifest?, source_url? }\n**MCP Gateway** (examples):\n• GET  /health\n• POST /gateways { name, url, transport, description? }\nBoth axios clients (hub/gw) attach Authorization: Bearer <token> if set.\n🧭 Typical workflow\n1. **Add a remote index**: /remotes → paste index URL → **Add**\n2. **Ingest**: either /remotes → **Ingest All** or /ingest (single URL or all)\n3. **Browse & install**:\n• /search → filter results (type, capabilities, frameworks, providers, mode, rerank) → **Install**\n• or /entities → open an entity → **Install**\n4. **Register in Gateway**: /gateway → enter server name/U", "source": "github:agent-matrix/matrix-hub-admin/README.MD"}
{"text": ") → **Install**\n• or /entities → open an entity → **Install**\n4. **Register in Gateway**: /gateway → enter server name/URL/transport → **Register Server**\nDepending on your Hub setup, the install flow may also assert/register servers automatically.\n🧪 Development scripts\n**npm scripts**\n**Makefile**\n🐳 Docker\nBuild & run with the Makefile:\nOr directly:\n🛠 Troubleshooting\n• **404 at /**\nThe home page redirects to /catalog. If you see 404, ensure src/pages/index.tsx exists and your dev server restarted.\n• **Unauthorized / admin pages redirect to /login**\nYou’re unauthenticated or session expired. Log in at /login.\n• **Hub/Gateway calls fail**\nConfirm NEXT_PUBLIC_HUB_URL / NEXT_PUBLIC_GW_URL and tokens in **Settings**. Check CORS rules on the servers.\n• **DELETE /remotes**\nFastAPI often expects ", "source": "github:agent-matrix/matrix-hub-admin/README.MD"}
{"text": "_PUBLIC_GW_URL and tokens in **Settings**. Check CORS rules on the servers.\n• **DELETE /remotes**\nFastAPI often expects JSON body on DELETE; this UI sends { data: { url } }.\n🧼 Code style & accessibility\n• MUI theming with color-mode toggle (persisted).\n• Active nav link uses aria-current=\"page\".\n• Health results expose status via aria-live=\"polite\".\n• Buttons/controls include descriptive labels.\n🙌 Contributing\nIssues and PRs are welcome. Please include:\n• Repro steps (for bugs)\n• Before/after screenshots (for UI changes)\n• API contract notes if endpoints change\n✅ Checklist before production\n• [ ] Replace credentials auth with your provider of choice (OIDC / SSO) or keep Credentials with strong secrets\n• [ ] Move tokens to secure **httpOnly cookies** behind a **Next.js API proxy**\n• [ ] Con", "source": "github:agent-matrix/matrix-hub-admin/README.MD"}
{"text": "redentials with strong secrets\n• [ ] Move tokens to secure **httpOnly cookies** behind a **Next.js API proxy**\n• [ ] Configure CORS on Hub/Gateway to the production origin\n• [ ] Add monitoring/alerts and Docker HEALTHCHECK if containerized\n• [ ] Review .env and disable any NEXT_PUBLIC_* secrets (never expose secrets client-side)", "source": "github:agent-matrix/matrix-hub-admin/README.MD"}
{"text": "MCP Server Template\nThis project is a template for building, packaging, and releasing \"Hello World\" MCP servers. It demonstrates a modern, automated workflow for creating distributable server bundles for two different transport modes:\n1.  **STDIO**: The server communicates over standard input/output pipes, ideal for direct CLI integrations.\n2.  **SSE (HTTP)**: The server runs as a standalone HTTP service, allowing multiple clients to connect via Server-Sent Events.\nThe repository is configured with an **industrialized build system** that automatically packages both server types for release.\n📂 Repository Layout\n✅ Prerequisites\n• **Python 3.11+**\n• **Poetry** (for dependency management)\n• **make** (GNU Make)\n• **gh CLI** (optional, for the make release command)\n🚀 Quickstart\nInstall dependenc", "source": "github:agent-matrix/mcp-template/README.md"}
{"text": "y management)\n• **make** (GNU Make)\n• **gh CLI** (optional, for the make release command)\n🚀 Quickstart\nInstall dependencies and set up your local virtual environment using Poetry. This single command prepares your entire development workspace.\n🧑‍💻 Development Workflow\nThis project uses the matrix SDK to simulate the full lifecycle of an MCP server: installing a bundle, running it as a managed process, and interacting with it.\nVersion 1: STDIO Communication\nThe STDIO server is managed as a background process by the matrix runtime.\n• **Build, Install, and Run the Server**\nThis command chains the entire process: builds the .zip bundle, installs it using the SDK, and starts the server.\n• **Test the Running Server**\nRuns the client script, which communicates with the background server over its ", "source": "github:agent-matrix/mcp-template/README.md"}
{"text": "he server.\n• **Test the Running Server**\nRuns the client script, which communicates with the background server over its STDIO pipes.\n• **Stop the Server**\nUses the SDK to gracefully stop the managed process.\n• **View Logs**\nVersion 2: SSE (HTTP) Communication\nThe SSE server is managed as a persistent HTTP service by the matrix runtime, which automatically handles port allocation.\n• **Build, Install, and Run the Server**\nBuilds the .zip bundle, installs it, and starts the HTTP server on an available port.\n• **Test the Running Server**\nRuns the client script, which connects to the server's SSE endpoint.\n• **Stop the Server**\n• **View Logs**\n📦 Automated Packaging & Release\nThis template is designed for automated releases.\n• **Build All Bundles Locally**\nThis command uses scripts/build_bundle.", "source": "github:agent-matrix/mcp-template/README.md"}
{"text": "his template is designed for automated releases.\n• **Build All Bundles Locally**\nThis command uses scripts/build_bundle.sh to create versioned .zip archives and .sha256 checksums for **both SSE and STDIO** servers in the dist/ directory.\n• **Create a GitHub Release**\nThe .github/workflows/release.yml workflow automates this entire process. Simply push a new tag to your repository:\nGitHub Actions will automatically build all bundles and attach them to a new release, ready for ingestion into Matrix Hub.\n📖 Makefile Targets\n| Target | Description |\n| make help | ✨ Display the list of available commands. |\n| make install | 📦 Set up virtualenv & install dependencies. |\n| make build | 🛠️  Builds versioned ZIP bundles for all server types. |\n| make release | 🚀 Creates a GitHub release with all bun", "source": "github:agent-matrix/mcp-template/README.md"}
{"text": "uild | 🛠️  Builds versioned ZIP bundles for all server types. |\n| make release | 🚀 Creates a GitHub release with all bundles (requires gh CLI). |\n| **STDIO** | |\n| make run-stdio | 🏃 Install and run the STDIO server via the SDK. |\n| make test-stdio | 🔬 Run the STDIO client against the SDK-managed server. |\n| make stop-stdio | 🛑 Stop the background STDIO agent server. |\n| make logs-stdio | 📜 View the logs for the STDIO server. |\n| **SSE (HTTP)** | |\n| make run-sse | 🏃 Install and run the SSE server via the SDK. |\n| make test-sse | 🔬 Run the client to connect to the SSE server. |\n| make stop-sse | 🛑 Stop the background SSE agent server. |\n| make logs-sse | 📜 View the logs for the SSE server. |\n| **General** | |\n| make clean | 🧹 Stop servers and remove virtual env and build artifacts. |\nHappy", "source": "github:agent-matrix/mcp-template/README.md"}
{"text": "How to Register an MCP Server Bundle in Matrix Hub\nThis guide explains how to register a versioned, distributable server bundle with Matrix Hub. The goal is to give the Hub a self-contained package and an \"install plan,\" allowing it to deploy and run the server without needing a live endpoint in advance.\n1\\. The Concept: From Live Server to Distributable Bundle\nInstead of starting a server manually and telling the Hub where it is, our new workflow follows these steps:\n1.  **Package**: We bundle the server's code, runner.json, and dependencies into a versioned .zip file.\n2.  **Plan**: We generate a corresponding install-plan.json that tells the Hub how to download, verify, and install this bundle.\n3.  **Host**: We upload the .zip bundle to a stable URL (like GitHub Releases).\n4.  **Register", "source": "github:agent-matrix/mcp-template/docs/README.md"}
{"text": " and install this bundle.\n3.  **Host**: We upload the .zip bundle to a stable URL (like GitHub Releases).\n4.  **Register**: We send the install-plan.json to the Hub.\nThe Hub now has everything it needs to deploy and manage the server's lifecycle automatically.\n2\\. Prerequisites\n• A running Matrix Hub instance.\n• You have generated the release bundles using make build or by pushing a git tag to trigger the GitHub Actions workflow.\n• The generated .zip bundle (e.g., dist/hello-mcp-sse-0.1.0.zip) is hosted at a URL that your Matrix Hub instance can access.\n3\\. The Install Plan\nThe make build command or the CI workflow automatically creates an install plan for each server type. This file is the \"blueprint\" you will send to the Hub.\nFor example, dist/hello-mcp-sse-0.1.0.plan.json will look like", "source": "github:agent-matrix/mcp-template/docs/README.md"}
{"text": "e. This file is the \"blueprint\" you will send to the Hub.\nFor example, dist/hello-mcp-sse-0.1.0.plan.json will look like this:\n4\\. Register the Bundle in Matrix Hub\nYou can now register this plan with the Hub using its /catalog/install API endpoint.\n**Step 4.1: Set Up Your Environment**\nExport the Hub base URL and your admin token.\n**Step 4.2: Register via curl**\nThis command reads your generated install-plan.json, wraps it in the required API payload, and sends it to the Hub.\nRun this from your project's root directory:\nThe target field is typically the same as the id and acts as the default alias for the installed server.\n5\\. Verification\nCheck if the Hub successfully registered your server bundle.\nYou should see your hello-sse-server returned in the search results. The Hub is now aware ", "source": "github:agent-matrix/mcp-template/docs/README.md"}
{"text": "egistered your server bundle.\nYou should see your hello-sse-server returned in the search results. The Hub is now aware of your server and has the plan to deploy it on demand.\n6\\. Common Gotchas\n• **Hub Cannot Access URL**: The .zip file's URL in the install plan must be reachable from the machine or container where Matrix Hub is running. localhost URLs will not work if the Hub is in Docker.\n• **SHA256 Mismatch**: If the hosted .zip file changes after you generate the plan, the Hub's installation will fail with a security error. Always use a plan generated from the exact same build as the uploaded artifact.\n• **Missing Wrapper Fields**: The /catalog/install API requires an id and target alongside the plan object. The jq command above constructs this wrapper correctly.\n• **Wrong Working Dir", "source": "github:agent-matrix/mcp-template/docs/README.md"}
{"text": "n id and target alongside the plan object. The jq command above constructs this wrapper correctly.\n• **Wrong Working Directory**: If curl or jq can't find the .plan.json file, the command will fail. Ensure you are running the commands from your project's root directory.", "source": "github:agent-matrix/mcp-template/docs/README.md"}
{"text": "Matrix Protocol Helper\n*A tiny, secure desktop utility that enables one-click installations from your browser to the Matrix CLI.*\n[](https://github.com/agent-matrix/matrix-protocol-helper/actions/workflows/ci-build.yml)\n[](https://www.apache.org/licenses/LICENSE-2.0)\n[](https://github.com/agent-matrix/matrix-protocol-helper/releases/latest)\nThe Matrix Protocol Helper is the essential bridge between your web browser and your local Matrix CLI. It registers the matrix:// custom URL scheme, allowing you to install agents and servers from the Hub with a single click—while prioritizing security through mandatory user consent.\nWhat it does (in plain words)\nThe Matrix Protocol Helper is the bridge between your web browser and your local Matrix CLI.\n• It registers the special link type **matrix://*", "source": "github:agent-matrix/matrix-protocol-helper/README.md"}
{"text": "lper is the bridge between your web browser and your local Matrix CLI.\n• It registers the special link type **matrix://** on your computer.\n• When you click an **Install** button on the Matrix Hub website, the app:\n1. asks for your **permission**,\n2. runs the safe **install command** for you, and\n3. shows clear **progress** and **results**.\n• If the Matrix CLI isn’t installed yet, it will **guide you** to install it.\nSafety at a glance\n• **You stay in control:** Every install requires your explicit confirmation in a native dialog.\n• **No risky commands:** The app prevents command-injection by sending parameters **directly** to the Matrix CLI (no shell).\n• **Minimal permissions:** It only handles matrix://install links and nothing else.\n• **Transparent:** Live logs show exactly what happene", "source": "github:agent-matrix/matrix-protocol-helper/README.md"}
{"text": "sions:** It only handles matrix://install links and nothing else.\n• **Transparent:** Live logs show exactly what happened (success or failure).\nSystem requirements\n• **Windows** 10/11 (64-bit)\n• **macOS** 12+ (Intel or Apple Silicon)\n• **Linux**: a recent 64-bit distribution\n• Debian/Ubuntu (use **.deb**)\n• Fedora/RHEL/openSUSE (use **.rpm**)\nIf your computer is very old or uses a different CPU, see **Build from Source** below.\nDownload\nGet the correct installer for your operating system from the **Latest Release** page:\n**➡ https://github.com/agent-matrix/matrix-protocol-helper/releases/latest**\nOn that page, download one of:\n• **Windows**: MatrixProtocolHelper-x64.msi\n• **macOS (Universal)**: MatrixProtocolHelper.dmg\n• **Linux (Debian/Ubuntu)**: matrix-protocol-helper_*.deb\n• **Linux (Fe", "source": "github:agent-matrix/matrix-protocol-helper/README.md"}
{"text": " **macOS (Universal)**: MatrixProtocolHelper.dmg\n• **Linux (Debian/Ubuntu)**: matrix-protocol-helper_*.deb\n• **Linux (Fedora/RHEL/openSUSE)**: matrix-protocol-helper-*.rpm\nInstall instructions (step by step)\nWindows (MSI)\n1. **Download** the .msi file.\n2. **Double-click** it and follow the prompts: **Next → Install → Finish**.\n3. If Windows asks for permission, choose **Yes**.\n4. Done — the app runs quietly in the background and registers matrix:// links.\n**Uninstall:**\n**Settings → Apps → Installed apps**, search **Matrix Protocol Helper**, click **Uninstall**.\n**Verify the download (recommended):**\nCompare the value with the SHA-256 checksum on the release page.\nmacOS (DMG)\n1. **Download** the .dmg file and **open** it.\n2. **Drag & drop** **Matrix Protocol Helper** into **Applications**.", "source": "github:agent-matrix/matrix-protocol-helper/README.md"}
{"text": "DMG)\n1. **Download** the .dmg file and **open** it.\n2. **Drag & drop** **Matrix Protocol Helper** into **Applications**.\n3. Open **Applications**, **right-click** the app → **Open** (first run to approve).\n4. Confirm any macOS prompts. The app registers matrix:// links.\n**Uninstall:**\nDrag **Matrix Protocol Helper** from **Applications** to **Trash**.\n**If macOS warns that the app is from an unidentified developer:**\nRight-click → **Open** → **Open** to confirm you trust it.\n**Verify the download (recommended):**\nCompare with the SHA-256 shown on the release page.\nLinux — Debian & Ubuntu (.deb)\n**Option A (GUI):** Double-click the .deb and install with your Software Center.\n**Option B (Terminal):**\n**Uninstall:**\n**Verify the download (recommended):**\nCompare with the SHA-256 on the releas", "source": "github:agent-matrix/matrix-protocol-helper/README.md"}
{"text": "r.\n**Option B (Terminal):**\n**Uninstall:**\n**Verify the download (recommended):**\nCompare with the SHA-256 on the release page.\nLinux — Fedora, RHEL, openSUSE (.rpm)\n**Option A (GUI):** Double-click the .rpm and install with your Software app.\n**Option B (Terminal):**\n**Uninstall:**\n**Verify the download (recommended):**\nCompare with the SHA-256 on the release page.\nFirst-time test (about 2 minutes)\n1. **Open the app** (Windows: Start menu; macOS: Applications; Linux: app launcher).\nThe app runs in the background.\n2. On the Matrix Hub website, click an **Install** button (a matrix://install?... link).\nYour browser may ask to open **Matrix Protocol Helper** → choose **Allow**.\n3. A **confirmation** window appears, showing exactly what will be installed.\nClick **Yes** to continue.\n4. Watch t", "source": "github:agent-matrix/matrix-protocol-helper/README.md"}
{"text": "w**.\n3. A **confirmation** window appears, showing exactly what will be installed.\nClick **Yes** to continue.\n4. Watch the **live log** until it says **Success** or shows an error.\nIf nothing happens when you click an install link, see **Troubleshooting**.\nEveryday use\n• You don’t need to open the app manually.\nJust click **Install from Hub** links — the app appears when needed.\n• You will **always** see a clear confirmation before anything runs.\n• The app only activates for matrix://install links.\nUsing the Matrix CLI (optional)\nIf you prefer the command line or are troubleshooting, you can install with the Matrix CLI directly.\n**Install the CLI (recommended via pipx):**\nIf pipx isn’t found, install Python (from python.org), then:\n**Example install command:**\nTroubleshooting\n**Clicking an", "source": "github:agent-matrix/matrix-protocol-helper/README.md"}
{"text": "\nIf pipx isn’t found, install Python (from python.org), then:\n**Example install command:**\nTroubleshooting\n**Clicking an install link doesn’t open the app**\n• Ensure the Helper is installed and running (reopen it from Start/Applications).\n• Your browser may prompt each time — choose **Allow** and optionally **Remember**.\n• Try another browser, or temporarily disable extensions that block custom links.\n**“Matrix CLI not found”**\n• The Helper will offer guidance to install it.\nManual install:\n**Corporate/school computer**\n• You might need **administrator** approval to install apps or register custom links.\n• If your network uses a proxy, the Helper uses your system’s proxy settings.\n**Still stuck?**\n• Open an issue on the project’s GitHub and include the **log output** (no personal data).\nSe", "source": "github:agent-matrix/matrix-protocol-helper/README.md"}
{"text": "settings.\n**Still stuck?**\n• Open an issue on the project’s GitHub and include the **log output** (no personal data).\nSecurity model\n• **No Shell Execution:** Arguments are passed directly to the matrix binary, eliminating shell-injection risk.\n• **Strict Validation:** URL parameters are validated for allowed characters and length; only matrix://install is processed.\n• **Least Privilege:** The Helper’s capabilities are limited to the *install* action.\n• **Mandatory User Consent:** No action is taken without explicit approval in a native OS dialog.\n• **Integrity checks:** We publish **SHA-256** checksums for every release (verify with the commands above).\n• **Code signing:** Where supported by the OS, installers are signed; see release notes for details.\nPrivacy\n• The app **does not collect", "source": "github:agent-matrix/matrix-protocol-helper/README.md"}
{"text": "** Where supported by the OS, installers are signed; see release notes for details.\nPrivacy\n• The app **does not collect personal data**.\n• Logs are stored **locally** and only show installation details.\n• No background network services are installed; the app respects system proxy settings.\nAccessibility & international use\n• Works with platform accessibility features (keyboard navigation, high-contrast, screen readers).\n• Simple, plain language suitable for non-technical users.\n• This README is Markdown and can be translated easily (aim for **WCAG 2.1 AA** documentation guidance).\nBuild from source (advanced / other Linux)\nIf your distribution isn’t covered by .deb/.rpm, or you prefer building locally:\nPrerequisites\n• Node.js **v18+** with npm\n• Rust (stable toolchain)\n• Tauri CLI prerequ", "source": "github:agent-matrix/matrix-protocol-helper/README.md"}
{"text": " or you prefer building locally:\nPrerequisites\n• Node.js **v18+** with npm\n• Rust (stable toolchain)\n• Tauri CLI prerequisites for your OS\nBuild steps\nArtifacts are created under:\nsrc-tauri/target/release/bundle/\nFor a list of available make targets, run:\nContributing\nBug reports, feature requests, and pull requests are welcome.\nPlease open an issue to discuss significant changes.\nLicense\n**Apache License 2.0** — see the LICENSE for details.\nQuick checklist\n• [ ] Downloaded the installer for my OS\n• [ ] Installed it (Next → Install → Finish / drag to Applications / install package)\n• [ ] Clicked an **Install from Hub** link and chose **Allow**\n• [ ] Read the confirmation and clicked **Yes**\n• [ ] Saw **Success** in the log window\nYou’re all set — enjoy one-click installs with confidence!", "source": "github:agent-matrix/matrix-protocol-helper/README.md"}
{"text": "MatrixHub PostgreSQL — Production Stack (OCI / Oracle Linux 9)\nA production-grade PostgreSQL 16 setup purpose-built for **MatrixHub**:\n• **One command** bootstrap: make init\n• Idempotent **schema init** (entity, embedding_chunk, remote) on first boot\n• Durable data via Docker volume, **systemd** auto-start on boot\n• Optional **PgBouncer** connection pooling, **Prometheus** exporter\n• Backup/restore automation (CLI + systemd nightly timer)\n• Secure defaults with configurable pg_hba CIDR allow list\n**Compatibility:** Mirrors the MatrixHub models/migrations you provided (columns, JSONB defaults, check constraints, indexes). No breaking changes.\n🚀 Quick Start (Oracle Linux 9 on OCI)\nConnect from apps:\nWhat make init does\n1. Installs Docker CE\n2. Opens firewall 5432/tcp (configurable via PG_HOS", "source": "github:agent-matrix/matrixhub-db/README.md"}
{"text": "on OCI)\nConnect from apps:\nWhat make init does\n1. Installs Docker CE\n2. Opens firewall 5432/tcp (configurable via PG_HOST_PORT)\n3. Builds the custom Postgres image (schema/extension init)\n4. Runs the DB container with durable volume & healthcheck\n5. Installs and enables a systemd unit for auto-start\n6. Waits until the DB is healthy\nOptional Components\nPgBouncer (recommended at scale)\nStart a pooler on the same Docker network (port 6432 by default):\nApps connect to pgbouncer:6432 (inside the Docker network) or host:<PGBOUNCER_PORT> if you publish it.\nPrometheus Exporter\nCreate a read-only monitoring role and run the exporter:\nIt listens on host port 9187 by default.\nBackups\n• **On-demand:** make backup-now\n• **Nightly (02:30) with systemd timer:** make backup-install\nBackups are stored in t", "source": "github:agent-matrix/matrixhub-db/README.md"}
{"text": "s\n• **On-demand:** make backup-now\n• **Nightly (02:30) with systemd timer:** make backup-install\nBackups are stored in the ./backups/ directory.\nSecurity Notes\n• **Passwords**: Never commit .env.db.\n• **pg_hba**: Restrict PG_ALLOW_CIDR in .env.db to your VCN subnets/VPN.\n• **TLS**: For client TLS, set TLS_ENABLE=1 in .env.db, create a certs directory with server.crt/server.key, and re-run make up.\n• **Users**: Prefer separate DB users per service (rw vs ro) with least privilege.\nUninstall", "source": "github:agent-matrix/matrixhub-db/README.md"}
{"text": "Database (Postgres)\nYou can run Postgres in a separate container on the shared Docker network.\nEnvironment\nWe use .env.db at repo root. If it’s missing, a .env.db.template will be created and symlinked for you.\n**.env.db (defaults):**\nMakefile targets (DB repo)\nFrom the DB directory (the Makefile auto-creates .env.db.template if needed):\n**Connection string**", "source": "github:agent-matrix/matrixhub-db/docs/database.md"}
{"text": "Run the Hub with TLS (no nginx)\nMatrixHub terminates TLS directly in **Gunicorn** using a **Cloudflare Origin Certificate**.\n1) Prepare certs on the host\nCreate/Download a Cloudflare **Origin Certificate** for your domain (Full/Strict). Then:\nThese are trusted by Cloudflare, not browsers—perfect for Full (strict).\n2) Start Hub + Gateway\nFrom the project root:\nThis mounts:\n• Hub env: .env (or .env.example) → /app/.env\n• Gateway env: .env.gateway.local (or .env.gateway.example) → /app/.env.gateway.*\n• TLS certs: /etc/ssl/matrixhub (read-only)\nGunicorn starts on :443 with:\n3) Ports & URLs\n• **Hub (TLS):** https://localhost:443/\n• **Gateway Admin:** http://localhost:4444/admin/\n4) Cloudflare sanity\n• DNS A/AAAA → your server → **Proxied (orange)**\n• SSL/TLS → **Full (strict)**\n• Edge Certifica", "source": "github:agent-matrix/matrixhub-db/docs/hub.md"}
{"text": "MatrixHub\nMatrixHub bundles:\n• **Hub API** (FastAPI + Gunicorn/Uvicorn)\n• **MCP Gateway** (admin UI on port 4444)\n• Optional **Postgres** and **pgAdmin** containers\nThis documentation is minimal and **developer-focused**. It’s compatible with MkDocs.", "source": "github:agent-matrix/matrixhub-db/docs/index.md"}
{"text": "Installation\nPrerequisites\n• Linux VM (Ubuntu/Oracle Linux OK)\n• Docker CE\n• Git\nInstall Docker (Oracle Linux 9, idempotent)\n(Optional) Open Postgres port on the host firewall\nClone & Build\nFrom the project root:\nFirst Run (Hub + Gateway)\nTLS is supported directly by Gunicorn (no nginx). If you’re fronting with Cloudflare:\n1. Create a **Cloudflare Origin Certificate** for your domain\nIn Cloudflare → SSL/TLS → Origin Server → Create certificate.\nYou’ll download:\n• cf-origin.pem\n• cf-origin.key\n2. Put certs on the host where Docker runs:\n3. Start the container:\n**Ports**\n• Hub API (TLS): https://localhost:443/\n• MCP Gateway Admin: http://localhost:4444/admin/", "source": "github:agent-matrix/matrixhub-db/docs/installation.md"}
{"text": "pgAdmin UI (optional)\nUse pgAdmin to inspect your Postgres on the same Docker network.\nStart pgAdmin\nThe helper script reuses your Postgres password from .env.db (or the template):\n**Open:** http://localhost:5050\n**Login:** admin@local / *same as your POSTGRES\\_PASSWORD*\nA Docker volume matrixhub-pgadmin is created for persistence.\nAdd your database in pgAdmin\n• **General → Name:** MatrixHub DB\n• **Connection → Host name/address:** matrixhub-db (or db)\n• **Port:** 5432\n• **Maintenance DB:** value of POSTGRES_DB\n• **Username:** value of POSTGRES_USER\n• **Password:** value of POSTGRES_PASSWORD\n• **SSL:** Off (unless you enabled TLS in Postgres and require it)\nIf you can’t connect, confirm both containers share the matrixhub-net network:", "source": "github:agent-matrix/matrixhub-db/docs/pgadmin.md"}
{"text": "Troubleshooting\nHub worker exits with code 52\nIf Hub logs show:\nCheck your environment files are present and valid:\n• Hub: .env (or .env.example)\n• Gateway: .env.gateway.local (or .env.gateway.example)\nThe launcher will create .env.gateway.local from the example if missing—update credentials there.\nHTTPS shows 525/526 via Cloudflare\n• Use **Cloudflare Origin Certificates** at the origin (this project).\n• Cloudflare SSL/TLS → **Full (strict)**.\n• Verify the mounted files exist and are readable in the container:\n• /etc/ssl/matrixhub/cf-origin.pem\n• /etc/ssl/matrixhub/cf-origin.key\nCan’t bind to port 443\nPorts <1024 may require extra capability. The run script configures the container appropriately. If you changed security settings, ensure the container can bind :443.\npgAdmin can’t connect\n• ", "source": "github:agent-matrix/matrixhub-db/docs/troubleshooting.md"}
{"text": " container appropriately. If you changed security settings, ensure the container can bind :443.\npgAdmin can’t connect\n• Ensure both DB and pgAdmin containers are on matrixhub-net.\n• Use host matrixhub-db (or db), port 5432.\n• Verify DB is healthy:\n• Confirm credentials match .env.db.\nPostgres not starting / healthcheck failing\n• Check container logs:\n• Ensure .env.db exists (or the .env.db.template symlink fallback).\n• If you changed tuning params (e.g., shared_buffers), roll them back and retry.\nWhere are the env files?\n• **DB:** .env.db (template auto-created as .env.db.template and symlinked)\n• **Hub:** .env (or .env.example)\n• **Gateway:** .env.gateway.local (or .env.gateway.example)\nRecreate containers cleanly\nStop & remove, then start again:", "source": "github:agent-matrix/matrixhub-db/docs/troubleshooting.md"}
{"text": "matrix-ai\n**matrix-ai** is the AI planning microservice for the Matrix EcoSystem. It generates **short, low‑risk, auditable remediation plans** from a compact health context provided by **Matrix Guardian**. The service is designed for **Hugging Face Spaces** or **Inference Endpoints**, but also runs locally.\n**Endpoints**\n* POST /v1/plan – internal API for Matrix Guardian: returns a safe JSON plan.\n* POST /v1/chat – (optional) RAG-style Q&A about MatrixHub (kept lightweight in Stage‑1).\nThe service emphasizes **safety, performance, and auditability**:\n• Strict, schema‑validated JSON plans (bounded steps, risk label, rationale)\n• PII redaction before calling upstream model endpoints\n• Exponential backoff, short timeouts, and structured JSON logs\n• In‑memory rate limiting (per‑IP), optional ", "source": "README.md"}
{"text": " endpoints\n• Exponential backoff, short timeouts, and structured JSON logs\n• In‑memory rate limiting (per‑IP), optional auth for private deployments\n• ETag support and response caching for non‑mutating reads\n*Last Updated: 2025‑09‑27 (UTC)*\nArchitecture (at a glance)\nSequence: POST /v1/plan\nQuick Start (Local Development)\nOpenAPI docs: http://localhost:7860/docs\nDeploy to Hugging Face Spaces\n1) Push the repository to a new Space.\n2) In **Settings → Secrets**, add:\n• HF_TOKEN (required) – used by the upstream HF Inference client\n• ADMIN_TOKEN (optional) – if set, private‑gates /v1/plan and /v1/chat\n3) Choose hardware. CPU is fine for tests; GPU recommended for larger models.\n4) The Space will serve FastAPI on the default port; the two endpoints are ready.\nFor Inference Endpoints, mirror the", "source": "README.md"}
{"text": "s.\n4) The Space will serve FastAPI on the default port; the two endpoints are ready.\nFor Inference Endpoints, mirror the same env and start command.\nConfiguration\nAll options can be set via environment variables (Space Secrets in HF) or .env for local use.\n| Variable | Default | Purpose |\n| HF_TOKEN | — | Token for Hugging Face Inference API (required) |\n| MODEL_NAME | meta-llama/Meta-Llama-3.1-8B-Instruct | Upstream model ID (example) |\n| MAX_NEW_TOKENS | 256 | Output token cap for plan generations |\n| TEMPERATURE | 0.2 | Generation temperature |\n| RATE_LIMIT_PER_MIN | 120 | Per‑IP fixed‑window limit |\n| REQUEST_TIMEOUT_SEC | 15 | HTTP client timeout to HF |\n| RETRY_MAX_ATTEMPTS | 3 | Retry budget to HF |\n| CACHE_TTL_SEC | 30 | Optional in‑memory caching for GET |\n| ADMIN_TOKEN | — | If s", "source": "README.md"}
{"text": "ATTEMPTS | 3 | Retry budget to HF |\n| CACHE_TTL_SEC | 30 | Optional in‑memory caching for GET |\n| ADMIN_TOKEN | — | If set, requires Authorization: Bearer <ADMIN_TOKEN> |\n| LOG_LEVEL | INFO | Log level (JSON logs) |\nNames are illustrative; keep them in sync with your configs/settings.yaml if present.\nAPI\nPOST /v1/plan\n**Description:** Generate a short, low‑risk remediation plan from a compact app health context.\n**Headers**\n**Request body (example)**\n**Response (example)**\n**Status codes**\n• 200 – plan generated\n• 400 – invalid payload (schema)\n• 401/403 – missing/invalid bearer (only if ADMIN_TOKEN configured)\n• 429 – rate limited\n• 502 – upstream model error after retries\nPOST /v1/chat\n*Optional, Stage‑1 placeholder.* Given a query about MatrixHub, returns an answer with citations if a l", "source": "README.md"}
{"text": "es\nPOST /v1/chat\n*Optional, Stage‑1 placeholder.* Given a query about MatrixHub, returns an answer with citations if a local KB is configured.\nSafety & Reliability\n• **PII redaction** – tokens/emails removed from prompts as a pre‑filter\n• **Strict schema** – JSON plan parsing with fallbacks; rejects unsafe shapes\n• **Time‑boxed** – short timeouts and bounded retries to HF Inference\n• **Rate‑limited** – per‑IP fixed window (configurable)\n• **Structured logs** – JSON logs only; no sensitive payloads are logged\nObservability\n• Request IDs (correlated across Guardian ↔ AI)\n• Latency + retry counters\n• Plan success/failure metrics (prom‑friendly if you expose metrics)\nDevelopment Notes\n• Keep /v1/plan **internal** behind a network boundary or ADMIN_TOKEN.\n• Validate payloads rigorously (Pydanti", "source": "README.md"}
{"text": "ent Notes\n• Keep /v1/plan **internal** behind a network boundary or ADMIN_TOKEN.\n• Validate payloads rigorously (Pydantic) and write contract tests for the plan schema.\n• If you switch models, re‑run golden tests to guard against plan drift.\nLicense\nApache‑2.0", "source": "README.md"}