tokrepo-mcp-server 2.0.0 → 2.2.0

package/README.md

@@ -2,14 +2,14 @@
 
 > Search, browse, and install AI assets from [TokRepo](https://tokrepo.com) — the open registry for AI skills, prompts, MCP configs, scripts, and workflows.
 
-[![npm](https://img.shields.io/npm/v/@tokrepo/mcp-server)](https://www.npmjs.com/package/@tokrepo/mcp-server)
+[![npm](https://img.shields.io/npm/v/tokrepo-mcp-server)](https://www.npmjs.com/package/tokrepo-mcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
 ## Quick Start
 
 ### Claude Code
 ```bash
-claude mcp add tokrepo -- npx tokrepo-mcp-server
+claude mcp add tokrepo -- npx -y tokrepo-mcp-server
 ```
 
 ### Cursor / Windsurf
@@ -19,7 +19,7 @@ Add to your MCP config (`~/.cursor/mcp.json`):
   "mcpServers": {
     "tokrepo": {
       "command": "npx",
-      "args": ["@tokrepo/mcp-server"]
+      "args": ["-y", "tokrepo-mcp-server"]
     }
   }
 }
@@ -27,8 +27,8 @@ Add to your MCP config (`~/.cursor/mcp.json`):
 
 ### OpenAI Codex / Gemini CLI
 ```bash
-codex --mcp-server tokrepo -- npx tokrepo-mcp-server
-gemini settings mcp add tokrepo -- npx tokrepo-mcp-server
+codex --mcp-server tokrepo -- npx -y tokrepo-mcp-server
+gemini settings mcp add tokrepo -- npx -y tokrepo-mcp-server
 ```
 
 ## What It Does
@@ -38,7 +38,9 @@ Once connected, your AI assistant can:
 - **Search** 200+ curated AI assets by keyword or category
 - **Browse** trending assets, filter by type (MCP, Skill, Prompt, Agent, Script)
 - **Get details** — full documentation, install instructions, and metadata
-- **Install** — get raw content ready to save or execute
+- **Plan before install** — get install plan v2 with policy decisions, rollback, and verification
+- **Safe Codex install** — dry-run by default; risky assets must be staged or explicitly approved
+- **Lifecycle control** — list installed assets, uninstall managed files, and roll back install sessions
 
 ## Available Tools
 
@@ -46,6 +48,12 @@ Once connected, your AI assistant can:
 |------|-------------|
 | `tokrepo_search` | Search assets by keyword and tag |
 | `tokrepo_detail` | Get full asset details by UUID |
+| `tokrepo_install_plan` | Get agent-native install plan v2 |
+| `tokrepo_codex_install` | Dry-run, stage, or install a Codex skill safely |
+| `tokrepo_clone_plan` | Bulk profile clone dry-run plan |
+| `tokrepo_installed` | List TokRepo-managed Codex installs |
+| `tokrepo_uninstall` | Dry-run or remove a managed Codex install |
+| `tokrepo_rollback` | Dry-run or roll back a prior Codex install session |
 | `tokrepo_install` | Get raw installable content |
 | `tokrepo_trending` | Browse popular/latest assets |
 
@@ -59,7 +67,9 @@ You: "What's trending on TokRepo?"
 AI: [calls tokrepo_trending] → Shows top assets by popularity
 
 You: "Install that cursor rules asset"
-AI: [calls tokrepo_install] → Returns raw content ready to save
+AI: [calls tokrepo_install_plan] → Reviews policy and actions
+AI: [calls tokrepo_codex_install with dry_run=false, confirm=true] → Writes only after explicit confirmation
+AI: [calls tokrepo_rollback with dry_run=true] → Shows exactly what would be removed before rollback
 ```
 
 ## Why TokRepo?

package/bin/server.js

@@ -7,25 +7,25 @@
  * Works with Claude Code, Cursor, Codex, Gemini CLI, and any MCP client.
  *
  * Usage:
- *   claude mcp add tokrepo -- npx @tokrepo/mcp-server
- *   npx @tokrepo/mcp-server
+ *   claude mcp add tokrepo -- npx -y tokrepo-mcp-server
+ *   npx -y tokrepo-mcp-server
  */
 
 const https = require('https');
-const readline = require('readline');
-const fs = require('fs');
-const path = require('path');
 const crypto = require('crypto');
+const { execFile } = require('child_process');
 
 const API_BASE = process.env.TOKREPO_API || 'https://api.tokrepo.com';
 const TOKREPO_URL = 'https://tokrepo.com';
 const TOKREPO_TOKEN = process.env.TOKREPO_TOKEN || '';
+const TOKREPO_CLI = process.env.TOKREPO_CLI || '';
+const SERVER_VERSION = '2.2.0';
 
 // ─── MCP Protocol (JSON-RPC over stdio) ───
 
 const SERVER_INFO = {
   name: 'tokrepo',
-  version: '2.0.0',
+  version: SERVER_VERSION,
 };
 
 const CAPABILITIES = {
@@ -53,6 +53,20 @@ const TOOLS = [
           description: 'Max results (default 10, max 20)',
           default: 10,
         },
+        target: {
+          type: 'string',
+          description: 'Optional agent target filter. Use codex for Codex-compatible assets.',
+          enum: ['codex'],
+        },
+        kind: {
+          type: 'string',
+          description: 'Optional asset kind filter, e.g. skill, prompt, knowledge, mcp_config, script',
+        },
+        policy: {
+          type: 'string',
+          description: 'Optional Codex install policy filter.',
+          enum: ['allow', 'confirm', 'stage_only', 'deny'],
+        },
       },
       required: ['query'],
     },
@@ -85,6 +99,152 @@ const TOOLS = [
       required: ['uuid'],
     },
   },
+  {
+    name: 'tokrepo_install_plan',
+    description: 'Return an agent-native install plan v2 for a TokRepo asset. Use this before installing: it includes preconditions, actions, risk profile, policy decision, rollback, and post-install verification.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        uuid: {
+          type: 'string',
+          description: 'Asset UUID, workflow URL slug, or workflow UUID from search/detail results',
+        },
+        target: {
+          type: 'string',
+          description: 'Install target. Currently codex is supported.',
+          enum: ['codex'],
+          default: 'codex',
+        },
+      },
+      required: ['uuid'],
+    },
+  },
+  {
+    name: 'tokrepo_codex_install',
+    description: 'Safely install a TokRepo asset into local Codex. Defaults to dry_run=true. To write files, set dry_run=false and confirm=true. Risky assets require stage=true or approve_risk=true.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        uuid: {
+          type: 'string',
+          description: 'Asset UUID, workflow URL, or search term accepted by the TokRepo CLI',
+        },
+        dry_run: {
+          type: 'boolean',
+          description: 'When true, return the plan only and do not write files. Default true.',
+          default: true,
+        },
+        stage: {
+          type: 'boolean',
+          description: 'Write only a staged install plan under ~/.codex/tokrepo/staged instead of activating a skill.',
+          default: false,
+        },
+        confirm: {
+          type: 'boolean',
+          description: 'Required when dry_run=false to prevent accidental writes.',
+          default: false,
+        },
+        approve_risk: {
+          type: 'boolean',
+          description: 'Required to activate assets whose policy decision is confirm or stage_only. Prefer stage=true for high-risk assets.',
+          default: false,
+        },
+      },
+      required: ['uuid'],
+    },
+  },
+  {
+    name: 'tokrepo_clone_plan',
+    description: 'Plan a bulk Codex install from a TokRepo user profile using the TokRepo CLI. Returns JSON dry-run output without writing files.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        user: {
+          type: 'string',
+          description: 'TokRepo username such as @henuwangkai or @me',
+        },
+        keyword: {
+          type: 'string',
+          description: 'Optional keyword filter, e.g. video',
+        },
+        types: {
+          type: 'string',
+          description: 'Optional comma-separated asset kinds, e.g. skill,prompt,knowledge',
+        },
+      },
+      required: ['user'],
+    },
+  },
+  {
+    name: 'tokrepo_installed',
+    description: 'List Codex assets installed by TokRepo from the local install manifest, including file status and session ids.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'tokrepo_uninstall',
+    description: 'Safely uninstall a TokRepo-managed Codex asset. Defaults to dry_run=true. To remove files, set dry_run=false and confirm=true. Local changes are blocked unless force=true.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        uuid: {
+          type: 'string',
+          description: 'Installed asset UUID, UUID prefix, or title.',
+        },
+        dry_run: {
+          type: 'boolean',
+          description: 'When true, return the removal plan without deleting files. Default true.',
+          default: true,
+        },
+        confirm: {
+          type: 'boolean',
+          description: 'Required when dry_run=false to prevent accidental deletes.',
+          default: false,
+        },
+        force: {
+          type: 'boolean',
+          description: 'Allow removal when local files changed since installation.',
+          default: false,
+        },
+      },
+      required: ['uuid'],
+    },
+  },
+  {
+    name: 'tokrepo_rollback',
+    description: 'Roll back a previous TokRepo Codex install session. Defaults to dry_run=true and last=true.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: {
+          type: 'string',
+          description: 'Session id to roll back. Omit when last=true.',
+        },
+        last: {
+          type: 'boolean',
+          description: 'Use the latest install/stage session. Default true.',
+          default: true,
+        },
+        dry_run: {
+          type: 'boolean',
+          description: 'When true, return the rollback plan without deleting files. Default true.',
+          default: true,
+        },
+        confirm: {
+          type: 'boolean',
+          description: 'Required when dry_run=false to prevent accidental deletes.',
+          default: false,
+        },
+        force: {
+          type: 'boolean',
+          description: 'Allow rollback when local files changed since installation.',
+          default: false,
+        },
+      },
+    },
+  },
   {
     name: 'tokrepo_trending',
     description: 'Get trending/popular AI assets on TokRepo. Use when user asks for recommended or popular AI tools.',
@@ -107,22 +267,22 @@ const TOOLS = [
   },
   {
     name: 'tokrepo_push',
-    description: 'Push files to TokRepo as an AI asset. Idempotent upsert — will create if new, update if title matches, skip if unchanged. Requires TOKREPO_TOKEN env var.',
+    description: 'Push ONE specific asset to TokRepo. You choose exactly which files to include — nothing is uploaded automatically. Set visibility=0 for private (only you can see) or visibility=1 for public. IMPORTANT: Always confirm with the user before pushing, and never push files that may contain secrets, credentials, or personal data. Requires TOKREPO_TOKEN env var.',
     inputSchema: {
       type: 'object',
       properties: {
         title: {
           type: 'string',
-          description: 'Asset title',
+          description: 'Asset title (descriptive name for this specific asset)',
         },
         files: {
           type: 'array',
-          description: 'Array of files to push',
+          description: 'Only the specific files for THIS asset — not all project files. Each file you list will be uploaded.',
           items: {
             type: 'object',
             properties: {
               name: { type: 'string', description: 'File name (e.g. "rules.md")' },
-              content: { type: 'string', description: 'File content' },
+              content: { type: 'string', description: 'File content — review for secrets before including' },
               type: { type: 'string', description: 'File type: skill, prompt, script, config, other', default: 'other' },
             },
             required: ['name', 'content'],
@@ -136,8 +296,8 @@ const TOOLS = [
         },
         visibility: {
           type: 'number',
-          description: '0=private, 1=public (default 1)',
-          default: 1,
+          description: '0 = private (only visible to you, safe default for personal assets), 1 = public (visible to everyone). When unsure, default to 0 (private).',
+          default: 0,
         },
       },
       required: ['title', 'files'],
@@ -247,7 +407,7 @@ function apiPost(urlPath, body, token) {
         'Content-Type': 'application/json',
         'Content-Length': Buffer.byteLength(bodyStr),
         'Authorization': `Bearer ${token}`,
-        'User-Agent': 'tokrepo-mcp-server/2.0.0',
+        'User-Agent': `tokrepo-mcp-server/${SERVER_VERSION}`,
       },
       timeout: 15000,
     }, (res) => {
@@ -278,7 +438,7 @@ function apiGetAuth(urlPath, token) {
       headers: {
         'Accept': 'application/json',
         'Authorization': `Bearer ${token}`,
-        'User-Agent': 'tokrepo-mcp-server/2.0.0',
+        'User-Agent': `tokrepo-mcp-server/${SERVER_VERSION}`,
       },
       timeout: 10000,
     }, (res) => {
@@ -300,35 +460,117 @@ function requireToken() {
   return TOKREPO_TOKEN;
 }
 
+function workflowIdentifier(input) {
+  const raw = String(input || '').trim();
+  const match = raw.match(/workflows\/([^/?#]+)/);
+  const value = match ? match[1] : raw;
+  if (/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(value)) {
+    return { param: 'uuid', value };
+  }
+  return { param: 'slug', value };
+}
+
+async function fetchInstallPlan(input, target = 'codex') {
+  const id = workflowIdentifier(input);
+  const params = new URLSearchParams({ target });
+  params.set(id.param, id.value);
+  let res = await apiGet(`/api/v1/tokenboard/workflows/install-plan?${params}`);
+  if (res.code === 200 && res.data?.plan) return res.data.plan;
+
+  if (id.param === 'slug') {
+    const search = await apiGet(`/api/v1/tokenboard/workflows/list?keyword=${encodeURIComponent(id.value.replace(/[-_.]/g, ' '))}&page=1&page_size=1&sort_by=views`);
+    const uuid = search.data?.list?.[0]?.uuid;
+    if (uuid) {
+      res = await apiGet(`/api/v1/tokenboard/workflows/install-plan?uuid=${encodeURIComponent(uuid)}&target=${encodeURIComponent(target)}`);
+      if (res.code === 200 && res.data?.plan) return res.data.plan;
+    }
+  }
+
+  throw new Error(res.message || `Install plan not found for ${input}`);
+}
+
+function planPolicyDecision(plan) {
+  const policy = plan?.policy_decision || plan?.policyDecision || {};
+  return String(policy.decision || 'confirm');
+}
+
+function runTokrepoCli(args) {
+  const command = TOKREPO_CLI || 'npx';
+  const finalArgs = TOKREPO_CLI ? args : ['-y', 'tokrepo@latest', ...args];
+  return new Promise((resolve, reject) => {
+    execFile(command, finalArgs, {
+      env: { ...process.env, TOKREPO_NONINTERACTIVE: '1' },
+      maxBuffer: 20 * 1024 * 1024,
+      timeout: 120000,
+    }, (err, stdout, stderr) => {
+      if (err) {
+        reject(new Error(`${err.message}${stderr ? `\n${stderr}` : ''}`));
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+function jsonText(title, data) {
+  return `${title}\n\n\`\`\`json\n${JSON.stringify(data, null, 2)}\n\`\`\``;
+}
+
 // ─── Tool Handlers ───
 
 async function handleSearch(args) {
-  const { query, tag, limit = 10 } = args;
+  const { query, tag, limit = 10, target = '', kind = '', policy = '' } = args;
+  if (target || kind || policy) {
+    const cliArgs = ['search', query, '--json', '--page-size', String(Math.min(limit, 20))];
+    if (target) cliArgs.push('--target', target);
+    if (kind) cliArgs.push('--kind', kind);
+    if (policy) cliArgs.push('--policy', policy);
+    const { stdout, stderr } = await runTokrepoCli(cliArgs);
+    let data;
+    try {
+      data = JSON.parse(stdout);
+    } catch {
+      data = { stdout, stderr };
+    }
+    return { content: [{ type: 'text', text: jsonText('Filtered TokRepo search results', data) }] };
+  }
+
+  // Normalize: hyphens/underscores/dots → spaces for better matching
+  const normalized = query.replace(/[-_.]/g, ' ').replace(/\s+/g, ' ').trim();
   const params = new URLSearchParams({
-    keyword: query,
+    keyword: normalized,
     page: '1',
     page_size: String(Math.min(limit, 20)),
     sort_by: 'popular',
   });
   if (tag) {
-    // Map tag name to tag_id (approximate)
     const tagMap = { agent: 11, coding: 7, efficiency: 10, 'cost-saving': 12, methodology: 15, 'data-analysis': 14, writing: 1, marketing: 16, learning: 17, research: 8 };
     if (tagMap[tag]) params.set('tag_id', String(tagMap[tag]));
   }
 
   const res = await apiGet(`/api/v1/tokenboard/workflows/list?${params}`);
   if (res.code !== 200 || !res.data?.list?.length) {
-    return { content: [{ type: 'text', text: `No assets found for "${query}". Try broader keywords.` }] };
+    // Suggest broader terms when no results
+    const words = normalized.split(' ');
+    let hint = 'Try broader keywords.';
+    if (words.length > 1) {
+      hint = `Try: "${words[0]}" or "${words.slice(0, 2).join(' ')}"`;
+    }
+    return { content: [{ type: 'text', text: `No assets found for "${query}". ${hint}` }] };
   }
 
   const items = res.data.list.slice(0, limit);
   const lines = items.map((item, i) => {
     const tags = (item.tags || []).map(t => t.name || t.slug).join(', ');
+    // Truncate description to keep agent context concise
+    let desc = item.description || '';
+    if (desc.length > 120) desc = desc.substring(0, 117) + '...';
     return [
       `${i + 1}. **${item.title}**`,
-      `   ${item.description || ''}`,
+      `   ${desc}`,
       `   Tags: ${tags || 'general'} | ★ ${item.vote_count || 0} | 👁 ${item.view_count || 0}`,
-      `   Install: \`tokrepo install ${item.uuid}\``,
+      `   Plan: call \`tokrepo_install_plan\` with uuid \`${item.uuid}\``,
+      `   Install: \`tokrepo install ${item.uuid} --target codex --dry-run --json\``,
       `   URL: ${TOKREPO_URL}/en/workflows/${item.uuid}`,
     ].join('\n');
   });
@@ -359,7 +601,8 @@ async function handleDetail(args) {
     `**Stars**: ${w.vote_count || 0} | **Views**: ${w.view_count || 0} | **Forks**: ${w.fork_count || 0}`,
     `**Author**: ${w.author_name || 'Anonymous'}`,
     `**URL**: ${TOKREPO_URL}/en/workflows/${w.uuid}`,
-    `**Install**: \`tokrepo install ${w.uuid}\``,
+    `**Plan**: call \`tokrepo_install_plan\` with uuid \`${w.uuid}\` before installing`,
+    `**Install**: \`tokrepo install ${w.uuid} --target codex --dry-run --json\``,
     ``,
     steps,
   ].join('\n');
@@ -380,6 +623,186 @@ async function handleInstall(args) {
   }
 }
 
+async function handleInstallPlan(args) {
+  const { uuid, target = 'codex' } = args;
+  const plan = await fetchInstallPlan(uuid, target);
+  const decision = planPolicyDecision(plan);
+  const command = decision === 'allow'
+    ? `tokrepo install ${plan.asset_uuid || uuid} --target codex --yes`
+    : `tokrepo install ${plan.asset_uuid || uuid} --target codex --dry-run --json`;
+  return {
+    content: [{
+      type: 'text',
+      text: jsonText(`Install plan v${plan.schema_version || 1} for ${plan.asset_title || uuid}\n\nPolicy: ${decision}\nCLI: ${command}`, plan),
+    }],
+  };
+}
+
+async function handleCodexInstall(args) {
+  const {
+    uuid,
+    dry_run = true,
+    stage = false,
+    confirm = false,
+    approve_risk = false,
+  } = args;
+
+  const plan = await fetchInstallPlan(uuid, 'codex');
+  const decision = planPolicyDecision(plan);
+  if (dry_run !== false) {
+    const cliArgs = ['install', plan.asset_uuid || uuid, '--target', 'codex', '--dry-run', '--json'];
+    if (stage) cliArgs.push('--stage');
+    const { stdout, stderr } = await runTokrepoCli(cliArgs);
+    let data;
+    try {
+      data = JSON.parse(stdout);
+    } catch {
+      data = { stdout, stderr };
+    }
+    return {
+      content: [{
+        type: 'text',
+        text: jsonText(`Dry run only. Policy: ${decision}. Set dry_run=false and confirm=true to write files.`, data),
+      }],
+    };
+  }
+
+  if (!confirm) {
+    const cliArgs = ['install', plan.asset_uuid || uuid, '--target', 'codex', '--dry-run', '--json'];
+    const { stdout, stderr } = await runTokrepoCli(cliArgs);
+    let data;
+    try {
+      data = JSON.parse(stdout);
+    } catch {
+      data = { stdout, stderr };
+    }
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: jsonText('Refused to write files because confirm=true was not provided. Dry-run plan follows.', data),
+      }],
+    };
+  }
+  if (decision === 'deny') {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: jsonText('Install policy denied this asset.', plan) }],
+    };
+  }
+  if ((decision === 'confirm' || decision === 'stage_only') && !stage && !approve_risk) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: jsonText(`Policy is ${decision}. Re-run with stage=true to avoid activation, or approve_risk=true to activate anyway.`, plan),
+      }],
+    };
+  }
+
+  const cliArgs = ['install', plan.asset_uuid || uuid, '--target', 'codex', '--json', '--yes'];
+  if (stage) cliArgs.push('--stage');
+  if (approve_risk) cliArgs.push('--approve-mcp');
+  const { stdout, stderr } = await runTokrepoCli(cliArgs);
+  let data;
+  try {
+    data = JSON.parse(stdout);
+  } catch {
+    data = { stdout, stderr };
+  }
+  return { content: [{ type: 'text', text: jsonText('Codex install result', data) }] };
+}
+
+async function handleClonePlan(args) {
+  const { user, keyword = '', types = '' } = args;
+  const cliArgs = ['clone', user, '--target', 'codex', '--dry-run', '--json'];
+  if (keyword) cliArgs.push('--keyword', keyword);
+  if (types) cliArgs.push('--types', types);
+  const { stdout, stderr } = await runTokrepoCli(cliArgs);
+  let data;
+  try {
+    data = JSON.parse(stdout);
+  } catch {
+    data = { stdout, stderr };
+  }
+  return { content: [{ type: 'text', text: jsonText('Bulk Codex clone dry-run plan', data) }] };
+}
+
+async function handleInstalled() {
+  const { stdout, stderr } = await runTokrepoCli(['installed', '--target', 'codex', '--json']);
+  let data;
+  try {
+    data = JSON.parse(stdout);
+  } catch {
+    data = { stdout, stderr };
+  }
+  return { content: [{ type: 'text', text: jsonText('TokRepo Codex installed assets', data) }] };
+}
+
+async function handleUninstall(args) {
+  const { uuid, dry_run = true, confirm = false, force = false } = args;
+  const cliArgs = ['uninstall', uuid, '--target', 'codex', '--json'];
+  if (dry_run !== false) cliArgs.push('--dry-run');
+  if (force) cliArgs.push('--force');
+
+  if (dry_run === false && !confirm) {
+    cliArgs.push('--dry-run');
+    const { stdout, stderr } = await runTokrepoCli(cliArgs);
+    let data;
+    try {
+      data = JSON.parse(stdout);
+    } catch {
+      data = { stdout, stderr };
+    }
+    return {
+      isError: true,
+      content: [{ type: 'text', text: jsonText('Refused to uninstall because confirm=true was not provided. Dry-run plan follows.', data) }],
+    };
+  }
+
+  const { stdout, stderr } = await runTokrepoCli(cliArgs);
+  let data;
+  try {
+    data = JSON.parse(stdout);
+  } catch {
+    data = { stdout, stderr };
+  }
+  return { content: [{ type: 'text', text: jsonText(dry_run === false ? 'TokRepo Codex uninstall result' : 'TokRepo Codex uninstall dry-run', data) }] };
+}
+
+async function handleRollback(args) {
+  const { session_id = '', last = true, dry_run = true, confirm = false, force = false } = args;
+  const cliArgs = ['rollback', '--target', 'codex', '--json'];
+  if (session_id) cliArgs.push(session_id);
+  else if (last !== false) cliArgs.push('--last');
+  if (dry_run !== false) cliArgs.push('--dry-run');
+  if (force) cliArgs.push('--force');
+
+  if (dry_run === false && !confirm) {
+    cliArgs.push('--dry-run');
+    const { stdout, stderr } = await runTokrepoCli(cliArgs);
+    let data;
+    try {
+      data = JSON.parse(stdout);
+    } catch {
+      data = { stdout, stderr };
+    }
+    return {
+      isError: true,
+      content: [{ type: 'text', text: jsonText('Refused to roll back because confirm=true was not provided. Dry-run plan follows.', data) }],
+    };
+  }
+
+  const { stdout, stderr } = await runTokrepoCli(cliArgs);
+  let data;
+  try {
+    data = JSON.parse(stdout);
+  } catch {
+    data = { stdout, stderr };
+  }
+  return { content: [{ type: 'text', text: jsonText(dry_run === false ? 'TokRepo Codex rollback result' : 'TokRepo Codex rollback dry-run', data) }] };
+}
+
 async function handleTrending(args) {
   const { sort = 'popular', limit = 10 } = args;
   const params = new URLSearchParams({
@@ -528,6 +951,12 @@ async function handleRequest(msg) {
           case 'tokrepo_search': result = await handleSearch(args || {}); break;
           case 'tokrepo_detail': result = await handleDetail(args || {}); break;
           case 'tokrepo_install': result = await handleInstall(args || {}); break;
+          case 'tokrepo_install_plan': result = await handleInstallPlan(args || {}); break;
+          case 'tokrepo_codex_install': result = await handleCodexInstall(args || {}); break;
+          case 'tokrepo_clone_plan': result = await handleClonePlan(args || {}); break;
+          case 'tokrepo_installed': result = await handleInstalled(args || {}); break;
+          case 'tokrepo_uninstall': result = await handleUninstall(args || {}); break;
+          case 'tokrepo_rollback': result = await handleRollback(args || {}); break;
           case 'tokrepo_trending': result = await handleTrending(args || {}); break;
           case 'tokrepo_push': result = await handlePush(args || {}); break;
           case 'tokrepo_status': result = await handleStatus(args || {}); break;
@@ -551,8 +980,13 @@ async function handleRequest(msg) {
 // ─── Stdio Transport ───
 
 function main() {
-  const rl = readline.createInterface({ input: process.stdin, terminal: false });
   let buffer = '';
+  let pending = 0;
+  let inputEnded = false;
+
+  const maybeExit = () => {
+    if (inputEnded && pending === 0) process.exit(0);
+  };
 
   process.stdin.on('data', (chunk) => {
     buffer += chunk.toString();
@@ -564,6 +998,7 @@ function main() {
       if (!trimmed) continue;
       try {
         const msg = JSON.parse(trimmed);
+        pending++;
         handleRequest(msg).then((response) => {
           if (response) {
             process.stdout.write(JSON.stringify(response) + '\n');
@@ -574,6 +1009,9 @@ function main() {
             id: msg.id || null,
             error: { code: -32603, message: e.message },
           }) + '\n');
+        }).finally(() => {
+          pending--;
+          maybeExit();
         });
       } catch (e) {
         // Skip malformed JSON
@@ -581,10 +1019,13 @@ function main() {
     }
   });
 
-  process.stdin.on('end', () => process.exit(0));
+  process.stdin.on('end', () => {
+    inputEnded = true;
+    maybeExit();
+  });
 
   // Log to stderr (not stdout, which is the MCP transport)
-  process.stderr.write(`TokRepo MCP Server v2.0.0 started${TOKREPO_TOKEN ? ' (authenticated)' : ' (read-only, set TOKREPO_TOKEN for write access)'}\n`);
+  process.stderr.write(`TokRepo MCP Server v${SERVER_VERSION} started${TOKREPO_TOKEN ? ' (authenticated)' : ' (read-only, set TOKREPO_TOKEN for write access)'}\n`);
 }
 
 main();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tokrepo-mcp-server",
-  "version": "2.0.0",
-  "description": "MCP server for TokRepo — search, browse, install, and push AI assets from any MCP client (Claude Code, Cursor, Codex, Gemini CLI).",
+  "version": "2.2.0",
+  "description": "Agent-native MCP server for TokRepo — search, plan, safely install, and push AI assets from MCP clients.",
   "mcpName": "io.github.tokrepo/mcp-server",
   "bin": {
     "tokrepo-mcp-server": "bin/server.js"