@nimblebrain/mpak 0.0.1 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/.claude/settings.local.json +3 -1
  2. package/CLAUDE.md +85 -34
  3. package/README.md +245 -57
  4. package/dist/commands/packages/run.d.ts +12 -1
  5. package/dist/commands/packages/run.d.ts.map +1 -1
  6. package/dist/commands/packages/run.js +116 -45
  7. package/dist/commands/packages/run.js.map +1 -1
  8. package/dist/commands/search.d.ts +12 -0
  9. package/dist/commands/search.d.ts.map +1 -0
  10. package/dist/commands/search.js +144 -0
  11. package/dist/commands/search.js.map +1 -0
  12. package/dist/commands/skills/index.d.ts +8 -0
  13. package/dist/commands/skills/index.d.ts.map +1 -0
  14. package/dist/commands/skills/index.js +8 -0
  15. package/dist/commands/skills/index.js.map +1 -0
  16. package/dist/commands/skills/install.d.ts +9 -0
  17. package/dist/commands/skills/install.d.ts.map +1 -0
  18. package/dist/commands/skills/install.js +110 -0
  19. package/dist/commands/skills/install.js.map +1 -0
  20. package/dist/commands/skills/list.d.ts +8 -0
  21. package/dist/commands/skills/list.d.ts.map +1 -0
  22. package/dist/commands/skills/list.js +89 -0
  23. package/dist/commands/skills/list.js.map +1 -0
  24. package/dist/commands/skills/pack.d.ts +22 -0
  25. package/dist/commands/skills/pack.d.ts.map +1 -0
  26. package/dist/commands/skills/pack.js +116 -0
  27. package/dist/commands/skills/pack.js.map +1 -0
  28. package/dist/commands/skills/pull.d.ts +9 -0
  29. package/dist/commands/skills/pull.d.ts.map +1 -0
  30. package/dist/commands/skills/pull.js +68 -0
  31. package/dist/commands/skills/pull.js.map +1 -0
  32. package/dist/commands/skills/search.d.ts +14 -0
  33. package/dist/commands/skills/search.d.ts.map +1 -0
  34. package/dist/commands/skills/search.js +53 -0
  35. package/dist/commands/skills/search.js.map +1 -0
  36. package/dist/commands/skills/show.d.ts +8 -0
  37. package/dist/commands/skills/show.d.ts.map +1 -0
  38. package/dist/commands/skills/show.js +64 -0
  39. package/dist/commands/skills/show.js.map +1 -0
  40. package/dist/commands/skills/validate.d.ts +25 -0
  41. package/dist/commands/skills/validate.d.ts.map +1 -0
  42. package/dist/commands/skills/validate.js +191 -0
  43. package/dist/commands/skills/validate.js.map +1 -0
  44. package/dist/index.js +0 -0
  45. package/dist/lib/api/skills-client.d.ts +30 -0
  46. package/dist/lib/api/skills-client.d.ts.map +1 -0
  47. package/dist/lib/api/skills-client.js +110 -0
  48. package/dist/lib/api/skills-client.js.map +1 -0
  49. package/dist/program.d.ts +5 -1
  50. package/dist/program.d.ts.map +1 -1
  51. package/dist/program.js +112 -35
  52. package/dist/program.js.map +1 -1
  53. package/dist/schemas/generated/api-responses.d.ts +541 -0
  54. package/dist/schemas/generated/api-responses.d.ts.map +1 -0
  55. package/dist/schemas/generated/api-responses.js +313 -0
  56. package/dist/schemas/generated/api-responses.js.map +1 -0
  57. package/dist/schemas/generated/auth.d.ts +18 -0
  58. package/dist/schemas/generated/auth.d.ts.map +1 -0
  59. package/dist/schemas/generated/auth.js +18 -0
  60. package/dist/schemas/generated/auth.js.map +1 -0
  61. package/dist/schemas/generated/index.d.ts +5 -0
  62. package/dist/schemas/generated/index.d.ts.map +1 -0
  63. package/dist/schemas/generated/index.js +6 -0
  64. package/dist/schemas/generated/index.js.map +1 -0
  65. package/dist/schemas/generated/package.d.ts +43 -0
  66. package/dist/schemas/generated/package.d.ts.map +1 -0
  67. package/dist/schemas/generated/package.js +20 -0
  68. package/dist/schemas/generated/package.js.map +1 -0
  69. package/dist/schemas/generated/skill.d.ts +381 -0
  70. package/dist/schemas/generated/skill.d.ts.map +1 -0
  71. package/dist/schemas/generated/skill.js +216 -0
  72. package/dist/schemas/generated/skill.js.map +1 -0
  73. package/dist/utils/config-manager.d.ts +13 -1
  74. package/dist/utils/config-manager.d.ts.map +1 -1
  75. package/dist/utils/config-manager.js +76 -11
  76. package/dist/utils/config-manager.js.map +1 -1
  77. package/package.json +6 -2
  78. package/src/commands/packages/run.test.ts +40 -1
  79. package/src/commands/packages/run.ts +131 -46
  80. package/src/commands/search.ts +191 -0
  81. package/src/commands/skills/index.ts +7 -0
  82. package/src/commands/skills/install.ts +129 -0
  83. package/src/commands/skills/list.ts +116 -0
  84. package/src/commands/skills/pack.test.ts +260 -0
  85. package/src/commands/skills/pack.ts +145 -0
  86. package/src/commands/skills/pull.ts +88 -0
  87. package/src/commands/skills/search.ts +73 -0
  88. package/src/commands/skills/show.ts +72 -0
  89. package/src/commands/skills/validate.test.ts +466 -0
  90. package/src/commands/skills/validate.ts +227 -0
  91. package/src/lib/api/skills-client.ts +148 -0
  92. package/src/program.test.ts +1 -3
  93. package/src/program.ts +140 -36
  94. package/src/schemas/config.v1.schema.json +37 -0
  95. package/src/schemas/generated/api-responses.ts +386 -0
  96. package/src/schemas/generated/auth.ts +21 -0
  97. package/src/schemas/generated/index.ts +5 -0
  98. package/src/schemas/generated/package.ts +29 -0
  99. package/src/schemas/generated/skill.ts +271 -0
  100. package/src/utils/config-manager.test.ts +182 -2
  101. package/src/utils/config-manager.ts +126 -12
