@prave/cli 1.2.2 → 1.3.0

package/dist/commands/deploy.js

@@ -3,7 +3,7 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import chalk from 'chalk';
 import ora from 'ora';
-import { AGENT_REGISTRY } from '@prave/shared';
+import { AGENT_REGISTRY, compileSkill } from '@prave/shared';
 import { track } from '../lib/analytics.js';
 import { api, ApiError } from '../lib/api.js';
 import { requireAuth } from '../lib/credentials.js';
@@ -41,34 +41,30 @@ async function fetchRemoteSkill(slug) {
     }
     return data.content;
 }
-function describeContentForCursor(content, slug) {
-    // Has frontmatter? best-effort rename triggers: → globs:
-    const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?/);
-    if (fmMatch && fmMatch[1] !== undefined) {
-        const body = content.slice(fmMatch[0].length);
-        const fmInner = fmMatch[1].replace(/(^|\n)triggers:/g, '$1globs:');
-        return `---\n${fmInner}\n---\n${body}`;
-    }
-    // No frontmatter — synthesize
-    const trimmed = content.trim().replace(/\s+/g, ' ').slice(0, 200);
-    return `---\nname: ${slug}\ndescription: ${trimmed}\n---\n${content}`;
-}
-function buildDestPath(agent, basePath, os, slug) {
+/**
+ * Build the on-disk write path for the given agent + slug. The
+ * `compileSkill()` import from `@prave/shared` decides the *content*
+ * transform (e.g. Cursor `.mdc` frontmatter rewrite); this function
+ * only resolves the absolute filesystem location by combining the
+ * agent's `basePath` from user settings with the relative path the
+ * shared compiler returned.
+ */
+function buildDestPath(agent, basePath, os, slug, relPath) {
     const expanded = expandHome(basePath, os);
-    if (agent === 'cursor') {
-        // .cursor/rules/<slug>.mdc — the basePath already points at .cursor/rules
-        return {
-            dir: expanded,
-            file: join(expanded, `${slug}.mdc`),
-            converted: true,
-            display: `${basePath.replace(/[\\/]+$/, '')}/${slug}.mdc`,
-        };
-    }
+    // The shared compiler returns POSIX-style relPaths
+    // (e.g. `<slug>/SKILL.md` or `.cursor/rules/<slug>.mdc`). For
+    // Cursor specifically the user's `basePath` already points at
+    // `.cursor/rules/`, so we collapse the leading `.cursor/rules/`
+    // to avoid the path duplicating to `.cursor/rules/.cursor/rules/`.
+    const collapsed = agent === 'cursor' && relPath.startsWith('.cursor/rules/')
+        ? relPath.slice('.cursor/rules/'.length)
+        : relPath;
+    const file = join(expanded, ...collapsed.split('/'));
+    const dir = file.slice(0, file.length - collapsed.split('/').slice(-1)[0].length - 1);
     return {
-        dir: join(expanded, slug),
-        file: join(expanded, slug, 'SKILL.md'),
-        converted: false,
-        display: `${basePath.replace(/[\\/]+$/, '')}/${slug}/SKILL.md`,
+        dir,
+        file,
+        display: `${basePath.replace(/[\\/]+$/, '')}/${collapsed}`,
     };
 }
 export async function deployCommand(skillName, opts = {}) {
@@ -146,10 +142,12 @@ export async function deployCommand(skillName, opts = {}) {
         const meta = AGENT_REGISTRY[agent];
         const paths = settings.skill_paths[agent] ?? meta.defaultPath;
         const basePath = os === 'windows' ? paths.windows : paths.mac;
-        const dest = buildDestPath(agent, basePath, os, skillName);
-        const content = dest.converted
-            ? describeContentForCursor(source, skillName)
-            : source;
+        // Shared compileSkill() is the single source of truth — same
+        // function the SaaS /dashboard/compile page calls, so the CLI
+        // and the web zip produce byte-identical output for the same
+        // SKILL.md.
+        const artifact = compileSkill(source, skillName, agent);
+        const dest = buildDestPath(agent, basePath, os, skillName, artifact.path);
         spinner.text = `→ ${meta.label}`;
         if (opts.dryRun) {
             okCount += 1;
@@ -157,7 +155,7 @@ export async function deployCommand(skillName, opts = {}) {
         }
         try {
             await mkdir(dest.dir, { recursive: true });
-            await writeFile(dest.file, content, 'utf8');
+            await writeFile(dest.file, artifact.content, 'utf8');
             okCount += 1;
         }
         catch (err) {
@@ -169,8 +167,9 @@ export async function deployCommand(skillName, opts = {}) {
         const meta = AGENT_REGISTRY[agent];
         const paths = settings.skill_paths[agent] ?? meta.defaultPath;
         const basePath = os === 'windows' ? paths.windows : paths.mac;
-        const dest = buildDestPath(agent, basePath, os, skillName);
-        const tag = dest.converted ? chalk.dim(' (converted)') : '';
+        const artifact = compileSkill(source, skillName, agent);
+        const dest = buildDestPath(agent, basePath, os, skillName, artifact.path);
+        const tag = artifact.converted ? chalk.dim(' (converted)') : '';
         console.log(`${chalk.green('✓')} ${meta.label.padEnd(14)} → ${dest.display}${tag}`);
     }
     const elapsed = ((Date.now() - start) / 1000).toFixed(1);

package/dist/commands/mcp-install.js

@@ -0,0 +1,197 @@
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, writeFile, stat } from 'node:fs/promises';
+import { homedir, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+import process from 'node:process';
+import chalk from 'chalk';
+import { track } from '../lib/analytics.js';
+import { log } from '../utils/logger.js';
+const ENTRY_NPX = {
+    command: 'npx',
+    args: ['-y', '@prave/cli', 'mcp-server'],
+};
+const ENTRY_GLOBAL = {
+    command: 'prave',
+    args: ['mcp-server'],
+};
+export async function mcpInstallCommand() {
+    track('cli_mcp_install');
+    const target = resolveClaudeDesktopConfigPath();
+    if (!target) {
+        log.error(`This OS (${platform()}) isn't supported by Claude Desktop yet. Use the manual JSON snippet from /dashboard/settings/mcp instead.`);
+        process.exitCode = 1;
+        return;
+    }
+    // Prefer the global `prave` binary when it's on PATH — it's faster
+    // (no npx resolution at every Claude Desktop launch), version-pinned
+    // by the user (no surprise updates mid-session), and the config
+    // entry is two tokens shorter. Fall back to the npx form when the
+    // user is on a one-shot `npx @prave/cli mcp install` path.
+    const hasGlobalPrave = await detectGlobalPrave();
+    const PRAVE_ENTRY = hasGlobalPrave ? ENTRY_GLOBAL : ENTRY_NPX;
+    // Read existing config, tolerate the "file doesn't exist yet" case
+    // — Claude Desktop creates the file on first launch, but users often
+    // run our setup BEFORE opening the app for the first time.
+    let existing = {};
+    let fileExisted = false;
+    try {
+        const raw = await readFile(target, 'utf8');
+        fileExisted = true;
+        try {
+            existing = JSON.parse(raw);
+        }
+        catch (err) {
+            log.error(`Couldn't parse ${target} as JSON (${err.message}). Fix it manually or delete it and re-run.`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            log.error(`Couldn't read ${target}: ${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // Idempotency check — if a `prave` entry with our exact command +
+    // args already exists, don't churn the file.
+    const current = existing.mcpServers?.prave;
+    if (current &&
+        current.command === PRAVE_ENTRY.command &&
+        JSON.stringify(current.args ?? []) === JSON.stringify(PRAVE_ENTRY.args ?? [])) {
+        log.success('Prave MCP server is already wired into Claude Desktop.');
+        log.dim(`Config: ${target}`);
+        log.dim('Restart Claude Desktop if you haven\'t since the last edit.');
+        return;
+    }
+    // Backup before mutating. Only when the file existed — there's
+    // nothing to back up otherwise.
+    if (fileExisted) {
+        try {
+            const raw = await readFile(target, 'utf8');
+            await writeFile(`${target}.bak`, raw, 'utf8');
+        }
+        catch (err) {
+            log.warn(`Couldn't write ${target}.bak — proceeding anyway: ${err.message}`);
+        }
+    }
+    // Merge our entry, preserving everything else (including any other
+    // MCP servers the user has configured).
+    const nextConfig = {
+        ...existing,
+        mcpServers: {
+            ...(existing.mcpServers ?? {}),
+            prave: PRAVE_ENTRY,
+        },
+    };
+    try {
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, JSON.stringify(nextConfig, null, 2) + '\n', 'utf8');
+    }
+    catch (err) {
+        log.error(`Couldn't write ${target}: ${err.message}`);
+        process.exitCode = 1;
+        return;
+    }
+    log.success('Prave MCP server installed for Claude Desktop.');
+    console.log();
+    console.log(`  ${chalk.dim('Config:')}  ${target}`);
+    if (fileExisted) {
+        console.log(`  ${chalk.dim('Backup:')}  ${target}.bak`);
+    }
+    else {
+        console.log(`  ${chalk.dim('Note:')}    New config file created.`);
+    }
+    console.log(`  ${chalk.dim('Mode:')}    ${hasGlobalPrave
+        ? 'global `prave` binary (fast, no npx hop)'
+        : 'npx (no global install needed)'}`);
+    console.log();
+    log.info('Next:');
+    log.dim('  1. Restart Claude Desktop.');
+    log.dim('  2. Prave\'s tools appear in the MCP panel.');
+    log.dim('  3. Try: "Find me a skill for React testing".');
+    if (!hasGlobalPrave) {
+        console.log();
+        log.dim(`Tip: ${chalk.bold('npm i -g @prave/cli')} once, and Claude Desktop boots Prave a second faster (no npx resolution).`);
+    }
+    // Ping the heartbeat so the SaaS Settings → MCP card shows
+    // "Connection wired" even before the user fires the first real
+    // tool call. Best-effort; failure swallowed.
+    void pingHeartbeatBestEffort();
+}
+/* ─── internals ─────────────────────────────────────────────────── */
+function resolveClaudeDesktopConfigPath() {
+    const home = homedir();
+    switch (platform()) {
+        case 'darwin':
+            return join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+        case 'win32': {
+            const appData = process.env.APPDATA;
+            if (!appData)
+                return null;
+            return join(appData, 'Claude', 'claude_desktop_config.json');
+        }
+        case 'linux':
+            return join(home, '.config', 'Claude', 'claude_desktop_config.json');
+        default:
+            return null;
+    }
+}
+async function pingHeartbeatBestEffort() {
+    try {
+        const { api } = await import('../lib/api.js');
+        await api.post('/api/v1/me/mcp-heartbeat', {}, true);
+    }
+    catch {
+        // No creds yet, or API unreachable — fine. The first real tool
+        // call from Claude Desktop will set the heartbeat anyway.
+    }
+}
+/**
+ * Is the `prave` binary globally installed and on PATH?
+ *
+ * Uses `which` (POSIX) / `where` (Windows) to probe. Returns true only
+ * when the resolved path is NOT inside an npx temp directory — that
+ * way running this command via `npx @prave/cli mcp install` doesn't
+ * fool the detector into thinking the user has a permanent install
+ * (the resolved binary in that case is in `~/.npm/_npx/...`).
+ *
+ * Timeout: 1s. If `which` hangs (shouldn't ever, but networked
+ * filesystems are weird), we fall back to the npx form. Worst case
+ * is one extra npx hop per Claude Desktop launch — not a correctness
+ * issue.
+ */
+async function detectGlobalPrave() {
+    return new Promise((resolve) => {
+        const cmd = platform() === 'win32' ? 'where' : 'which';
+        const child = spawn(cmd, ['prave'], { stdio: ['ignore', 'pipe', 'ignore'] });
+        let output = '';
+        const timer = setTimeout(() => {
+            child.kill();
+            resolve(false);
+        }, 1_000);
+        child.stdout?.on('data', (chunk) => {
+            output += chunk.toString('utf8');
+        });
+        child.on('error', () => {
+            clearTimeout(timer);
+            resolve(false);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (code !== 0 || !output.trim()) {
+                resolve(false);
+                return;
+            }
+            // Filter out npx-temp paths so an in-flight `npx @prave/cli` run
+            // doesn't get mistaken for a global install.
+            const firstLine = output.split('\n')[0]?.trim() ?? '';
+            const looksLikeNpxTemp = /[/\\](_npx|\.npm[/\\]_npx|npm-cache[/\\]_npx)[/\\]/i.test(firstLine);
+            resolve(!looksLikeNpxTemp);
+        });
+    });
+}
+// Silences the unused-import lint when no other branch reads `stat`.
+// The function is kept here intentionally for future expansion (e.g.
+// staleness check on `.bak` files) without re-adding the import.
+void stat;

package/dist/commands/mcp-server.js

@@ -0,0 +1,211 @@
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { api, ApiError } from '../lib/api.js';
+import { loadCredentials } from '../lib/credentials.js';
+const TOOLS = [
+    {
+        name: 'prave_search_skills',
+        description: 'Search the public Prave catalogue of Claude Skills. Returns up to 20 results. Use this when the user is exploring which Skill to install, or asking what Skills exist for a domain.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Keyword or phrase to search. Searches name + description + tags.',
+                },
+                category: {
+                    type: 'string',
+                    description: 'Optional category filter (e.g. "testing", "design", "deployment"). See the Discover page for the full list.',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 20,
+                    default: 10,
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'prave_whatdoes',
+        description: 'Look up one Skill by slug. Returns the canonical name, description, tags, install count, and rating. Useful as a confirmation step before `prave_install_skill`.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                slug: { type: 'string', description: 'Skill slug, e.g. "vercel-labs-agent-skills-react-best-practices".' },
+            },
+            required: ['slug'],
+        },
+    },
+    {
+        name: 'prave_my_skills',
+        description: 'List Skills the signed-in user has installed locally or authored. Useful when the user asks "what Skills do I already have?".',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'prave_audit_library',
+        description: 'Return the Skill Intelligence overview for the signed-in user: total Skill count, library token footprint, trigger count over the last 30 days, conflicts detected, and the 5 token-heaviest Skills. Use this when the user asks about token cost, performance, or which Skills to trim.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'prave_install_skill',
+        description: 'Install a Skill from the catalogue into the user\'s local agent directory (~/.claude/skills/). Spawns the `prave install <slug>` CLI subprocess and streams its output back. Use only after confirming the slug with `prave_whatdoes`.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                slug: { type: 'string', description: 'Skill slug to install.' },
+            },
+            required: ['slug'],
+        },
+    },
+];
+export async function mcpServerCommand() {
+    // Auth check up-front. If the user runs `prave mcp-server` without
+    // logging in, the MCP frame would otherwise look healthy but every
+    // tool call would fail with 401 — confusing. Emit a clear stderr
+    // message and exit, so Claude Desktop's MCP UI surfaces a bad-config
+    // error instead of letting the user wonder.
+    const creds = await loadCredentials();
+    if (!creds) {
+        process.stderr.write('prave mcp-server: not logged in. Run `prave login` first.\n');
+        process.exit(1);
+    }
+    const server = new Server({ name: 'prave-mcp', version: '1.0.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS,
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: args = {} } = req.params;
+        // Best-effort heartbeat — every successful tool call pings the
+        // server so the Settings → MCP card knows the user is wired in.
+        // Fired-and-forgotten; failures don't break the tool response.
+        void pingHeartbeat();
+        try {
+            switch (name) {
+                case 'prave_search_skills':
+                    return await handleSearch(args);
+                case 'prave_whatdoes':
+                    return await handleWhatdoes(args);
+                case 'prave_my_skills':
+                    return await handleMySkills();
+                case 'prave_audit_library':
+                    return await handleAuditLibrary();
+                case 'prave_install_skill':
+                    return await handleInstallSkill(args);
+                default:
+                    return mcpError(`Unknown tool: ${name}`);
+            }
+        }
+        catch (err) {
+            const msg = err instanceof ApiError ? err.message : err.message;
+            return mcpError(msg);
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Block forever — the transport keeps the event loop alive while
+    // stdio is open. Process exits cleanly when the parent (Claude
+    // Desktop) closes the pipe.
+}
+/* ─── tool handlers ────────────────────────────────────────────── */
+async function handleSearch(args) {
+    const params = new URLSearchParams();
+    params.set('q', args.query);
+    if (args.category)
+        params.set('category', args.category);
+    params.set('limit', String(Math.min(20, Math.max(1, args.limit ?? 10))));
+    const { data } = await api.get(`/api/v1/skills?${params.toString()}`, true);
+    const items = data.items ?? [];
+    const lines = items.map((s) => `• ${s.name} (${s.slug}) — ${s.description ?? 'no description'} · ↓${s.install_count}`);
+    return mcpText(lines.length
+        ? `Found ${lines.length} Skill${lines.length === 1 ? '' : 's'}:\n\n${lines.join('\n')}`
+        : `No Skills matched "${args.query}".`);
+}
+async function handleWhatdoes(args) {
+    const { data } = await api.get(`/api/v1/skills/${encodeURIComponent(args.slug)}`, true);
+    return mcpText([
+        `${data.name} (${data.slug})`,
+        data.description ?? '(no description)',
+        '',
+        `Tags: ${data.tags.length ? data.tags.join(', ') : '(none)'}`,
+        `Installs: ${data.install_count}`,
+        data.rating != null ? `Rating: ${data.rating.toFixed(1)}/5` : '',
+    ]
+        .filter(Boolean)
+        .join('\n'));
+}
+async function handleMySkills() {
+    const { data } = await api.get('/api/v1/me/skills', true);
+    const items = data.items ?? [];
+    if (items.length === 0) {
+        return mcpText('You haven\'t installed or authored any Skills yet. Try `prave_search_skills` to browse the catalogue.');
+    }
+    const lines = items.map((s) => `• ${s.name} (${s.slug})`);
+    return mcpText(`You have ${items.length} Skill${items.length === 1 ? '' : 's'}:\n\n${lines.join('\n')}`);
+}
+async function handleAuditLibrary() {
+    const { data } = await api.get('/api/v1/intelligence/overview', true);
+    const heaviestLines = data.heaviest
+        .slice(0, 5)
+        .map((s) => `  • ${s.name ?? s.slug ?? '(unnamed)'} — ${s.estimated_tokens.toLocaleString()} tokens`);
+    return mcpText([
+        `Skill Intelligence overview`,
+        ``,
+        `Total Skills indexed: ${data.total_skills}`,
+        `Library token footprint: ${data.total_estimated_tokens.toLocaleString()} tokens`,
+        `Triggered in last 30 days: ${data.triggered_30d}`,
+        `Conflicts detected: ${data.conflict_count}`,
+        ``,
+        `Top 5 token-heaviest:`,
+        ...(heaviestLines.length ? heaviestLines : ['  (none indexed yet — run `prave sync`)']),
+    ].join('\n'));
+}
+async function handleInstallSkill(args) {
+    // Run the existing CLI install command as a subprocess. Identical
+    // behavior to a user typing `prave install <slug>` — same plan
+    // checks, same dependency resolution, same on-disk effects. Tail
+    // the output for the MCP response.
+    return await new Promise((resolve) => {
+        const child = spawn(process.argv[0] ?? 'node', [process.argv[1] ?? '', 'install', args.slug], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (err) => {
+            resolve(mcpError(`Failed to spawn install: ${err.message}`));
+        });
+        child.on('close', (code) => {
+            const output = (stdout + (stderr ? `\n${stderr}` : '')).trim() ||
+                (code === 0 ? `Installed ${args.slug}.` : `Install exited with code ${code}.`);
+            resolve(code === 0
+                ? mcpText(output)
+                : mcpError(output));
+        });
+    });
+}
+/* ─── helpers ──────────────────────────────────────────────────── */
+function mcpText(text) {
+    return { content: [{ type: 'text', text }] };
+}
+function mcpError(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+async function pingHeartbeat() {
+    try {
+        await api.post('/api/v1/me/mcp-heartbeat', {}, true);
+    }
+    catch {
+        // Heartbeat is fire-and-forget. The MCP tool still works even
+        // when the heartbeat endpoint is unreachable (e.g. brief API
+        // outage); the SaaS Settings card just won't update its
+        // last-seen timestamp.
+    }
+}

package/dist/index.js

@@ -12,6 +12,8 @@ import { installCommand } from './commands/install.js';
 import { listCommand } from './commands/list.js';
 import { loginCommand } from './commands/login.js';
 import { logoutCommand } from './commands/logout.js';
+import { mcpInstallCommand } from './commands/mcp-install.js';
+import { mcpServerCommand } from './commands/mcp-server.js';
 import { optimizeCommand } from './commands/optimize.js';
 import { overviewCommand } from './commands/overview.js';
 import { searchCommand } from './commands/search.js';
@@ -161,6 +163,15 @@ program
     .option('--agent <agent>', 'restrict deploy to a single agent (claude-code | codex | cursor | gemini | cline | amp)')
     .option('--dry-run', 'log every destination path but write nothing — preview before committing')
     .action(deployCommand);
+program
+    .command('mcp-server')
+    .description('Run the Prave MCP server over stdio. Wire into Claude Desktop / Cursor MCP / Continue.dev via { "command": "npx", "args": ["-y", "@prave/cli", "mcp-server"] }. Exposes search, install, audit, my-skills, whatdoes as MCP tools.')
+    .action(mcpServerCommand);
+program
+    .command('mcp install')
+    .alias('mcp-install')
+    .description('One-command setup: patches Claude Desktop\'s config to wire the Prave MCP server. Idempotent, takes a `.bak` of any existing config, preserves other mcpServers entries. Restart Claude Desktop after running.')
+    .action(mcpInstallCommand);
 // ─── Help command — full quick-reference ───────────────────────────
 program
     .command('cheat')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prave/cli",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Prave CLI — discover, install, version, test, and ship Claude Skills. The developer platform for the complete Skill lifecycle.",
   "type": "module",
   "keywords": [
@@ -46,12 +46,13 @@
     "dist"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "open": "^10.1.0",
     "ora": "^8.0.1",
     "undici": "^6.18.0",
-    "@prave/shared": "1.2.2"
+    "@prave/shared": "1.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",