@nimblebrain/mpak 0.0.1 → 0.0.2

package/.claude/settings.local.json

@@ -11,7 +11,9 @@
       "Bash(npm publish:*)",
       "Bash(git push)",
       "Bash(git tag:*)",
-      "Bash(git push:*)"
+      "Bash(git push:*)",
+      "Bash(gh pr create:*)",
+      "Bash(ls:*)"
     ]
   }
 }

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # mpak CLI
 
-CLI for discovering and downloading MCPB bundles from the mpak registry.
+CLI for MCP bundles and Agent Skills.
 
 ## Architecture
 
@@ -11,15 +11,24 @@ This is a standalone CLI that uses only the public v1 API. It has no dependencie
 | File | Purpose |
 |------|---------|
 | `src/program.ts` | Commander program setup with all commands |
-| `src/lib/api/registry-client.ts` | API client for v1 endpoints |
+| `src/lib/api/registry-client.ts` | API client for bundle endpoints |
+| `src/lib/api/skills-client.ts` | API client for skill endpoints |
 | `src/lib/api/schema.d.ts` | Generated types from OpenAPI spec |
-| `src/commands/packages/search.ts` | Search command implementation |
-| `src/commands/packages/show.ts` | Show/info command implementation |
-| `src/commands/packages/pull.ts` | Pull/install command implementation |
-| `src/commands/packages/run.ts` | Run command implementation (caching, extraction, execution, user_config substitution) |
+| `src/commands/packages/*.ts` | Bundle commands (search, show, pull, run) |
+| `src/commands/skills/*.ts` | Skill commands (validate, pack, search, show, pull, install, list) |
 | `src/commands/config.ts` | Config commands (set, get, list, clear) |
+| `src/schemas/generated/skill.ts` | Skill validation schemas (Zod) |
 | `src/utils/config-manager.ts` | Config file handling (~/.mpak/config.json) |
 
+### Command Structure
+
+```
+mpak search <query>     # Unified search (bundles + skills)
+mpak bundle <command>   # MCP bundle operations
+mpak skill <command>    # Agent skill operations
+mpak config <command>   # Configuration management
+```
+
 ### Type Generation
 
 Types are generated from the server's OpenAPI spec using `openapi-typescript`:
@@ -44,7 +53,7 @@ export type Bundle = BundleSearchResponse['bundles'][number];
 
 ## v1 API Endpoints
 
-The CLI uses these public endpoints:
+### Bundle Endpoints
 
 | Endpoint | Description |
 |----------|-------------|
@@ -52,9 +61,18 @@ The CLI uses these public endpoints:
 | `GET /v1/bundles/@{scope}/{package}` | Get bundle details (metadata, readme) |
 | `GET /v1/bundles/@{scope}/{package}/versions` | List versions with platform availability |
 | `GET /v1/bundles/@{scope}/{package}/versions/{version}/download` | Get download URL for specific version/platform |
-| `GET /v1/bundles/@{scope}/{package}/versions/latest/download` | Get download URL for latest version |
 
-### Platform Selection
+### Skill Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /v1/skills/search` | Search skills by query, tags, category |
+| `GET /v1/skills/@{scope}/{name}` | Get skill details |
+| `GET /v1/skills/@{scope}/{name}/download` | Get download URL for latest version |
+| `GET /v1/skills/@{scope}/{name}/versions/{version}/download` | Get download URL for specific version |
+| `POST /v1/skills/announce` | Announce skill version (OIDC auth) |
+
+### Platform Selection (Bundles)
 
 Download endpoints accept `os` and `arch` query parameters:
 - `os`: darwin, linux, win32, any
