Matrix Hub

矩阵中心

](https://hub.docker.com/r/ruslanmv/matrix-hub)    

欢迎来到Matrix Hub，您的一体化AI代理市场和安装程序！

矩阵中心 是您的AI代理、自定义工具和MCP服务器的生产就绪目录和安装程序。 它从远程目录（例如GitHub）中获取结构良好的清单，提供闪电般的速度 搜索 （词汇+语义混合），安全计算和执行 安装计划 （pip/uv、Docker、Git、ZIP），并且可以自动 注册 使用您的MCP网关。

• API：端口上的FastAPI 8000 （制作：443反向代理背后）
• 数据库：PostgreSQL（SQLite支持轻量级/开发使用）
• 摄取：拉动 index.json 从一个或多个遥控器，验证和丰富清单，可选块+嵌入
• 安装：临时步骤、项目适配器、锁文件生成
• 认证：管理员端点的可选承载令牌
• 日志：带相关ID的结构化JSON
• 码头工人: docker pull ruslanmv/matrix-hub:latest

什么是Matrix Hub?

想象一下PyPI用于智能代理和自定义工具——Matrix Hub从GitHub（或任何远程目录）接收精心策划的清单，让您使用混合文本在几秒钟内找到完美的代理 + 语义搜索，然后使用单个命令将所有内容安全地安装到您的项目中（pip、Docker、Git或ZIP）。它甚至可以自动向您的MCP注册新服务 Gateway编写脚手架适配器，并生成锁文件，使您的构建坚如磐石。

flowchart TD
    A[Agent Authors
manifests] --> B[GitHub Catalog]
    B --> C[Matrix Hub
catalog & install]
    C --> D[CLI & SDK
agent‑creator]
    C --> E[Agent Generator
planning_agent]
    D & E --> F[Install Agents/Tools]
    F --> G[MCP Gateway
runtime registry]
    G --> H[Your App
invokes agents]

准备好发现、安装和管理企业级人工智能技能了吗？ 探索 全部文件 开始吧！

______________________________________________________________________

官方搜索API

Matrix Hub公开了一个稳定的公共端点，该端点返回 前5名 跨代理、工具和MCP服务器的查询的最佳匹配。本合同为附加合同，生产安全。

端点

GET /catalog/search

通用参数

• q *（字符串，必填）* –用户意图，例如。 summarize pdfs
• type *（枚举：代理|工具| mcpserver|任意，默认任意）* –按类型过滤； any 搜索全部。
• limit *（int，默认值5）* –返回的最大项目数。公共API上限为 5.
• with_snippets *（bool，默认为false）* –如果可用，请包含一个简短的片段（摘要/描述的前200个字符）。

高级参数（可选）： mode (keyword|semantic|hybrid), with_rag （布尔）， rerank (none|llm)，以及CSV过滤器 capabilities, frameworks, providers.

响应

每个项目都包括排名分数和导入/安装的便利链接：

{
  "items": [
    {
      "id": "tool:hello@0.1.0",
      "type": "tool",
      "name": "hello",
      "version": "0.1.0",
      "summary": "Return greeting",
      "capabilities": ["hello"],
      "frameworks": ["example"],
      "providers": ["self"],
      "score_lexical": 0.81,
      "score_semantic": 0.74,
      "score_quality": 0.90,
      "score_recency": 0.88,
      "score_final": 0.82,
      "fit_reason": null,
      "manifest_url": "https://…/hello.manifest.json",
      "install_url": "https://api.example.com/catalog/install?id=tool:hello@0.1.0",
      "snippet": "Short summary snippet if with_snippets=true"
    }
  ],
  "total": 1
}

快速启动（卷曲）

curl -s 'https://api.example.com/catalog/search?q=extract%20pdf%20tables&type=any&limit=5&with_snippets=true' | jq

要安装所选项目，请执行以下操作：

curl -s -X POST 'https://api.example.com/catalog/install' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "tool:pdf_table_extractor@1.1.0",
    "target": "./"
  }'

见API文件全文： 排名前五的搜索API.

部署说明

• 集 PUBLIC_BASE_URL 在您的环境中（例如。， https://api.example.com).
• 可选助手路线 GET /catalog/manifest/{id} 可以在以下情况下重定向到外部清单 source_url 已设置。
• 无需进行数据库迁移。

______________________________________________________________________

快速启动（docker编写）

要求：Docker 24+，Docker编写插件。

# 1) Clone and enter the repo
git clone https://github.com/agent-matrix/matrix-hub.git
cd matrix-hub

# 2) Create .env from template and adjust if needed
cp .env.example .env
# (Optionally) set MATRIX_REMOTES to your catalog index.json URLs in .env

# 3) Build & run
docker compose up -d --build

# 4) Health check
curl -s http://localhost:443/health | jq

您应该看到：

{ "status": "ok" }

应用程序容器等待Postgres恢复健康，然后启动API。已安排摄入（请参阅.env中的INGESTINTERVAL_MIN）。

