tokrepo-mcp-server 2.12.2 → 2.13.0

package/README.md

@@ -36,6 +36,7 @@ gemini settings mcp add tokrepo -- npx -y tokrepo-mcp-server
 Once connected, your AI assistant can:
 
 - **Discover during planning** — turn a task or capability gap into structured candidate skills, prompts, MCP configs, scripts, and workflows
+- **Resolve capability gaps** — select a candidate with verification evidence, install plan, lifecycle contract, next MCP calls, and CLI fallbacks before local build
 - **Search** 200+ curated AI assets by keyword or category with agent fit signals
 - **Browse** trending assets, filter by type (MCP, Skill, Prompt, Agent, Script)
 - **Get details** — full documentation, install instructions, and metadata
@@ -43,7 +44,7 @@ Once connected, your AI assistant can:
 - **Plan before install** — get install plan v2 with policy decisions, rollback, verification, `evidence_bundle`, SBOM-lite, and `signature_evidence`
 - **Safe Codex install** — dry-run by default; risky assets must be staged or explicitly approved
 - **Lifecycle control** — list, update, uninstall, and roll back managed Codex installs
-- **Post-task handoff planning** — inspect reusable local work with `tokrepo_handoff_plan` before any push, including `quality_gate`, package manifest, SBOM-lite, and provenance
+- **Post-task harvest** — inspect changed or explicit local files with `tokrepo_harvest` before any push, including private package drafts, `quality_gate`, package manifest, SBOM-lite, and provenance
 - **Project memory** — pair with `tokrepo init-agent --target all` so future agents know to call TokRepo during planning
 - **Discovery surfaces** — official MCP `server.json`, A2A agent card, portable agent manifest, tool catalog, `.well-known`, `agents.txt`, `llms.txt`, and npm metadata are kept machine-readable for agents and registries
 - **Funnel visibility** — anonymous aggregate events show whether agents actually discover, plan, install, hand off, and push reusable assets
@@ -53,6 +54,7 @@ Once connected, your AI assistant can:
 | Tool | Description |
 |------|-------------|
 | `tokrepo_discover` | Planning-time capability discovery from a task, environment, and constraints |
+| `tokrepo_resolve_capability` | Resolve a capability gap into a selected asset, verification evidence, install plan, lifecycle contract, next MCP calls, and CLI fallbacks |
 | `tokrepo_search` | Search assets by keyword/tag with `agent_fit` ranking |
 | `tokrepo_detail` | Get full asset details by UUID |
 | `tokrepo_verify` | Verify trust, hashes, permissions, policy, evidence_bundle, SBOM-lite, and signature_evidence before activation |
@@ -63,16 +65,17 @@ Once connected, your AI assistant can:
 | `tokrepo_uninstall` | Dry-run or remove a managed Codex install |
 | `tokrepo_rollback` | Dry-run or roll back a prior Codex install session |
 | `tokrepo_handoff_plan` | Read-only packaging plan with quality_gate and package manifest for reusable local work after a task |
+| `tokrepo_harvest` | Read-only package draft generator for reusable changed or explicit local files after a task |
 | `tokrepo_push` | Push one explicit asset to TokRepo after user confirmation |
 
 ## Example Conversations
 
 ```
 You: "Find me a good MCP server for databases"
-AI: [calls tokrepo_discover] → Ranks DBHub, Supabase MCP, PostgreSQL MCP as candidate capabilities
+AI: [calls tokrepo_resolve_capability] → Ranks DBHub, Supabase MCP, PostgreSQL MCP and returns verification/install-plan evidence for the selected candidate
 
 You: "What video assets should I install?"
-AI: [calls tokrepo_discover] → Finds relevant skills, checks fit and policy, then asks before installing
+AI: [calls tokrepo_resolve_capability] → Finds relevant skills, checks fit, trust, and policy, then asks before installing
 
 You: "Install that cursor rules asset"
 AI: [calls tokrepo_verify] → Checks trust_score_v2, permissions, blockers, and warnings
@@ -81,7 +84,7 @@ AI: [calls tokrepo_codex_install with dry_run=false, confirm=true] → Writes on
 AI: [calls tokrepo_rollback with dry_run=true] → Shows exactly what would be removed before rollback
 
 You: "We created a reusable project rule; save it for future agents"
-AI: [calls tokrepo_handoff_plan] → Returns explicit files, hashes, quality_gate, package manifest, SBOM-lite, provenance, metadata defaults, and private-by-default push guidance
+AI: [calls tokrepo_harvest] → Returns explicit files, hashes, quality_gate, package drafts, SBOM-lite, provenance, metadata defaults, and private-by-default push guidance
 AI: [asks for confirmation before tokrepo_push] → Uploads only reviewed files
 ```
 
