AI导哈

AI代理连接套件

MatrixLink Suite是一个生产级工具包，用于在多云环境中发现、选择和运行MCP服务器（协调器）和A2A代理，提供客户端库、BFF和UI管理功能。

  • by agent-matrix
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 agent-matrix/matrixlink

使用说明

⚡️ 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/<flow>)带有租赁标头和承载身份验证
  • 通过环境变量自动解析服务端点（每个提供者无需进行代码编辑）

一起: 在全球范围内发现，在本地运行。您从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/<flow>" --> 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代码引擎上部署（示例）

  1. 创建秘密 （先填写令牌）： ./infra/secrets/create-secrets.sh
  2. 构建和推送图像: make docker-build-bff docker-build-ui make docker-push-bff docker-push-ui
  3. 创建应用程序: make ce-create-bff make ce-create-ui
  4. API网关路由:
    • /api/health|/api/ready|/api/admin/*|/api/mcp/* ->BFF
    • /api/chat （或 /api/flows/<flow>)->编排器（单独的仓库/应用程序）

其他提供者（环境预设）

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

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://<apprunner-mcp-host>
ORCH_BASE_URL=https://<apprunner-orch-host>
AGENTS_BASE_URL=https://<apprunner-agents-host>

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 <token> 从UI。

许可证

Apache 2.0——请参阅 LICENSE.

相关 MCP