@nimblebrain/mpak 0.1.0 → 0.2.0

package/LICENSE

@@ -1,201 +1,13 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+Copyright 2026 NimbleBrain Inc.
 
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
-   1. Definitions.
+      http://www.apache.org/licenses/LICENSE-2.0
 
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2025 NimbleBrain, Inc.
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,13 +1,6 @@
-# mpak CLI
+# @nimblebrain/mpak
 
-[![CI](https://github.com/NimbleBrainInc/mpak-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/NimbleBrainInc/mpak-cli/actions/workflows/ci.yml)
-[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![npm](https://img.shields.io/npm/v/@nimblebrain/mpak)](https://www.npmjs.com/package/@nimblebrain/mpak)
-[![node](https://img.shields.io/node/v/@nimblebrain/mpak)](https://nodejs.org)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white)](https://www.nimblebrain.ai/discord?utm_source=github&utm_medium=readme&utm_campaign=mpak-cli&utm_content=discord-badge)
-
-CLI for MCP bundles and Agent Skills.
+CLI for downloading MCPB bundles and Agent Skills from the [mpak registry](https://mpak.dev).
 
 ## Installation
 
@@ -15,421 +8,95 @@ CLI for MCP bundles and Agent Skills.
 npm install -g @nimblebrain/mpak
 ```
 
-## Quick Start
-
-```bash
-# Search for everything (bundles + skills)
-mpak search postgres
-
-# Run an MCP server
-mpak run @owner/my-server
+## Usage
 
-# Search skills only
-mpak skill search strategy
+### Search
 
-# Install a skill
-mpak skill install @owner/my-skill
-```
-
-## Claude Code Integration
-
-Add any mpak bundle to Claude Code with a single command:
+Search across both bundles and skills:
 
 ```bash
-claude mcp add --transport stdio echo -- mpak run @nimblebraininc/echo
+mpak search <query>
+mpak search <query> --type bundle
+mpak search <query> --type skill
 ```
 
-For bundles requiring API keys:
+### Bundles
 
 ```bash
-# Set config once
-mpak config set @nimblebraininc/ipinfo api_key=your_token
+# Search bundles
+mpak bundle search <query>
 
-# Then add to Claude Code
-claude mcp add --transport stdio ipinfo -- mpak run @nimblebraininc/ipinfo
-```
+# Show bundle details
+mpak bundle show @scope/name
 
-## Commands
+# Download a bundle
+mpak bundle pull @scope/name
+mpak bundle pull @scope/name@1.0.0
 
-### Unified Search
-
-Search across both bundles and skills.
-
-```bash
-# Search everything
-mpak search postgres
-
-# Filter by type
-mpak search postgres --type bundle
-mpak search strategy --type skill
-
-# Sort and limit
-mpak search mcp --sort downloads --limit 10
+# Run an MCP server from the registry
+mpak run @scope/name
+mpak bundle run @scope/name --update
+mpak bundle run --local ./path/to/bundle.mcpb
 ```
 
-Options:
-- `--type <type>` - Filter by type (bundle, skill)
-- `--sort <field>` - Sort by: downloads, recent, name
-- `--limit <n>` - Limit results
-- `--offset <n>` - Pagination offset
-- `--json` - Output as JSON
-
-### Bundle Commands
-
-MCP bundle operations for discovering, downloading, and running MCP servers.
-
-| Command | Description |
-|---------|-------------|
-| `mpak bundle search <query>` | Search public bundles |
-| `mpak bundle show <package>` | Show bundle details with platforms |
-| `mpak bundle pull <package>` | Download a bundle |
-| `mpak bundle run <package>` | Run an MCP server from the registry |
-
-#### bundle search
-
-Search for bundles in the registry.
-
-```bash
-mpak bundle search echo
-mpak bundle search --type python echo
-mpak bundle search --sort downloads --limit 10 mcp
-```
-
-Options:
-- `--type <type>` - Filter by server type (node, python, binary)
-- `--sort <field>` - Sort by: downloads, recent, name (default: downloads)
-- `--limit <n>` - Limit results (default: 20)
-- `--offset <n>` - Pagination offset
-- `--json` - Output as JSON
-
-#### bundle show
-
-Display detailed information about a bundle.
+### Skills
 
 ```bash
-mpak bundle show @nimblebraininc/echo
-mpak bundle show @nimblebraininc/echo --json
-```
-
-Shows:
-- Bundle metadata (name, author, type, license)
-- Provenance info (if published via GitHub Actions OIDC)
-- Download stats
-- Available versions with platforms
-- Install instructions
+# Validate a skill directory
+mpak skill validate ./path/to/skill
 
-Options:
-- `--json` - Output as JSON
+# Pack a skill into a .skill bundle
+mpak skill pack ./path/to/skill
 
-#### bundle pull
-
-Download a bundle from the registry.
-
-```bash
-# Download latest version for current platform
-mpak bundle pull @nimblebraininc/echo
+# Search skills in the registry
+mpak skill search <query>
 
-# Download specific version
-mpak bundle pull @nimblebraininc/echo@1.0.0
-
-# Download for different platform (cross-compile use case)
-mpak bundle pull @nimblebraininc/echo --os linux --arch arm64
-
-# Custom output path
-mpak bundle pull @nimblebraininc/echo -o ./bundles/echo.mcpb
-```
-
-Options:
-- `-o, --output <path>` - Output file path
-- `--os <os>` - Target OS: darwin, linux, win32
-- `--arch <arch>` - Target architecture: x64, arm64
-- `--json` - Output download info as JSON (doesn't download)
-
-#### bundle run
-
-Run an MCP server directly from the registry. Bundles are cached locally for fast subsequent runs.
-
-```bash
-# Run latest version
-mpak bundle run @nimblebraininc/echo
-
-# Run specific version
-mpak bundle run @nimblebraininc/echo@1.0.0
-
-# Force re-download (update cache)
-mpak bundle run @nimblebraininc/echo --update
-```
-
-Options:
-- `--update` - Force re-download even if cached
-
-> **Tip:** Use `mpak run` as a shortcut for `mpak bundle run`.
-
-**Claude Code:**
-
-```bash
-claude mcp add --transport stdio echo -- mpak run @nimblebraininc/echo
-```
-
-**Claude Desktop:**
-
-```json
-{
-  "mcpServers": {
-    "echo": {
-      "command": "mpak",
-      "args": ["run", "@nimblebraininc/echo"]
-    }
-  }
-}
-```
-
-Bundles are cached in `~/.mpak/cache/` and automatically extracted on first run.
-
-### Skill Commands
-
-Agent skill operations for validating, packaging, and installing skills.
-
-| Command | Description |
-|---------|-------------|
-| `mpak skill validate <path>` | Validate a skill directory |
-| `mpak skill pack <path>` | Create a .skill bundle |
-| `mpak skill search <query>` | Search skills in the registry |
-| `mpak skill show <name>` | Show skill details |
-| `mpak skill pull <name>` | Download a .skill bundle |
-| `mpak skill install <name>` | Install to ~/.claude/skills/ |
-| `mpak skill list` | List installed skills |
-
-#### skill validate
-
-Validate a skill directory against the [Agent Skills specification](https://agentskills.io/specification).
-
-```bash
-mpak skill validate ./my-skill
-mpak skill validate ./my-skill --json
-```
+# Show skill details
+mpak skill show @scope/name
 
-Options:
-- `--json` - Output as JSON
+# Download a .skill bundle
+mpak skill pull @scope/name
 
-#### skill pack
+# Install a skill to ~/.claude/skills/
+mpak skill install @scope/name
 
-Create a `.skill` bundle from a skill directory.
-
-```bash
-mpak skill pack ./my-skill
-mpak skill pack ./my-skill -o ./dist/my-skill.skill
-```
-
-Options:
-- `-o, --output <path>` - Output file path
-- `--json` - Output as JSON
-
-#### skill search
-
-Search for skills in the registry.
-
-```bash
-mpak skill search strategy
-mpak skill search --category development docs
-mpak skill search --tags documentation,refactoring
-```
-
-Options:
-- `--tags <tags>` - Filter by tags (comma-separated)
-- `--category <category>` - Filter by category
-- `--surface <surface>` - Filter by surface (claude-code, claude-api, claude-ai)
-- `--sort <field>` - Sort by: downloads, recent, name
-- `--limit <n>` - Limit results
-- `--offset <n>` - Pagination offset
-- `--json` - Output as JSON
-
-#### skill show
-
-Display detailed information about a skill.
-
-```bash
-mpak skill show @nimblebraininc/docs-auditor
-mpak skill show @nimblebraininc/docs-auditor --json
-```
-
-Options:
-- `--json` - Output as JSON
-
-#### skill pull
-
-Download a skill bundle from the registry.
-
-```bash
-mpak skill pull @nimblebraininc/docs-auditor
-mpak skill pull @nimblebraininc/docs-auditor -o ./skills/
-```
-
-Options:
-- `-o, --output <path>` - Output file path
-- `--json` - Output as JSON
-
-#### skill install
-
-Download and install a skill to `~/.claude/skills/`.
-
-```bash
-mpak skill install @nimblebraininc/docs-auditor
-mpak skill install @nimblebraininc/docs-auditor --force
-```
-
-Options:
-- `--force` - Overwrite existing installation
-- `--json` - Output as JSON
-
-#### skill list
-
-List installed skills.
-
-```bash
+# List installed skills
 mpak skill list
-mpak skill list --json
 ```
 
-Options:
-- `--json` - Output as JSON
-
-### Config Commands
-
-Manage per-package configuration values (e.g., API keys).
-
-| Command | Description |
-|---------|-------------|
-| `mpak config set <pkg> <k=v...>` | Set config values |
-| `mpak config get <pkg>` | Show config (values masked) |
-| `mpak config list` | List packages with config |
-| `mpak config clear <pkg> [key]` | Clear config |
+### Configuration
 
 ```bash
-# Set API key for a package
-mpak config set @nimblebraininc/ipinfo api_key=your_token
+# Set config values for a package
+mpak config set @scope/name api_key=xxx
 
 # View stored config (values are masked)
-mpak config get @nimblebraininc/ipinfo
+mpak config get @scope/name
 
-# List all packages with stored config
+# List packages with config
 mpak config list
 
 # Clear config
-mpak config clear @nimblebraininc/ipinfo
-mpak config clear @nimblebraininc/ipinfo api_key  # Clear specific key
+mpak config clear @scope/name
+mpak config clear @scope/name api_key
 ```
 
-## Configuration
-
-Configuration is stored in `~/.mpak/config.json`:
-
-```json
-{
-  "version": "1.0.0",
-  "lastUpdated": "2025-12-30T...",
-  "registryUrl": "https://api.mpak.dev"
-}
-```
-
-### Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `MPAK_REGISTRY_URL` | Registry API URL | `https://api.mpak.dev` |
-
-## API
-
-The CLI uses the public v1 API:
-
-| Endpoint | Description |
-|----------|-------------|
-| `GET /v1/bundles/search` | Search bundles |
-| `GET /v1/bundles/@{scope}/{pkg}` | Get bundle details |
-| `GET /v1/bundles/@{scope}/{pkg}/versions` | List versions with platforms |
-| `GET /v1/bundles/@{scope}/{pkg}/versions/{version}/download` | Get download URL |
-| `GET /v1/skills/search` | Search skills |
-| `GET /v1/skills/@{scope}/{name}` | Get skill details |
-| `GET /v1/skills/@{scope}/{name}/download` | Get skill download URL |
-
 ## Development
 
-### Setup
-
-```bash
-npm install
-npm run build
-```
-
-### Scripts
-
-| Script | Description |
-|--------|-------------|
-| `npm run build` | Build TypeScript to JavaScript |
-| `npm run dev` | Run CLI in development mode |
-| `npm run typecheck` | Type check without building |
-| `npm run generate:types` | Generate types from OpenAPI spec |
-| `npm test` | Run unit tests |
-| `npm run test:all` | Run all tests including integration |
-| `npm run lint` | Lint source code |
-
-### Publishing
-
 ```bash
-# Stable release
-npm publish
-
-# Beta/prerelease
-npm publish --tag beta
-```
+# Build
+pnpm build
 
-### Local Testing
+# Run tests
+pnpm test
 
-1. Start the server locally:
-   ```bash
-   cd ../mpak/server
-   npm run dev
-   ```
+# Type checking
+pnpm typecheck
 
-2. Run CLI with local registry:
-   ```bash
-   MPAK_REGISTRY_URL=http://localhost:3200 npm run dev -- bundle search echo
-   ```
-
-### Project Structure
-
-```
-src/
-├── index.ts                    # Entry point
-├── program.ts                  # Commander program setup
-├── commands/
-│   ├── packages/               # Bundle commands
-│   │   ├── search.ts
-│   │   ├── show.ts
-│   │   ├── pull.ts
-│   │   └── run.ts
-│   ├── skills/                 # Skill commands
-│   │   ├── validate.ts
-│   │   ├── pack.ts
-│   │   ├── search.ts
-│   │   ├── show.ts
-│   │   ├── pull.ts
-│   │   ├── install.ts
-│   │   └── list.ts
-│   └── config.ts               # Config commands
-├── lib/
-│   └── api/
-│       ├── registry-client.ts  # Bundle API client
-│       ├── skills-client.ts    # Skills API client
-│       └── schema.d.ts         # Generated OpenAPI types
-├── schemas/
-│   └── generated/
-│       └── skill.ts            # Skill validation schemas
-└── utils/
-    ├── config-manager.ts       # Config file handling
-    └── version.ts              # Version helper
+# Lint
+pnpm lint
 ```
 
 ## License
 
-[Apache 2.0](LICENSE)
+Apache-2.0