@@ -93,7 +96,7 @@ Run this once in a project:
 npx tokrepo init-agent --target all
 ```
 
-It writes managed instructions to `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Cursor rules, GitHub Copilot instructions, Cline rules, Windsurf rules, Roo rules, OpenHands microagents, Aider conventions, `.mcp.json`, and `.tokrepo/agent.json`. The rule is simple: during planning, when the agent sees a capability gap, it should call `tokrepo_discover` before inventing a one-off local tool. After a task, agents can call `tokrepo_handoff_plan` or run `tokrepo agent-handoff --json` to suggest reusable files for user-confirmed private publishing.
+It writes managed instructions to `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Cursor rules, GitHub Copilot instructions, Cline rules, Windsurf rules, Roo rules, OpenHands microagents, Aider conventions, `.mcp.json`, and `.tokrepo/agent.json`. The rule is simple: during planning, when the agent sees a capability gap, it should call `tokrepo_resolve_capability` or `tokrepo_discover` before inventing a one-off local tool. After a task, agents can call `tokrepo_harvest` or run `tokrepo harvest --changed --json` to suggest reusable files for user-confirmed private publishing.
 
 ## Machine-Readable Listing
 
@@ -110,6 +113,8 @@ Registries and agents can discover this server through:
 - Multi-agent compatibility: [tokrepo.com/evals/multi-agent-compatibility.json](https://tokrepo.com/evals/multi-agent-compatibility.json)
 - Agent memory schema: [tokrepo.com/schemas/agent-memory.schema.json](https://tokrepo.com/schemas/agent-memory.schema.json)
 - Agent evidence bundle schema: [tokrepo.com/schemas/agent-evidence-bundle.schema.json](https://tokrepo.com/schemas/agent-evidence-bundle.schema.json)
+- Capability resolution schema: [tokrepo.com/schemas/capability-resolution.schema.json](https://tokrepo.com/schemas/capability-resolution.schema.json)
+- Harvest report schema: [tokrepo.com/schemas/harvest-report.schema.json](https://tokrepo.com/schemas/harvest-report.schema.json)
 - Handoff package schema: [tokrepo.com/schemas/handoff-package.schema.json](https://tokrepo.com/schemas/handoff-package.schema.json)
 - Agent text entry: [tokrepo.com/agents.txt](https://tokrepo.com/agents.txt)
 - Agent instructions: [tokrepo.com/agent-instructions/tokrepo.md](https://tokrepo.com/agent-instructions/tokrepo.md)
@@ -118,7 +123,7 @@ Registries and agents can discover this server through:
 
 Use `https://tokrepo.com/agent-ecosystem.json` for agent marketplace submissions, starter templates, README snippets, install guides, and example projects. It contains canonical listing copy, ecosystem channels, target project-memory files, and verification commands.
 
-TokRepo emits anonymous aggregate funnel events for `tokrepo_discover`, `tokrepo_verify`, `tokrepo_install_plan`, install dry-runs, installs, handoffs, and pushes. It does not send task text or file contents. Disable with `TOKREPO_TELEMETRY=0`.
+TokRepo emits anonymous aggregate funnel events for `tokrepo_resolve_capability`, `tokrepo_discover`, `tokrepo_verify`, `tokrepo_install_plan`, install dry-runs, installs, harvests, handoffs, and pushes. It does not send task text or file contents. Disable with `TOKREPO_TELEMETRY=0`.
 
 ## Why TokRepo?
 

package/bin/server.js

@@ -20,7 +20,7 @@ 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.12.2';
+const SERVER_VERSION = '2.13.0';
 
 // ─── MCP Protocol (JSON-RPC over stdio) ───
 
@@ -69,6 +69,60 @@ const TOOLS = [
       required: ['task'],
     },
   },