@@ -11,7 +11,9 @@
11
11
  "Bash(npm publish:*)",
12
12
  "Bash(git push)",
13
13
  "Bash(git tag:*)",
14
- "Bash(git push:*)"
14
+ "Bash(git push:*)",
15
+ "Bash(gh pr create:*)",
16
+ "Bash(ls:*)"
15
17
  ]
16
18
  }
17
19
  }
package/CLAUDE.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # mpak CLI
2
2
 
3
- CLI for discovering and downloading MCPB bundles from the mpak registry.
3
+ CLI for MCP bundles and Agent Skills.
4
4
 
5
5
  ## Architecture
6
6
 
@@ -11,15 +11,24 @@ This is a standalone CLI that uses only the public v1 API. It has no dependencie
11
11
  | File | Purpose |
12
12
  |------|---------|
13
13
  | `src/program.ts` | Commander program setup with all commands |
14
- | `src/lib/api/registry-client.ts` | API client for v1 endpoints |
14
+ | `src/lib/api/registry-client.ts` | API client for bundle endpoints |
15
+ | `src/lib/api/skills-client.ts` | API client for skill endpoints |
15
16
  | `src/lib/api/schema.d.ts` | Generated types from OpenAPI spec |
16
- | `src/commands/packages/search.ts` | Search command implementation |
17
- | `src/commands/packages/show.ts` | Show/info command implementation |
18
- | `src/commands/packages/pull.ts` | Pull/install command implementation |
19
- | `src/commands/packages/run.ts` | Run command implementation (caching, extraction, execution, user_config substitution) |
17
+ | `src/commands/packages/*.ts` | Bundle commands (search, show, pull, run) |
18
+ | `src/commands/skills/*.ts` | Skill commands (validate, pack, search, show, pull, install, list) |
20
19
  | `src/commands/config.ts` | Config commands (set, get, list, clear) |
20
+ | `src/schemas/generated/skill.ts` | Skill validation schemas (Zod) |
21
21
  | `src/utils/config-manager.ts` | Config file handling (~/.mpak/config.json) |
22
22
 
23
+ ### Command Structure
24
+
25
+ ```
26
+ mpak search <query> # Unified search (bundles + skills)
27
+ mpak bundle <command> # MCP bundle operations
28
+ mpak skill <command> # Agent skill operations
29
+ mpak config <command> # Configuration management
30
+ ```
31
+
23
32
  ### Type Generation
24
33
 
25
34
  Types are generated from the server's OpenAPI spec using `openapi-typescript`:
