使用说明

Blackout安全MCP注册表引擎

静态MCP注册表生成器和GitHub Marketplace Action，用于生成与主机无关的注册表工件。

现场演示

Cloudflare页面演示

代表：https://github.com/blackoutsecure/bos-mcp-engine-demo
分行： registry-demo-cf
地点：https://demo.mcp.registry.blackoutsecure.dev/

GitHub页面演示

代表：https://github.com/blackoutsecure/bos-mcp-engine-demo
分行： registry-demo-gh
地点：https://demo-gh.mcp.registry.blackoutsecure.dev/

公司和赞助商

该项目由以下人员建造和维护 停电安全.

公司网址：https://blackoutsecure.app
组织简介：https://github.com/blackoutsecure
市场列表：https://github.com/marketplace/actions/blackout-secure-mcp-registry-engine

规格对齐

协议基线：MCP规范2025-11-25(https://modelcontextprotocol.io/specification/2025-11-25)
协议模式真值来源： https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-11-25/schema.ts
注册表清单架构引用： https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/draft/server.schema.json
此项目保留了一个拆分的静态清单模型(server.json + versions/<semver>.json)并遵循当前注册表字段语义。
远程传输必须使用 remotes[].type 当前值(sse, streamable-http).

它做什么

验证 servers/<name>/server.json 和 servers/<name>/versions/<semver>.json
在下生成静态注册表输出 <output_directory>/<output>
支持MCP服务器存储库中的服务器清单生命周期（生成/更新+验证）
将生成的公共工件保存在配置的 output 文件夹（默认值： public)
为生成版本化的API兼容项目 v0.1
支持部署配置文件：
- github （生成 .nojekyll)
- cloudflare （生成 _headers 和 _redirects)
- none （没有特定于主机的配置文件；适用于Apache/Nginx等本地/静态主机）

操作使用（市场）

name: Build MCP Registry

on:
  push:
    branches: [main]
    paths:
      - 'servers/**'
      - 'src/**'

jobs:
  registry:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate registry
        uses: blackoutsecure/bos-mcp-registry-engine@v1
        with:
          # Required
          # Supported values:
          # generate_registry, validate_registry,
          # generate_server_manifest, validate_server_manifest
          action_type: 'generate_registry'
          # Optional (default): info
          # Suggested: debug, info, warn, error
          log_level: 'info'
          source: './servers'
          # Optional (default): dist
          output_directory: 'dist'
          # Optional (default): public
          # Generates to dist/public
          output: 'public'
          # Optional (default): github
          deployment_environment: 'github'
          # Optional
          # config: './config/custom-registry-config.json'

输入

下表与 action.yml 输入。

输入	必填	默认	说明
`action_type`	是的	（无）	操作模式
`log_level`	没有	`info`	控制台日志记录级别
`source`	没有	`./servers`	服务器根路径
`output_directory`	没有	`dist`	基本输出目录路径
`output`	没有	`public`	注册表公用文件夹
`deployment_environment`	没有	`github`	主机配置文件
`cloudflare_lean_output`	没有	`true`	Cloudflare仅JSON精简输出
`config`	没有	（无）	注册表配置文件
`upload_artifacts`	没有	`true`	将生成的注册表作为工件上传
`artifact_name`	没有	`mcp-registry-files`	启用上传时的工件名称
`artifact_retention_days`	没有	`1`	保留天数
`server_slug`	没有	（无）	服务器文件夹slug
`server_name`	没有	（无）	服务器清单名称
`server_description`	没有	（无）	服务器描述
`server_title`	没有	（无）	服务器标题
`server_website_url`	没有	（无）	服务器网站URL
`repository_url`	没有	（无）	存储库URL
`repository_source`	没有	`github`	存储库源
`repository_subfolder`	没有	（无）	存储库子文件夹
`server_version`	没有	`1.0.0`	版本清单值
`release_date`	没有	（无）	发布日期
`package_registry_type`	没有	`npm`	包注册表类型
`package_identifier`	没有	（无）	包标识符
`package_transport_type`	没有	`stdio`	包装运输类型

输入详细信息：

