@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.
- package/.claude/settings.local.json +3 -1
- package/CLAUDE.md +85 -34
- package/README.md +245 -57
- package/dist/commands/packages/run.d.ts +12 -1
- package/dist/commands/packages/run.d.ts.map +1 -1
- package/dist/commands/packages/run.js +116 -45
- package/dist/commands/packages/run.js.map +1 -1
- package/dist/commands/search.d.ts +12 -0
- package/dist/commands/search.d.ts.map +1 -0
- package/dist/commands/search.js +144 -0
- package/dist/commands/search.js.map +1 -0
- package/dist/commands/skills/index.d.ts +8 -0
- package/dist/commands/skills/index.d.ts.map +1 -0
- package/dist/commands/skills/index.js +8 -0
- package/dist/commands/skills/index.js.map +1 -0
- package/dist/commands/skills/install.d.ts +9 -0
- package/dist/commands/skills/install.d.ts.map +1 -0
- package/dist/commands/skills/install.js +110 -0
- package/dist/commands/skills/install.js.map +1 -0
- package/dist/commands/skills/list.d.ts +8 -0
- package/dist/commands/skills/list.d.ts.map +1 -0
- package/dist/commands/skills/list.js +89 -0
- package/dist/commands/skills/list.js.map +1 -0
- package/dist/commands/skills/pack.d.ts +22 -0
- package/dist/commands/skills/pack.d.ts.map +1 -0
- package/dist/commands/skills/pack.js +116 -0
- package/dist/commands/skills/pack.js.map +1 -0
- package/dist/commands/skills/pull.d.ts +9 -0
- package/dist/commands/skills/pull.d.ts.map +1 -0
- package/dist/commands/skills/pull.js +68 -0
- package/dist/commands/skills/pull.js.map +1 -0
- package/dist/commands/skills/search.d.ts +14 -0
- package/dist/commands/skills/search.d.ts.map +1 -0
- package/dist/commands/skills/search.js +53 -0
- package/dist/commands/skills/search.js.map +1 -0
- package/dist/commands/skills/show.d.ts +8 -0
- package/dist/commands/skills/show.d.ts.map +1 -0
- package/dist/commands/skills/show.js +64 -0
- package/dist/commands/skills/show.js.map +1 -0
- package/dist/commands/skills/validate.d.ts +25 -0
- package/dist/commands/skills/validate.d.ts.map +1 -0
- package/dist/commands/skills/validate.js +191 -0
- package/dist/commands/skills/validate.js.map +1 -0
- package/dist/index.js +0 -0
- package/dist/lib/api/skills-client.d.ts +30 -0
- package/dist/lib/api/skills-client.d.ts.map +1 -0
- package/dist/lib/api/skills-client.js +110 -0
- package/dist/lib/api/skills-client.js.map +1 -0
- package/dist/program.d.ts +5 -1
- package/dist/program.d.ts.map +1 -1
- package/dist/program.js +112 -35
- package/dist/program.js.map +1 -1
- package/dist/schemas/generated/api-responses.d.ts +541 -0
- package/dist/schemas/generated/api-responses.d.ts.map +1 -0
- package/dist/schemas/generated/api-responses.js +313 -0
- package/dist/schemas/generated/api-responses.js.map +1 -0
- package/dist/schemas/generated/auth.d.ts +18 -0
- package/dist/schemas/generated/auth.d.ts.map +1 -0
- package/dist/schemas/generated/auth.js +18 -0
- package/dist/schemas/generated/auth.js.map +1 -0
- package/dist/schemas/generated/index.d.ts +5 -0
- package/dist/schemas/generated/index.d.ts.map +1 -0
- package/dist/schemas/generated/index.js +6 -0
- package/dist/schemas/generated/index.js.map +1 -0
- package/dist/schemas/generated/package.d.ts +43 -0
- package/dist/schemas/generated/package.d.ts.map +1 -0
- package/dist/schemas/generated/package.js +20 -0
- package/dist/schemas/generated/package.js.map +1 -0
- package/dist/schemas/generated/skill.d.ts +381 -0
- package/dist/schemas/generated/skill.d.ts.map +1 -0
- package/dist/schemas/generated/skill.js +216 -0
- package/dist/schemas/generated/skill.js.map +1 -0
- package/dist/utils/config-manager.d.ts +13 -1
- package/dist/utils/config-manager.d.ts.map +1 -1
- package/dist/utils/config-manager.js +76 -11
- package/dist/utils/config-manager.js.map +1 -1
- package/package.json +6 -2
- package/src/commands/packages/run.test.ts +40 -1
- package/src/commands/packages/run.ts +131 -46
- package/src/commands/search.ts +191 -0
- package/src/commands/skills/index.ts +7 -0
- package/src/commands/skills/install.ts +129 -0
- package/src/commands/skills/list.ts +116 -0
- package/src/commands/skills/pack.test.ts +260 -0
- package/src/commands/skills/pack.ts +145 -0
- package/src/commands/skills/pull.ts +88 -0
- package/src/commands/skills/search.ts +73 -0
- package/src/commands/skills/show.ts +72 -0
- package/src/commands/skills/validate.test.ts +466 -0
- package/src/commands/skills/validate.ts +227 -0
- package/src/lib/api/skills-client.ts +148 -0
- package/src/program.test.ts +1 -3
- package/src/program.ts +140 -36
- package/src/schemas/config.v1.schema.json +37 -0
- package/src/schemas/generated/api-responses.ts +386 -0
- package/src/schemas/generated/auth.ts +21 -0
- package/src/schemas/generated/index.ts +5 -0
- package/src/schemas/generated/package.ts +29 -0
- package/src/schemas/generated/skill.ts +271 -0
- package/src/utils/config-manager.test.ts +182 -2
- package/src/utils/config-manager.ts +126 -12
package/CLAUDE.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# mpak CLI
|
|
2
2
|
|
|
3
|
-
CLI for
|
|
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
|
|
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
|
|
17
|
-
| `src/commands/
|
|
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
|
-
|
|
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
|
-
###
|
|
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
|
|
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
|
|
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
|
-
| `
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
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**:
|
|
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
|
[](https://www.typescriptlang.org/)
|
|
8
8
|
[](https://www.nimblebrain.ai/discord?utm_source=github&utm_medium=readme&utm_campaign=mpak-cli&utm_content=discord-badge)
|
|
9
9
|
|
|
10
|
-
CLI for
|
|
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
|
-
#
|
|
25
|
-
mpak
|
|
24
|
+
# Run an MCP server
|
|
25
|
+
mpak run @owner/my-server
|
|
26
26
|
|
|
27
|
-
#
|
|
28
|
-
mpak
|
|
29
|
-
|
|
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
|
-
| `
|
|
39
|
-
| `
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
|
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
|
-
│
|
|
233
|
-
│
|
|
234
|
-
│
|
|
235
|
-
│
|
|
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
|
-
*
|
|
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":"
|
|
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"}
|