@mpakmcp/cli

mpak cli

CLI for publishing MCPB bundles to the mpak package directory.

Installation

npm install -g @mpak/cli

Usage

mpak --help
mpak --version

Authentication

Authenticate with the mpak registry using OAuth:

mpak auth login

Options:

• -p, --port <port> - Port for local OAuth callback server (default: 41248)
• -t, --timeout <ms> - OAuth timeout in milliseconds (default: 300000)
• -f, --force - Force re-authentication even if already logged in
• -v, --verbose - Enable verbose logging

The authentication flow will:

• Open your browser for Clerk OAuth authentication
• Start a local server to receive the OAuth callback
• Fetch your user information from Clerk
• Store the credentials in ~/.mpak/config.json

Development

Setup

npm install

Available Scripts

• npm run dev - Run CLI in development mode with tsx
• npm run build - Build TypeScript to JavaScript
• npm test - Run unit tests
• npm run test:ui - Run tests with UI
• npm run test:coverage - Run tests with coverage report
• npm run typecheck - Type check without building
• npm run lint - Lint source code
• npm run lint:fix - Fix linting errors

Publishing

Pre-release versions (alpha, beta, rc) must be published with a distribution tag:

npm publish --tag beta

Stable releases use the default latest tag:

npm publish

Testing

# Run tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run tests with coverage
npm run test:coverage

Project Structure

src/
├── index.ts                  # CLI entry point
├── program.ts                # Commander program configuration
├── commands/
│   └── auth/
│       └── login.ts          # OAuth login flow
├── lib/
│   └── auth/
│       ├── clerk-oauth-client.ts   # Clerk OAuth 2.0 + PKCE
│       ├── local-server.ts         # Local OAuth callback server
│       └── token-manager.ts        # Auth session management
├── utils/
│   ├── config-manager.ts     # Config file management
│   ├── config.ts             # Config singleton
│   ├── errors.ts             # Error handling utilities
│   └── version.ts            # Version helper
└── types/
    └── auth.ts               # Authentication type definitions

Architecture

Tech Stack

• TypeScript: Type-safe code
• Commander: CLI framework
• Vitest: Fast unit testing
• Express: Local OAuth callback server
• Clerk: OAuth authentication provider
• ESM: Modern module system

Configuration

Configuration is stored in ~/.mpak/config.json with the following structure:

{
  "version": "1.0.0",
  "lastUpdated": "2025-10-19T...",
  "registryUrl": "http://localhost:3000",
  "auth": {
    "bearerToken": "...",
    "expiresAt": 1234567890,
    "user": {
      "id": "user_...",
      "email": "[e-mail]",
      "firstName": "John",
      "lastName": "Doe"
    }
  }
}

Environment Variables

• CLERK_OAUTH_CLIENT_ID - Clerk OAuth client ID (default: 96WRYcxabFktp9wn)
• CLERK_OAUTH_DOMAIN - Clerk OAuth domain (default: clerk.nimblebrain.ai)
• MPAK_DEFAULT_PORT - Default OAuth callback port (default: 41248)
• MPAK_OAUTH_TIMEOUT - OAuth timeout in ms (default: 300000)

Commands

Implemented

Authentication

• ✅ mpak login or mpak auth login - Authenticate with OAuth
  • Options: --port, --timeout, --force, --verbose
• ✅ mpak whoami - Display current authenticated user
  • Shows email, user ID, name, and token expiration

Package Management

• ✅ mpak publish <file> - Publish an MCPB bundle

  • Options: --dry-run
  • Uploads .mcpb file to registry
  • Validates package format and metadata
  • Returns download URL and package info

• ✅ mpak list or mpak packages - List your published packages

  • Options: --json, --limit, --offset, --sort
  • Shows packages owned by you
  • Displays download stats, tools, and verification status

• ✅ mpak search <query> - Search public packages

  • Options: --type, --sort, --limit, --offset, --json
  • Search by name, description, or keywords
  • Filter by server type (node, python, binary)
  • Sort by downloads, recent, or name

• ✅ mpak show <package> or mpak info <package> - Show package details

  • Options: --json
  • Displays full package information
  • Shows versions, tools, downloads, GitHub stats
  • Includes claiming and verification status

• ✅ mpak pull <package> or mpak install <package> - Download a package

  • Options: --output <path>, --json
  • Download latest: mpak pull @scope/package
  • Download specific version: mpak pull @scope/package@1.0.0
  • Saves to current directory as scope-package-version.mcpb
  • Use --output to specify custom file path

Future Commands

• mpak logout - Clear authentication

License

Apache 2.0