Add --local flag for running local .mcpb bundles

- Add -l/--local option to run command for testing bundles before publishing
- Extract to ~/.mpak/cache/_local/<hash>/ with mtime-based cache invalidation
- Add getLocalCacheDir() and localBundleNeedsExtract() helpers
- Make package argument optional when --local is provided
- Add unit tests for new helper functions
- Update docs with run command and Claude Code integration examples

Author: mgoldsborough

CLAUDE.md

@@ -142,6 +142,18 @@ git push && git push --tags
 | `mpak search <query> --type bundle` | Search bundles only |
 | `mpak search <query> --type skill` | Search skills only |
 
+### Run (Top-Level Alias)
+
+| Command | Description |
+|---------|-------------|
+| `mpak run <package>` | Run an MCP server (alias for `bundle run`) |
+
+This is the recommended way to integrate with Claude Code:
+
+```bash
+claude mcp add --transport stdio echo -- mpak run @nimblebraininc/echo
+```
+
 ### Bundle Commands
 
 | Command | Description |

README.md

@@ -21,11 +21,8 @@ npm install -g @nimblebrain/mpak
 # Search for everything (bundles + skills)
 mpak search postgres
 
-# Search bundles only
-mpak bundle search postgres
-
 # Run an MCP server
-mpak bundle run @owner/my-server
+mpak run @owner/my-server
 
 # Search skills only
 mpak skill search strategy