@@ -80,12 +98,12 @@ npm run build
 The CLI defaults to `https://api.mpak.dev`. For local development:
 
 ```bash
-# Start the server (from ../server)
-cd ../server && npm run dev
+# Start the server (from ../mpak/server)
+cd ../mpak/server && npm run dev
 
 # Run CLI commands with local registry
-MPAK_REGISTRY_URL=http://localhost:3200 npm run dev -- search echo
-MPAK_REGISTRY_URL=http://localhost:3200 node dist/index.js pull @nimblebraininc/echo
+MPAK_REGISTRY_URL=http://localhost:3200 npm run dev -- bundle search echo
+MPAK_REGISTRY_URL=http://localhost:3200 node dist/index.js skill search strategy
 ```
 
 ### Verification
@@ -114,20 +132,45 @@ npm publish --otp=<code>
 git push && git push --tags
 ```
 
-## Commands (MVP)
+## Commands
+
+### Unified Search
 
 | Command | Description |
 |---------|-------------|
-| `search <query>` | Search public bundles |
-| `show <package>` | Show bundle details with platforms |
-| `info <package>` | Alias for show |
-| `pull <package>` | Download a bundle |
-| `install <package>` | Alias for pull |
-| `run <package>` | Run an MCP server (pulls, caches, executes) |
-| `config set <pkg> <k=v...>` | Store config values for a package |
-| `config get <pkg>` | Show stored config (values masked) |
-| `config list` | List packages with stored config |
-| `config clear <pkg> [key]` | Clear stored config |
+| `mpak search <query>` | Search bundles and skills |
+| `mpak search <query> --type bundle` | Search bundles only |
+| `mpak search <query> --type skill` | Search skills only |
+
+### Bundle Commands
+
+| 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 (pulls, caches, executes) |
+
+### Skill Commands
+
+| Command | Description |
+|---------|-------------|
+| `mpak skill validate <path>` | Validate skill directory against Agent Skills spec |
+| `mpak skill pack <path>` | Create a .skill bundle |
+| `mpak skill search <query>` | Search skills in 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 |
+
+### Config Commands
+
+| Command | Description |
+|---------|-------------|
+| `mpak config set <pkg> <k=v...>` | Store config values for a package |
+| `mpak config get <pkg>` | Show stored config (values masked) |
+| `mpak config list` | List packages with stored config |
+| `mpak config clear <pkg> [key]` | Clear stored config |
 
 ## User Config (MCPB v0.3)
 
@@ -153,7 +196,7 @@ Packages can declare `user_config` in their manifest for values like API keys:
 }
 ```
 
-When `mpak run` executes, it substitutes `${user_config.*}` placeholders with actual values.
+When `mpak bundle run` executes, it substitutes `${user_config.*}` placeholders with actual values.
 
 ### Two Ways to Provide Config
 
@@ -166,7 +209,7 @@ Use `mpak config set` with keys matching the manifest's `user_config` field name
 mpak config set @nimblebraininc/ipinfo api_key=your_token
 
 # Run uses stored config automatically
-mpak run @nimblebraininc/ipinfo
+mpak bundle run @nimblebraininc/ipinfo
 
 # View stored config (values masked)
 mpak config get @nimblebraininc/ipinfo