action_type: generate_registry, validate_registry, generate_server_manifest, validate_server_manifest.
log_level: debug, info, warn, error.
output_directory, output, deployment_environment，以及 cloudflare_lean_output 应用于注册表操作。
cloudflare_lean_output 仅在以下情况下适用 deployment_environment=cloudflare；默认 true 发出JSON文件并依赖于 _redirects 用于无扩展别名。
如果已配置 source 目录不存在， generate_registry 创建一个空的源目录并生成一个空注册表输出（而不是崩溃）。
upload_artifacts, artifact_name, artifact_retention_days, commit_generated_artifacts, artifact_committer_name，以及 artifact_committer_email 应用于 generate_registry 只有。
commit_generated_artifacts：默认为 true从签出的存储库工作区暂存、提交和推送生成的输出；需要 upload_artifacts=true.
artifact_retention_days：必须是介于之间的整数 1 和 400；无效值在配置过程中无法执行操作。
GitHub保留默认值由您的存储库/组织策略控制（请参阅 GitHub工件/日志保留策略文档).
此存储库/操作默认为 artifact_retention_days 是 1.
artifact_committer_name：可选；默认为 github-actions[bot] 当本地 git user.name 未设置。
artifact_committer_email：可选；默认为 41898282+github-actions[bot]@users.noreply.github.com 当本地 git user.email 未设置。
server_slug 是服务器清单操作所必需的。
server_name 和 server_description 是必需的 generate_server_manifest.
config 支持 version 和 externalRepositories.

输入方式 `action_type`

输入组	生成注册表	验证注册表	生成服务器初始化	验证服务器初始化
`source`	必填	必需	必需	必填
`log_level`	可选	可选	可选
`output_directory`	可选	可选	不适用	不适用
`output`	可选	可选	不适用	不适用
`deployment_environment`	可选	可选	不适用	不适用
`cloudflare_lean_output`	可选	可选	不适用	不适用
`config`	可选	可选	不适用	不适用
`upload_artifacts`	可选	N/A	N/A	不适用
`artifact_name`	可选	N/A	N/A	不适用
`artifact_retention_days`	可选	N/A	N/A	不适用
`server_slug`	N/A	N/A	必填	必填
`server_name`	N/A	N/A	必填	N/A
`server_description`	N/A	N/A	必填	N/A
`server_title`	N/A	N/A	可选	N/A
`server_website_url`	N/A	N/A	可选	N/A
`repository_*`	N/A	N/A	可选	N/A
`server_version`	N/A	N/A	可选	N/A
`release_date`	N/A	N/A	可选	N/A
`package_*`	N/A	N/A	可选	N/A

传说：

必需=必须为该操作类型提供。
可选=支持但不是必需的。
N/A=对于该操作类型忽略。

`action_type` 价值观

值	行为	生成文件	描述
generate_registry	验证+生成	是	验证发现的清单，然后写入注册表工件。
validate_registry	仅验证	否	验证发现的清单，而不写入输出文件。
generate_server_manifest	生成/更新文件	是	生成或更新一个服务器清单集，然后进行验证。
validate_server_manifest	验证一台服务器	否	验证特定服务器的清单 `server_slug` 只有。

笔记：

仅使用显式值；不支持旧别名。

`log_level` 价值观

debug：故障排除。
info：默认操作日志记录。
warn：警告和错误。
error：仅错误。

验证保证

generate_registry：在写入注册表工件之前验证所有发现的清单。
validate_registry：验证所有发现的清单，并退出而不写入输出。
generate_server_manifest：生成/更新文件，然后在成功之前验证生成的清单。
generate_server_manifest：更新 versions/latest.json 以匹配生成的 server_version 显示。
validate_server_manifest：验证现有清单 server_slug 并因架构/版本错误而失败。

如果验证失败，则操作退出非零，工作流步骤失败。

可信贡献模型

对于可信摄取（避免盲目添加），请使用此工作流模式：

需要基于PR的更改 servers/** （不得直接推送受保护的分支）。
执行代码所有者审查 servers/** 以及注册表配置文件。
跑 action_type: validate_registry 合并前的PR检查。
在工作流中固定操作版本（例如 @v1 或在更严格的环境中完全SHA）。
保持外部来源明确 config 并像代码一样查看配置更改。
可选择添加策略检查（组织分配列表、签名提交、分支保护）。

可信PR验证示例：

name: Verify Registry Inputs

on:
  pull_request:
    paths:
      - 'servers/**'
      - 'config/**'

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate registry manifests
        uses: blackoutsecure/bos-mcp-registry-engine@v1
        with:
          action_type: 'validate_registry'
          log_level: 'info'
          source: './servers'
          config: './config/custom-registry-config.json'

`deployment_environment` 价值观

值	目标主机	生成的配置文件	备注
`github`	GitHub页面	`.nojekyll`	防止页面上的Jekyll处理
`cloudflare`	Cloudflare Pages/Workers静态托管	`_headers`, `_redirects`	应用标头并重定向别名
`none`	通用静态主机	（无）	与主机无关的输出，没有配置文件

动作与CLI输出语义

在GitHub操作中， output_directory 控制基本输出路径（默认 dist).
在GitHub操作中， output 控制该基下的公共目录名称（默认 public).
有效动作输出路径为 <output_directory>/<output>.
在本地CLI使用中， --output 表示基本输出目录（例如 ./dist)以及 --public-directory 控制公用文件夹名称。

输出路径如何工作

动作输入 output_directory 控制基础路径。
动作输入 output 控制该库下的公共目录。
有效动作输出路径为 <output_directory>/<output>.

示例：

output_directory: dist 和 output: public → dist/public
output_directory: build 和 output: registry → build/registry

工作流示例：验证然后生成

使用两个作业，以便生成仅在成功验证后运行。

name: Validate and Generate MCP Registry

on:
  push:
    branches: [main]
    paths:
      - 'servers/**'
      - 'src/**'
      - 'action.yml'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate MCP manifests
        uses: blackoutsecure/bos-mcp-registry-engine@v1
        with:
          action_type: 'validate_registry'
          log_level: 'info'
          source: './servers'

  generate:
    runs-on: ubuntu-latest
    needs: validate
    steps:
      - uses: actions/checkout@v4
      - name: Generate static registry artifacts
        uses: blackoutsecure/bos-mcp-registry-engine@v1
        with:
          action_type: 'generate_registry'
          log_level: 'info'
          source: './servers'
          output: 'public'
          deployment_environment: 'github'

      - name: Upload registry artifact
        uses: actions/upload-artifact@v4
        with:
          name: mcp-registry-public
          path: dist/public

可选的内置工件上传

您可以让此操作直接将生成的注册表目录作为GitHub Actions工件上传：

- name: Generate static registry artifacts
  uses: blackoutsecure/bos-mcp-registry-engine@v1
  with:
    action_type: 'generate_registry'
    source: './servers'
    output: 'public'
    upload_artifacts: 'true'
    artifact_name: 'mcp-registry-public'
    artifact_retention_days: '7'
    commit_generated_artifacts: 'true'
    artifact_committer_name: 'github-actions[bot]'
    artifact_committer_email: '41898282+github-actions[bot]@users.noreply.github.com'

commit_generated_artifacts 从签出的存储库工作区暂存、提交和推送生成的文件。

工作流示例：在MCP服务器仓库中生成/更新服务器清单

name: Generate MCP Server Manifests

on:
  workflow_dispatch:

jobs:
  server-manifest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate or update server manifests
        uses: blackoutsecure/bos-mcp-registry-engine@v1
        with:
          action_type: 'generate_server_manifest'
          log_level: 'info'
          source: './servers'
          server_slug: 'github'
          server_name: 'io.github.github/github'
          server_description: 'Official GitHub MCP server.'
          server_version: '1.0.0'
          package_identifier: '@modelcontextprotocol/server-github'

      - name: Validate generated server manifests
        uses: blackoutsecure/bos-mcp-registry-engine@v1
        with:
          action_type: 'validate_server_manifest'
          log_level: 'info'
          source: './servers'
          server_slug: 'github'

## Local usage

```bash
npm install
npm run validate
npm run generate

可选自定义配置文件：

node src/index.js --config ./config/custom-registry-config.json

或者：

MCP_REGISTRY_CONFIG=./config/custom-registry-config.json npm run generate

仅运行验证模式（不生成输出）：

node src/index.js --action-type validate_registry

默认情况下不需要配置文件。内置默认值为：

version: 0.1
externalRepositories: []

所需输入布局

servers/
  <name>/
    server.json
    versions/
      <semver>.json

在存储库中使用此布局创建自己的服务器清单。

清单格式

server.json

最少必填字段：

name
description

推荐字段：

$schema
title
websiteUrl
repository
_meta

例子：

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.github/github",
  "title": "GitHub",
  "description": "Official GitHub MCP server for repositories, pull requests, issues, and related workflows.",
  "websiteUrl": "https://github.com/modelcontextprotocol/servers/tree/main/src/github",
  "repository": {
    "url": "https://github.com/modelcontextprotocol/servers",
    "source": "github",
    "subfolder": "src/github"
  }
}

`versions/<semver>.json`

必填字段：

version （必须是有效的，不能是 latest)
至少以下之一：
- packages
- remotes

例子：

{
  "version": "1.0.0",
  "releaseDate": "2024-11-20",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@modelcontextprotocol/server-github",
      "version": "1.0.0",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}

可选配置文件

如果需要，请提供一个自定义配置文件，其中包含：

version
externalRepositories

当您想要执行以下操作时，请使用配置文件：

从其他本地存储库聚合服务器
将特定于环境的源根保持在默认值之外 servers/
覆盖受控发布流的注册表版本元数据

建议：

使用 config 设定 version 以及一个可重用的签入文件中的外部存储库。

外部存储库格式

externalRepositories 必须是本地目录引用的数组。每个条目可以是：

字符串路径
一个物体 path
一个物体 serversPath

每个解析路径必须指向 servers-样式目录包含：

<server-name>/server.json
<server-name>/versions/<semver>.json

例子：

{
  "version": "0.1",
  "externalRepositories": [
    "../another-repo/servers",
    { "path": "../team-repo/servers" },
    { "serversPath": "../shared/servers" }
  ]
}

笔记：

路径从工作区根解析。
跳过无效或缺失的路径，并发出警告。
首次加载后，重复的服务器名称将被忽略。

带有配置的GitHub操作示例

jobs:
  registry:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate registry with external repositories
        uses: blackoutsecure/bos-mcp-registry-engine@v1
        with:
          action_type: 'generate_registry'
          log_level: 'info'
          source: './servers'
          output: 'public'
          deployment_environment: 'github'
          config: './config/custom-registry-config.json'

输出

核心生成的文件（显示为操作默认值，其中 output: public):

dist/public/index.html
dist/public/v0.1/index.html
dist/public/v0.1/servers.json
dist/public/v0.1/servers/index.json
dist/public/v0.1/servers/<url-encoded-serverName>/versions/<version>.json
dist/public/v0.1/servers/<url-encoded-serverName>/versions/latest.json

部署特定：

github: dist/public/.nojekyll
cloudflare: dist/public/_headers, dist/public/_redirects
none：不生成特定于平台的配置文件（输出仍然是根/版本的可移植静态文件 index.html 重定向）

托管矩阵

`deployment_environment`	推荐主机	生成的配置文件	备注
`github`	GitHub页面	`.nojekyll`	防止页面运行Jekyll处理。
`cloudflare`	Cloudflare Pages/Workers静态文件	`_headers`, `_redirects`	应用安全/缓存标头和重定向别名。
`none`	本地预览、Apache、Nginx、通用静态主机	（无）	仅与主机无关的静态输出；根和版本 `index.html` 文件仍然提供导航/重定向行为。

存储库范围

此存储库仅用于静态注册表生成和Marketplace Action打包。

无运行时MCP服务器
无后端托管逻辑
此仓库中没有工作流编排文件
此操作不会直接向第三方MCP市场发布

放行/质量检查

npm run check

这将运行lint、格式检查、验证、测试、构建和生产审核门。

许可证

阿帕奇-2.0。看许可证.

支持

问题： blackoutsecure/bos-mcp注册表引擎/问题
安全：安全.md