tokrepo-mcp-server 2.9.2 → 2.11.0

package/README.md

@@ -39,6 +39,7 @@ Once connected, your AI assistant can:
 - **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
+- **Verify trust** — read-only content hash, install plan hash, permission envelope, policy, trust_score_v2, blockers, and warnings
 - **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
@@ -53,6 +54,7 @@ Once connected, your AI assistant can:
 | `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_verify` | Verify trust, hashes, permissions, and policy before activation |
 | `tokrepo_install_plan` | Get agent-native install plan v2 |
 | `tokrepo_codex_install` | Dry-run, stage, or install a Codex skill safely |
 | `tokrepo_installed` | List TokRepo-managed Codex installs |
@@ -71,6 +73,7 @@ You: "What video assets should I install?"
 AI: [calls tokrepo_discover] → Finds relevant skills, checks fit and policy, then asks before installing
 
 You: "Install that cursor rules asset"
+AI: [calls tokrepo_verify] → Checks trust_score_v2, permissions, blockers, and warnings
 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
@@ -95,6 +98,9 @@ Registries and agents can discover this server through:
 - Portable agent manifest: [tokrepo.com/.well-known/agent.json](https://tokrepo.com/.well-known/agent.json)
 - A2A agent card: [tokrepo.com/.well-known/agent-card.json](https://tokrepo.com/.well-known/agent-card.json)
 - Tool catalog: [tokrepo.com/.well-known/tool-catalog.json](https://tokrepo.com/.well-known/tool-catalog.json)
+- Trust manifest: [tokrepo.com/.well-known/tokrepo-trust.json](https://tokrepo.com/.well-known/tokrepo-trust.json)
+- Default agent policy pack: [tokrepo.com/policy-packs/default-agent-policy.json](https://tokrepo.com/policy-packs/default-agent-policy.json)
+- Eval evidence: [tokrepo.com/evals/agent-discovery.json](https://tokrepo.com/evals/agent-discovery.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)
 - Agent ecosystem distribution pack: [tokrepo.com/agent-ecosystem.json](https://tokrepo.com/agent-ecosystem.json)
@@ -102,7 +108,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_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_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`.
 
 ## 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.9.2';
+const SERVER_VERSION = '2.11.0';
 
 // ─── MCP Protocol (JSON-RPC over stdio) ───
 
@@ -155,6 +155,36 @@ const TOOLS = [
       required: ['uuid'],
     },
   },
+  {
+    name: 'tokrepo_verify',
+    description: 'Read-only asset trust verification for agents. Produces content hash, install plan hash, policy decision, permission envelope, trust_score_v2, blockers, warnings, schemas, and safe next actions before activation.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        uuid: {
+          type: 'string',
+          description: 'Asset UUID, workflow URL slug, or workflow UUID from search/detail results. Ignored when offline=true.',
+        },
+        target: {
+          type: 'string',
+          description: 'Verification target adapter.',
+          enum: ['codex'],
+          default: 'codex',
+        },
+        strict: {
+          type: 'boolean',
+          description: 'When true, warnings fail the verification report.',
+          default: false,
+        },
+        offline: {
+          type: 'boolean',
+          description: 'Use the bundled offline fixture. Intended for agent/toolchain self-tests.',
+          default: false,
+        },
+      },
+      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.',
@@ -436,6 +466,7 @@ const EXPOSED_TOOL_NAMES = new Set([
   'tokrepo_search',
   'tokrepo_detail',
   'tokrepo_install_plan',
+  'tokrepo_verify',
   'tokrepo_codex_install',
   'tokrepo_installed',
   'tokrepo_update',
@@ -473,6 +504,13 @@ const TOOL_ANNOTATIONS = {
     idempotentHint: true,
     openWorldHint: true,
   },
+  tokrepo_verify: {
+    title: 'Verify asset trust, hashes, permissions, and policy before activation',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
   tokrepo_codex_install: {
     title: 'Dry-run, stage, or install an asset for Codex',
     readOnlyHint: false,
@@ -613,6 +651,7 @@ function eventForTool(name, args = {}) {
   if (name === 'tokrepo_search') return 'mcp_search';
   if (name === 'tokrepo_detail') return 'mcp_detail';
   if (name === 'tokrepo_install_plan') return 'install_plan';
+  if (name === 'tokrepo_verify') return 'verify_asset';
   if (name === 'tokrepo_codex_install') return args.dry_run === false ? 'install_apply' : 'install_dry_run';
   if (name === 'tokrepo_push') return 'push';
   return '';
@@ -846,6 +885,112 @@ function buildDiscoveryQuery(task, environment, constraints) {
   return compactText([...new Set(parts)].join(' '), 100);
 }
 
+function inferAgentCapabilityAnalysis(task, target = 'any', constraints = {}, environment = {}) {
+  const text = [
+    task,
+    constraints.kind,
+    constraints.policy,
+    environment.project_type,
+    environment.language,
+    ...asArray(environment.frameworks),
+  ].filter(Boolean).join(' ').toLowerCase();
+  const normalizeKind = (value) => String(value || '').toLowerCase().replace(/[-\s]+/g, '_');
+  const rules = [
+    {
+      name: 'domain_or_workflow_skill',
+      kind: 'skill',
+      evidence: ['skill', 'rule', 'guideline', 'review', 'audit', 'seo', 'design', 'frontend', 'backend', 'security', 'test', 'deploy', 'video', 'writing'],
+      why: 'The task likely benefits from reusable instructions, domain rules, or a repeatable agent workflow.',
+    },
+    {
+      name: 'agent_tool_or_mcp_integration',
+      kind: 'mcp_config',
+      evidence: ['mcp', 'tool', 'api', 'integration', 'github', 'browser', 'calendar', 'email', 'gmail', 'slack', 'notion', 'database', 'vercel'],
+      why: 'The task may require a callable tool surface instead of hand-written one-off glue code.',
+    },
+    {
+      name: 'automation_script',
+      kind: 'script',
+      evidence: ['script', 'cli', 'batch', 'cron', 'automation', 'generate', 'convert', 'migrate', 'lint', 'check'],
+      why: 'The task may reuse a tested script or command wrapper.',
+    },
+    {
+      name: 'prompt_or_reasoning_template',
+      kind: 'prompt',
+      evidence: ['prompt', 'copy', 'research', 'analysis', 'summarize', 'translate', 'plan', 'brainstorm'],
+      why: 'The task may reuse a prompt template or reasoning checklist.',
+    },
+    {
+      name: 'knowledge_or_policy_pack',
+      kind: 'knowledge',
+      evidence: ['policy', 'standard', 'compliance', 'docs', 'documentation', 'architecture', 'best practice', 'trust'],
+      why: 'The task may need reusable reference knowledge or policy constraints.',
+    },
+  ];
+  const inferred = [];
+  for (const rule of rules) {
+    const matches = rule.evidence.filter(term => text.includes(term));
+    if (constraints.kind && normalizeKind(constraints.kind) === normalizeKind(rule.kind)) matches.push(`requested kind ${rule.kind}`);
+    if (!matches.length) continue;
+    inferred.push({
+      name: rule.name,
+      asset_kind: rule.kind,
+      confidence: Math.min(0.95, 0.55 + matches.length * 0.08),
+      evidence: Array.from(new Set(matches)).slice(0, 6),
+      why: rule.why,
+    });
+  }
+  if (!inferred.length) {
+    inferred.push({
+      name: 'general_reusable_agent_capability',
+      asset_kind: constraints.kind || 'skill',
+      confidence: 0.5,
+      evidence: ['new task capability gap'],
+      why: 'Before creating local one-off work, the agent should check whether TokRepo already has a reusable asset.',
+    });
+  }
+  const preferredAssetKinds = Array.from(new Set([
+    constraints.kind,
+    ...inferred.map(item => item.asset_kind),
+    'skill',
+    'prompt',
+    'mcp_config',
+    'script',
+    'workflow',
+    'knowledge',
+  ].filter(Boolean))).slice(0, 6);
+  const taskTerms = extractSearchTerms(task, 6);
+  return {
+    schema_version: 1,
+    decision: 'discover_before_build',
+    target,
+    trigger: 'planning_time_capability_gap',
+    inferred_capabilities: inferred,
+    preferred_asset_kinds: preferredAssetKinds,
+    search_queries: Array.from(new Set([
+      buildDiscoveryQuery(task, environment, constraints),
+      compactText(taskTerms.slice(0, 4).join(' '), 100),
+      ...preferredAssetKinds.map(kind => compactText(`${taskTerms.slice(0, 3).join(' ')} ${kind}`, 100)),
+    ].filter(Boolean))).slice(0, 6),
+    required_mcp_sequence: [
+      'tokrepo_discover',
+      'tokrepo_detail',
+      'tokrepo_verify',
+      'tokrepo_install_plan',
+    ],
+    acceptance_criteria: [
+      'Do not require the human to browse the TokRepo GUI before discovery.',
+      'Use a candidate only when fit, policy, trust, and permission envelope match the active subtask.',
+      'Prefer dry-run or stage-only before writes, execution, secrets, network access, or global config changes.',
+      'After completing the task, run tokrepo agent-handoff --json to preserve reusable improvements.',
+    ],
+    empty_state_strategy: [
+      'Try broader capability terms from search_queries.',
+      'If still empty, build locally and package the reusable part with tokrepo agent-handoff.',
+    ],
+  };
+}
+
 function scoreDiscoveryCandidate(item, task, target, constraints = {}) {
   const metadata = itemAgentMetadata(item);
   const fit = itemAgentFit(item);
@@ -935,10 +1080,13 @@ function buildCandidate(item, target, ranking = {}) {
     ranking,
     next_mcp_calls: [
       { tool: 'tokrepo_detail', arguments: { uuid } },
+      { tool: 'tokrepo_verify', arguments: { uuid, target: planTarget } },
       { tool: 'tokrepo_install_plan', arguments: { uuid, target: planTarget } },
     ],
     commands: {
       inspect: `npx tokrepo detail ${uuid} --json`,
+      audit: `npx tokrepo audit ${uuid} --target ${planTarget} --json`,
+      verify: `npx tokrepo verify ${uuid} --target ${planTarget} --json`,
       dry_run_install: planTarget === 'codex'
         ? `npx tokrepo install ${uuid} --dry-run --json`
         : `npx tokrepo install ${uuid} --target ${planTarget} --dry-run --json`,
@@ -946,6 +1094,8 @@ function buildCandidate(item, target, ranking = {}) {
     agent_use_contract: [
       'Use only if the capability matches the current subtask.',
       'Call tokrepo_detail before install to inspect content and metadata.',
+      'Call tokrepo_verify to inspect hashes, permissions, trust_score_v2, blockers, and warnings.',
+      'Call tokrepo audit if future agents need a persistent trust-history snapshot.',
       '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.',
@@ -1022,10 +1172,12 @@ async function handleDiscover(args) {
       environment,
       constraints,
     },
+    capability_analysis: inferAgentCapabilityAnalysis(task, target, constraints, environment),
     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 audit if the chosen asset materially affects the task and future agents need a trust-history snapshot.',
       '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.',
@@ -1179,6 +1331,33 @@ async function handleInstallPlan(args) {
   };
 }
 
+async function handleVerify(args) {
+  const {
+    uuid = '00000000-0000-4000-8000-000000000001',
+    target = 'codex',
+    strict = false,
+    offline = false,
+  } = args || {};
+  const cliArgs = ['verify', uuid, '--target', target, '--json'];
+  if (strict) cliArgs.push('--strict');
+  if (offline) cliArgs.push('--offline');
+  const { stdout, stderr } = await runTokrepoCli(cliArgs);
+  let data;
+  try {
+    data = JSON.parse(stdout);
+  } catch {
+    data = { stdout, stderr };
+  }
+  const status = data?.status || 'unknown';
+  return {
+    isError: status === 'fail',
+    content: [{
+      type: 'text',
+      text: jsonText(`TokRepo asset verification (${status})`, data),
+    }],
+  };
+}
+
 async function handleCodexInstall(args) {
   const {
     uuid,
@@ -1552,6 +1731,7 @@ async function handleRequest(msg) {
           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_verify': result = await handleVerify(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;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tokrepo-mcp-server",
-  "version": "2.9.2",
-  "description": "Agent-native MCP server for TokRepo — search, plan, safely install, and push AI assets from MCP clients.",
+  "version": "2.11.0",
+  "description": "Agent-native MCP server for TokRepo - discover, verify, plan, safely install, and push AI assets from MCP clients.",
   "mcpName": "io.github.henu-wang/tokrepo-mcp-server",
   "bin": {
     "tokrepo-mcp-server": "bin/server.js"
@@ -37,10 +37,14 @@
     "claude-code",
     "openai-codex",
     "mcp-registry",
+    "hosted-mcp",
     "agent-manifest",
     "a2a-agent-card",
     "tool-discovery",
-    "llms-txt"
+    "llms-txt",
+    "trust-verification",
+    "agent-audit",
+    "agent-evals"
   ],
   "engines": {
     "node": ">=18"