+  {
+    name: 'tokrepo_resolve_capability',
+    description: 'Resolve a planning-time capability gap into a selected TokRepo asset, verification evidence, and install plan. Use this as the default first action when the agent identifies a missing skill, MCP, prompt, script, workflow, or reusable capability. Read-only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task: {
+          type: 'string',
+          description: 'The user goal, subtask, or capability gap the agent needs to solve.',
+        },
+        target: {
+          type: 'string',
+          description: 'Optional agent/runtime target. Use "any" or "all" for generic cross-agent resolution.',
+          enum: ['any', 'all', 'codex', 'claude_code', 'gemini_cli', 'cursor', 'copilot', 'cline', 'windsurf', 'roo', 'openhands', 'aider', 'mcp_client'],
+          default: 'any',
+        },
+        environment: {
+          type: 'object',
+          description: 'Optional local environment signals, such as project_type, frameworks, language, can_run_shell, can_write_files, or browser_available.',
+          additionalProperties: true,
+        },
+        constraints: {
+          type: 'object',
+          description: 'Optional constraints such as kind, policy, risk, language, prefer_verified, or must_not_modify_files.',
+          additionalProperties: true,
+        },
+        kind: {
+          type: 'string',
+          description: 'Optional asset kind preference, e.g. skill, prompt, knowledge, mcp_config, script, workflow.',
+        },
+        policy: {
+          type: 'string',
+          description: 'Optional install policy preference.',
+          enum: ['allow', 'confirm', 'stage_only', 'deny'],
+        },
+        min_trust: {
+          type: 'number',
+          description: 'Minimum trust_score_v2 threshold before recommending direct use. Default 70.',
+          default: 70,
+        },
+        min_fit: {
+          type: 'number',
+          description: 'Minimum fit score threshold before recommending direct use. Default 70.',
+          default: 70,
+        },
+        limit: {
+          type: 'number',
+          description: 'Max discovery candidates (default 6, max 10).',
+          default: 6,
+        },
+      },
+      required: ['task'],
+    },
+  },
   {
     name: 'tokrepo_search',
     description: 'Search TokRepo for AI assets (skills, prompts, MCP configs, scripts, workflows). Returns matching assets with titles, descriptions, tags, stars, and install commands. Use this when the user asks to find AI tools, MCP servers, skills, prompts, or workflows.',
@@ -359,6 +413,30 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: 'tokrepo_harvest',
+    description: 'Read-only post-task harvest. Inspect changed or explicit local files and produce private-by-default reusable asset package drafts with metadata, usage examples, risk notes, compatibility, and quality gates. Never publishes automatically.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        paths: {
+          type: 'array',
+          description: 'Optional explicit local paths to inspect. Omit to scan common reusable agent asset files.',
+          items: { type: 'string' },
+        },
+        changed: {
+          type: 'boolean',
+          description: 'When true, inspect git-changed files from the current repository.',
+          default: false,
+        },
+        limit: {
+          type: 'number',
+          description: 'Max drafts to return (default 12, max 30).',
+          default: 12,
+        },
+      },
+    },
+  },
   {
     name: 'tokrepo_eval_agent',
     description: 'Run TokRepo agent-native evals through the CLI. Verifies filtered search, install-plan contracts, metadata quality reporting, Codex install verification, manifest state, and rollback using temporary local state.',
@@ -482,6 +560,7 @@ const TOOLS = [
 
 const EXPOSED_TOOL_NAMES = new Set([
   'tokrepo_discover',
+  'tokrepo_resolve_capability',
   'tokrepo_search',
   'tokrepo_detail',
   'tokrepo_install_plan',
@@ -492,6 +571,7 @@ const EXPOSED_TOOL_NAMES = new Set([
   'tokrepo_uninstall',
   'tokrepo_rollback',
   'tokrepo_handoff_plan',
+  'tokrepo_harvest',
   'tokrepo_push',
 ]);
 
@@ -503,6 +583,13 @@ const TOOL_ANNOTATIONS = {
     idempotentHint: true,
     openWorldHint: true,
   },
+  tokrepo_resolve_capability: {
+    title: 'Resolve a capability gap into a verified asset and install plan',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
   tokrepo_search: {
     title: 'Search reusable AI assets',
     readOnlyHint: true,
@@ -573,6 +660,13 @@ const TOOL_ANNOTATIONS = {
     idempotentHint: true,
     openWorldHint: false,
   },
+  tokrepo_harvest: {
+    title: 'Harvest reusable local work into private-by-default package drafts',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
   tokrepo_push: {
     title: 'Publish explicit reviewed files to TokRepo after confirmation',
     readOnlyHint: false,
@@ -675,6 +769,7 @@ function telemetryDisabled() {
 
 function eventForTool(name, args = {}) {
   if (name === 'tokrepo_discover') return 'mcp_discover';
+  if (name === 'tokrepo_resolve_capability') return 'capability_resolve';
   if (name === 'tokrepo_search') return 'mcp_search';
   if (name === 'tokrepo_detail') return 'mcp_detail';
   if (name === 'tokrepo_install_plan') return 'install_plan';
@@ -682,6 +777,7 @@ function eventForTool(name, args = {}) {
   if (name === 'tokrepo_codex_install') return args.dry_run === false ? 'install_apply' : 'install_dry_run';
   if (name === 'tokrepo_rollback') return 'rollback_plan';
   if (name === 'tokrepo_handoff_plan') return 'handoff_plan';
+  if (name === 'tokrepo_harvest') return 'harvest_plan';
   if (name === 'tokrepo_push') return 'push';
   return '';
 }
@@ -1624,6 +1720,71 @@ async function handleHandoffPlan(args) {
   return { content: [{ type: 'text', text: jsonText('TokRepo agent handoff plan', data) }] };
 }
 
+async function handleResolveCapability(args) {
+  const {
+    task = '',
+    target = args?.constraints?.target || 'any',
+    kind = args?.constraints?.kind || '',
+    policy = args?.constraints?.policy || '',
+    limit = 6,
+    min_trust = 70,
+    min_fit = 70,
+    offline = false,
+  } = args || {};
+  const taskText = compactText(task, 500);
+  if (!taskText) {
+    return { content: [{ type: 'text', text: 'Error: task is required.' }], isError: true };
+  }
+  const cliArgs = [
+    'resolve',
+    taskText,
+    '--json',
+    '--target',
+    String(target || 'any'),
+    '--limit',
+    String(Math.min(Math.max(Number(limit) || 6, 1), 10)),
+    '--min-trust',
+    String(Math.min(Math.max(Number(min_trust) || 70, 0), 100)),
+    '--min-fit',
+    String(Math.min(Math.max(Number(min_fit) || 70, 0), 100)),
+  ];
+  if (kind) cliArgs.push('--kind', String(kind));
+  if (policy) cliArgs.push('--policy', String(policy));
+  if (offline) cliArgs.push('--offline');
+
+  const { stdout, stderr } = await runTokrepoCli(cliArgs);
+  let data;
+  try {
+    data = JSON.parse(stdout);
+  } catch {
+    data = { stdout, stderr };
+  }
+  return {
+    structuredContent: data,
+    content: [{ type: 'text', text: jsonText('TokRepo capability resolution', data) }],
+  };
+}
+
+async function handleHarvest(args) {
+  const { paths = [], changed = false, limit = 12 } = args || {};
+  const cliArgs = ['harvest', '--json', '--limit', String(Math.min(Math.max(Number(limit) || 12, 1), 30))];
+  if (changed) cliArgs.push('--changed');
+  for (const inputPath of asArray(paths)) {
+    if (inputPath) cliArgs.push(String(inputPath));
+  }
+  const { stdout, stderr } = await runTokrepoCli(cliArgs);
+  let data;
+  try {
+    data = JSON.parse(stdout);
+  } catch {
+    data = { stdout, stderr };
+  }
+  return {
+    structuredContent: data,
+    content: [{ type: 'text', text: jsonText('TokRepo harvest report', data) }],
+  };
+}
+
 async function handleEvalAgent(args) {
   const { uuid = '', keyword = '' } = args || {};
   const cliArgs = ['eval-agent', '--json'];
@@ -1795,6 +1956,7 @@ async function handleRequest(msg) {
         }
         switch (name) {
           case 'tokrepo_discover': result = await handleDiscover(args || {}); break;
+          case 'tokrepo_resolve_capability': result = await handleResolveCapability(args || {}); break;
           case 'tokrepo_search': result = await handleSearch(args || {}); break;
           case 'tokrepo_detail': result = await handleDetail(args || {}); break;
           case 'tokrepo_install': result = await handleInstall(args || {}); break;
@@ -1807,6 +1969,7 @@ async function handleRequest(msg) {
           case 'tokrepo_uninstall': result = await handleUninstall(args || {}); break;
           case 'tokrepo_rollback': result = await handleRollback(args || {}); break;
           case 'tokrepo_handoff_plan': result = await handleHandoffPlan(args || {}); break;
+          case 'tokrepo_harvest': result = await handleHarvest(args || {}); break;
           case 'tokrepo_eval_agent': result = await handleEvalAgent(args || {}); break;
           case 'tokrepo_trending': result = await handleTrending(args || {}); break;
           case 'tokrepo_push': result = await handlePush(args || {}); break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokrepo-mcp-server",
-  "version": "2.12.2",
+  "version": "2.13.0",
   "description": "Agent-native MCP server for TokRepo - discover, verify, plan, safely install, hand off, and push AI assets from MCP clients.",
   "mcpName": "io.github.henu-wang/tokrepo-mcp-server",
   "bin": {
@@ -43,6 +43,8 @@
     "tool-discovery",
     "llms-txt",
     "trust-verification",
+    "capability-resolution",
+    "asset-harvest",
     "agent-audit",
     "agent-evals"
   ],