ziprin-context-optimizer 8.0.0

package/src/mcp-server.js

@@ -0,0 +1,372 @@
+'use strict';
+
+/**
+ * Ziprin AI Context MCP v8 — 8 tools, compact JSON, Serena-first.
+ * Intelligence via MCP; native Chat remains the UI.
+ */
+
+const path = require('path');
+const { z } = require('zod');
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const api = require('./gateway-api');
+const { publishEvent, EVENT_TYPES } = require('./mcp-event-stream');
+const { VERSION } = require('./version');
+
+function parseArgs(argv) {
+  const out = { project: process.env.ZIPRIN_WORKSPACE || process.cwd() };
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === '--project' && argv[i + 1]) {
+      out.project = path.resolve(argv[++i]);
+    }
+  }
+  return out;
+}
+
+const cfg = parseArgs(process.argv);
+let ROOT = cfg.project;
+
+function textResult(obj) {
+  const body = typeof obj === 'string' ? obj : JSON.stringify(obj);
+  return { content: [{ type: 'text', text: body }] };
+}
+
+/** Stable tool catalog — max 8. quality_guard alias dropped. */
+const TOOLS = [
+  {
+    name: 'ziprin_optimize_context',
+    description:
+      'PRIMARY. Call BEFORE Serena/search/read/@folder. Returns lean map: filesIncluded, readNow, skeletons, serenaEmit. Skips greetings.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt: { type: 'string' },
+        profileId: { type: 'string' },
+        force: { type: 'boolean' },
+        sessionId: { type: 'string' },
+      },
+      required: ['prompt'],
+    },
+  },
+  {
+    name: 'ziprin_analyze_task',
+    description: 'Classify task: category, complexity, token budget, FA/EN expansion.',
+    inputSchema: {
+      type: 'object',
+      properties: { prompt: { type: 'string' }, profileId: { type: 'string' } },
+      required: ['prompt'],
+    },
+  },
+  {
+    name: 'ziprin_rank_context',
+    description: 'Score and select relevant files; drop noise; keep/drop lists.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt: { type: 'string' },
+        profileId: { type: 'string' },
+        limit: { type: 'number' },
+      },
+      required: ['prompt'],
+    },
+  },
+  {
+    name: 'ziprin_find_symbol',
+    description:
+      'Serena-first find_symbol emit + local regex fallback. Call before read_file.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        paths: { type: 'array', items: { type: 'string' } },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'ziprin_unfold_symbol',
+    description: 'Unfold one function/class body from a skeleton map file.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string' },
+        name: { type: 'string' },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'ziprin_validate_context',
+    description: 'Quality guard: validate optimized set; restore risky removals.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt: { type: 'string' },
+        selected: { type: 'array', items: { type: 'string' } },
+        restored: { type: 'array', items: { type: 'string' } },
+        budget: { type: 'number' },
+        usedTokens: { type: 'number' },
+      },
+    },
+  },
+  {
+    name: 'ziprin_context_memory',
+    description: 'Read/learn path usefulness + co-occurrence from successful sessions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['read', 'learn', 'clear'] },
+        filesIncluded: { type: 'array', items: { type: 'string' } },
+        taskClassification: { type: 'string' },
+      },
+    },
+  },
+  {
+    name: 'ziprin_health',
+    description: 'MCP health: version, FTS index, session count, memory.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+function handleTool(name, args) {
+  const a = args || {};
+  switch (name) {
+    case 'ziprin_optimize_context': {
+      const full = api.optimizeContext(ROOT, {
+        prompt: a.prompt,
+        profileId: a.profileId,
+        force: a.force,
+        sessionId: a.sessionId,
+        source: 'mcp',
+      });
+      return api.toLeanResult(full);
+    }
+    case 'ziprin_analyze_task':
+      return api.analyzeTask(a.prompt, a.profileId);
+    case 'ziprin_rank_context':
+      return api.rankContext(ROOT, a.prompt, {
+        profileId: a.profileId,
+        limit: a.limit,
+      });
+    case 'ziprin_find_symbol':
+      return api.findSymbol(ROOT, a.name, a.paths || a.searchPaths || []);
+    case 'ziprin_unfold_symbol':
+      return api.unfoldSymbol(ROOT, a.path, a.name);
+    case 'ziprin_dependency_graph':
+      return api.dependencyGraph(ROOT, a.seeds || []);
+    case 'ziprin_compress_context':
+      return api.compressContext(ROOT, a.paths || [], a.maxChars || 1800);
+    case 'ziprin_validate_context': {
+      const task = api.analyzeTask(a.prompt || '', a.profileId);
+      return api.validateContext({
+        taskTokens: task.tokens || [],
+        selected: a.selected || [],
+        restored: a.restored || [],
+        scores: (a.selected || []).map((p, i) => ({ path: p, final_score: 50 - i })),
+        budget: a.budget,
+        usedTokens: a.usedTokens,
+        symbols: task.symbols || [],
+        pathHints: task.pathHints || [],
+        domain: task.domain,
+      });
+    }
+    case 'ziprin_context_memory':
+      return api.contextMemory(ROOT, a.action || 'read', {
+        filesIncluded: a.filesIncluded,
+        taskClassification: a.taskClassification,
+      });
+    case 'ziprin_health':
+      return api.healthInfo(ROOT);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+function createServer() {
+  const server = new McpServer({
+    name: 'ziprin-context',
+    version: VERSION,
+  });
+
+  const wrap = (toolName) => async (args) => {
+    try {
+      return textResult(handleTool(toolName, args || {}));
+    } catch (err) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: err.message || String(err) }],
+      };
+    }
+  };
+
+  server.registerTool(
+    'ziprin_optimize_context',
+    {
+      title: 'Ziprin Optimize Context',
+      description: TOOLS[0].description,
+      inputSchema: {
+        prompt: z.string().describe('User request / task text'),
+        profileId: z.string().optional(),
+        force: z.boolean().optional(),
+        sessionId: z.string().optional(),
+      },
+    },
+    wrap('ziprin_optimize_context')
+  );
+
+  server.registerTool(
+    'ziprin_analyze_task',
+    {
+      title: 'Ziprin Analyze Task',
+      description: TOOLS[1].description,
+      inputSchema: {
+        prompt: z.string(),
+        profileId: z.string().optional(),
+      },
+    },
+    wrap('ziprin_analyze_task')
+  );
+
+  server.registerTool(
+    'ziprin_rank_context',
+    {
+      title: 'Ziprin Rank Context',
+      description: TOOLS[2].description,
+      inputSchema: {
+        prompt: z.string(),
+        profileId: z.string().optional(),
+        limit: z.number().optional(),
+      },
+    },
+    wrap('ziprin_rank_context')
+  );
+
+  server.registerTool(
+    'ziprin_find_symbol',
+    {
+      title: 'Ziprin Find Symbol',
+      description: TOOLS[3].description,
+      inputSchema: {
+        name: z.string(),
+        paths: z.array(z.string()).optional(),
+      },
+    },
+    wrap('ziprin_find_symbol')
+  );
+
+  server.registerTool(
+    'ziprin_unfold_symbol',
+    {
+      title: 'Ziprin Unfold Symbol',
+      description: TOOLS[4].description,
+      inputSchema: {
+        path: z.string(),
+        name: z.string().optional(),
+      },
+    },
+    wrap('ziprin_unfold_symbol')
+  );
+
+  server.registerTool(
+    'ziprin_validate_context',
+    {
+      title: 'Ziprin Validate Context',
+      description: TOOLS[5].description,
+      inputSchema: {
+        prompt: z.string().optional(),
+        selected: z.array(z.string()).optional(),
+        restored: z.array(z.string()).optional(),
+        budget: z.number().optional(),
+        usedTokens: z.number().optional(),
+      },
+    },
+    wrap('ziprin_validate_context')
+  );
+
+  server.registerTool(
+    'ziprin_context_memory',
+    {
+      title: 'Ziprin Context Memory',
+      description: TOOLS[6].description,
+      inputSchema: {
+        action: z.enum(['read', 'learn', 'clear']).optional(),
+        filesIncluded: z.array(z.string()).optional(),
+        taskClassification: z.string().optional(),
+      },
+    },
+    wrap('ziprin_context_memory')
+  );
+
+  server.registerTool(
+    'ziprin_health',
+    {
+      title: 'Ziprin Health',
+      description: TOOLS[7].description,
+      inputSchema: {},
+    },
+    wrap('ziprin_health')
+  );
+
+  return server;
+}
+
+async function main() {
+  console.error(`[ziprin-context-mcp] v8 project=${ROOT} sdk=official`);
+  publishEvent(ROOT, {
+    service: 'ziprin-context',
+    type: EVENT_TYPES.server_started,
+    status: 'starting',
+    health: 'starting',
+  });
+
+  const server = createServer();
+  for (const t of TOOLS) {
+    publishEvent(ROOT, {
+      service: 'ziprin-context',
+      type: EVENT_TYPES.tool_registered,
+      status: 'starting',
+      health: 'starting',
+      toolsCount: TOOLS.length,
+      tool: t.name,
+    });
+  }
+
+  const transport = new StdioServerTransport();
+  try {
+    await server.connect(transport);
+    publishEvent(ROOT, {
+      service: 'ziprin-context',
+      type: EVENT_TYPES.server_connected,
+      status: 'connected',
+      health: 'healthy',
+      toolsCount: TOOLS.length,
+      tools: TOOLS.map((t) => t.name),
+    });
+  } catch (err) {
+    publishEvent(ROOT, {
+      service: 'ziprin-context',
+      type: EVENT_TYPES.server_failed,
+      status: 'failed',
+      health: 'failed',
+      error: err.message,
+    });
+    throw err;
+  }
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('[ziprin-context-mcp] fatal', err);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  TOOLS,
+  handleTool,
+  parseArgs,
+  createServer,
+  setProjectRoot(root) {
+    ROOT = path.resolve(root);
+  },
+};

