tokrepo-mcp-server 2.5.0 → 2.7.0

package/README.md

@@ -35,17 +35,20 @@ gemini settings mcp add tokrepo -- npx -y tokrepo-mcp-server
 
 Once connected, your AI assistant can:
 
-- **Search** 200+ curated AI assets by keyword or category with Codex-first `agent_fit` ranking
+- **Discover during planning** — turn a task or capability gap into structured candidate skills, prompts, MCP configs, scripts, and workflows
+- **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
 - **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, update, uninstall, and roll back managed Codex installs
+- **Project memory** — pair with `tokrepo init-agent --target all` so future agents know to call TokRepo during planning
 
 ## Available Tools
 
 | Tool | Description |
 |------|-------------|
+| `tokrepo_discover` | Planning-time capability discovery from a task, environment, and constraints |
 | `tokrepo_search` | Search assets by keyword/tag with `agent_fit` ranking |
 | `tokrepo_detail` | Get full asset details by UUID |
 | `tokrepo_install_plan` | Get agent-native install plan v2 |
@@ -60,10 +63,10 @@ Once connected, your AI assistant can:
 
 ```
 You: "Find me a good MCP server for databases"
-AI: [calls tokrepo_search] → Shows DBHub, Supabase MCP, PostgreSQL MCP with install commands
+AI: [calls tokrepo_discover] → Ranks DBHub, Supabase MCP, PostgreSQL MCP as candidate capabilities
 
 You: "What video assets should I install?"
-AI: [calls tokrepo_search] → Ranks native Codex assets by `agent_fit`
+AI: [calls tokrepo_discover] → Finds relevant skills, checks fit and policy, then asks before installing
 
 You: "Install that cursor rules asset"
 AI: [calls tokrepo_install_plan] → Reviews policy and actions
@@ -71,6 +74,16 @@ 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
 ```
 
+## Make Future Agents Discover TokRepo
+
+Run this once in a project:
+
+```bash
+npx tokrepo init-agent --target all
+```
+
+It writes managed instructions to `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Cursor rules, and `.mcp.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 run `tokrepo agent-handoff --json` to suggest reusable files for user-confirmed private publishing.
+
 ## Why TokRepo?
 
 TokRepo is the **open registry for AI assets** — like npm for packages, but for AI skills, prompts, MCP configs, and workflows.

package/bin/server.js

@@ -19,7 +19,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.5.0';
+const SERVER_VERSION = '2.7.0';
 
 // ─── MCP Protocol (JSON-RPC over stdio) ───
 
