tokrepo-mcp-server 2.6.0 → 2.8.0

package/README.md

@@ -42,6 +42,9 @@ Once connected, your AI assistant can:
 - **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
+- **Discovery surfaces** — official MCP `server.json`, `.well-known`, `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
 
 ## Available Tools
 
@@ -73,6 +76,27 @@ 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.
+
+## Machine-Readable Listing
+
+Registries and agents can discover this server through:
+
+- MCP server manifest: [tokrepo.com/.well-known/mcp/server.json](https://tokrepo.com/.well-known/mcp/server.json)
+- TokRepo manifest: [tokrepo.com/.well-known/tokrepo.json](https://tokrepo.com/.well-known/tokrepo.json)
+- Agent instructions: [tokrepo.com/agent-instructions/tokrepo.md](https://tokrepo.com/agent-instructions/tokrepo.md)
+- LLM crawler entry: [tokrepo.com/llms.txt](https://tokrepo.com/llms.txt)
+
+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`.
+
 ## Why TokRepo?
 
 TokRepo is the **open registry for AI assets** — like npm for packages, but for AI skills, prompts, MCP configs, and workflows.
@@ -91,7 +115,7 @@ TokRepo is the **open registry for AI assets** — like npm for packages, but fo
 
 - **Website**: [tokrepo.com](https://tokrepo.com)
 - **CLI**: [npm: tokrepo](https://www.npmjs.com/package/tokrepo)
-- **GitHub**: [tokrepo/mcp-server](https://github.com/tokrepo/mcp-server)
+- **GitHub**: [henu-wang/tokrepo-mcp-server](https://github.com/henu-wang/tokrepo-mcp-server)
 - **API**: [tokrepo.com/.well-known/tokrepo.json](https://tokrepo.com/.well-known/tokrepo.json)
 
 ## License

package/bin/server.js

@@ -12,6 +12,7 @@
  */
 
 const https = require('https');
+const http = require('http');
 const crypto = require('crypto');
 const { execFile } = require('child_process');
 
@@ -19,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.6.0';
+const SERVER_VERSION = '2.8.0';
 
 // ─── MCP Protocol (JSON-RPC over stdio) ───
 
@@ -524,6 +525,72 @@ function apiPost(urlPath, body, token) {
   });
 }
 
+function telemetryDisabled() {
+  const value = String(process.env.TOKREPO_TELEMETRY || '').toLowerCase();
+  return ['0', 'false', 'off', 'no'].includes(value);
+}
+
+function eventForTool(name, args = {}) {
+  if (name === 'tokrepo_discover') return 'mcp_discover';
+  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_codex_install') return args.dry_run === false ? 'install_apply' : 'install_dry_run';
+  if (name === 'tokrepo_push') return 'push';
+  return '';
+}
+
+function candidateCountFromResult(result) {
+  const text = result?.content?.map(item => item.text || '').join('\n') || '';
+  return (text.match(/"uuid"\s*:/g) || []).length;
+}
+
+function trackAgentEventForTool(name, args = {}, result = {}) {
+  if (telemetryDisabled()) return;
+  const event = eventForTool(name, args);
+  if (!event) return;
+  try {
+    const url = new URL('/api/v1/tokenboard/agent/events', API_BASE);
+    if (url.protocol === 'http:' && !url.hostname.match(/^(localhost|127\.0\.0\.1)$/)) {
+      url.protocol = 'https:';
+    }
+    const body = JSON.stringify({
+      event,
+      source: 'mcp',
+      version: SERVER_VERSION,
+      target: args.target || args?.constraints?.target || 'any',
+      kind: args.kind || args?.constraints?.kind || '',
+      policy: args.policy || args?.constraints?.policy || '',
+      result: result?.isError ? 'error' : 'pass',
+      dry_run: name === 'tokrepo_codex_install' ? args.dry_run !== false : undefined,
+      candidate_count: candidateCountFromResult(result),
+    });
+    const isHttps = url.protocol === 'https:';
+    const mod = isHttps ? https : http;
+    const req = mod.request({
+      hostname: url.hostname,
+      port: url.port || (isHttps ? 443 : 80),
+      path: url.pathname,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+        'User-Agent': `tokrepo-mcp-server/${SERVER_VERSION}`,
+      },
+      timeout: 700,
+    }, (res) => {
+      res.resume();
+    });
+    req.on('socket', socket => socket.unref?.());
+    req.on('error', () => {});
+    req.on('timeout', () => req.destroy());
+    req.write(body);
+    req.end();
+  } catch {
+    // Telemetry is best-effort only.
+  }
+}
+
 function apiGetAuth(urlPath, token) {
   return new Promise((resolve, reject) => {
     const url = new URL(urlPath, API_BASE);
@@ -701,7 +768,60 @@ function buildDiscoveryQuery(task, environment, constraints) {
   return compactText([...new Set(parts)].join(' '), 100);
 }
 
-function buildCandidate(item, target) {
+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);
@@ -734,6 +854,7 @@ function buildCandidate(item, target) {
       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 } },
@@ -832,7 +953,11 @@ async function handleDiscover(args) {
       '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.slice(0, limit).map(item => buildCandidate(item, target)).filter(candidate => candidate.uuid),
+    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}".`
@@ -1365,6 +1490,7 @@ async function handleRequest(msg) {
       } catch (e) {
         result = { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
       }
+      trackAgentEventForTool(name, args || {}, result);
       return { jsonrpc: '2.0', id, result };
     }
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "tokrepo-mcp-server",
-  "version": "2.6.0",
+  "version": "2.8.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",
+  "mcpName": "io.github.henu-wang/tokrepo-mcp-server",
   "bin": {
     "tokrepo-mcp-server": "bin/server.js"
   },
@@ -12,7 +12,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tokrepo/mcp-server.git"
+    "url": "git+https://github.com/henu-wang/tokrepo-mcp-server.git"
   },
   "homepage": "https://tokrepo.com",
   "keywords": [
@@ -27,7 +27,14 @@
     "skills",
     "prompts",
     "workflows",
-    "agent"
+    "agent",
+    "agent-tools",
+    "agent-skills",
+    "claude-code",
+    "openai-codex",
+    "mcp-registry",
+    "tool-discovery",
+    "llms-txt"
   ],
   "engines": {
     "node": ">=18"