环境

所有配置都是通过环境变量进行的；看见 .env.example 用于记录模板。

按键设置（常用）：

安全： 如果你设置 API_TOKEN，通过 Authorization: Bearer 在受保护的端点上（例如手动摄取）。没有它，管理员端点将根据路由配置禁用或打开。

API演练

基本URL默认为 http://localhost:443.

GET/健康

活力/准备就绪。可选DB探测器：

curl -s 'http://localhost:443/health?check_db=true' | jq

退货：

{ "status": "ok", "db": "ok" }

GET/目录/搜索

使用可选过滤器对目录进行混合搜索。

查询参数

• q （必填）--自由文本查询
• type — agent | tool | mcp_server
• capabilities --CSV，例如。 pdf,summarize
• frameworks --CSV，例如。 langgraph,watsonx_orchestrate
• providers --CSV，例如。 openai,watsonx
• mode — keyword | semantic | hybrid （默认设置）
• limit --默认值 20
• with_rag — true 用简短的“fit_reason”丰富结果
• rerank — none | llm （默认设置）

示例

curl -s 'http://localhost:443/catalog/search?q=summarize%20pdfs&type=agent&capabilities=pdf,summarize&limit=5&with_rag=true' | jq

响应（截断）

{
  "items": [
    {
      "id": "agent:pdf-summarizer@1.4.2",
      "type": "agent",
      "name": "PDF Summarizer",
      "version": "1.4.2",
      "summary": "Summarizes long PDF documents into concise points.",
      "capabilities": ["pdf", "summarize"],
      "frameworks": ["langgraph"],
      "providers": ["watsonx"],
      "score_lexical": 0.82,
      "score_semantic": 0.76,
      "score_quality": 0.9,
      "score_recency": 0.88,
      "score_final": 0.83,
      "fit_reason": "Matches 'summarize pdfs'; strong README snippet about legal contracts."
    }
  ],
  "total": 1
}

GET/目录/实体/｛id｝

获取特定目录ID的完整实体详细信息。

示例

curl -s 'http://localhost:443/catalog/entities/agent:pdf-summarizer@1.4.2' | jq

POST/编目/安装

计算并执行安装计划（pip/uv、docker、git、zip），将适配器写入项目，并（可选）向MCP-Gateway注册工具/服务器。发射 matrix.lock.json.

身体

{
  "id": "agent:pdf-summarizer@1.4.2",
  "target": "./apps/pdf-bot"
}

示例

curl -s -X POST 'http://localhost:443/catalog/install' \
  -H 'Content-Type: application/json' \
  -d '{"id":"agent:pdf-summarizer@1.4.2","target":"./apps/pdf-bot"}' | jq

响应（截断）

{
  "plan": {
    "artifacts": [
      {"kind": "pypi", "command": "uv pip install --system --no-cache-dir pdf-summarizer-agent==1.4.2"}
    ],
    "adapters": [{"framework":"langgraph","template_key":"langgraph-node"}],
    "mcp_registration": {
      "tool": { "name": "pdf_summarize", "integration_type": "REST", "request_type": "POST", "url": "http://..." }
    }
  },
  "results": [
    {"step":"pypi","ok":true,"returncode":0,"elapsed_secs":5.91},
    {"step":"adapters.write","ok":true,"extra":{"count":1}},
    {"step":"gateway.register","ok":true,"extra":{"tool":{"id":"...","name":"pdf_summarize"}}},
    {"step":"lockfile.write","ok":true,"extra":{"path":"apps/pdf-bot/matrix.lock.json"}}
  ],
  "files_written": ["apps/pdf-bot/src/flows/pdf_summarizer_node.py","apps/pdf-bot/matrix.lock.json"],
  "lockfile": { "version":1, "entities":[{ "id":"agent:pdf-summarizer@1.4.2", "...": "..." }] }
}

清单和示意图

目录作者在单独的内容仓库中发布清单（例如。， agent-matrix/catalog)并生成 index.json.

Matrix Hub按计划或通过管理员触发器接收这些清单。 支持的模式（2020‑12年JSON模式草案）：

• 代理人： schemas/agent.manifest.schema.json
• 工具： schemas/tool.manifest.schema.json
• MCP服务器： schemas/mcp-server.manifest.schema.json

最小化 index.json 接受的格式：

{ "manifests": ["https://.../agents/pdf/1.4.2/agent.manifest.yaml"] }

或

{ "items": [ {"manifest_url": "https://.../tool.manifest.yaml"} ] }

或

{ "entries": [ {"base_url": "https://raw.githubusercontent.com/ORG/REPO/main/", "path": "agents/pdf/1.4.2/agent.manifest.yaml"} ] }

代理清单示例（摘录）：