@@ -33,9 +33,44 @@ const CAPABILITIES = {
 };
 
 const TOOLS = [
+  {
+    name: 'tokrepo_discover',
+    description: 'Planning-time capability discovery for agents. Call this during autonomous planning when the task may need a reusable skill, MCP config, prompt, script, workflow, or other AI asset. Returns structured candidates, fit signals, and next MCP calls.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task: {
+          type: 'string',
+          description: 'The user goal, subtask, or capability gap the agent is planning for.',
+        },
+        target: {
+          type: 'string',
+          description: 'Optional agent/runtime target. Use "any" for generic discovery.',
+          enum: ['any', 'codex', 'claude_code', 'gemini_cli', 'cursor', 'windsurf', '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,
+        },
+        limit: {
+          type: 'number',
+          description: 'Max 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, Claude skills, prompts, or workflows.',
+    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.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -55,9 +90,8 @@ const TOOLS = [
         },
         target: {
           type: 'string',
-          description: 'Agent target filter. Defaults to codex so results include agent_fit ranking for installable Codex assets.',
-          enum: ['codex'],
-          default: 'codex',
+          description: 'Optional agent target filter. Use "any" or omit it for generic discovery.',
+          enum: ['any', 'codex', 'claude_code', 'gemini_cli', 'cursor', 'windsurf', 'mcp_client'],
         },
         kind: {
           type: 'string',
@@ -112,8 +146,8 @@ const TOOLS = [
         },
         target: {
           type: 'string',
-          description: 'Install target. Currently codex is supported.',
-          enum: ['codex'],
+          description: 'Install target adapter. Codex is native; other adapters may return planned or staged contracts as they become available.',
+          enum: ['codex', 'claude_code', 'gemini_cli'],
           default: 'codex',
         },
       },
@@ -397,6 +431,7 @@ const TOOLS = [
 ];
 
 const EXPOSED_TOOL_NAMES = new Set([
+  'tokrepo_discover',
   'tokrepo_search',
   'tokrepo_detail',
   'tokrepo_install_plan',
@@ -577,13 +612,313 @@ function jsonText(title, data) {
   return `${title}\n\n\`\`\`json\n${JSON.stringify(data, null, 2)}\n\`\`\``;
 }
 
+function compactText(value, maxLength = 240) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, Math.max(0, maxLength - 3))}...`;
+}
+
+function clampLimit(value, fallback, max) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.min(Math.floor(parsed), max);
+}
+
+function asArray(value) {
+  if (Array.isArray(value)) return value.filter(Boolean);
+  if (value === undefined || value === null || value === '') return [];
+  return [value];
+}
+
+function normalizeTarget(value) {
+  const raw = compactText(value || 'any', 64).toLowerCase().replace(/[-\s]+/g, '_');
+  const aliases = {
+    claude: 'claude_code',
+    claude_code: 'claude_code',
+    gemini: 'gemini_cli',
+    gemini_cli: 'gemini_cli',
+    codex: 'codex',
+    cursor: 'cursor',
+    windsurf: 'windsurf',
+    mcp: 'mcp_client',
+    mcp_client: 'mcp_client',
+    any: 'any',
+    all: 'any',
+  };
+  return aliases[raw] || raw || 'any';
+}
+
+function itemTags(item) {
+  return asArray(item.tags).map(tag => compactText(tag.name || tag.slug || tag, 64)).filter(Boolean);
+}
+
+function itemAgentMetadata(item) {
+  return item.agent_metadata || item.agentMetadata || item.metadata?.agent_metadata || {};
+}
+
+function itemAgentFit(item) {
+  return item.agent_fit || item.agentFit || item.fit || {};
+}
+
+function candidateUuid(item) {
+  return compactText(item.uuid || item.workflow_uuid || item.workflowUuid || item.id, 128);
+}
+
+function candidateKind(item, metadata, fit) {
+  return compactText(item.asset_kind || item.assetKind || metadata.asset_kind || fit.asset_kind || '', 64);
+}
+
+function candidateTargets(item, metadata) {
+  const targets = [
+    ...asArray(item.target_tools || item.targetTools),
+    ...asArray(metadata.target_tools || metadata.targetTools),
+  ].map(target => compactText(target, 64)).filter(Boolean);
+  return [...new Set(targets)];
+}
+
+function extractSearchTerms(value, maxTerms = 8) {
+  const text = compactText(value, 240);
+  const stopWords = new Set([
+    'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'can', 'do', 'for', 'from', 'how',
+    'i', 'in', 'into', 'is', 'it', 'me', 'my', 'of', 'on', 'or', 'our', 'the', 'this',
+    'to', 'use', 'with', 'fix', 'make', 'need', 'needs', 'want', 'issue', 'issues',
+  ]);
+  const words = text
+    .split(/[^a-zA-Z0-9+#.]+/)
+    .map(word => word.trim().toLowerCase())
+    .filter(word => word.length >= 2 && !stopWords.has(word));
+  const unique = [...new Set(words)].slice(0, maxTerms);
+  return unique.length ? unique : [compactText(text, 80)];
+}
+
+function buildDiscoveryQuery(task, environment, constraints) {
+  const parts = extractSearchTerms(task, 6);
+  for (const key of ['project_type', 'language', 'framework', 'domain']) {
+    if (environment?.[key]) parts.push(...extractSearchTerms(environment[key], 2));
+  }
+  for (const value of asArray(environment?.frameworks)) parts.push(...extractSearchTerms(value, 2));
+  if (constraints?.kind) parts.push(...extractSearchTerms(constraints.kind, 2));
+  return compactText([...new Set(parts)].join(' '), 100);
+}
+
+function scoreDiscoveryCandidate(item, task, target, constraints = {}) {
+  const metadata = itemAgentMetadata(item);
+  const fit = itemAgentFit(item);
+  const tags = itemTags(item);
+  const targets = candidateTargets(item, metadata);
+  const terms = extractSearchTerms(task, 10);
+  const haystack = [
+    item.title,
+    item.description,
+    tags.join(' '),
+    metadata.entrypoint,
+    metadata.asset_kind,
+  ].filter(Boolean).join(' ').toLowerCase();
+  let score = Number.isFinite(Number(fit.score)) ? Number(fit.score) : 45;
+  const reasons = [];
+  const matched = terms.filter(term => haystack.includes(term));
+  if (matched.length) {
+    score += Math.min(24, matched.length * 4);
+    reasons.push(`task term match: ${matched.slice(0, 5).join(', ')}`);
+  }
+  if (target && target !== 'any') {
+    if (targets.includes(target) || fit.target === target) {
+      score += 12;
+      reasons.push(`target matches ${target}`);
+    } else if (targets.length) {
+      score -= 10;
+      reasons.push(`target metadata is ${targets.join(', ')}`);
+    }
+  }
+  const kind = candidateKind(item, metadata, fit);
+  if (constraints.kind && String(kind).toLowerCase() === String(constraints.kind).toLowerCase()) {
+    score += 8;
+    reasons.push(`kind matches ${constraints.kind}`);
+  }
+  const policy = fit.policy || item.policy || '';
+  if (policy === 'allow') {
+    score += 6;
+    reasons.push('policy allow');
+  } else if (policy === 'deny') {
+    score -= 35;
+    reasons.push('policy deny');
+  } else if (policy === 'stage_only' || policy === 'confirm') {
+    score -= 6;
+    reasons.push(`policy ${policy}`);
+  }
+  const trust = item.trust || item.agent_trust || {};
+  if (trust.review_status === 'reviewed' || trust.verified_publisher) {
+    score += 4;
+    reasons.push('reviewed or verified');
+  }
+  return { score: Math.max(0, Math.min(100, Math.round(score))), reasons };
+}
+
+function buildCandidate(item, target, ranking = {}) {
+  const uuid = candidateUuid(item);
+  const metadata = itemAgentMetadata(item);
+  const fit = itemAgentFit(item);
+  const kind = candidateKind(item, metadata, fit);
+  const targets = candidateTargets(item, metadata);
+  const planTarget = target && target !== 'any' && ['codex', 'claude_code', 'gemini_cli'].includes(target)
+    ? target
+    : 'codex';
+  const urlSlug = compactText(item.slug || uuid, 180);
+  const score = Number.isFinite(Number(fit.score)) ? Number(fit.score) : null;
+  const why = asArray(fit.why).map(reason => compactText(reason, 160)).filter(Boolean);
+
+  return {
+    uuid,
+    slug: compactText(item.slug || '', 180),
+    title: compactText(item.title, 160),
+    description: compactText(item.description || item.summary || '', 320),
+    url: urlSlug ? `${TOKREPO_URL}/en/workflows/${urlSlug}` : '',
+    tags: itemTags(item),
+    capability: {
+      kind,
+      install_mode: compactText(item.install_mode || item.installMode || metadata.install_mode || fit.install_mode || '', 64),
+      entrypoint: compactText(item.entrypoint || metadata.entrypoint || '', 160),
+      target_tools: targets,
+    },
+    fit: {
+      target: compactText(fit.target || target || 'any', 64),
+      score,
+      status: compactText(fit.status || item.agent_status || '', 64),
+      policy: compactText(fit.policy || item.policy || '', 64),
+      why,
+    },
+    ranking,
+    next_mcp_calls: [
+      { tool: 'tokrepo_detail', arguments: { uuid } },
+      { tool: 'tokrepo_install_plan', arguments: { uuid, target: planTarget } },
+    ],
+    commands: {
+      inspect: `npx tokrepo detail ${uuid} --json`,
+      dry_run_install: planTarget === 'codex'
+        ? `npx tokrepo install ${uuid} --dry-run --json`
+        : `npx tokrepo install ${uuid} --target ${planTarget} --dry-run --json`,
+    },
+    agent_use_contract: [
+      'Use only if the capability matches the current subtask.',
+      'Call tokrepo_detail before install to inspect content and metadata.',
+      'Call tokrepo_install_plan and respect policy_decision before writing files.',
+      'Prefer dry-run or stage-only when risk or fit is uncertain.',
+      'After using it, verify the original task outcome and record failures.',
+    ],
+  };
+}
+
 // ─── Tool Handlers ───
 
+async function handleDiscover(args) {
+  const task = compactText(args.task, 500);
+  if (!task) {
+    return {
+      content: [{ type: 'text', text: 'task is required for tokrepo_discover' }],
+      isError: true,
+    };
+  }
+
+  const environment = args.environment && typeof args.environment === 'object' ? args.environment : {};
+  const constraints = args.constraints && typeof args.constraints === 'object' ? args.constraints : {};
+  const target = normalizeTarget(args.target || constraints.target || 'any');
+  const limit = clampLimit(args.limit, 6, 10);
+  const kind = compactText(args.kind || constraints.kind || '', 64);
+  const policy = compactText(args.policy || constraints.policy || '', 64);
+  const query = buildDiscoveryQuery(task, environment, constraints);
+
+  let items = [];
+  let discoveryError = '';
+  let selectedQuery = query;
+  const taskTerms = extractSearchTerms(task, 6);
+  const attempts = [
+    { query, kind, policy },
+    { query: taskTerms.slice(0, 3).join(' '), kind, policy },
+    { query: taskTerms.slice(0, 2).join(' '), kind: '', policy: '' },
+    { query: taskTerms[0] || query, kind: '', policy: '' },
+  ].filter(attempt => attempt.query);
+  const seenAttempts = new Set();
+  const errors = [];
+
+  for (const attempt of attempts) {
+    const key = `${attempt.query}|${attempt.kind}|${attempt.policy}`;
+    if (seenAttempts.has(key)) continue;
+    seenAttempts.add(key);
+    const params = new URLSearchParams({
+      keyword: attempt.query,
+      page: '1',
+      page_size: String(limit),
+      sort_by: 'popular',
+    });
+    if (target && target !== 'any') params.set('target', target);
+    if (attempt.kind) params.set('kind', attempt.kind);
+    if (attempt.policy) params.set('policy', attempt.policy);
+
+    try {
+      const res = await apiGet(`/api/v1/tokenboard/workflows/list?${params}`);
+      items = res.code === 200 ? (res.data?.list || res.data?.items || []) : [];
+      if (res.code !== 200) errors.push(compactText(res.message || `API returned code ${res.code}`, 200));
+      if (items.length) {
+        selectedQuery = attempt.query;
+        break;
+      }
+    } catch (e) {
+      errors.push(compactText(e.message, 200));
+    }
+  }
+  discoveryError = errors.find(Boolean) || '';
+  const payload = {
+    schema_version: 1,
+    intent: {
+      task,
+      target,
+      query: selectedQuery,
+      queries_tried: [...seenAttempts].map(key => key.split('|')[0]),
+      environment,
+      constraints,
+    },
+    recommended_flow: [
+      'During planning, call tokrepo_discover when the task exposes a capability gap.',
+      'Rank candidates by fit, policy, trust, and whether the entrypoint matches the active agent runtime.',
+      'Call tokrepo_detail for the top candidate before installation or use.',
+      'Call tokrepo_install_plan and respect policy_decision, rollback, and verification steps.',
+      'Dry-run or stage when the asset may write files, execute code, require secrets, or change global config.',
+      'Use the installed capability only for the matching subtask, then verify the user goal.',
+      'If the agent creates a reusable improvement, ask before publishing and use tokrepo_push with explicit files.',
+    ],
+    candidates: items
+      .map(item => buildCandidate(item, target, scoreDiscoveryCandidate(item, task, target, constraints)))
+      .filter(candidate => candidate.uuid)
+      .sort((a, b) => (b.ranking?.score || 0) - (a.ranking?.score || 0))
+      .slice(0, limit),
+    empty_state: items.length ? null : {
+      message: discoveryError
+        ? `TokRepo discovery could not fetch live candidates for "${selectedQuery}".`
+        : `No TokRepo candidates found for "${selectedQuery}".`,
+      error: discoveryError || undefined,
+      suggested_queries: [
+        task.split(/\s+/).slice(0, 4).join(' '),
+        compactText([kind, environment.project_type, environment.language].filter(Boolean).join(' '), 120),
+        'agent skill workflow',
+      ].filter(Boolean),
+    },
+  };
+
+  return {
+    content: [{
+      type: 'text',
+      text: jsonText('TokRepo planning-time discovery', payload),
+    }],
+  };
+}
+
 async function handleSearch(args) {
-  const { query, tag, limit = 10, target = 'codex', kind = '', policy = '' } = args;
-  if (target || kind || policy) {
+  const { query, tag, limit = 10, target = '', kind = '', policy = '' } = args;
+  const normalizedTarget = normalizeTarget(target || 'any');
+  const targetFilter = normalizedTarget === 'any' ? '' : normalizedTarget;
+  if (targetFilter || kind || policy) {
     const cliArgs = ['search', query, '--json', '--page-size', String(Math.min(limit, 20))];
-    if (target) cliArgs.push('--target', target);
+    if (targetFilter) cliArgs.push('--target', targetFilter);
     if (kind) cliArgs.push('--kind', kind);
     if (policy) cliArgs.push('--policy', policy);
     const { stdout, stderr } = await runTokrepoCli(cliArgs);
@@ -631,7 +966,7 @@ async function handleSearch(args) {
       `   ${desc}`,
       `   Tags: ${tags || 'general'} | ★ ${item.vote_count || 0} | 👁 ${item.view_count || 0}`,
       `   Plan: call \`tokrepo_install_plan\` with uuid \`${item.uuid}\``,
-      `   Install: \`tokrepo install ${item.uuid} --target codex --dry-run --json\``,
+      `   Install: \`tokrepo install ${item.uuid} --dry-run --json\``,
       `   URL: ${TOKREPO_URL}/en/workflows/${item.uuid}`,
     ].join('\n');
   });