package/src/mmr.js

@@ -0,0 +1,57 @@
+'use strict';
+
+/**
+ * Maximal Marginal Relevance — folder diversity after lexical/graph rank.
+ * Max-normalize (not min-max) so low scores stay usable.
+ */
+
+function folderOf(p) {
+  const s = String(p || '').replace(/\\/g, '/');
+  const i = s.lastIndexOf('/');
+  return i === -1 ? '' : s.slice(0, i);
+}
+
+function pathSim(a, b) {
+  const da = String(a || '').replace(/\\/g, '/').split('/').slice(0, -1);
+  const db = String(b || '').replace(/\\/g, '/').split('/').slice(0, -1);
+  let i = 0;
+  while (i < da.length && i < db.length && da[i] === db[i]) i++;
+  const denom = Math.max(da.length, db.length, 1);
+  return i / denom;
+}
+
+function mmrSelect(ranked, opts = {}) {
+  const k = opts.k || 20;
+  const lambda = opts.lambda == null ? 0.72 : opts.lambda;
+  const rest = (ranked || []).map((x) => (typeof x === 'string' ? { path: x, score: 1 } : { ...x }));
+  if (!rest.length) return [];
+  const max = Math.max(...rest.map((x) => Number(x.score) || 0), 1e-9);
+
+  const selected = [];
+  const folderCount = new Map();
+  while (selected.length < k && rest.length) {
+    let bestI = 0;
+    let best = -Infinity;
+    for (let i = 0; i < rest.length; i++) {
+      const cand = rest[i];
+      const rel = (Number(cand.score) || 0) / max;
+      let maxSim = 0;
+      for (const s of selected) maxSim = Math.max(maxSim, pathSim(cand.path, s.path));
+      const folder = folderOf(cand.path);
+      const same = folderCount.get(folder) || 0;
+      const folderPenalty = same >= 3 ? 0.25 * same : 0;
+      const mmr = lambda * rel - (1 - lambda) * maxSim - folderPenalty;
+      if (mmr > best) {
+        best = mmr;
+        bestI = i;
+      }
+    }
+    const pick = rest.splice(bestI, 1)[0];
+    selected.push({ ...pick, mmr: best });
+    const folder = folderOf(pick.path);
+    folderCount.set(folder, (folderCount.get(folder) || 0) + 1);
+  }
+  return selected;
+}
+
+module.exports = { mmrSelect, pathSim, folderOf };

