mpak (Nimble Brain Inc)

篮子

开源包注册表 主控程序 （模型上下文协议）服务器。扫描每个捆绑包，对每个安装进行评分。

mpak提供了三件事：

1. 2甲4氯丁酸 （MCP Bundle），一种用于MCP服务器的标准化包格式，具有声明的依赖关系、锁定的版本和可复制的安装。
2. 跨性别女性 （mpak Trust Framework），一个安全扫描器，对整个供应链、代码质量、工件完整性和来源控制中的每个捆绑包进行评分。
3. 自托管注册表 存储、服务和评分MCPB捆绑包。在以下位置使用公共实例 mpak.dev 或者自己经营。

为什么存在

MCP是一种开放协议，允许AI代理调用外部工具。MCP服务器公开代理在运行时调用的功能（API调用、文件访问、数据库查询）。这意味着MCP服务器可以特权访问AI代理执行环境。受损的服务器意味着在工作流中执行任意代码。

MCP生态系统没有标准化的供应链安全。服务器以松散脚本、GitHub repos、npm包和Docker镜像的形式分发，没有一致的打包，也没有在运行前对其包含的内容进行验证。官方的MCP注册表对数千台服务器进行了索引，但没有对其安全性做出任何声明。

发现已解决。信任不是。mpak处理发现后的事情：打包、验证、分发和治理。

概念

捆绑包

捆绑是指 .mcpb 文件（ZIP存档），其中包含运行MCP服务器所需的所有内容：

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.

技能

技能是捆绑的知识对应物。虽然捆绑包赋予AI代理以下能力 *做* 事物（调用API、运行命令）、技能使其能够 *思考* 关于事物（领域专业知识、工作流程说明）。

技能是一个标记文件(SKILL.md)使用声明元数据（名称、描述、类别、触发短语）的YAML frontmatter。技能可以打包为 .skill 文件（也是ZIP存档）并通过注册表分发。

信任级别

每个捆绑包都会收到MTF扫描仪的信任评分。分数有两个部分：一个级别（L1到L4）和一个数字分数（0到100），表示在该级别内通过了多少控制。查看完整框架 mpaktrust.org.

在CLI输出中， L3 87 意味着该捆绑达到了3级，并通过了87%的L3控制。

出版

捆绑包是通过GitHub Actions发布的，而不是CLI。GitHub Actions工作流调用 POST /v1/bundles/announce 使用GitHub OIDC代币。注册表验证令牌，从GitHub下载发布工件，验证SHA256哈希，存储捆绑包，并触发MTF安全扫描。这种设计确保了每个发布的捆绑包都有一个可验证的链接，可以链接回源存储库和CI运行。

要求

声明让维护者证明他们拥有一个包。索赔 @scope/my-server，添加a mpak.json 文件到您的GitHub仓库：

{
  "name": "@scope/my-server",
  "maintainers": ["your-github-username"]
}

然后调用索赔端点。注册表验证文件是否存在于您的存储库中，并具有匹配的元数据。一旦声明，只有声明者（或回购所有者）可以发布新版本。

快速启动

安装CLI：

npm install -g @nimblebrain/mpak

搜索捆绑包：

mpak search github

# NAME                      VERSION   TRUST    DESCRIPTION
# @anthropic/github-mcp     1.2.0     L3 87    GitHub API integration
# community/github-issues   2.0.1     L4 94    Issue management

拉动并运行它：

mpak bundle run @anthropic/github-mcp

CLI从mpak.dev下载捆绑包，并将其提取到 ~/.mpak/cache/，并启动MCP服务器。

与Claude Desktop一起使用

将服务器添加到Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "github": {
      "command": "mpak",
      "args": ["bundle", "run", "@anthropic/github-mcp"]
    }
  }
}

与Claude Code一起使用

claude mcp add github -- mpak bundle run @anthropic/github-mcp

存储库结构

这是一个用以下方式管理的monorepo 和 Turborepo.

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清单格式的Zod架构和推断的TypeScript类型、API响应、信任分数、技能和验证助手。这是整个堆栈中数据形状的真实来源。