@@ -44,7 +53,7 @@ export type Bundle = BundleSearchResponse['bundles'][number];
44
53
 
45
54
  ## v1 API Endpoints
46
55
 
47
- The CLI uses these public endpoints:
56
+ ### Bundle Endpoints
48
57
 
49
58
  | Endpoint | Description |
50
59
  |----------|-------------|
@@ -52,9 +61,18 @@ The CLI uses these public endpoints:
52
61
  | `GET /v1/bundles/@{scope}/{package}` | Get bundle details (metadata, readme) |
53
62
  | `GET /v1/bundles/@{scope}/{package}/versions` | List versions with platform availability |
54
63
  | `GET /v1/bundles/@{scope}/{package}/versions/{version}/download` | Get download URL for specific version/platform |
55
- | `GET /v1/bundles/@{scope}/{package}/versions/latest/download` | Get download URL for latest version |
56
64
 
57
- ### Platform Selection
65
+ ### Skill Endpoints
66
+
67
+ | Endpoint | Description |
68
+ |----------|-------------|
69
+ | `GET /v1/skills/search` | Search skills by query, tags, category |
70
+ | `GET /v1/skills/@{scope}/{name}` | Get skill details |
71
+ | `GET /v1/skills/@{scope}/{name}/download` | Get download URL for latest version |
72
+ | `GET /v1/skills/@{scope}/{name}/versions/{version}/download` | Get download URL for specific version |
73
+ | `POST /v1/skills/announce` | Announce skill version (OIDC auth) |
74
+
75
+ ### Platform Selection (Bundles)
58
76
 
59
77
  Download endpoints accept `os` and `arch` query parameters:
60
78
  - `os`: darwin, linux, win32, any
@@ -80,12 +98,12 @@ npm run build
80
98
  The CLI defaults to `https://api.mpak.dev`. For local development:
81
99
 
82
100
  ```bash
83
- # Start the server (from ../server)
84
- cd ../server && npm run dev
101
+ # Start the server (from ../mpak/server)
102
+ cd ../mpak/server && npm run dev
85
103
 
86
104
  # Run CLI commands with local registry
87
- MPAK_REGISTRY_URL=http://localhost:3200 npm run dev -- search echo
88
- MPAK_REGISTRY_URL=http://localhost:3200 node dist/index.js pull @nimblebraininc/echo
105
+ MPAK_REGISTRY_URL=http://localhost:3200 npm run dev -- bundle search echo
106
+ MPAK_REGISTRY_URL=http://localhost:3200 node dist/index.js skill search strategy
89
107
  ```
90
108
 
91
109
  ### Verification
@@ -114,20 +132,57 @@ npm publish --otp=<code>
114
132
  git push && git push --tags
115
133
  ```
116
134
 
117
- ## Commands (MVP)
135
+ ## Commands
136
+
137
+ ### Unified Search
138
+
139
+ | Command | Description |
140
+ |---------|-------------|
141
+ | `mpak search <query>` | Search bundles and skills |
142
+ | `mpak search <query> --type bundle` | Search bundles only |
143
+ | `mpak search <query> --type skill` | Search skills only |
144
+
145
+ ### Run (Top-Level Alias)
118
146
 
119
147
  | Command | Description |
120
148
  |---------|-------------|
121
- | `search <query>` | Search public bundles |
122
- | `show <package>` | Show bundle details with platforms |
123
- | `info <package>` | Alias for show |
124
- | `pull <package>` | Download a bundle |
125
- | `install <package>` | Alias for pull |
126
- | `run <package>` | Run an MCP server (pulls, caches, executes) |
127
- | `config set <pkg> <k=v...>` | Store config values for a package |
128
- | `config get <pkg>` | Show stored config (values masked) |
129
- | `config list` | List packages with stored config |
130
- | `config clear <pkg> [key]` | Clear stored config |
149
+ | `mpak run <package>` | Run an MCP server (alias for `bundle run`) |
150
+
151
+ This is the recommended way to integrate with Claude Code:
152
+
153
+ ```bash
154
+ claude mcp add --transport stdio echo -- mpak run @nimblebraininc/echo
155
+ ```
156
+
157
+ ### Bundle Commands
158
+
159
+ | Command | Description |
160
+ |---------|-------------|
161
+ | `mpak bundle search <query>` | Search public bundles |
162
+ | `mpak bundle show <package>` | Show bundle details with platforms |
163
+ | `mpak bundle pull <package>` | Download a bundle |
164
+ | `mpak bundle run <package>` | Run an MCP server (pulls, caches, executes) |
165
+
166
+ ### Skill Commands
167
+
168
+ | Command | Description |
169
+ |---------|-------------|
170
+ | `mpak skill validate <path>` | Validate skill directory against Agent Skills spec |
171
+ | `mpak skill pack <path>` | Create a .skill bundle |
172
+ | `mpak skill search <query>` | Search skills in registry |
173
+ | `mpak skill show <name>` | Show skill details |
174
+ | `mpak skill pull <name>` | Download a .skill bundle |
175
+ | `mpak skill install <name>` | Install to ~/.claude/skills/ |
176
+ | `mpak skill list` | List installed skills |
177
+
178
+ ### Config Commands
179
+
180
+ | Command | Description |
181
+ |---------|-------------|
182
+ | `mpak config set <pkg> <k=v...>` | Store config values for a package |
183
+ | `mpak config get <pkg>` | Show stored config (values masked) |
184
+ | `mpak config list` | List packages with stored config |
185
+ | `mpak config clear <pkg> [key]` | Clear stored config |
131
186
 
132
187
  ## User Config (MCPB v0.3)
133
188
 
@@ -153,7 +208,7 @@ Packages can declare `user_config` in their manifest for values like API keys:
153
208
  }
154
209
  ```