package/src/pagerank.js

@@ -0,0 +1,176 @@
+'use strict';
+
+/**
+ * Personalized PageRank on the import graph (Aider-style).
+ * Personalization: query seeds + dirty + open editor files.
+ * Graph cached by path:mtime fingerprint.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { buildDependencyBoost, extractImports, resolveImport } = require('./dependency-graph');
+
+const CACHE_REL = '.ziprin-context/graph-cache.json';
+const cacheMem = new Map();
+
+function fingerprint(root, files) {
+  const parts = [];
+  for (const rel of files.slice().sort()) {
+    let m = 0;
+    try {
+      m = Math.round(fs.statSync(path.join(root, rel)).mtimeMs);
+    } catch {
+      m = 0;
+    }
+    parts.push(`${rel}:${m}`);
+  }
+  return crypto.createHash('sha1').update(parts.join('|')).digest('hex').slice(0, 16);
+}
+
+function loadCache(root) {
+  if (cacheMem.has(root)) return cacheMem.get(root);
+  const abs = path.join(root, CACHE_REL);
+  if (!fs.existsSync(abs)) return null;
+  try {
+    const j = JSON.parse(fs.readFileSync(abs, 'utf8'));
+    cacheMem.set(root, j);
+    return j;
+  } catch {
+    return null;
+  }
+}
+
+function saveCache(root, data) {
+  cacheMem.set(root, data);
+  try {
+    const abs = path.join(root, CACHE_REL);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, JSON.stringify(data), 'utf8');
+  } catch {
+    /* ignore */
+  }
+}
+
+function buildGraph(root, seedPaths, maxFiles = 80) {
+  const fp = fingerprint(root, seedPaths);
+  const cached = loadCache(root);
+  if (cached && cached.fingerprint === fp && Array.isArray(cached.edges)) {
+    return { ...cached, cached: true };
+  }
+
+  const nodes = new Set(seedPaths);
+  const edges = [];
+  const { boost, edges: depEdges } = buildDependencyBoost(root, seedPaths, maxFiles);
+  for (const e of depEdges) {
+    edges.push({ from: e.from, to: e.to });
+    nodes.add(e.from);
+    nodes.add(e.to);
+  }
+  for (const b of boost) nodes.add(b);
+
+  // one extra hop for package roots already in boost
+  for (const rel of [...nodes].slice(0, maxFiles)) {
+    const abs = path.join(root, rel);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) continue;
+    let text = '';
+    try {
+      text = fs.readFileSync(abs, 'utf8').slice(0, 80_000);
+    } catch {
+      continue;
+    }
+    for (const spec of extractImports(text).slice(0, 16)) {
+      const resolved = resolveImport(rel, spec, root);
+      if (!resolved) continue;
+      edges.push({ from: rel, to: resolved });
+      nodes.add(resolved);
+    }
+  }
+
+  const data = {
+    fingerprint: fp,
+    builtAt: new Date().toISOString(),
+    nodes: [...nodes],
+    edges,
+    cached: false,
+  };
+  saveCache(root, data);
+  return data;
+}
+
+function personalizedPageRank(nodes, edges, seeds, opts = {}) {
+  const damping = opts.damping == null ? 0.85 : opts.damping;
+  const iters = opts.iters || 20;
+  const list = [...new Set(nodes.filter(Boolean))];
+  const n = list.length;
+  if (!n) return [];
+  const index = new Map(list.map((p, i) => [p, i]));
+  const out = Array.from({ length: n }, () => []);
+  for (const e of edges || []) {
+    const i = index.get(e.from);
+    const j = index.get(e.to);
+    if (i == null || j == null || i === j) continue;
+    out[i].push(j);
+  }
+
+  const pers = new Array(n).fill(0);
+  let mass = 0;
+  for (const s of seeds || []) {
+    const i = index.get(s);
+    if (i == null) continue;
+    pers[i] += 1;
+    mass += 1;
+  }
+  if (!mass) {
+    for (let i = 0; i < n; i++) pers[i] = 1 / n;
+  } else {
+    for (let i = 0; i < n; i++) pers[i] /= mass;
+  }
+
+  let r = pers.slice();
+  for (let t = 0; t < iters; t++) {
+    const next = new Array(n).fill(0);
+    for (let i = 0; i < n; i++) {
+      next[i] += (1 - damping) * pers[i];
+    }
+    for (let i = 0; i < n; i++) {
+      const dests = out[i];
+      if (!dests.length) {
+        const share = damping * r[i] / n;
+        for (let j = 0; j < n; j++) next[j] += share;
+      } else {
+        const share = damping * r[i] / dests.length;
+        for (const j of dests) next[j] += share;
+      }
+    }
+    r = next;
+  }
+
+  const ranked = list
+    .map((p, i) => ({ path: p, score: r[i] }))
+    .sort((a, b) => b.score - a.score);
+
+  if (seeds && seeds.length) {
+    const seedSet = new Set(seeds);
+    const bonus = 0.2;
+    for (const item of ranked) {
+      if (seedSet.has(item.path)) item.score += bonus;
+    }
+    ranked.sort((a, b) => b.score - a.score);
+  }
+  return ranked;
+}
+
+function rankGraph(root, seedPaths, personalize, opts = {}) {
+  const graph = buildGraph(root, seedPaths, opts.maxFiles || 80);
+  const ranked = personalizedPageRank(graph.nodes, graph.edges, personalize || seedPaths, opts);
+  return { ranked, graph };
+}
+
+module.exports = {
+  fingerprint,
+  buildGraph,
+  personalizedPageRank,
+  rankGraph,
+  CACHE_REL,
+};