@@ -181,7 +224,7 @@ Set the actual environment variable directly in your Claude Desktop config:
   "mcpServers": {
     "ipinfo": {
       "command": "mpak",
-      "args": ["run", "@nimblebraininc/ipinfo"],
+      "args": ["bundle", "run", "@nimblebraininc/ipinfo"],
       "env": {
         "IPINFO_API_TOKEN": "your_token"
       }
@@ -214,9 +257,10 @@ manifest.user_config.api_key  →  mpak config set ... api_key=xxx  →  env IPI
 ## Design Decisions
 
 1. **Standalone**: No shared dependencies with server/client. Types generated from OpenAPI.
-2. **Public API only**: MVP uses only v1 API. Publishing requires separate tooling.
+2. **Public API only**: Uses v1 API. Publishing requires OIDC via GitHub Actions.
 3. **Platform detection**: Auto-detects OS/arch, allows explicit override for cross-platform downloads.
 4. **Config file**: Stores registry URL in `~/.mpak/config.json`, overridable via `MPAK_REGISTRY_URL`.
+5. **Skill schemas**: Uses Zod schemas in `src/schemas/generated/skill.ts` for validation.
 
 ## Gotchas
 
@@ -224,9 +268,4 @@ manifest.user_config.api_key  →  mpak config set ... api_key=xxx  →  env IPI
 - **Type generation**: Requires server running locally (`npm run generate:types` hits localhost:3200)
 - **Schema changes**: May introduce breaking type changes; always run full verification after regenerating
 - **Env merge order**: Use `{ ...substitutedEnv, ...process.env }` so parent env vars (Claude Desktop) take priority over manifest substitutions
-
-## Future Considerations
-
-- The CLI will be broken out into a completely standalone repository
-- Authentication commands (login, publish) may be added when needed
-- Consider adding `npx` support for zero-install usage
+- **Skill endpoints**: Currently implemented in server code but may not be deployed to production yet

package/README.md

@@ -7,7 +7,7 @@
 [![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 discovering and downloading MCPB bundles from the mpak registry.
+CLI for MCP bundles and Agent Skills.
 
 ## Installation
 
@@ -18,36 +18,66 @@ npm install -g @nimblebrain/mpak
 ## Quick Start
 
 ```bash
-# Search for bundles
+# Search for everything (bundles + skills)
 mpak search postgres
 
-# Show bundle details
-mpak show @owner/my-server
+# Search bundles only
+mpak bundle search postgres
 
-# Download a bundle
-mpak pull @owner/my-server
-mpak pull @owner/my-server@1.0.0  # specific version
+# Run an MCP server
+mpak bundle run @owner/my-server
+
+# Search skills only
+mpak skill search strategy
+
+# Install a skill
+mpak skill install @owner/my-skill
 ```
 
 ## Commands
 
+### 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
+```
+
+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 |
 |---------|-------------|
-| `search <query>` | Search public bundles |
-| `show <package>` | Show bundle details with platforms |
-| `info <package>` | Alias for show |
-| `pull <package>` | Download a bundle |
-| `install <package>` | Alias for pull |
-| `run <package>` | Run an MCP server from the registry |
+| `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 |
 
-### search
+#### bundle search
 
 Search for bundles in the registry.
 
 ```bash
-mpak search echo
-mpak search --type python echo
-mpak search --sort downloads --limit 10 mcp
+mpak bundle search echo
+mpak bundle search --type python echo
+mpak bundle search --sort downloads --limit 10 mcp
 ```
 
 Options:
@@ -57,13 +87,13 @@ Options:
 - `--offset <n>` - Pagination offset
 - `--json` - Output as JSON
 
-### show / info
+#### bundle show
 
 Display detailed information about a bundle.
 
 ```bash
-mpak show @nimblebraininc/echo
-mpak show @nimblebraininc/echo --json
+mpak bundle show @nimblebraininc/echo
+mpak bundle show @nimblebraininc/echo --json
 ```
 
 Shows:
@@ -76,22 +106,22 @@ Shows:
 Options:
 - `--json` - Output as JSON
 
-### pull / install
+#### bundle pull
 
 Download a bundle from the registry.
 
 ```bash
 # Download latest version for current platform
-mpak pull @nimblebraininc/echo
+mpak bundle pull @nimblebraininc/echo
 
 # Download specific version
-mpak pull @nimblebraininc/echo@1.0.0
+mpak bundle pull @nimblebraininc/echo@1.0.0
 
 # Download for different platform (cross-compile use case)
-mpak pull @nimblebraininc/echo --os linux --arch arm64
+mpak bundle pull @nimblebraininc/echo --os linux --arch arm64
 
 # Custom output path
-mpak pull @nimblebraininc/echo -o ./bundles/echo.mcpb
+mpak bundle pull @nimblebraininc/echo -o ./bundles/echo.mcpb
 ```
 
 Options:
@@ -100,19 +130,19 @@ Options:
 - `--arch <arch>` - Target architecture: x64, arm64
 - `--json` - Output download info as JSON (doesn't download)
 
-### run
+#### bundle run
 
 Run an MCP server directly from the registry. Bundles are cached locally for fast subsequent runs.
 
 ```bash
 # Run latest version
-mpak run @nimblebraininc/echo
+mpak bundle run @nimblebraininc/echo
 
 # Run specific version
-mpak run @nimblebraininc/echo@1.0.0
+mpak bundle run @nimblebraininc/echo@1.0.0
 
 # Force re-download (update cache)
-mpak run @nimblebraininc/echo --update
+mpak bundle run @nimblebraininc/echo --update
 ```
 
 Options:
@@ -125,7 +155,7 @@ Options:
   "mcpServers": {
     "echo": {
       "command": "mpak",
-      "args": ["run", "@nimblebraininc/echo"]
+      "args": ["bundle", "run", "@nimblebraininc/echo"]
     }
   }
 }
@@ -133,6 +163,140 @@ Options:
 
 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
+```
+
+Options:
+- `--json` - Output as JSON
+
+#### skill pack
+
+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
+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 |
+
+```bash
+# Set API key for a package
+mpak config set @nimblebraininc/ipinfo api_key=your_token
+
+# View stored config (values are masked)
+mpak config get @nimblebraininc/ipinfo
+
+# List all packages with stored config
+mpak config list
+
+# Clear config
+mpak config clear @nimblebraininc/ipinfo
+mpak config clear @nimblebraininc/ipinfo api_key  # Clear specific key
+```
+
 ## Configuration
 
 Configuration is stored in `~/.mpak/config.json`:
@@ -161,14 +325,17 @@ The CLI uses the public v1 API:
 | `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
-cd apps/mpak/cli
 npm install
+npm run build
 ```
 
 ### Scripts
@@ -179,7 +346,8 @@ npm install
 | `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 tests |
+| `npm test` | Run unit tests |
+| `npm run test:all` | Run all tests including integration |
 | `npm run lint` | Lint source code |
 
 ### Publishing
@@ -188,7 +356,7 @@ npm install
 # Stable release
 npm publish
 
-# Beta/prerelease (required for versions like 0.0.1-beta.1)
+# Beta/prerelease
 npm publish --tag beta
 ```
 
@@ -196,32 +364,15 @@ npm publish --tag beta
 
 1. Start the server locally:
    ```bash
-   cd ../server
+   cd ../mpak/server
    npm run dev
    ```
 
 2. Run CLI with local registry:
    ```bash
-   MPAK_REGISTRY_URL=http://localhost:3200 npm run dev -- search echo
-   ```
-
-3. Or build and test:
-   ```bash
-   npm run build
-   MPAK_REGISTRY_URL=http://localhost:3200 node dist/index.js search echo
+   MPAK_REGISTRY_URL=http://localhost:3200 npm run dev -- bundle search echo
    ```
 
-### Type Generation
-
-Types are generated from the server's OpenAPI spec:
-
-```bash
-# Requires server running locally
-npm run generate:types
-```
-
-This generates `src/lib/api/schema.d.ts` from `http://localhost:3200/documentation/json`.
-
 ### Project Structure
 
 ```
@@ -229,14 +380,28 @@ src/
 ├── index.ts                    # Entry point
 ├── program.ts                  # Commander program setup
 ├── commands/
-│   └── packages/
-│       ├── search.ts           # Search command
-│       ├── show.ts             # Show/info command
-│       └── pull.ts             # Pull/install command
+│   ├── 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  # API client
+│       ├── 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

package/dist/commands/search.d.ts

@@ -0,0 +1,12 @@
+export interface UnifiedSearchOptions {
+    type?: 'bundle' | 'skill';
+    sort?: 'downloads' | 'recent' | 'name';
+    limit?: number;
+    offset?: number;
+    json?: boolean;
+}
+/**
+ * Unified search across bundles and skills
+ */
+export declare function handleUnifiedSearch(query: string, options?: UnifiedSearchOptions): Promise<void>;
+//# sourceMappingURL=search.d.ts.map

package/dist/commands/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/commands/search.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAiBD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CA8Jf"}