@@ -34,6 +31,24 @@ mpak skill search strategy
 mpak skill install @owner/my-skill
 ```
 
+## Claude Code Integration
+
+Add any mpak bundle to Claude Code with a single command:
+
+```bash
+claude mcp add --transport stdio echo -- mpak run @nimblebraininc/echo
+```
+
+For bundles requiring API keys:
+
+```bash
+# Set config once
+mpak config set @nimblebraininc/ipinfo api_key=your_token
+
+# Then add to Claude Code
+claude mcp add --transport stdio ipinfo -- mpak run @nimblebraininc/ipinfo
+```
+
 ## Commands
 
 ### Unified Search
@@ -148,14 +163,22 @@ mpak bundle run @nimblebraininc/echo --update
 Options:
 - `--update` - Force re-download even if cached
 
-**Claude Desktop Integration:**
+> **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": ["bundle", "run", "@nimblebraininc/echo"]
+      "args": ["run", "@nimblebraininc/echo"]
     }
   }
 }

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimblebrain/mpak",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "CLI for downloading MCPB bundles from the mpak registry",
   "main": "dist/index.js",
   "type": "module",

package.json

@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { homedir } from 'os';
 import { join } from 'path';
-import { parsePackageSpec, getCacheDir, resolveArgs, substituteUserConfig, substituteEnvVars } from './run.js';
+import { parsePackageSpec, getCacheDir, resolveArgs, substituteUserConfig, substituteEnvVars, getLocalCacheDir, localBundleNeedsExtract } from './run.js';
 
 describe('parsePackageSpec', () => {
   describe('scoped packages', () => {
@@ -220,3 +220,42 @@ describe('substituteEnvVars', () => {
     });
   });
 });
+
+describe('getLocalCacheDir', () => {
+  const expectedBase = join(homedir(), '.mpak', 'cache', '_local');
+
+  it('returns consistent hash for same path', () => {
+    const dir1 = getLocalCacheDir('/path/to/bundle.mcpb');
+    const dir2 = getLocalCacheDir('/path/to/bundle.mcpb');
+    expect(dir1).toBe(dir2);
+  });
+
+  it('returns different hash for different paths', () => {
+    const dir1 = getLocalCacheDir('/path/to/bundle1.mcpb');
+    const dir2 = getLocalCacheDir('/path/to/bundle2.mcpb');
+    expect(dir1).not.toBe(dir2);
+  });
+
+  it('includes _local in path', () => {
+    const dir = getLocalCacheDir('/path/to/bundle.mcpb');
+    expect(dir).toContain('_local');
+    expect(dir.startsWith(expectedBase)).toBe(true);
+  });
+
+  it('produces a 12-character hash suffix', () => {
+    const dir = getLocalCacheDir('/path/to/bundle.mcpb');
+    const hashPart = dir.split('/').pop();
+    expect(hashPart).toHaveLength(12);
+  });
+});
+
+describe('localBundleNeedsExtract', () => {
+  it('returns true when cache directory does not exist', () => {
+    expect(localBundleNeedsExtract('/any/path.mcpb', '/nonexistent/cache')).toBe(true);
+  });
+
+  it('returns true when meta file does not exist in cache dir', () => {
+    // Using a directory that exists but has no .mpak-meta.json
+    expect(localBundleNeedsExtract('/any/path.mcpb', '/tmp')).toBe(true);
+  });
+});

src/commands/packages/run.test.ts

@@ -1,13 +1,15 @@
 import { spawn, spawnSync } from 'child_process';
 import { createInterface } from 'readline';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, rmSync, statSync } from 'fs';
+import { createHash } from 'crypto';
 import { homedir } from 'os';
-import { join, dirname } from 'path';
+import { join, dirname, resolve, basename } from 'path';
 import { RegistryClient } from '../../lib/api/registry-client.js';
 import { ConfigManager } from '../../utils/config-manager.js';
 
 export interface RunOptions {
   update?: boolean;
+  local?: string;  // Path to local .mcpb file
 }
 
 interface McpConfig {
@@ -169,6 +171,33 @@ export function substituteEnvVars(
   return result;
 }
 
+/**
+ * Get cache directory for a local bundle.
+ * Uses hash of absolute path to avoid collisions.
+ */
+export function getLocalCacheDir(bundlePath: string): string {
+  const absolutePath = resolve(bundlePath);
+  const hash = createHash('md5').update(absolutePath).digest('hex').slice(0, 12);
+  return join(homedir(), '.mpak', 'cache', '_local', hash);
+}
+
+/**
+ * Check if local bundle needs re-extraction.
+ * Returns true if cache doesn't exist or bundle was modified after extraction.
+ */
+export function localBundleNeedsExtract(bundlePath: string, cacheDir: string): boolean {
+  const metaPath = join(cacheDir, '.mpak-meta.json');
+  if (!existsSync(metaPath)) return true;
+
+  try {
+    const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+    const bundleStat = statSync(bundlePath);
+    return bundleStat.mtimeMs > new Date(meta.extractedAt).getTime();
+  } catch {
+    return true;
+  }
+}
+
 /**
  * Prompt user for a config value (interactive terminal input)
  */
@@ -295,69 +324,125 @@ function findPythonCommand(): string {
 }
 
 /**
- * Run a package from the registry
+ * Run a package from the registry or a local bundle file
  */
 export async function handleRun(
   packageSpec: string,
   options: RunOptions = {}
 ): Promise<void> {
-  const { name, version: requestedVersion } = parsePackageSpec(packageSpec);
-  const client = new RegistryClient();
-  const platform = RegistryClient.detectPlatform();
-  const cacheDir = getCacheDir(name);
-
-  let needsPull = true;
-  let cachedMeta = getCacheMetadata(cacheDir);
-
-  // Check if we have a cached version
-  if (cachedMeta && !options.update) {
-    if (requestedVersion) {
-      // Specific version requested - check if cached version matches
-      needsPull = cachedMeta.version !== requestedVersion;
-    } else {
-      // Latest requested - use cache (user can --update to refresh)
-      needsPull = false;
-    }
+  // Validate that either --local or package spec is provided
+  if (!options.local && !packageSpec) {
+    process.stderr.write(`=> Error: Either provide a package name or use --local <path>\n`);
+    process.exit(1);
   }
 
-  if (needsPull) {
-    // Fetch download info
-    const downloadInfo = await client.getDownloadInfo(name, requestedVersion, platform);
-    const bundle = downloadInfo.bundle;
+  let cacheDir: string;
+  let packageName: string;
+
+  if (options.local) {
+    // === LOCAL BUNDLE MODE ===
+    const bundlePath = resolve(options.local);
 
-    // Check if cached version is already the latest
-    if (cachedMeta && cachedMeta.version === bundle.version && !options.update) {
-      needsPull = false;
+    // Validate bundle exists
+    if (!existsSync(bundlePath)) {
+      process.stderr.write(`=> Error: Bundle not found: ${bundlePath}\n`);
+      process.exit(1);
     }
 
-    if (needsPull) {
-      // Download to temp file
-      const tempPath = join(homedir(), '.mpak', 'tmp', `${Date.now()}.mcpb`);
-      mkdirSync(dirname(tempPath), { recursive: true });
+    // Validate .mcpb extension
+    if (!bundlePath.endsWith('.mcpb')) {
+      process.stderr.write(`=> Error: Not an MCPB bundle: ${bundlePath}\n`);
+      process.exit(1);
+    }
 
-      process.stderr.write(`=> Pulling ${name}@${bundle.version}...\n`);
-      await client.downloadBundle(downloadInfo.url, tempPath);
+    cacheDir = getLocalCacheDir(bundlePath);
+    const needsExtract = options.update || localBundleNeedsExtract(bundlePath, cacheDir);
 
-      // Clear old cache and extract
-      const { rmSync } = await import('fs');
+    if (needsExtract) {
+      // Clear old extraction
       if (existsSync(cacheDir)) {
         rmSync(cacheDir, { recursive: true, force: true });
       }
       mkdirSync(cacheDir, { recursive: true });
 
-      await extractZip(tempPath, cacheDir);
+      process.stderr.write(`=> Extracting ${basename(bundlePath)}...\n`);
+      await extractZip(bundlePath, cacheDir);
+
+      // Write local metadata
+      writeFileSync(
+        join(cacheDir, '.mpak-meta.json'),
+        JSON.stringify({
+          localPath: bundlePath,
+          extractedAt: new Date().toISOString(),
+        })
+      );
+    }
 
-      // Write metadata
-      writeCacheMetadata(cacheDir, {
-        version: bundle.version,
-        pulledAt: new Date().toISOString(),
-        platform: bundle.platform,
-      });
+    // Read manifest to get package name for config lookup
+    const manifest = readManifest(cacheDir);
+    packageName = manifest.name;
+    process.stderr.write(`=> Running ${packageName} (local)\n`);
+
+  } else {
+    // === REGISTRY MODE ===
+    const { name, version: requestedVersion } = parsePackageSpec(packageSpec);
+    packageName = name;
+    const client = new RegistryClient();
+    const platform = RegistryClient.detectPlatform();
+    cacheDir = getCacheDir(name);
+
+    let needsPull = true;
+    let cachedMeta = getCacheMetadata(cacheDir);
+
+    // Check if we have a cached version
+    if (cachedMeta && !options.update) {
+      if (requestedVersion) {
+        // Specific version requested - check if cached version matches
+        needsPull = cachedMeta.version !== requestedVersion;
+      } else {
+        // Latest requested - use cache (user can --update to refresh)
+        needsPull = false;
+      }
+    }
+
+    if (needsPull) {
+      // Fetch download info
+      const downloadInfo = await client.getDownloadInfo(name, requestedVersion, platform);
+      const bundle = downloadInfo.bundle;
 
-      // Cleanup temp file
-      rmSync(tempPath, { force: true });
+      // Check if cached version is already the latest
+      if (cachedMeta && cachedMeta.version === bundle.version && !options.update) {
+        needsPull = false;
+      }
 
-      process.stderr.write(`=> Cached ${name}@${bundle.version}\n`);
+      if (needsPull) {
+        // Download to temp file
+        const tempPath = join(homedir(), '.mpak', 'tmp', `${Date.now()}.mcpb`);
+        mkdirSync(dirname(tempPath), { recursive: true });
+
+        process.stderr.write(`=> Pulling ${name}@${bundle.version}...\n`);
+        await client.downloadBundle(downloadInfo.url, tempPath);
+
+        // Clear old cache and extract
+        if (existsSync(cacheDir)) {
+          rmSync(cacheDir, { recursive: true, force: true });
+        }
+        mkdirSync(cacheDir, { recursive: true });
+
+        await extractZip(tempPath, cacheDir);
+
+        // Write metadata
+        writeCacheMetadata(cacheDir, {
+          version: bundle.version,
+          pulledAt: new Date().toISOString(),
+          platform: bundle.platform,
+        });
+
+        // Cleanup temp file
+        rmSync(tempPath, { force: true });
+
+        process.stderr.write(`=> Cached ${name}@${bundle.version}\n`);
+      }
     }
   }
 
@@ -369,7 +454,7 @@ export async function handleRun(
   let userConfigValues: Record<string, string> = {};
   if (manifest.user_config && Object.keys(manifest.user_config).length > 0) {
     const configManager = new ConfigManager();
-    userConfigValues = await gatherUserConfigValues(name, manifest.user_config, configManager);
+    userConfigValues = await gatherUserConfigValues(packageName, manifest.user_config, configManager);
   }
 
   // Substitute user_config placeholders in env vars