package/src/profiles.js

@@ -0,0 +1,74 @@
+'use strict';
+
+const PROFILES = {
+  minimal: {
+    id: 'minimal',
+    label: 'Minimal',
+    description: 'فقط stub ناظر + ignore سنگین. کمترین توکن همیشه-لود.',
+    charsPerToken: 4,
+    maxAlwaysLoadTokens: 400,
+    maxOnDemandTokens: 8000,
+    stripOtherMdc: true,
+    preferSerena: true,
+    preferToolsFirst: true,
+    allowAgentsInChat: false,
+    allowSkillsInChat: false,
+    allowFullIndex: false,
+    confidenceFloor: 'PROVEN',
+  },
+  standard: {
+    id: 'standard',
+    label: 'Standard',
+    description: 'تعادل کیفیت و توکن. stub ناظر + خلاصه ایندکس + Serena.',
+    charsPerToken: 4,
+    maxAlwaysLoadTokens: 600,
+    maxOnDemandTokens: 20000,
+    stripOtherMdc: true,
+    preferSerena: true,
+    preferToolsFirst: true,
+    allowAgentsInChat: false,
+    allowSkillsInChat: true,
+    allowFullIndex: false,
+    confidenceFloor: 'PROVEN',
+  },
+  strict: {
+    id: 'strict',
+    label: 'Strict',
+    description: 'حذف تقریباً همه always-load؛ فقط path مرتبط با تسک.',
+    charsPerToken: 4,
+    maxAlwaysLoadTokens: 300,
+    maxOnDemandTokens: 12000,
+    stripOtherMdc: true,
+    preferSerena: true,
+    preferToolsFirst: true,
+    allowAgentsInChat: false,
+    allowSkillsInChat: false,
+    allowFullIndex: false,
+    confidenceFloor: 'PROVEN',
+  },
+  maximum: {
+    id: 'maximum',
+    label: 'Maximum quality',
+    description: 'بیشتر context برای تسک‌های سخت؛ هنوز از dump کل ریپو جلوگیری می‌کند.',
+    charsPerToken: 4,
+    maxAlwaysLoadTokens: 1200,
+    maxOnDemandTokens: 40000,
+    stripOtherMdc: false,
+    preferSerena: true,
+    preferToolsFirst: true,
+    allowAgentsInChat: true,
+    allowSkillsInChat: true,
+    allowFullIndex: true,
+    confidenceFloor: 'REVIEW',
+  },
+};
+
+function getProfile(id) {
+  return PROFILES[id] || PROFILES.standard;
+}
+
+function listProfiles() {
+  return Object.values(PROFILES);
+}
+
+module.exports = { PROFILES, getProfile, listProfiles };