155
210
 
156
- When `mpak run` executes, it substitutes `${user_config.*}` placeholders with actual values.
211
+ When `mpak bundle run` executes, it substitutes `${user_config.*}` placeholders with actual values.
157
212
 
158
213
  ### Two Ways to Provide Config
159
214
 
@@ -166,7 +221,7 @@ Use `mpak config set` with keys matching the manifest's `user_config` field name
166
221
  mpak config set @nimblebraininc/ipinfo api_key=your_token
167
222
 
168
223
  # Run uses stored config automatically
169
- mpak run @nimblebraininc/ipinfo
224
+ mpak bundle run @nimblebraininc/ipinfo
170
225
 
171
226
  # View stored config (values masked)
172
227
  mpak config get @nimblebraininc/ipinfo
@@ -181,7 +236,7 @@ Set the actual environment variable directly in your Claude Desktop config:
181
236
  "mcpServers": {
182
237
  "ipinfo": {
183
238
  "command": "mpak",
184
- "args": ["run", "@nimblebraininc/ipinfo"],
239
+ "args": ["bundle", "run", "@nimblebraininc/ipinfo"],
185
240
  "env": {
186
241
  "IPINFO_API_TOKEN": "your_token"
187
242
  }
@@ -214,9 +269,10 @@ manifest.user_config.api_key → mpak config set ... api_key=xxx → env IPI
214
269
  ## Design Decisions
215
270
 
216
271
  1. **Standalone**: No shared dependencies with server/client. Types generated from OpenAPI.
217
- 2. **Public API only**: MVP uses only v1 API. Publishing requires separate tooling.
272
+ 2. **Public API only**: Uses v1 API. Publishing requires OIDC via GitHub Actions.
218
273
  3. **Platform detection**: Auto-detects OS/arch, allows explicit override for cross-platform downloads.
219
274
  4. **Config file**: Stores registry URL in `~/.mpak/config.json`, overridable via `MPAK_REGISTRY_URL`.
275
+ 5. **Skill schemas**: Uses Zod schemas in `src/schemas/generated/skill.ts` for validation.
220
276
 
221
277
  ## Gotchas
222
278
 
@@ -224,9 +280,4 @@ manifest.user_config.api_key → mpak config set ... api_key=xxx → env IPI
224
280
  - **Type generation**: Requires server running locally (`npm run generate:types` hits localhost:3200)
225
281
  - **Schema changes**: May introduce breaking type changes; always run full verification after regenerating
226
282
  - **Env merge order**: Use `{ ...substitutedEnv, ...process.env }` so parent env vars (Claude Desktop) take priority over manifest substitutions
227
-
228
- ## Future Considerations
229
-
230
- - The CLI will be broken out into a completely standalone repository
231
- - Authentication commands (login, publish) may be added when needed
232
- - Consider adding `npx` support for zero-install usage
283
+ - **Skill endpoints**: Currently implemented in server code but may not be deployed to production yet
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
8
8
  [![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)
9
9
 
10
- CLI for discovering and downloading MCPB bundles from the mpak registry.
10
+ CLI for MCP bundles and Agent Skills.
11
11
 
12
12
  ## Installation
13
13
 
@@ -18,36 +18,81 @@ npm install -g @nimblebrain/mpak
18
18
  ## Quick Start
19
19
 
20
20
  ```bash
21
- # Search for bundles
21
+ # Search for everything (bundles + skills)
22
22
  mpak search postgres
23
23
 
24
- # Show bundle details
25
- mpak show @owner/my-server
24
+ # Run an MCP server
25
+ mpak run @owner/my-server
26
26
 
27
- # Download a bundle
28
- mpak pull @owner/my-server
29
- mpak pull @owner/my-server@1.0.0 # specific version
27
+ # Search skills only
28
+ mpak skill search strategy
29
+
30
+ # Install a skill
31
+ mpak skill install @owner/my-skill
32
+ ```
33
+
34
+ ## Claude Code Integration
35
+
36
+ Add any mpak bundle to Claude Code with a single command:
37
+
38
+ ```bash
39
+ claude mcp add --transport stdio echo -- mpak run @nimblebraininc/echo
40
+ ```
41
+
42
+ For bundles requiring API keys:
43
+
44
+ ```bash
45
+ # Set config once
46
+ mpak config set @nimblebraininc/ipinfo api_key=your_token
47
+
48
+ # Then add to Claude Code
49
+ claude mcp add --transport stdio ipinfo -- mpak run @nimblebraininc/ipinfo
30
50
  ```
31
51
 
32
52
  ## Commands
33
53
 
54
+ ### Unified Search
55
+
56
+ Search across both bundles and skills.
57
+
58
+ ```bash
59
+ # Search everything
60
+ mpak search postgres
61
+
62
+ # Filter by type
63
+ mpak search postgres --type bundle
64
+ mpak search strategy --type skill
65
+
66
+ # Sort and limit
67
+ mpak search mcp --sort downloads --limit 10
68
+ ```
69
+
70
+ Options:
71
+ - `--type <type>` - Filter by type (bundle, skill)
72
+ - `--sort <field>` - Sort by: downloads, recent, name
73
+ - `--limit <n>` - Limit results
74
+ - `--offset <n>` - Pagination offset
75
+ - `--json` - Output as JSON
76
+
77
+ ### Bundle Commands
78
+
79
+ MCP bundle operations for discovering, downloading, and running MCP servers.
80
+
34
81
  | Command | Description |
35
82
  |---------|-------------|
36
- | `search <query>` | Search public bundles |
37
- | `show <package>` | Show bundle details with platforms |
38
- | `info <package>` | Alias for show |
39
- | `pull <package>` | Download a bundle |
40
- | `install <package>` | Alias for pull |
41
- | `run <package>` | Run an MCP server from the registry |
83
+ | `mpak bundle search <query>` | Search public bundles |
84
+ | `mpak bundle show <package>` | Show bundle details with platforms |
85
+ | `mpak bundle pull <package>` | Download a bundle |
86
+ | `mpak bundle run <package>` | Run an MCP server from the registry |
42
87
 
43
- ### search
88
+ #### bundle search
44
89
 
45
90
  Search for bundles in the registry.
46
91
 
47
92
  ```bash
48
- mpak search echo
49
- mpak search --type python echo
50
- mpak search --sort downloads --limit 10 mcp
93
+ mpak bundle search echo
94
+ mpak bundle search --type python echo
95
+ mpak bundle search --sort downloads --limit 10 mcp
51
96
  ```
52
97
 
53
98
  Options:
@@ -57,13 +102,13 @@ Options:
57
102
  - `--offset <n>` - Pagination offset
58
103
  - `--json` - Output as JSON
59
104
 
60
- ### show / info
105
+ #### bundle show
61
106
 
62
107
  Display detailed information about a bundle.
63
108
 
64
109
  ```bash
65
- mpak show @nimblebraininc/echo
66
- mpak show @nimblebraininc/echo --json
110
+ mpak bundle show @nimblebraininc/echo
111
+ mpak bundle show @nimblebraininc/echo --json
67
112
  ```
68
113
 
69
114
  Shows:
@@ -76,22 +121,22 @@ Shows:
76
121
  Options:
77
122
  - `--json` - Output as JSON
78
123
 
79
- ### pull / install
124
+ #### bundle pull
80
125
 
81
126
  Download a bundle from the registry.
82
127
 
83
128
  ```bash
84
129
  # Download latest version for current platform
85
- mpak pull @nimblebraininc/echo
130
+ mpak bundle pull @nimblebraininc/echo
86
131
 
87
132
  # Download specific version
88
- mpak pull @nimblebraininc/echo@1.0.0
133
+ mpak bundle pull @nimblebraininc/echo@1.0.0
89
134
 
90
135
  # Download for different platform (cross-compile use case)
91
- mpak pull @nimblebraininc/echo --os linux --arch arm64
136
+ mpak bundle pull @nimblebraininc/echo --os linux --arch arm64
92
137
 
93
138
  # Custom output path
94
- mpak pull @nimblebraininc/echo -o ./bundles/echo.mcpb
139
+ mpak bundle pull @nimblebraininc/echo -o ./bundles/echo.mcpb
95
140
  ```
96
141
 
97
142
  Options:
@@ -100,25 +145,33 @@ Options:
100
145
  - `--arch <arch>` - Target architecture: x64, arm64
101
146
  - `--json` - Output download info as JSON (doesn't download)
102
147
 
103
- ### run
148
+ #### bundle run
104
149
 
105
150
  Run an MCP server directly from the registry. Bundles are cached locally for fast subsequent runs.
106
151
 
107
152
  ```bash
108
153
  # Run latest version
109
- mpak run @nimblebraininc/echo
154
+ mpak bundle run @nimblebraininc/echo
110
155
 
111
156
  # Run specific version
112
- mpak run @nimblebraininc/echo@1.0.0
157
+ mpak bundle run @nimblebraininc/echo@1.0.0
113
158
 
114
159
  # Force re-download (update cache)
115
- mpak run @nimblebraininc/echo --update
160
+ mpak bundle run @nimblebraininc/echo --update
116
161
  ```
117
162
 
118
163
  Options:
119
164
  - `--update` - Force re-download even if cached
120
165
 
121
- **Claude Desktop Integration:**
166
+ > **Tip:** Use `mpak run` as a shortcut for `mpak bundle run`.
167
+
168
+ **Claude Code:**
169
+
170
+ ```bash
171
+ claude mcp add --transport stdio echo -- mpak run @nimblebraininc/echo
172
+ ```
173
+
174
+ **Claude Desktop:**
122
175
 
123
176
  ```json
124
177
  {
@@ -133,6 +186,140 @@ Options:
133
186
 
134
187
  Bundles are cached in `~/.mpak/cache/` and automatically extracted on first run.
135
188
 
189
+ ### Skill Commands
190
+
191
+ Agent skill operations for validating, packaging, and installing skills.
192
+
193
+ | Command | Description |
194
+ |---------|-------------|
195
+ | `mpak skill validate <path>` | Validate a skill directory |
196
+ | `mpak skill pack <path>` | Create a .skill bundle |
197
+ | `mpak skill search <query>` | Search skills in the registry |
198
+ | `mpak skill show <name>` | Show skill details |
199
+ | `mpak skill pull <name>` | Download a .skill bundle |
200
+ | `mpak skill install <name>` | Install to ~/.claude/skills/ |
201
+ | `mpak skill list` | List installed skills |
202
+
203
+ #### skill validate
204
+
205
+ Validate a skill directory against the [Agent Skills specification](https://agentskills.io/specification).
206
+
207
+ ```bash
208
+ mpak skill validate ./my-skill
209
+ mpak skill validate ./my-skill --json
210
+ ```
211
+
212
+ Options:
213
+ - `--json` - Output as JSON
214
+
215
+ #### skill pack
216
+
217
+ Create a `.skill` bundle from a skill directory.
218
+
219
+ ```bash
220
+ mpak skill pack ./my-skill
221
+ mpak skill pack ./my-skill -o ./dist/my-skill.skill
222
+ ```
223
+
224
+ Options:
225
+ - `-o, --output <path>` - Output file path
226
+ - `--json` - Output as JSON
227
+
228
+ #### skill search
229
+
230
+ Search for skills in the registry.
231
+
232
+ ```bash
233
+ mpak skill search strategy
234
+ mpak skill search --category development docs
235
+ mpak skill search --tags documentation,refactoring
236
+ ```
237
+
238
+ Options:
239
+ - `--tags <tags>` - Filter by tags (comma-separated)
240
+ - `--category <category>` - Filter by category
241
+ - `--surface <surface>` - Filter by surface (claude-code, claude-api, claude-ai)
242
+ - `--sort <field>` - Sort by: downloads, recent, name
243
+ - `--limit <n>` - Limit results
244
+ - `--offset <n>` - Pagination offset
245
+ - `--json` - Output as JSON
246
+
247
+ #### skill show
248
+
249
+ Display detailed information about a skill.
250
+
251
+ ```bash
252
+ mpak skill show @nimblebraininc/docs-auditor
253
+ mpak skill show @nimblebraininc/docs-auditor --json
254
+ ```
255
+
256
+ Options:
257
+ - `--json` - Output as JSON
258
+
259
+ #### skill pull
260
+
261
+ Download a skill bundle from the registry.
262
+
263
+ ```bash
264
+ mpak skill pull @nimblebraininc/docs-auditor
265
+ mpak skill pull @nimblebraininc/docs-auditor -o ./skills/
266
+ ```
267
+
268
+ Options:
269
+ - `-o, --output <path>` - Output file path
270
+ - `--json` - Output as JSON
271
+
272
+ #### skill install
273
+
274
+ Download and install a skill to `~/.claude/skills/`.
275
+
276
+ ```bash
277
+ mpak skill install @nimblebraininc/docs-auditor
278
+ mpak skill install @nimblebraininc/docs-auditor --force
279
+ ```
280
+
281
+ Options:
282
+ - `--force` - Overwrite existing installation
283
+ - `--json` - Output as JSON
284
+
285
+ #### skill list
286
+
287
+ List installed skills.
288
+
289
+ ```bash
290
+ mpak skill list
291
+ mpak skill list --json
292
+ ```
293
+
294
+ Options:
295
+ - `--json` - Output as JSON
296
+
297
+ ### Config Commands
298
+
299
+ Manage per-package configuration values (e.g., API keys).
300
+
301
+ | Command | Description |
302
+ |---------|-------------|
303
+ | `mpak config set <pkg> <k=v...>` | Set config values |
304
+ | `mpak config get <pkg>` | Show config (values masked) |
305
+ | `mpak config list` | List packages with config |
306
+ | `mpak config clear <pkg> [key]` | Clear config |
307
+
308
+ ```bash
309
+ # Set API key for a package
310
+ mpak config set @nimblebraininc/ipinfo api_key=your_token
311
+
312
+ # View stored config (values are masked)
313
+ mpak config get @nimblebraininc/ipinfo
314
+
315
+ # List all packages with stored config
316
+ mpak config list
317
+
318
+ # Clear config
319
+ mpak config clear @nimblebraininc/ipinfo
320
+ mpak config clear @nimblebraininc/ipinfo api_key # Clear specific key
321
+ ```
322
+
136
323
  ## Configuration
137
324
 
138
325
  Configuration is stored in `~/.mpak/config.json`:
@@ -161,14 +348,17 @@ The CLI uses the public v1 API:
161
348
  | `GET /v1/bundles/@{scope}/{pkg}` | Get bundle details |
162
349
  | `GET /v1/bundles/@{scope}/{pkg}/versions` | List versions with platforms |
163
350
  | `GET /v1/bundles/@{scope}/{pkg}/versions/{version}/download` | Get download URL |
351
+ | `GET /v1/skills/search` | Search skills |
352
+ | `GET /v1/skills/@{scope}/{name}` | Get skill details |
353
+ | `GET /v1/skills/@{scope}/{name}/download` | Get skill download URL |
164
354
 
165
355
  ## Development
166
356
 
167
357
  ### Setup
168
358
 
169
359
  ```bash
170
- cd apps/mpak/cli
171
360
  npm install
361
+ npm run build
172
362
  ```
173
363
 
174
364
  ### Scripts
@@ -179,7 +369,8 @@ npm install
179
369
  | `npm run dev` | Run CLI in development mode |
180
370
  | `npm run typecheck` | Type check without building |
181
371
  | `npm run generate:types` | Generate types from OpenAPI spec |
182
- | `npm test` | Run tests |
372
+ | `npm test` | Run unit tests |
373
+ | `npm run test:all` | Run all tests including integration |
183
374
  | `npm run lint` | Lint source code |
184
375
 
185
376
  ### Publishing
@@ -188,7 +379,7 @@ npm install
188
379
  # Stable release
189
380
  npm publish
190
381
 
191
- # Beta/prerelease (required for versions like 0.0.1-beta.1)
382
+ # Beta/prerelease
192
383
  npm publish --tag beta
193
384
  ```
194
385
 
@@ -196,32 +387,15 @@ npm publish --tag beta
196
387
 
197
388
  1. Start the server locally:
198
389
  ```bash
199
- cd ../server
390
+ cd ../mpak/server
200
391
  npm run dev
201
392
  ```
202
393
 
203
394
  2. Run CLI with local registry:
204
395
  ```bash
205
- MPAK_REGISTRY_URL=http://localhost:3200 npm run dev -- search echo
206
- ```
207
-
208
- 3. Or build and test:
209
- ```bash
210
- npm run build
211
- MPAK_REGISTRY_URL=http://localhost:3200 node dist/index.js search echo
396
+ MPAK_REGISTRY_URL=http://localhost:3200 npm run dev -- bundle search echo
212
397
  ```
213
398
 
214
- ### Type Generation
215
-
216
- Types are generated from the server's OpenAPI spec:
217
-
218
- ```bash
219
- # Requires server running locally
220
- npm run generate:types
221
- ```
222
-
223
- This generates `src/lib/api/schema.d.ts` from `http://localhost:3200/documentation/json`.
224
-
225
399
  ### Project Structure
226
400
 
227
401
  ```
@@ -229,14 +403,28 @@ src/
229
403
  ├── index.ts # Entry point
230
404
  ├── program.ts # Commander program setup
231
405
  ├── commands/
232
- └── packages/
233
- ├── search.ts # Search command
234
- ├── show.ts # Show/info command
235
- └── pull.ts # Pull/install command
406
+ ├── packages/ # Bundle commands
407
+ ├── search.ts
408
+ ├── show.ts
409
+ │ ├── pull.ts
410
+ │ │ └── run.ts
411
+ │ ├── skills/ # Skill commands
412
+ │ │ ├── validate.ts
413
+ │ │ ├── pack.ts
414
+ │ │ ├── search.ts
415
+ │ │ ├── show.ts
416
+ │ │ ├── pull.ts
417
+ │ │ ├── install.ts
418
+ │ │ └── list.ts
419
+ │ └── config.ts # Config commands
236
420
  ├── lib/
237
421
  │ └── api/
238
- │ ├── registry-client.ts # API client
422
+ │ ├── registry-client.ts # Bundle API client
423
+ │ ├── skills-client.ts # Skills API client
239
424
  │ └── schema.d.ts # Generated OpenAPI types
425
+ ├── schemas/
426
+ │ └── generated/
427
+ │ └── skill.ts # Skill validation schemas
240
428
  └── utils/
241
429
  ├── config-manager.ts # Config file handling
242
430
  └── version.ts # Version helper
@@ -1,5 +1,6 @@
1
1
  export interface RunOptions {
2
2
  update?: boolean;
3
+ local?: string;
3
4
  }
4
5
  /**
5
6
  * Parse package specification into name and version
@@ -30,7 +31,17 @@ export declare function substituteUserConfig(value: string, userConfigValues: Re
30
31
  */
31
32
  export declare function substituteEnvVars(env: Record<string, string> | undefined, userConfigValues: Record<string, string>): Record<string, string>;
32
33
  /**
33
- * Run a package from the registry
34
+ * Get cache directory for a local bundle.
35
+ * Uses hash of absolute path to avoid collisions.
36
+ */
37
+ export declare function getLocalCacheDir(bundlePath: string): string;
38
+ /**
39
+ * Check if local bundle needs re-extraction.
40
+ * Returns true if cache doesn't exist or bundle was modified after extraction.
41
+ */
42
+ export declare function localBundleNeedsExtract(bundlePath: string, cacheDir: string): boolean;
43
+ /**
44
+ * Run a package from the registry or a local bundle file
34
45
  */
35
46
  export declare function handleRun(packageSpec: string, options?: RunOptions): Promise<void>;
36
47
  //# sourceMappingURL=run.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/commands/packages/run.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAuCD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAejF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAKvD;AAqDD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAItE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACvC,MAAM,CAIR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EACvC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACvC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AA+HD;;GAEG;AACH,wBAAsB,SAAS,CAC7B,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,IAAI,CAAC,CAoJf"}
1
+ {"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/commands/packages/run.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAuCD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAejF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAKvD;AAqDD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAItE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACvC,MAAM,CAIR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EACvC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACvC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAI3D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAWrF;AA+HD;;GAEG;AACH,wBAAsB,SAAS,CAC7B,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,IAAI,CAAC,CA4Mf"}