pmpt-cli 1.11.0 → 1.12.0

package/dist/commands/browse.js

@@ -1,73 +1,11 @@
 import * as p from '@clack/prompts';
-import { fetchProjects } from '../lib/api.js';
-export async function cmdBrowse() {
-    p.intro('pmpt browse');
-    const s = p.spinner();
-    s.start('Loading projects...');
-    let projects;
-    try {
-        const index = await fetchProjects();
-        projects = index.projects;
-    }
-    catch (err) {
-        s.stop('Failed to load');
-        p.log.error(err instanceof Error ? err.message : 'Could not load project list.');
-        process.exit(1);
-    }
-    s.stop(`${projects.length} projects`);
-    if (projects.length === 0) {
-        p.log.info('No published projects yet.');
-        p.log.message('  pmpt publish  — share your first project!');
-        p.outro('');
-        return;
-    }
-    // Select project
-    const selected = await p.select({
-        message: 'Select a project:',
-        options: projects.map((proj) => ({
-            value: proj.slug,
-            label: proj.projectName,
-            hint: `v${proj.versionCount} · @${proj.author}${proj.description ? ` — ${proj.description.slice(0, 40)}` : ''}`,
-        })),
-    });
-    if (p.isCancel(selected)) {
-        p.cancel('');
-        process.exit(0);
-    }
-    const project = projects.find((p) => p.slug === selected);
-    // Show details
-    p.note([
-        `Project: ${project.projectName}`,
-        `Author: @${project.author}`,
-        `Versions: ${project.versionCount}`,
-        project.description ? `Description: ${project.description}` : '',
-        project.tags.length ? `Tags: ${project.tags.join(', ')}` : '',
-        `Published: ${project.publishedAt.slice(0, 10)}`,
-        `Size: ${(project.fileSize / 1024).toFixed(1)} KB`,
-    ].filter(Boolean).join('\n'), 'Project Details');
-    // Action
-    const action = await p.select({
-        message: 'What would you like to do?',
-        options: [
-            { value: 'clone', label: 'Clone this project', hint: 'pmpt clone' },
-            { value: 'url', label: 'Show URL', hint: 'View in browser' },
-            { value: 'back', label: 'Go back' },
-        ],
-    });
-    if (p.isCancel(action) || action === 'back') {
-        p.outro('');
-        return;
-    }
-    if (action === 'clone') {
-        const { cmdClone } = await import('./clone.js');
-        await cmdClone(project.slug);
-        return;
-    }
-    if (action === 'url') {
-        const url = `https://pmptwiki.com/p/${project.slug}`;
-        p.log.info(`URL: ${url}`);
-        p.log.message(`Download: ${project.downloadUrl}`);
-        p.log.message(`\npmpt clone ${project.slug}  — clone via terminal`);
-        p.outro('');
-    }
+import open from 'open';
+const EXPLORE_URL = 'https://pmptwiki.com/explore';
+export async function cmdExplore() {
+    p.intro('pmpt explore');
+    p.log.info(`Opening ${EXPLORE_URL}`);
+    await open(EXPLORE_URL);
+    p.log.message('  Search, filter, and clone projects from the web.');
+    p.log.message('  Found something you like? →  pmpt clone <slug>');
+    p.outro('');
 }

package/dist/commands/clone.js

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from
 import { isInitialized, getConfigDir, getHistoryDir, getDocsDir, initializeProject } from '../lib/config.js';
 import { validatePmptFile, isSafeFilename } from '../lib/pmptFile.js';
 import { fetchPmptFile, trackClone } from '../lib/api.js';
+import { copyToClipboard } from '../lib/clipboard.js';
 /**
  * Restore history from .pmpt data (shared with import command)
  */
@@ -81,12 +82,15 @@ export async function cmdClone(slug) {
     const pmptData = validation.data;
     s.stop('Download complete');
     // Show summary
-    p.note([
+    const infoLines = [
         `Project: ${pmptData.meta.projectName}`,
         `Versions: ${pmptData.history.length}`,
         pmptData.meta.author ? `Author: @${pmptData.meta.author}` : '',
-        pmptData.meta.description ? `Description: ${pmptData.meta.description.slice(0, 80)}` : '',
-    ].filter(Boolean).join('\n'), 'Project Info');
+        pmptData.meta.description ? `\n${pmptData.meta.description}` : '',
+        pmptData.plan?.productIdea ? `\n💡 ${pmptData.plan.productIdea.slice(0, 120)}` : '',
+        pmptData.plan?.techStack ? `🛠  ${pmptData.plan.techStack.slice(0, 80)}` : '',
+    ];
+    p.note(infoLines.filter(Boolean).join('\n'), 'Project Info');
     const projectPath = process.cwd();
     if (isInitialized(projectPath)) {
         const overwrite = await p.confirm({
@@ -147,6 +151,19 @@ export async function cmdClone(slug) {
         '',
         '---',
         '',
+        `## Documentation Rule`,
+        '',
+        `**Important:** When you make progress, update \`.pmpt/docs/pmpt.md\` (the human-facing project document) at these moments:`,
+        `- When architecture or tech decisions are finalized`,
+        `- When a feature is implemented (mark as done)`,
+        `- When a development phase is completed`,
+        `- When requirements change or new decisions are made`,
+        '',
+        `Keep the Progress and Snapshot Log sections in pmpt.md up to date.`,
+        `After significant milestones, run \`pmpt save\` to create a snapshot.`,
+        '',
+        '---',
+        '',
         originalAiMd,
     ].join('\n');
     writeFileSync(aiMdPath, cloneGuide, 'utf-8');
@@ -170,9 +187,38 @@ export async function cmdClone(slug) {
         `Versions: ${versionCount}`,
         `Location: ${pmptDir}`,
     ].join('\n'), 'Clone Summary');
-    p.log.info('Next steps:');
+    // Copy AI prompt to clipboard
+    const aiContent = readFileSync(aiMdPath, 'utf-8');
+    const copied = copyToClipboard(aiContent);
+    if (copied) {
+        p.log.message('');
+        p.log.success('AI prompt copied to clipboard!');
+        p.log.message('');
+        const banner = [
+            '',
+            '┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓',
+            '┃                                                        ┃',
+            '┃   📋  NEXT STEP                                        ┃',
+            '┃                                                        ┃',
+            '┃   Open your AI coding tool and press:           ┃',
+            '┃                                                        ┃',
+            '┃              ⌘ + V  (Mac)                              ┃',
+            '┃             Ctrl + V (Windows/Linux)                   ┃',
+            '┃                                                        ┃',
+            '┃   Your cloned project context is ready! 🚀             ┃',
+            '┃                                                        ┃',
+            '┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛',
+            '',
+        ];
+        console.log(banner.join('\n'));
+    }
+    else {
+        p.log.warn('Could not copy to clipboard.');
+        p.log.info(`Read it at: ${aiMdPath}`);
+    }
+    p.log.info('Tips:');
     p.log.message('  pmpt history    — view version history');
-    p.log.message('  pmpt plan       — view AI prompt');
+    p.log.message('  pmpt plan       — view or edit AI prompt');
     p.log.message('  pmpt save       — save a new snapshot');
     p.outro('Project cloned!');
 }

package/dist/commands/edit.js

@@ -79,6 +79,47 @@ export async function cmdEdit() {
         p.cancel('Cancelled');
         process.exit(0);
     }
+    // Product link (optional)
+    const linkTypeInput = await p.select({
+        message: 'Product link (optional):',
+        initialValue: project.productUrlType || 'none',
+        options: [
+            { value: 'none', label: 'No link' },
+            { value: 'git', label: 'Git Repository' },
+            { value: 'url', label: 'Website / URL' },
+        ],
+    });
+    if (p.isCancel(linkTypeInput)) {
+        p.cancel('Cancelled');
+        process.exit(0);
+    }
+    let productUrl = '';
+    let productUrlType = '';
+    if (linkTypeInput !== 'none') {
+        productUrlType = linkTypeInput;
+        const productUrlInput = await p.text({
+            message: 'Product URL:',
+            placeholder: linkTypeInput === 'git'
+                ? `https://github.com/${auth.username}/${slug}`
+                : 'https://...',
+            defaultValue: project.productUrl || '',
+            validate: (v) => {
+                if (!v.trim())
+                    return 'URL is required when link type is selected.';
+                try {
+                    new URL(v);
+                }
+                catch {
+                    return 'Invalid URL format.';
+                }
+            },
+        });
+        if (p.isCancel(productUrlInput)) {
+            p.cancel('Cancelled');
+            process.exit(0);
+        }
+        productUrl = productUrlInput;
+    }
     const s2 = p.spinner();
     s2.start('Updating...');
     try {
@@ -86,6 +127,8 @@ export async function cmdEdit() {
             description: description,
             tags,
             category: category,
+            productUrl,
+            productUrlType,
         });
         s2.stop('Updated!');
         p.log.success(`Project "${slug}" has been updated.`);

package/dist/commands/hist.js

@@ -75,8 +75,12 @@ export function cmdHistory(path, options) {
             if (snapshot.git.dirty)
                 header += ' (dirty)';
         }
-        const files = snapshot.files.map((f) => `  - ${f}`).join('\n');
-        p.note(files || '  (no files)', header);
+        const lines = [];
+        if (snapshot.note) {
+            lines.push(`  ${snapshot.note}`, '');
+        }
+        lines.push(...snapshot.files.map((f) => `  - ${f}`));
+        p.note(lines.join('\n') || '  (no files)', header);
     }
     if (options?.compact && hiddenVersions.length > 0) {
         p.log.info(`Hidden versions (minor changes): ${hiddenVersions.map(v => `v${v}`).join(', ')}`);

package/dist/commands/internal-seed.js

@@ -84,13 +84,12 @@ export async function cmdInternalSeed(options) {
             const content = readFileSync(resolve(specDir, fromPath), 'utf-8');
             writeDocFile(docsDir, fileName, content);
         }
-        const entry = createFullSnapshot(projectPath);
-        const note = step.saveNote ? ` — ${step.saveNote}` : '';
-        p.log.success(`v${entry.version} saved${note}`);
+        const entry = createFullSnapshot(projectPath, { note: step.saveNote });
+        const noteStr = entry.note ? ` — ${entry.note}` : '';
+        p.log.success(`v${entry.version} saved${noteStr}`);
     }
     if (spec.publish?.enabled) {
         await cmdPublish(projectPath, {
-            force: spec.publish.force ?? false,
             nonInteractive: true,
             yes: spec.publish.yes ?? true,
             metaFile: spec.publish.metaFile ? resolve(specDir, spec.publish.metaFile) : undefined,

package/dist/commands/publish.js

@@ -8,6 +8,7 @@ import { createPmptFile } from '../lib/pmptFile.js';
 import { loadAuth } from '../lib/auth.js';
 import { publishProject, fetchProjects } from '../lib/api.js';
 import { computeQuality } from '../lib/quality.js';
+import { copyToClipboard } from '../lib/clipboard.js';
 import pc from 'picocolors';
 import glob from 'fast-glob';
 import { join } from 'path';
@@ -22,6 +23,29 @@ const CATEGORY_OPTIONS = [
     { value: 'other', label: 'Other' },
 ];
 const VALID_CATEGORIES = new Set(CATEGORY_OPTIONS.map((o) => o.value));
+function generateImprovementPrompt(quality) {
+    const missing = [];
+    for (const item of quality.details) {
+        if (item.score < item.maxScore && item.tip) {
+            missing.push(`- ${item.label}: ${item.tip}`);
+        }
+    }
+    return [
+        `My pmpt project scored ${quality.score}/100 (Grade ${quality.grade}) and needs at least 40 to publish.`,
+        '',
+        'Areas to improve:',
+        ...missing,
+        '',
+        'Please help me improve the project quality:',
+        '',
+        '1. Read `.pmpt/docs/pmpt.ai.md` and `.pmpt/docs/pmpt.md`',
+        '2. Expand pmpt.ai.md to 500+ characters with clear project context, architecture, and instructions for AI',
+        '3. Make sure pmpt.md has progress tracking, decisions, and a snapshot log',
+        '4. If plan.md is missing, create it with product overview',
+        '5. After improving, run `pmpt save` to create a new snapshot',
+        '6. Then try `pmpt publish` again',
+    ].join('\n');
+}
 function normalizeTags(value) {
     if (Array.isArray(value)) {
         return value
@@ -124,11 +148,22 @@ export async function cmdPublish(path, options) {
         if (tips.length > 0) {
             p.log.info('How to improve:\n' + tips.join('\n'));
         }
-        if (!options?.force) {
-            p.log.error('Use `pmpt publish --force` to publish anyway.');
-            process.exit(1);
+        // Generate and copy AI improvement prompt
+        const improvementPrompt = generateImprovementPrompt(quality);
+        const copied = copyToClipboard(improvementPrompt);
+        if (copied) {
+            p.log.message('');
+            p.log.success('AI improvement prompt copied to clipboard!');
+            p.log.message('  Paste it into Claude Code, Cursor, or any AI tool to improve your project.');
+            p.log.message('  After improving, run `pmpt save` then `pmpt publish` again.');
+        }
+        else {
+            p.log.message('');
+            p.note(improvementPrompt, 'AI Improvement Prompt');
+            p.log.message('  Copy the prompt above and paste into your AI tool.');
         }
-        p.log.warn('Publishing with --force despite low quality score.');
+        p.outro('');
+        process.exit(1);
     }
     const projectName = planProgress?.answers?.projectName || basename(projectPath);
     // Try to load existing published data for prefill

package/dist/commands/save.js

@@ -38,6 +38,12 @@ export async function cmdSave(fileOrPath) {
             msg += ` (${changedCount} changed, ${unchangedCount} skipped)`;
         }
         p.log.success(msg);
+        // Warn if pmpt.md was not updated since last save
+        if (entry.version > 1 && entry.changedFiles && !entry.changedFiles.includes('pmpt.md')) {
+            p.log.message('');
+            p.log.warn('pmpt.md has not been updated since the last save.');
+            p.log.message('  Tip: Mark completed features and update the Snapshot Log before saving.');
+        }
         p.log.message('');
         p.log.info('Files included:');
         for (const file of entry.files) {

package/dist/index.js

@@ -37,7 +37,7 @@ import { cmdPublish } from './commands/publish.js';
 import { cmdEdit } from './commands/edit.js';
 import { cmdUnpublish } from './commands/unpublish.js';
 import { cmdClone } from './commands/clone.js';
-import { cmdBrowse } from './commands/browse.js';
+import { cmdExplore } from './commands/browse.js';
 import { cmdRecover } from './commands/recover.js';
 import { cmdDiff } from './commands/diff.js';
 import { cmdInternalSeed } from './commands/internal-seed.js';
@@ -64,7 +64,7 @@ Examples:
   $ pmpt login                   Authenticate with pmptwiki
   $ pmpt publish                 Publish project to pmptwiki
   $ pmpt clone <slug>            Clone a project from pmptwiki
-  $ pmpt browse                  Browse published projects
+  $ pmpt explore                  Explore projects on pmptwiki.com
   $ pmpt recover                 Recover damaged pmpt.md via AI
 
 Documentation: https://pmptwiki.com
@@ -133,7 +133,6 @@ program
 program
     .command('publish [path]')
     .description('Publish project to pmptwiki platform')
-    .option('--force', 'Publish even if quality score is below minimum')
     .option('--non-interactive', 'Run without interactive prompts')
     .option('--meta-file <file>', 'JSON file with slug, description, tags, category')
     .option('--slug <slug>', 'Project slug')
@@ -157,9 +156,9 @@ program
     .description('Clone a project from pmptwiki platform')
     .action(cmdClone);
 program
-    .command('browse')
-    .description('Browse and search published projects')
-    .action(cmdBrowse);
+    .command('explore')
+    .description('Open pmptwiki.com to explore and search projects')
+    .action(cmdExplore);
 program
     .command('recover [path]')
     .description('Generate a recovery prompt to regenerate pmpt.md via AI')

package/dist/lib/config.js

@@ -37,6 +37,11 @@ export function initializeProject(projectPath, options) {
         trackGit: options?.trackGit ?? true,
     };
     saveConfig(projectPath, config);
+    // Create README.md if it doesn't exist
+    const readmePath = join(configDir, 'README.md');
+    if (!existsSync(readmePath)) {
+        writeFileSync(readmePath, PMPT_README, 'utf-8');
+    }
     return config;
 }
 export function loadConfig(projectPath) {
@@ -54,3 +59,55 @@ export function saveConfig(projectPath, config) {
     const configPath = join(getConfigDir(projectPath), CONFIG_FILE);
     writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
 }
+const PMPT_README = `# .pmpt — Your Project's Development Journal
+
+This folder is managed by [pmpt](https://pmptwiki.com). It records your product development journey with AI.
+
+## What's Inside
+
+\`\`\`
+.pmpt/
+├── config.json     ← Project settings (auto-generated)
+├── docs/
+│   ├── pmpt.md     ← Human-facing project document (YOU update this)
+│   ├── pmpt.ai.md  ← AI-facing prompt (paste into your AI tool)
+│   └── plan.md     ← Original plan from pmpt plan
+└── .history/       ← Version snapshots (auto-managed)
+\`\`\`
+
+## Quick Reference
+
+| Command | What it does |
+|---------|-------------|
+| \`pmpt plan\` | Create or view your AI prompt |
+| \`pmpt save\` | Save a snapshot of current docs |
+| \`pmpt history\` | View version history |
+| \`pmpt diff\` | Compare versions side by side |
+| \`pmpt publish\` | Share your journey on pmptwiki.com |
+
+## How to Get the Most Out of pmpt
+
+1. **Paste \`pmpt.ai.md\` into your AI tool** to start building
+2. **Update \`pmpt.md\` as you go** — mark features done, log decisions
+3. **Run \`pmpt save\` at milestones** — after setup, after each feature, after big changes
+4. **Publish when ready** — others can clone your journey and learn from it
+
+## When Things Go Wrong
+
+| Problem | Solution |
+|---------|----------|
+| Lost your AI prompt | \`pmpt plan\` to regenerate or view it |
+| Messed up docs | \`pmpt history\` → \`pmpt diff\` to find the good version |
+| Need to start over | \`pmpt recover\` rebuilds context from history |
+| Accidentally deleted .pmpt | Re-clone from pmptwiki.com if published |
+
+## One Request
+
+Please keep \`pmpt.md\` updated as you build. It's the human-readable record of your journey — what you tried, what worked, what you decided. When you publish, this is what others will learn from.
+
+Your snapshots tell a story. Make it a good one.
+
+---
+
+*Learn more at [pmptwiki.com](https://pmptwiki.com)*
+`;

package/dist/lib/history.js

@@ -3,18 +3,31 @@ import { basename, join, relative } from 'path';
 import { getHistoryDir, getDocsDir, loadConfig } from './config.js';
 import { getGitInfo, isGitRepo } from './git.js';
 import glob from 'fast-glob';
+/** Generate compact timestamp for snapshot dir names: 20260225T163000 */
+function compactTimestamp() {
+    return new Date().toISOString().replace(/[-:\.]/g, '').slice(0, 15);
+}
+/** Parse snapshot dir timestamp (compact or legacy) to ISO string */
+function parseTimestamp(raw) {
+    // Compact: 20260225T163000
+    if (/^\d{8}T\d{6}$/.test(raw)) {
+        return `${raw.slice(0, 4)}-${raw.slice(4, 6)}-${raw.slice(6, 8)}T${raw.slice(9, 11)}:${raw.slice(11, 13)}:${raw.slice(13, 15)}`;
+    }
+    // Legacy: 2026-02-25T16-30-00
+    return raw.replace(/T(.+)$/, (_, time) => 'T' + time.replace(/-/g, ':'));
+}
 /**
  * Save .pmpt/docs MD files as snapshot
  * Copy only changed files to optimize storage
  */
-export function createFullSnapshot(projectPath) {
+export function createFullSnapshot(projectPath, options) {
     const historyDir = getHistoryDir(projectPath);
     const docsDir = getDocsDir(projectPath);
     mkdirSync(historyDir, { recursive: true });
     // Find next version number
     const existing = getAllSnapshots(projectPath);
     const version = existing.length + 1;
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const timestamp = compactTimestamp();
     const snapshotName = `v${version}-${timestamp}`;
     const snapshotDir = join(historyDir, snapshotName);
     mkdirSync(snapshotDir, { recursive: true });
@@ -63,12 +76,14 @@ export function createFullSnapshot(projectPath) {
         }
     }
     // Save metadata
+    const note = options?.note;
     const metaPath = join(snapshotDir, '.meta.json');
     writeFileSync(metaPath, JSON.stringify({
         version,
         timestamp,
         files,
         changedFiles,
+        ...(note ? { note } : {}),
         git: gitData,
     }, null, 2), 'utf-8');
     return {
@@ -77,6 +92,7 @@ export function createFullSnapshot(projectPath) {
         snapshotDir,
         files,
         changedFiles,
+        note,
         git: gitData,
     };
 }
@@ -98,7 +114,7 @@ export function createSnapshot(projectPath, filePath) {
 }
 function createSingleFileSnapshot(projectPath, filePath, relPath) {
     const historyDir = getHistoryDir(projectPath);
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const timestamp = compactTimestamp();
     // Check existing version count for this file
     const existing = getFileHistory(projectPath, relPath);
     const version = existing.length + 1;
@@ -168,10 +184,11 @@ export function getAllSnapshots(projectPath) {
         }
         entries.push({
             version: parseInt(match[1], 10),
-            timestamp: match[2].replace(/-/g, ':'),
+            timestamp: parseTimestamp(match[2]),
             snapshotDir,
             files: meta.files || [],
             changedFiles: meta.changedFiles,
+            note: meta.note,
             git: meta.git,
         });
     }
@@ -210,7 +227,7 @@ export function getFileHistory(projectPath, relPath) {
         }
         entries.push({
             version: parseInt(match[1], 10),
-            timestamp: match[2].replace(/-/g, ':'),
+            timestamp: parseTimestamp(match[2]),
             filePath: relPath,
             historyPath: filePath,
             git: gitData,

package/dist/lib/plan.js

@@ -88,6 +88,12 @@ I'll confirm progress at each step before moving to the next.
 
 Keep the Progress and Snapshot Log sections in pmpt.md up to date.
 After significant milestones, run \`pmpt save\` to create a snapshot.
+
+### Per-Feature Checklist
+After completing each feature above:
+1. Mark the feature done in \`.pmpt/docs/pmpt.md\` (change \`- [ ]\` to \`- [x]\`)
+2. Add a brief note to the Snapshot Log section
+3. Run \`pmpt save\` in terminal
 `;
 }
 // Generate human-facing project document (pmpt.md)

package/dist/mcp.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * pmpt MCP Server
+ *
+ * Exposes pmpt functionality as MCP tools so AI tools
+ * (Claude Code, Cursor, etc.) can interact with pmpt directly.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { resolve, join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import glob from 'fast-glob';
+import { createRequire } from 'module';
+import { isInitialized, loadConfig, getDocsDir } from './lib/config.js';
+import { createFullSnapshot, getAllSnapshots, getTrackedFiles, resolveFullSnapshot } from './lib/history.js';
+import { computeQuality } from './lib/quality.js';
+import { getPlanProgress } from './lib/plan.js';
+import { isGitRepo } from './lib/git.js';
+import { diffSnapshots } from './lib/diff.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+// ── Server ──────────────────────────────────────────
+const server = new McpServer({
+    name: 'pmpt',
+    version,
+});
+// ── Helpers ─────────────────────────────────────────
+function resolveProjectPath(projectPath) {
+    return projectPath ? resolve(projectPath) : process.cwd();
+}
+function assertInitialized(pp) {
+    if (!isInitialized(pp)) {
+        throw new Error(`Project not initialized at ${pp}. Run \`pmpt init\` first.`);
+    }
+}
+function readWorkingCopy(pp) {
+    const docsDir = getDocsDir(pp);
+    const files = {};
+    if (!existsSync(docsDir))
+        return files;
+    const mdFiles = glob.sync('**/*.md', { cwd: docsDir });
+    for (const file of mdFiles) {
+        try {
+            files[file] = readFileSync(join(docsDir, file), 'utf-8');
+        }
+        catch { /* skip */ }
+    }
+    return files;
+}
+function buildQualityInput(pp) {
+    const docsDir = getDocsDir(pp);
+    const aiMdPath = join(docsDir, 'pmpt.ai.md');
+    const pmptAiMd = existsSync(aiMdPath) ? readFileSync(aiMdPath, 'utf-8') : null;
+    const planProgress = getPlanProgress(pp);
+    const tracked = getTrackedFiles(pp);
+    const snapshots = getAllSnapshots(pp);
+    const hasGit = snapshots.some((s) => !!s.git) || isGitRepo(pp);
+    return {
+        pmptAiMd,
+        planAnswers: planProgress?.answers ?? null,
+        versionCount: snapshots.length,
+        docFiles: tracked,
+        hasGit,
+    };
+}
+function formatDiffs(diffs) {
+    if (diffs.length === 0)
+        return 'No differences found.';
+    const lines = [];
+    const modified = diffs.filter((d) => d.status === 'modified').length;
+    const added = diffs.filter((d) => d.status === 'added').length;
+    const removed = diffs.filter((d) => d.status === 'removed').length;
+    const parts = [];
+    if (modified > 0)
+        parts.push(`${modified} modified`);
+    if (added > 0)
+        parts.push(`${added} added`);
+    if (removed > 0)
+        parts.push(`${removed} removed`);
+    lines.push(`${diffs.length} file(s) changed: ${parts.join(', ')}`);
+    lines.push('');
+    for (const fd of diffs) {
+        const icon = fd.status === 'added' ? 'A' : fd.status === 'removed' ? 'D' : 'M';
+        lines.push(`[${icon}] ${fd.fileName}`);
+        for (const hunk of fd.hunks) {
+            lines.push(`@@ -${hunk.oldStart},${hunk.oldCount} +${hunk.newStart},${hunk.newCount} @@`);
+            for (const line of hunk.lines) {
+                const prefix = line.type === 'add' ? '+' : line.type === 'remove' ? '-' : ' ';
+                lines.push(`${prefix}${line.content}`);
+            }
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+// ── Tools ───────────────────────────────────────────
+server.tool('pmpt_save', 'Save a snapshot of .pmpt/docs/ files. Call after completing features, fixes, or milestones.', { projectPath: z.string().optional().describe('Project root path. Defaults to cwd.') }, async ({ projectPath }) => {
+    try {
+        const pp = resolveProjectPath(projectPath);
+        assertInitialized(pp);
+        const tracked = getTrackedFiles(pp);
+        if (tracked.length === 0) {
+            return { content: [{ type: 'text', text: 'No files to save. Add .md files to .pmpt/docs/ first.' }] };
+        }
+        const entry = createFullSnapshot(pp);
+        const changedCount = entry.changedFiles?.length ?? entry.files.length;
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        `Snapshot v${entry.version} saved (${changedCount} changed, ${entry.files.length - changedCount} unchanged).`,
+                        '',
+                        `Files: ${entry.files.join(', ')}`,
+                        entry.changedFiles ? `Changed: ${entry.changedFiles.join(', ')}` : '',
+                        entry.git ? `Git: ${entry.git.commit} (${entry.git.branch}${entry.git.dirty ? ', dirty' : ''})` : '',
+                    ].filter(Boolean).join('\n'),
+                }],
+        };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+    }
+});
+server.tool('pmpt_status', 'Check pmpt project status: tracked files, snapshot count, and quality score.', { projectPath: z.string().optional().describe('Project root path. Defaults to cwd.') }, async ({ projectPath }) => {
+    try {
+        const pp = resolveProjectPath(projectPath);
+        if (!isInitialized(pp)) {
+            return { content: [{ type: 'text', text: 'Project not initialized. Run `pmpt init` to start.' }] };
+        }
+        const config = loadConfig(pp);
+        const tracked = getTrackedFiles(pp);
+        const snapshots = getAllSnapshots(pp);
+        const quality = computeQuality(buildQualityInput(pp));
+        const lines = [
+            `pmpt status: ${tracked.length} file(s), ${snapshots.length} snapshot(s), quality ${quality.score}/100 (${quality.grade})`,
+            `Files: ${tracked.join(', ') || '(none)'}`,
+            config?.lastPublished ? `Last published: ${config.lastPublished.slice(0, 10)}` : '',
+            '',
+        ];
+        for (const d of quality.details) {
+            const icon = d.score === d.maxScore ? '[PASS]' : '[FAIL]';
+            lines.push(`${icon} ${d.label}: ${d.score}/${d.maxScore}${d.tip ? ` — ${d.tip}` : ''}`);
+        }
+        return { content: [{ type: 'text', text: lines.filter(Boolean).join('\n') }] };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+    }
+});
+server.tool('pmpt_history', 'View version history of pmpt snapshots.', {
+    projectPath: z.string().optional().describe('Project root path. Defaults to cwd.'),
+    limit: z.number().optional().describe('Max snapshots to return (most recent). Defaults to all.'),
+}, async ({ projectPath, limit }) => {
+    try {
+        const pp = resolveProjectPath(projectPath);
+        assertInitialized(pp);
+        const snapshots = getAllSnapshots(pp);
+        if (snapshots.length === 0) {
+            return { content: [{ type: 'text', text: 'No snapshots yet. Run `pmpt save` to create one.' }] };
+        }
+        let display = snapshots;
+        if (limit && limit > 0 && limit < snapshots.length) {
+            display = snapshots.slice(-limit);
+        }
+        const lines = [`${snapshots.length} snapshot(s)${limit ? `, showing last ${display.length}` : ''}:`, ''];
+        for (const s of display) {
+            const changed = s.changedFiles?.length ?? s.files.length;
+            const git = s.git ? ` [${s.git.commit}]` : '';
+            lines.push(`v${s.version} — ${s.timestamp.slice(0, 16)} — ${changed} changed, ${s.files.length} total${git}`);
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+    }
+});
+server.tool('pmpt_diff', 'Compare two versions, or a version against the current working copy.', {
+    projectPath: z.string().optional().describe('Project root path. Defaults to cwd.'),
+    v1: z.number().describe('First version number (e.g. 1 for v1).'),
+    v2: z.number().optional().describe('Second version. If omitted, compares against working copy.'),
+}, async ({ projectPath, v1, v2 }) => {
+    try {
+        const pp = resolveProjectPath(projectPath);
+        assertInitialized(pp);
+        const snapshots = getAllSnapshots(pp);
+        const fromIndex = snapshots.findIndex((s) => s.version === v1);
+        if (fromIndex === -1) {
+            return { content: [{ type: 'text', text: `Version v${v1} not found.` }], isError: true };
+        }
+        const oldFiles = resolveFullSnapshot(snapshots, fromIndex);
+        let newFiles;
+        let targetLabel;
+        if (v2 !== undefined) {
+            const toIndex = snapshots.findIndex((s) => s.version === v2);
+            if (toIndex === -1) {
+                return { content: [{ type: 'text', text: `Version v${v2} not found.` }], isError: true };
+            }
+            newFiles = resolveFullSnapshot(snapshots, toIndex);
+            targetLabel = `v${v2}`;
+        }
+        else {
+            newFiles = readWorkingCopy(pp);
+            targetLabel = 'working copy';
+        }
+        const diffs = diffSnapshots(oldFiles, newFiles);
+        return {
+            content: [
+                { type: 'text', text: `Diff: v${v1} → ${targetLabel}` },
+                { type: 'text', text: formatDiffs(diffs) },
+            ],
+        };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+    }
+});
+server.tool('pmpt_quality', 'Check project quality score and publish readiness.', { projectPath: z.string().optional().describe('Project root path. Defaults to cwd.') }, async ({ projectPath }) => {
+    try {
+        const pp = resolveProjectPath(projectPath);
+        assertInitialized(pp);
+        const quality = computeQuality(buildQualityInput(pp));
+        const lines = [
+            `Quality: ${quality.score}/100 (Grade ${quality.grade})`,
+            `Publish ready: ${quality.passesMinimum ? 'Yes' : 'No (minimum 40 required)'}`,
+            '',
+        ];
+        for (const item of quality.details) {
+            const icon = item.score === item.maxScore ? '[PASS]' : '[FAIL]';
+            lines.push(`${icon} ${item.label}: ${item.score}/${item.maxScore}${item.tip ? ` — ${item.tip}` : ''}`);
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
+    }
+});
+// ── Start ───────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('pmpt MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "pmpt-cli",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Record and share your AI-driven product development journey",
   "type": "module",
   "bin": {
-    "pmpt": "./dist/index.js"
+    "pmpt": "./dist/index.js",
+    "pmpt-mcp": "./dist/mcp.js"
   },
   "files": [
     "dist"
@@ -35,6 +36,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.7.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "chokidar": "^3.6.0",
     "commander": "^12.0.0",
     "fast-glob": "^3.3.0",