主要出口： 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 命令行工具。建于 指挥官.js.

应用

apps/registry

注册表API服务器。在PostgreSQL上使用Prisma ORM进行禁食。处理捆绑包存储、下载、信任分数跟踪和MTF扫描管道。

API表面：

• /v1/bundles/* -用于捆绑操作的本机mpak API
• /v1/skills/* -用于技能操作的本机mpak API
• /v0.1/servers -MCP注册表规范兼容性（因此MCP客户端可以通过标准协议发现捆绑包）
• /app/* -web UI使用的路由（身份验证、管理员、包声明、扫描结果）
• /health -健康检查
• /docs -OpenAPI/Swagger文档

存储后端： 本地文件系统、S3、GCS、Azure Blob存储。通过环境变量配置。

认证： 书记员（OIDC）。读取端点可选，发布时必需。

apps/web

React SPA用于浏览注册表。使用Vite、Tailwind CSS 4、React Router和TanStack Query构建。包括信任评分可视化、捆绑包详细信息、技能浏览和管理面板。

apps/scanner

实现mpak信任框架（MTF）的Python安全扫描程序。针对五个域中的20多个控件评估捆绑包：

生成从L1（基本）到L4（已认证）的信任评分，根据该评分通过控制。请参阅 信任级别 了解每个级别的详细信息。

扫描的工作原理： 当发布包时，注册表会创建一个运行扫描程序映像的Kubernetes作业。扫描程序评估包，将结果写入S3，并通过回调URL将分数回传到注册表。在Docker Compose中，扫描程序作为独立容器运行，而不是K8s作业。

apps/docs

文件网站。涵盖CLI使用、捆绑包格式、技能、集成（VS Code、Claude Desktop、Cursor、Claude Code）和安全控制。

开发设置

先决条件

• Node.js 22+
• pnpm 9+
• PostgreSQL 16+
• Python 3.13+和 紫外线 （适用于扫描仪）

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)具有多个版本、下载计数、标签和触发器。可安全运行多次（使用故障）。

要添加更多种子数据，请编辑 apps/registry/prisma/seed.ts.

6.建造

pnpm build

运行服务

单独启动服务。每个都在自己的终端中运行：

# Registry API (port 3200)
pnpm --filter @nimblebrain/mpak-registry dev

# Web UI (port 5173)
pnpm --filter @nimblebrain/mpak-web dev

# Docs site (port 4321)
pnpm --filter mpak-docs dev

验证注册表是否正在运行：

curl http://localhost:3200/health

使用Docker Compose运行

docker compose -f deploy/docker/docker-compose.yml up --build

运行测试

# All TypeScript tests
pnpm test

# Specific package
pnpm --filter @nimblebrain/mpak-schemas test
pnpm --filter @nimblebrain/mpak-sdk test
pnpm --filter @nimblebrain/mpak test       # CLI

# Python scanner tests
cd apps/scanner && uv sync --dev && uv run pytest

# Full verification (build + test + lint + typecheck)
pnpm build && pnpm test && pnpm lint && pnpm typecheck

构建

# Build all packages (respects dependency order via Turborepo)
pnpm build

# Build a specific package
pnpm --filter @nimblebrain/mpak-schemas build

# CLI smoke test after building
node packages/cli/dist/index.js --help

环境变量

每个应用程序都管理自己的 .env 文件。没有根 .env.

apps/registry/.env

看 apps/registry/.env.example 查看完整列表。关键变量：

apps/web/.env

看 apps/web/.env.example 查看完整列表。

部署

数据库迁移

直接运行Prisma迁移：

# Check migration status
cd apps/registry && DATABASE_URL="postgresql://..." npx prisma migrate status

# Run pending migrations
cd apps/registry && DATABASE_URL="postgresql://..." npx prisma migrate deploy

舵

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作业。扫描程序评估MTF控件，将详细结果写入S3，并通过回调URL将信任分数回传到注册表。

贡献

看 贡献.md 用于开发工作流、提交约定和代码风格指南。

许可证

Apache 2.0。看 许可证.