schema_version: 1
type: agent
id: pdf-summarizer
name: PDF Summarizer
version: 1.4.2
description: Summarizes long PDF documents into concise points.
capabilities: [pdf, summarize]
compatibility:
  frameworks: [langgraph]
  providers: [watsonx]
artifacts:
  - kind: pypi
    spec: { package: pdf-summarizer-agent, version: "==1.4.2" }
adapters:
  - framework: langgraph
    template_key: langgraph-node
mcp_registration:
  tool:
    name: pdf_summarize
    integration_type: REST
    request_type: POST
    url: https://example.com/invoke
    input_schema: { type: object, properties: { input: { type: string } }, required: [input] }

本地开发

# 1) Create a virtualenv (optional)
python3 -m venv .venv && source .venv/bin/activate

# 2) Install in editable mode
pip install -U pip
pip install -e .

# 3) Run with auto-reload
make dev
# or
uvicorn src.app:app --reload --port 443

质量和测试

make fmt        # ruff fix + format
make lint       # ruff check
make test       # pytest -q

东西住的地方

src/
  app.py                # FastAPI app, routers, scheduler
  routes/               # /health, /catalog/*
  services/             # ingest, search, install, adapters, gateway client...
  models.py             # SQLAlchemy models
  schemas.py            # Pydantic DTOs
  utils/                # logging, security, etag
schemas/                # JSON Schemas for manifests
tests/                  # starter tests and smoke checks

迁移

该项目包括Alembic脚手架。要创建和应用迁移，请执行以下操作：

# Generate a new revision (edit message)
make migrate m="add quality indexes"

# Apply to head
make upgrade

在生产环境中，在启动新的应用程序实例之前，将迁移作为部署步骤的一部分运行（例如，init容器或CI作业）。

生产说明

容器图像： 看 Dockerfile （多阶段）。运行方式：

docker build -t ghcr.io/agent-matrix/matrix-hub:latest .
docker run -p 443:443 --env-file .env ghcr.io/agent-matrix/matrix-hub:latest

数据库： 在生产环境中使用PostgreSQL。SQLite仅支持快速本地试用。 缩放比例： API是无状态的；在反向代理/负载均衡器后面水平扩展。确保迁移只有一个编写器。 可观察性： 日志采用JSON格式，带有相关ID（请参阅 src/utils/logging.py).将stdout/stderr转发到您的日志堆栈（例如Loki/ELK）。根据需要添加指标/跟踪。 安全：

• 集 API_TOKEN 以保护管理路由。
• 将服务置于TLS之后（例如NGINX/Envoy），并在需要时强制客户端身份验证。
• 为配置出站访问策略 pip, docker，以及 git 如果你的环境限制了出口。

MCP网关： 暴露 MCP_GATEWAY_URL 和 MCP_GATEWAY_TOKEN。安装程序将在安装工件后注册工具/服务器。

故障排除

API返回500 /catalog/search

• 检查数据库连接(/health?check_db=true).
• 确保实体表已填充（摄取日志）。
• 如果运行SQLite，默认情况下禁用语义/向量搜索。

摄入后无结果

• 验证 MATRIX_REMOTES 指向有效 index.json.
• 检查容器日志中的验证错误（架构不匹配）。

安装失败 pip/docker/git

• 请参阅 results stdout/stderr命令的安装响应中的数组。
• 检查容器是否具有网络访问权限，以及工件引用是否有效。

网关注册错误

• 确认 MCP_GATEWAY_URL 可访问且令牌正确。
• 一些网关会自动执行发现；我们的客户负责运输标准化。

许可证

Apache 2.0。看 许可证.

Docker Hub

Docker Hub上提供了官方Docker镜像：

# Pull the latest image
docker pull ruslanmv/matrix-hub:latest

# Run with default settings (SQLite, port 8000)
docker run -d -p 8000:8000 --name matrix-hub ruslanmv/matrix-hub:latest

# Run with PostgreSQL and custom config
docker run -d -p 8000:8000 \
  -e DATABASE_URL=postgresql+psycopg://matrix:matrix@db:5432/matrixhub \
  -e API_TOKEN=your-secret-token \
  -e CATALOG_REMOTES='["https://raw.githubusercontent.com/agent-matrix/catalog/main/index.json"]' \
  --name matrix-hub \
  ruslanmv/matrix-hub:latest

# Build locally
make container-build
make container-run

前端集成

前端通过服务器端代理路由与后端通信：

要将前端连接到后端，请设置 MATRIX_HUB_BASE 在前端 .env.local:

MATRIX_HUB_BASE=https://api.matrixhub.io

DNS配置（生产）

另见

• 矩阵中心 --Web前端（Next.js）
• 代理生成器 --AI代理脚手架工具
• 目录 --精心策划的清单存储库

架构：

• 代理商-- schemas/agent.manifest.schema.json
• 工具-- schemas/tool.manifest.schema.json
• MCP服务器-- schemas/mcp-server.manifest.schema.json

测验： tests/ --烟雾测试和示例；与...一起跑 make test.