⚡️ MatrixLink套件

*生产工具包 MatrixHub --在任何云上发现、选择和运行MCP服务器（编排器）和A2A代理。*

需要 Python 3.11+.图书馆出版为 matrixlink 在PyPI上。BFF/UI在上运行 :8080.

______________________________________________________________________

MatrixLink Suite为您提供了一个生产就绪的运行基础 MCP网关+编排器（MCP服务器）+A2A代理 在任何现代平台上（IBM代码引擎、Google Cloud Run、AWS App Runner、Azure容器应用程序、Knative/K8s、本地）。它包括：

libs/matrixlink/ --用于MCP发现、A2A消息传递和编排器调用的PyPI就绪客户端
apps/bff/ --前门（FastAPI）露出干净的 /api/* 带有管理员和MCP代理的表面
ui/matrixhub-admin/ --MCP服务器和代理的最小React管理员（只读）
infra/ce/ --用于应用程序和机密的IBM代码引擎脚本
Makefile --开发和运营目标(make help)

所有服务都绑定到端口 8080.东西方呼唤使用 承载服务令牌 （可选mTLS）。

默认提供程序= local。本地运行BFF+UI不需要外部服务。

______________________________________________________________________

什么是MatrixHub和MatrixLink？

MatrixHub 是一个 *互联网规模中心* 搜索引擎（想想 用于AI代理和MCP服务器的PyPI).您可以通过以下方式使用它来发现高质量的代理/编排者能力（技能、流程），信任（出版商、SBOM/认证），以及健身（成功率、延迟、区域）。使用权限将所选条目导入组织的私有目录 可见性 和政策.

MatrixLink 是运行时连接器：一个小型客户端库加上一个可选的BFF 发现和调用便携 穿过云层。它允许您的代码：

通过以下方式发现代理商技能通过你的 MCP网关
使用简单的呼叫代理 A2A 合同(/message/send，可选SSE）
调用编排器(/invoke/)带有租赁标头和承载身份验证
通过环境变量自动解析服务端点（每个提供者无需进行代码编辑）

一起: *在全球范围内发现，在本地运行*。您从MatrixHub中选择构建块；MatrixLink将它们安全且可重复地连接到您的环境中。

______________________________________________________________________

建筑

flowchart TD
  subgraph EXT["External"]
    UI["Clients / Apps / Chat UI"]
  end

  subgraph EDGE["API Gateway / Front Door (public)"]
    APIGW["https://your-host/api/*"]
  end

  subgraph CTRL["Control Plane"]
    MCP["MCP Gateway (registry, discovery, health)"]
  end

  subgraph RUNTIME["Serverless / Containers (:8080)"]
    BFF["BFF (Front Door + MCP proxy)"]
    ORCH["Orchestrator(s) (MCP Servers)"]
    A1["A2A Agents (skills)"]
    A2["A2A Agents (skills)"]
    AX["… more Agents"]
  end

  UI --> APIGW
  APIGW -- "/api/health|/api/ready|/api/mcp/*|/api/admin/*" --> BFF
  APIGW -- "/api/chat or /api/flows/" --> ORCH

  BFF --> MCP
  ORCH -.->|discover by skill| MCP
  ORCH --> A1
  ORCH --> A2
  ORCH --> AX

公共API（边缘）：

路径	目标	注释
`GET /api/health`	BFF	活性
`GET /api/ready`	BFF	准备就绪（+MCP健康状况）
`POST /api/chat` / `/api/flows/*`	编排器	主聊天/流入口点
`/api/mcp/*`	BFF→ MCP	代理、安全
`/api/admin/*`	BFF	代理CRUD/运行，安全

______________________________________________________________________

存储库布局

matrixlink-suite/
├─ libs/
│  └─ matrixlink/               # PyPI client
│     ├─ pyproject.toml
│     └─ src/matrixlink/
│        ├─ __init__.py
│        ├─ config.py
│        ├─ providers.py
│        ├─ discovery.py
│        ├─ a2a.py
│        ├─ orchestrator.py
│        ├─ sse.py
│        └─ errors.py
├─ apps/
│  └─ bff/
│     ├─ Dockerfile
│     ├─ requirements.txt
│     └─ app/
│        ├─ main.py
│        ├─ auth.py
│        ├─ db.py
│        ├─ models.py
│        ├─ observability.py
│        └─ clients/
│           ├─ mcp.py
│           └─ agents.py
├─ ui/
│  └─ matrixhub-admin/
│     ├─ Dockerfile
│     ├─ package.json
│     └─ src/...
├─ infra/
│  ├─ ce/                       # IBM Code Engine scripts
│  └─ secrets/
├─ docs/                        # MkDocs site (see below)
├─ mkdocs.yml                   # MkDocs config
├─ .env.example
├─ Makefile
├─ LICENSE
└─ README.md

______________________________________________________________________

需求

Python 3.10+
节点18+（UI）
Docker（用于容器构建）
可选：用于代码引擎部署的IBM Cloud CLI

______________________________________________________________________

快速入门（本地）

1）运行BFF（前门）

make install
# optional: point BFF to a local MCP Gateway (if you run one)
export MCP_BASE_URL="http://localhost:4444"
make run-bff
# → http://localhost:8080/api/health

2）运行管理UI

make dev-ui
# → http://localhost:3000

对于本地测试，设置 export ADMIN_BEARER=changeme-admin-bearer-token 并在UI设置中使用相同的设置。

______________________________________________________________________

我什么时候需要MCP网关？

MatrixLink的BFF和UI运行良好没有 MCP用于基本健康/管理。你会想要一个 MCP网关 当你需要：

运行时发现 按技能/标签分类的代理/编排者
中央登记处 + RBAC 和 可见性 每个团队/租户
健康与健身 信号（仅通往健康入口）
受控推出 （蓝色/绿色，金丝雀通过标签）

本地开发人员： 您可以在上运行轻量级MCP网关 http://localhost:4444.在云中，点 MCP_BASE_URL 到您的托管MCP实例（或通过解决 DOMAIN_SUFFIX+MCP_SERVICE_NAME).

______________________________________________________________________

环境变量

最好的朋友

ADMIN_BEARER --守卫令牌 /api/admin/* 和 /api/mcp/*
MCP_BASE_URL --MCP网关URL（默认为 http://localhost:4444 为了 CLOUD_PROVIDER=local)
MCP_BEARER_TOKEN --调用MCP网关的服务令牌
AGENTS_BASE_URL --代理的可选静态基座（扇入式主机）
AGENTS_API_TOKEN --代理调用的东西方承载者

MatrixLink库

CLOUD_PROVIDER — local （默认）， ce, gcrun, apprunner, aca, knative
DOMAIN_SUFFIX --例如。 proj.region.codeengine.appdomain.cloud
MCP_SERVICE_NAME --默认值 mcp-gateway
ORCH_SERVICE_NAME --默认值 orchestrator
AGENTS_DOMAIN_PREFIX --默认值 agents
MCP_BASE_URL, ORCH_BASE_URL, AGENTS_BASE_URL --显式覆盖
MCP_BEARER_TOKEN, A2A_SERVICE_TOKEN, TENANT_HEADER, REQUEST_TIMEOUT

______________________________________________________________________

使用MatrixLink（Python）

从repo本地安装：

cd libs/matrixlink
pip install -e .

或者从PyPI（发布后）：

pip install matrixlink

通过技能发现代理（通过MCP网关）

from matrixlink import MCPClient

mcp = MCPClient()  # reads MCP_BASE_URL or DOMAIN_SUFFIX + service name
agents = mcp.discover_agents(skill="report.generate")
print(agents[0]["endpoint"])  # https://agents.../agent-synth

向A2A代理发送数据

from matrixlink import A2AClient

a2a = A2AClient()  # uses A2A_SERVICE_TOKEN if set
endpoint = "https://agents.example.com/agent-synth"  # or from discovery
resp = a2a.send_message(endpoint, {"title": "Weekly Status", "bullets": ["A", "B", "C"]})
print(resp)

调用编排器（MCP服务器）流

from matrixlink import OrchestratorClient

orch = OrchestratorClient("https://orchestrator.example.com")
result = orch.invoke("hr.orchestrate", {"candidates":[{"id":"c1","skills":["py","sql"]}]})
print(result)

______________________________________________________________________

API管理员（BFF）

方法	路径	安全吗？	目的
`GET`	`/api/health`	❌	生活
`GET`	`/api/ready`	❌	准备就绪（+MCP健康状况）
`GET`	`/api/mcp/servers`	✅	MCP服务器列表（代理）
`GET`	`/api/mcp/tools`	✅	MCP工具列表（代理）
`POST`	`/api/mcp/servers`	✅	创建MCP服务器（代理）
`GET`	`/api/admin/agents`	✅	列出代理
`POST`	`/api/admin/agents`	✅	创建代理
`POST`	`/api/admin/agents/{id}/bind`	✅	粘合剂→ 目录URL
`POST`	`/api/admin/agents/{id}/run`	✅	按名称调用代理

安全=需要 Authorization: Bearer ${ADMIN_BEARER}.

______________________________________________________________________

码头工人

最好的朋友

docker build -f apps/bff/Dockerfile -t local/bff:dev .
docker run --rm -p 8080:8080 \
  -e CLOUD_PROVIDER=local \
  -e ADMIN_BEARER=changeme-admin-bearer-token \
  -e MCP_BASE_URL=http://host.docker.internal:4444 \
  local/bff:dev

管理用户界面

docker build -f ui/matrixhub-admin/Dockerfile -t local/matrixhub-admin:dev ui/matrixhub-admin
docker run --rm -p 8081:8080 local/matrixhub-admin:dev
# open http://localhost:8081

______________________________________________________________________

在IBM代码引擎上部署（示例）

创建秘密 （先填写令牌）：

./infra/secrets/create-secrets.sh

构建和推送图像:

make docker-build-bff docker-build-ui make docker-push-bff docker-push-ui

创建应用程序:

make ce-create-bff make ce-create-ui

API网关路由:

- /api/health|/api/ready|/api/admin/*|/api/mcp/* ->BFF - /api/chat （或 /api/flows/)->编排器（单独的仓库/应用程序）

______________________________________________________________________

其他提供者（环境预设）

谷歌云运行 （建议使用自定义域）

CLOUD_PROVIDER=gcrun
MCP_BASE_URL=https://mcp-gateway.example.com
ORCH_BASE_URL=https://orchestrator.example.com
AGENTS_BASE_URL=https://orchestrator.example.com
MCP_BEARER_TOKEN=...
A2A_SERVICE_TOKEN=...

AWS应用程序运行程序

CLOUD_PROVIDER=apprunner
MCP_BASE_URL=https://
ORCH_BASE_URL=https://
AGENTS_BASE_URL=https://

Azure容器应用

CLOUD_PROVIDER=aca
DOMAIN_SUFFIX=myenv.azurecontainerapps.io
MCP_SERVICE_NAME=mcp-gateway
ORCH_SERVICE_NAME=orchestrator
AGENTS_DOMAIN_PREFIX=agents

Knative/K8s

CLOUD_PROVIDER=knative
DOMAIN_SUFFIX=apps.example.internal
MCP_SERVICE_NAME=mcp-gateway
ORCH_SERVICE_NAME=orchestrator
AGENTS_DOMAIN_PREFIX=agents

本地/Docker作曲+Traefik

CLOUD_PROVIDER=local
MCP_BASE_URL=http://localhost:4444

______________________________________________________________________

安全与运营

秘密：将令牌存储在提供商秘密存储中；从未出现在图像中
认证：边缘的OIDC/JWT /api/chat; ADMIN_BEARER 用于管理代理；服务熊为东-西
可观测性：结构化日志 X-Request-ID / X-Tenant-Id；如果需要，添加OTEL出口商
上海证券交易所：确保API网关不缓冲 /stream 回应
扩展：BFF和MCP网关 minScale=1；编排器/代理可以扩展到0
数据库：BFF使用SQLite进行开发；通过prod-via切换到托管数据库 DATABASE_URL

______________________________________________________________________

制定目标

make help              # list targets
make install           # venv + deps + install local matrixlink into BFF venv
make run-bff           # run BFF at :8080 (local)
make dev-ui            # run Admin UI at :3000 (Vite dev)
make build-ui          # build Admin UI static
make build-lib         # build matrixlink (wheel/sdist)
make docker-build-bff  # build BFF container
make docker-build-ui   # build UI container
make docker-push-bff   # push BFF image
make docker-push-ui    # push UI image
make ce-create-secrets # create CE secrets
make ce-create-bff     # create BFF app on CE
make ce-create-ui      # create UI app on CE

______________________________________________________________________

故障排除

ModuleNotFoundError: matrixlink 在本地运行BFF时→ run make install.
未设置MCP基本URL → set MCP_BASE_URL 或使用 CLOUD_PROVIDER + DOMAIN_SUFFIX + MCP_SERVICE_NAME.
跨域资源共享 → set CORS_ALLOW_ORIGINS 在BFF中（例如。， http://localhost:3000).
401在管理路线上 → set ADMIN_BEARER 并通过 Authorization: Bearer 从UI。

______________________________________________________________________

许可证

Apache 2.0——请参阅 LICENSE.

matrixlink (Agent Matrix)

快速接入

详细介绍

⚡️ MatrixLink套件

什么是MatrixHub和MatrixLink？

建筑

存储库布局

需求

快速入门（本地）

我什么时候需要MCP网关？

环境变量

使用MatrixLink（Python）

API管理员（BFF）

码头工人

在IBM代码引擎上部署（示例）

其他提供者（环境预设）

安全与运营

制定目标

故障排除

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP