NimbleBrainInc/mpak
GitHub: NimbleBrainInc/mpak
这是一个用于MCP服务器的开源包注册表，内置安全扫描、信任评分及CLI工具，确保AI工具供应链安全。
Stars: 2 | Forks: 2
# mpak
[](https://mpak.dev) [](https://github.com/NimbleBrainInc/mpak/actions/workflows/ci.yml)
用于 [MCP](https://modelcontextprotocol.io/)（Model Context Protocol）服务器的开源包注册表。每个扫描的包，每次安装都有评分。
mpak 提供三样东西：
1. **MCPB** (MCP Bundle)，一种标准化的 MCP 服务器包格式，包含声明的依赖项、锁定的版本和可复现的安装。
2. **MTF** (mpak Trust Framework)，一个安全扫描器，从供应链、代码质量、工件完整性和来源控制四个维度对每个包进行评分。
3. **可自托管的注册表**，用于存储、服务和评分 MCPB 包。使用 [mpak.dev](https://mpak.dev) 上的公共实例或运行你自己的实例。
## 为什么存在
MCP 是允许 AI 代理调用外部工具的开放协议。MCP 服务器暴露了代理在运行时调用的能力（API 调用、文件访问、数据库查询）。这意味着 MCP 服务器获得对 AI 代理执行环境的特权访问。被入侵的服务器意味着在你的工作流中执行任意代码。
MCP 生态系统没有标准化的供应链安全。服务器以松散的脚本、GitHub 仓库、npm 包和 Docker 镜像的形式分发，没有一致的打包，也没有在运行前验证其内容。官方 MCP 注册表索引了数千个服务器，但不对其安全性做出任何声明。
发现问题已解决。信任问题尚未解决。mpak 处理发现之后的环节：打包、验证、分发和治理。
## 概念
### Bundles（包）
包是一个包含运行 MCP 服务器所需所有内容的 `.mcpb` 文件（ZIP 归档）：
```
my-server.mcpb
├── manifest.json # Metadata: name, version, server_type, how to run it
├── src/ # Server source code
└── deps/ # All dependencies, vendored
```
`manifest.json` 是必需的入口点。它声明了包名称、版本、服务器类型（`node`、`python` 或 `binary`）、特定于平台的运行命令以及服务器暴露的工具/提示/资源。架构定义在 `packages/schemas` 中。
### Skills（技能）
技能是包的知识对应物。虽然包赋予 AI 代理*做*事情的能力（调用 API、运行命令），但技能赋予它*思考*事情的能力（领域专业知识、工作流指令）。
技能是一个带有 YAML frontmatter 的 markdown 文件（`SKILL.md`），声明了元数据（名称、描述、类别、触发短语）。技能可以打包为 `.skill` 文件（也是 ZIP 归档）并通过注册表分发。
### 信任级别
每个包都会从 MTF 扫描器获得信任分数。分数由两部分组成：级别（L1 到 L4）和数字分数（0 到 100），代表该级别内通过了多少项控制。有关完整框架，请参阅 [mpaktrust.org](https://mpaktrust.org)。
| Level | Name | Controls | What it means |
|-------|------|----------|---------------|
| **L1** | 基础 | 5 | 已生成 SBOM，未检测到机密信息或恶意软件，清单有效，已声明工具 |
| **L2** | 标准 | 15 | 增加了漏洞扫描、依赖固定、静态分析、作者身份 |
| **L3** | 已验证 | 22 | 增加了包签名、构建证明、输入验证、仓库健康检查 |
| **L4** | 已证明 | 25 | 增加了行为分析、可复现构建、提交链接 |
在 CLI 输出中，`L3 87` 表示该包达到了 Level 3 并通过了 87% 的 L3 控制项。
### 发布（Publishing）
包通过 GitHub Actions 发布，而不是 CLI。GitHub Actions 工作流使用 GitHub OIDC token 调用 `POST /v1/bundles/announce`。注册表验证 token，从 GitHub 下载发布工件，验证 SHA256 哈希，存储包，并触发 MTF 安全扫描。此设计确保每个发布的包都有可验证的链接回到源仓库和 CI 运行。
### 认领（Claiming）
认领让维护者证明他们拥有一个包。要认领 `@scope/my-server`，请将 `mpak.json` 文件添加到你的 GitHub 仓库：
```
{
"name": "@scope/my-server",
"maintainers": ["your-github-username"]
}
```
然后调用认领端点。注册表验证你的仓库中是否存在该文件，并且元数据匹配。一旦被认领，只有认领者（或仓库所有者）才能发布新版本。
## 快速开始
安装 CLI：
```
npm install -g @nimblebrain/mpak
```
搜索包：
```
mpak search github
# 名称 版本 信任 描述
# @anthropic/github-mcp 1.2.0 L3 87 GitHub API 集成
# community/github-issues 2.0.1 L4 94 Issue 管理
```
拉取并运行它：
```
mpak bundle run @anthropic/github-mcp
```
CLI 从 mpak.dev 下载包，将其解压到 `~/.mpak/cache/`，并启动 MCP 服务器。
### 与 Claude Desktop 一起使用
将服务器添加到你的 Claude Desktop 配置中（在 macOS 上位于 `~/Library/Application Support/Claude/claude_desktop_config.json`）：
```
{
"mcpServers": {
"github": {
"command": "mpak",
"args": ["bundle", "run", "@anthropic/github-mcp"]
}
}
}
```
### 与 Claude Code 一起使用
```
claude mcp add github -- mpak bundle run @anthropic/github-mcp
```
## 仓库结构
这是一个使用 [pnpm workspaces](https://pnpm.io/workspaces) 和 [Turborepo](https://turbo.build/) 管理的 monorepo。
```
packages/
schemas/ Zod schemas and TypeScript types (foundation for everything else)
sdk/ TypeScript client for the registry API
cli/ The `mpak` CLI
apps/
registry/ Fastify API server with Prisma/PostgreSQL
web/ React + Vite web UI (browse, search, trust scores)
scanner/ MTF security scanner (Python)
docs/ Documentation site (Astro/Starlight)
deploy/
docker/ Docker Compose for local dev and production
kubernetes/ Helm chart
scripts/
setup.sh One-time dev environment setup
dev.sh Start all services for local development
test.sh Run the full test suite
release.sh Version bump, changelog, publish
```
### 依赖关系图
```
schemas (no internal deps)
↓
sdk (depends on schemas)
↓
cli (depends on sdk + schemas)
registry (depends on schemas, standalone Fastify server)
web (standalone React app, talks to registry API)
scanner (standalone Python project, not in pnpm workspaces)
```
## 软件包
### `packages/schemas`
用于 MCPB 清单格式、API 响应、信任分数、技能和验证助手的 Zod 架构和推断的 TypeScript 类型。这是整个堆栈中数据形状的事实来源。
**主要导出：** `BundleSchema`、`SkillSchema`、`MpakJsonSchema`、`SearchParamsSchema`、验证函数。
### `packages/sdk-typescript`
用于与 mpak 注册表交互的 TypeScript SDK。使用类型化方法包装 HTTP API，用于搜索、下载和检查包及技能。
```
import { MpakClient } from "@nimblebrain/mpak-sdk";
const client = new MpakClient(); // defaults to https://mpak.dev
const results = await client.searchBundles("github");
const bundle = await client.getBundleDetails("@anthropic/github-mcp");
```
### `packages/cli`
`mpak` 命令行工具。使用 [Commander.js](https://github.com/tj/commander.js/) 构建。
| Command | Description |
|---------|-------------|
| `mpak search ` | 搜索包和技能 |
| `mpak bundle search ` | 仅搜索包 |
| `mpak bundle show ` | 显示包详细信息和信任分数 |
| `mpak bundle pull ` | 下载包 |
| `mpak bundle run ` | 下载并运行 MCP 服务器 |
| `mpak skill search ` | 搜索技能 |
| `mpak skill show ` | 显示技能详细信息 |
| `mpak skill install ` | 将技能安装到 `~/.claude/skills/` |
| `mpak skill validate ` | 验证技能目录 |
| `mpak skill pack ` | 创建 `.skill` 包 |
| `mpak config set ` | 为包设置配置 |
| `mpak config get ` | 显示包的配置 |
## 应用
### `apps/registry`
注册表 API 服务器。基于 PostgreSQL 的 Fastify 和 Prisma ORM。处理包存储、下载、信任分数跟踪和 MTF 扫描管道。
**API surface:**
- `/v1/bundles/*` - 用于包操作的原生 mpak API
- `/v1/skills/*` - 用于技能操作的原生 mpak API
- `/v0.1/servers` - MCP 注册表规范兼容性（以便 MCP 客户端可以通过标准协议发现包）
- `/app/*` - Web UI 使用的路由（身份验证、管理、包认领、扫描结果）
- `/health` - 健康检查
- `/docs` - OpenAPI/Swagger 文档
**存储后端：** 本地文件系统、S3、GCS、Azure Blob Storage。通过环境变量配置。
**身份验证：** Clerk (OIDC)。读取端点可选，发布端点必需。
### `apps/web`
用于浏览注册表的 React SPA。使用 Vite、Tailwind CSS 4、React Router 和 TanStack Query 构建。包括信任分数可视化、包详细信息、技能浏览和管理面板。
### `apps/scanner`
实现 mpak Trust Framework (MTF) 的 Python 安全扫描器。根据五个领域的 20 多项控制评估包：
| Domain | Controls | What it checks |
|--------|----------|----------------|
| Supply Chain (SC) | SC-01 through SC-03 | SBOM、漏洞扫描、依赖固定 |
| Code Quality (CQ) | CQ-01 through CQ-06 | 机密信息、恶意模式、静态分析、不安全执行 |
| Artifact Integrity (AI) | AI-01, AI-02 | 清单验证、内容哈希 |
| Provenance (PR) | PR-01, PR-02 | 仓库验证、作者身份 |
| Capability Declaration (CD) | CD-01 through CD-03 | 工具描述、权限范围 |
根据通过的控制项，生成从 L1（基础）到 L4（已证明）的信任分数。有关每个级别的详细信息，请参阅 [信任级别](#trust-levels)。
**扫描如何工作：** 当发布包时，注册表创建一个运行扫描器镜像的 Kubernetes Job。扫描器评估包，将结果写入 S3，并通过回调 URL 将分数 POST 回注册表。在 Docker Compose 中，扫描器作为独立容器运行，而不是 K8s Job。
### `apps/docs`
文档站点。涵盖 CLI 用法、包格式、技能、集成（VS Code、Claude Desktop、Cursor、Claude Code）和安全控制。
## 开发设置
### 前置条件
- Node.js 22+
- pnpm 9+
- PostgreSQL 16+
- Python 3.13+ 和 [uv](https://docs.astral.sh/uv/)（用于扫描器）
### 1. 安装依赖
```
pnpm install
```
### 2. 设置 PostgreSQL
如果你已经在本地运行 PostgreSQL：
```
psql -c "CREATE USER mpak WITH PASSWORD 'mpak' CREATEDB;"
psql -c "CREATE DATABASE mpak OWNER mpak;"
```
或者使用 Docker 启动一个：
```
docker run -d --name mpak-postgres \
-e POSTGRES_USER=mpak -e POSTGRES_PASSWORD=mpak -e POSTGRES_DB=mpak \
-p 5432:5432 postgres:16-alpine
```
### 3. 配置环境
每个需要配置的应用都有自己的 `.env.example`。复制它们：
```
cp apps/registry/.env.example apps/registry/.env
cp apps/web/.env.example apps/web/.env
```
默认设置适用于本地开发，无需更改。
### 4. 运行数据库迁移
```
cd apps/registry && npx prisma migrate dev && cd ../..
```
### 5. 播种示例数据
用示例技能填充数据库，以便 UI 有内容可显示：
```
cd apps/registry && npm run db:seed && cd ../..
```
这会插入一些真实的技能（`@nimblebraininc/docs-auditor`、`@nimblebraininc/seo-optimizer`、`@nimblebraininc/strategic-thought-partner`），包含多个版本、下载计数、标签和触发器。可以安全地多次运行（使用 upserts）。
要添加更多种子数据，请编辑 `apps/registry/prisma/seed.ts`。
### 6. 构建
```
pnpm build
```
### 运行服务
单独启动服务。每个服务在自己的终端中运行：
```
# Registry API (端口 3200)
pnpm --filter @nimblebrain/mpak-registry dev
# Web UI (端口 5173)
pnpm --filter @nimblebrain/mpak-web dev
# Docs site (端口 4321)
pnpm --filter mpak-docs dev
```
验证注册表是否正在运行：
```
curl http://localhost:3200/health
```
### 使用 Docker Compose 运行
```
docker compose -f deploy/docker/docker-compose.yml up --build
```
| Service | Port | Description |
|---------|------|-------------|
| `postgres` | 5432 | PostgreSQL 16 |
| `registry` | 3200 | Registry API |
| `web` | 8080 | Web UI (nginx) |
| `scanner` | - | MTF scanner (CLI tool) |
### 运行测试
```
# 所有 TypeScript 测试
pnpm test
# 特定软件包
pnpm --filter @nimblebrain/mpak-schemas test
pnpm --filter @nimblebrain/mpak-sdk test
pnpm --filter @nimblebrain/mpak test # CLI
# Python scanner 测试
cd apps/scanner && uv sync --dev && uv run pytest
# 完整验证 (build + test + lint + typecheck)
pnpm build && pnpm test && pnpm lint && pnpm typecheck
```
### 构建
```
# 构建所有软件包 (通过 Turborepo 遵循依赖顺序)
pnpm build
# 构建特定软件包
pnpm --filter @nimblebrain/mpak-schemas build
# 构建后的 CLI 冒烟测试
node packages/cli/dist/index.js --help
```
## 环境变量
每个应用管理自己的 `.env` 文件。没有根 `.env`。
### `apps/registry/.env`
完整列表请参阅 [`apps/registry/.env.example`](apps/registry/.env.example)。关键变量：
| Variable | Default | Description |
|----------|---------|-------------|
| `DATABASE_URL` | `postgresql://mpak:mpak@localhost:5432/mpak` | PostgreSQL 连接字符串 |
| `PORT` | `3200` | 注册表服务器端口 |
| `STORAGE_TYPE` | `local` | 包存储：`local` 或 `s3` |
| `STORAGE_PATH` | `./packages` | 本地存储路径（当 `STORAGE_TYPE=local` 时） |
| `CLERK_SECRET_KEY` | (empty) | Clerk 认证密钥。本地开发可选，生产环境必需 |
| `SCANNER_ENABLED` | `false` | 在发布时启用 MTF 扫描 |
| `SCANNER_CALLBACK_URL` | `http://localhost:3200/app/scan-results` | 扫描器 POST 结果的 URL。在 K8s 中设置为你集群内部的服务地址 |
| `SCANNER_SECRET_NAME` | `scanner-secrets` | 挂载到 scanner Jobs 的 K8s Secret 名称 |
### `apps/web/.env`
完整列表请参阅 [`apps/web/.env.example`](apps/web/.env.example)。
| Variable | Default | Description |
|----------|---------|-------------|
| `VITE_API_URL` | `http://localhost:3200` | 注册表 API 端点 |
| `VITE_CLERK_PUBLISHABLE_KEY` | (empty) | Clerk 公钥。本地开发可选 |
| `VITE_ENABLE_DEBUG_AUTH` | `true` | 在 UI 中显示认证调试面板 |
## 部署
### 数据库迁移直接运行 Prisma 迁移：
```
# 检查迁移状态
cd apps/registry && DATABASE_URL="postgresql://..." npx prisma migrate status
# 运行待处理的迁移
cd apps/registry && DATABASE_URL="postgresql://..." npx prisma migrate deploy
```
### Helm
```
helm lint deploy/kubernetes/helm/mpak/
helm install mpak deploy/kubernetes/helm/mpak/ \
--set config.databaseUrl="postgresql://..." \
--set config.storageBackend=s3
```
Helm chart 支持 `existingSecret` 用于生产密钥管理。
### Docker (生产环境)
```
docker compose -f deploy/docker/docker-compose.prod.yml up -d
```
使用带有 S3 存储和适当资源限制的预构建镜像。
## 架构
```
┌─────────────┐
│ Web UI │ React SPA
│ (Vite) │ Browse, search, trust scores
└──────┬──────┘
│ HTTP
▼
┌─────────┐ ┌─────────────┐ ┌──────────┐
│ CLI │──────▶│ Registry │──────▶│ Storage │
│ (mpak) │ HTTP │ (Fastify) │ │ (S3/GCS/ │
└─────────┘ └──────┬──────┘ │ local) │
│ └──────────┘
┌────┴────┐
│ │
▼ ▼
┌──────────┐ ┌─────────┐
│PostgreSQL│ │ Scanner │
│ (Prisma) │ │ (Python)│
└──────────┘ └─────────┘
```
CLI 和 Web UI 都与注册表 API 通信。注册表将包存储在可配置的存储（S3、GCS、Azure 或本地文件系统）中，并将元数据存储在 PostgreSQL 中。包通过 GitHub Actions OIDC（而不是 CLI）发布。当发布包时，注册表创建一个运行扫描器的 Kubernetes Job。扫描器评估 MTF 控制，将详细结果写入 S3，并通过回调 URL 将信任分数 POST 回注册表。
## 贡献
有关开发工作流、提交约定和代码风格指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
Apache 2.0。请参阅 [LICENSE](LICENSE)。
标签：AI代理, CLI, DevSecOps, L1-L4, MCP, MCPB, MITM代理, Model Context Protocol, WiFi技术, 上游代理, 依赖管理, 信任评分, 包注册表, 子域名突变, 安全合规, 工件完整性, 开源, 来源验证, 注册表, 测试用例, 版本锁定, 网络代理, 自动化攻击, 自托管, 请求拦截, 软件包管理器, 逆向工具