@@ -663,7 +998,7 @@ async function handleDetail(args) {
     `**Author**: ${w.author_name || 'Anonymous'}`,
     `**URL**: ${TOKREPO_URL}/en/workflows/${w.uuid}`,
     `**Plan**: call \`tokrepo_install_plan\` with uuid \`${w.uuid}\` before installing`,
-    `**Install**: \`tokrepo install ${w.uuid} --target codex --dry-run --json\``,
+    `**Install**: \`tokrepo install ${w.uuid} --dry-run --json\``,
     ``,
     steps,
   ].join('\n');
@@ -689,8 +1024,8 @@ async function handleInstallPlan(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`;
+    ? `tokrepo install ${plan.asset_uuid || uuid} --target ${target} --yes`
+    : `tokrepo install ${plan.asset_uuid || uuid} --target ${target} --dry-run --json`;
   return {
     content: [{
       type: 'text',
@@ -1056,7 +1391,18 @@ async function handleRequest(msg) {
       const { name, arguments: args } = params || {};
       let result;
       try {
+        if (!EXPOSED_TOOL_NAMES.has(name)) {
+          return {
+            jsonrpc: '2.0',
+            id,
+            result: {
+              content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+              isError: true,
+            },
+          };
+        }
         switch (name) {
+          case 'tokrepo_discover': result = await handleDiscover(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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokrepo-mcp-server",
-  "version": "2.5.0",
+  "version": "2.7.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": {