ultra-lean-mcp-proxy 0.3.0

package/src/result-compression.mjs

@@ -0,0 +1,332 @@
+/**
+ * Generic structured JSON result compression for Ultra Lean MCP Proxy.
+ */
+
+import { createHash } from 'node:crypto';
+import { cloneJson } from './state.mjs';
+
+function jsonSize(value) {
+  return Buffer.byteLength(JSON.stringify(value), 'utf-8');
+}
+
+function stableJson(value) {
+  return JSON.stringify(value, Object.keys(value || {}).sort());
+}
+
+export function makeCompressionOptions(overrides = {}) {
+  return {
+    mode: 'balanced', // off | balanced | aggressive
+    stripNulls: false,
+    stripDefaults: false,
+    minPayloadBytes: 512,
+    enableColumnar: true,
+    columnarMinRows: 8,
+    columnarMinFields: 2,
+    ...overrides,
+  };
+}
+
+export class TokenCounter {
+  constructor() {
+    this.backend = 'heuristic';
+    this.reason = 'node_builtin_estimator';
+  }
+
+  count(value) {
+    const text = JSON.stringify(value);
+    return Math.max(1, Math.floor(text.length / 4));
+  }
+}
+
+function collectKeyFrequency(node, counter) {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      collectKeyFrequency(item, counter);
+    }
+    return;
+  }
+  if (node && typeof node === 'object') {
+    for (const [key, value] of Object.entries(node)) {
+      const name = String(key);
+      counter[name] = (counter[name] || 0) + 1;
+      collectKeyFrequency(value, counter);
+    }
+  }
+}
+
+function buildKeyAliases(counter, mode) {
+  if (mode === 'off') return {};
+  const minFreq = mode === 'aggressive' ? 1 : 2;
+  const candidates = Object.entries(counter)
+    .filter(([key, freq]) => freq >= minFreq && key.length > 2)
+    .sort((a, b) => {
+      if (a[1] !== b[1]) return b[1] - a[1];
+      return b[0].length - a[0].length;
+    });
+
+  const aliases = {};
+  for (let i = 0; i < candidates.length; i++) {
+    const key = candidates[i][0];
+    const alias = `k${i}`;
+    if (alias.length < key.length) {
+      aliases[key] = alias;
+    }
+  }
+  return aliases;
+}
+
+function isDefaultish(value) {
+  if (value === null || value === '' || value === 0 || value === false) return true;
+  if (Array.isArray(value) && value.length === 0) return true;
+  if (value && typeof value === 'object' && Object.keys(value).length === 0) return true;
+  return false;
+}
+
+function canColumnar(items, opts) {
+  if (!opts.enableColumnar) return [false, []];
+  if (!Array.isArray(items) || items.length < opts.columnarMinRows) return [false, []];
+  if (!items.every((item) => item && typeof item === 'object' && !Array.isArray(item))) {
+    return [false, []];
+  }
+  const firstKeys = Object.keys(items[0]);
+  if (firstKeys.length < opts.columnarMinFields) return [false, []];
+  const firstSet = new Set(firstKeys);
+  for (let i = 1; i < items.length; i++) {
+    const keys = Object.keys(items[i]);
+    if (keys.length !== firstSet.size) return [false, []];
+    if (keys.some((key) => !firstSet.has(key))) return [false, []];
+  }
+  return [true, firstKeys];
+}
+
+function encode(node, keyAlias, opts) {
+  if (Array.isArray(node)) {
+    const [asColumnar, columns] = canColumnar(node, opts);
+    if (asColumnar) {
+      const encodedColumns = columns.map((col) => keyAlias[col] || col);
+      const rows = [];
+      for (const item of node) {
+        rows.push(columns.map((col) => encode(item[col], keyAlias, opts)));
+      }
+      return { '~t': { c: encodedColumns, r: rows } };
+    }
+    return node.map((item) => encode(item, keyAlias, opts));
+  }
+  if (node && typeof node === 'object') {
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+      if (opts.stripNulls && value === null) continue;
+      if (
+        opts.stripDefaults
+        && ['default', 'defaults'].includes(String(key).toLowerCase())
+        && isDefaultish(value)
+      ) {
+        continue;
+      }
+      const encodedKey = keyAlias[String(key)] || String(key);
+      out[encodedKey] = encode(value, keyAlias, opts);
+    }
+    return out;
+  }
+  return node;
+}
+
+function decode(node, aliasToKey) {
+  if (Array.isArray(node)) {
+    return node.map((item) => decode(item, aliasToKey));
+  }
+  if (node && typeof node === 'object') {
+    if (node['~t'] && typeof node['~t'] === 'object') {
+      const meta = node['~t'];
+      const columns = Array.isArray(meta.c) ? meta.c : [];
+      const rows = Array.isArray(meta.r) ? meta.r : [];
+      const decodedColumns = columns.map((col) => aliasToKey[String(col)] || String(col));
+      const items = [];
+      for (const row of rows) {
+        if (!Array.isArray(row)) continue;
+        const item = {};
+        for (let i = 0; i < decodedColumns.length; i++) {
+          if (i < row.length) {
+            item[decodedColumns[i]] = decode(row[i], aliasToKey);
+          }
+        }
+        items.push(item);
+      }
+      return items;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+      const decodedKey = aliasToKey[String(key)] || String(key);
+      out[decodedKey] = decode(value, aliasToKey);
+    }
+    return out;
+  }
+  return node;
+}
+
+function keyRef(aliasToKey) {
+  const digest = createHash('sha256').update(stableJson(aliasToKey), 'utf-8').digest('hex').slice(0, 12);
+  return `kdict-${digest}`;
+}
+
+export function compressResult(
+  inputData,
+  options = null,
+  {
+    keyRegistry = null,
+    registryCounter = null,
+    reuseKeys = false,
+    keyBootstrapInterval = 8,
+  } = {}
+) {
+  const opts = makeCompressionOptions(options || {});
+  const originalBytes = jsonSize(inputData);
+
+  if (originalBytes < opts.minPayloadBytes) {
+    return {
+      encoding: 'lapc-json-v1',
+      compressed: false,
+      originalBytes,
+      compressedBytes: originalBytes,
+      savedBytes: 0,
+      savedRatio: 0,
+      data: inputData,
+      keys: {},
+    };
+  }
+
+  const keyCounter = {};
+  collectKeyFrequency(inputData, keyCounter);
+  const keyAlias = buildKeyAliases(keyCounter, opts.mode);
+  const encoded = encode(inputData, keyAlias, opts);
+  const aliasToKey = {};
+  for (const [key, alias] of Object.entries(keyAlias)) {
+    aliasToKey[alias] = key;
+  }
+
+  const envelope = {
+    encoding: 'lapc-json-v1',
+    compressed: true,
+    mode: opts.mode,
+    originalBytes,
+    data: encoded,
+    keys: aliasToKey,
+  };
+
+  if (reuseKeys && keyRegistry && typeof keyRegistry === 'object') {
+    const ref = keyRef(aliasToKey);
+    let includeKeys = true;
+    const previous = keyRegistry[ref];
+    if (previous && JSON.stringify(previous) === JSON.stringify(aliasToKey)) {
+      includeKeys = false;
+      if (registryCounter && typeof registryCounter === 'object') {
+        const count = (registryCounter[ref] || 0) + 1;
+        registryCounter[ref] = count;
+        if (keyBootstrapInterval > 0 && count % keyBootstrapInterval === 0) {
+          includeKeys = true;
+        }
+      }
+    } else {
+      keyRegistry[ref] = cloneJson(aliasToKey);
+      if (registryCounter && typeof registryCounter === 'object') {
+        registryCounter[ref] = 1;
+      }
+    }
+    envelope.keysRef = ref;
+    if (!includeKeys) {
+      delete envelope.keys;
+    }
+  }
+
+  const compressedBytes = jsonSize(envelope);
+  const savedBytes = originalBytes - compressedBytes;
+  envelope.compressedBytes = compressedBytes;
+  envelope.savedBytes = savedBytes;
+  envelope.savedRatio = originalBytes > 0 ? savedBytes / originalBytes : 0;
+
+  if (savedBytes <= 0) {
+    envelope.compressed = false;
+    envelope.data = inputData;
+    envelope.keys = {};
+    delete envelope.keysRef;
+    envelope.compressedBytes = originalBytes;
+    envelope.savedBytes = 0;
+    envelope.savedRatio = 0;
+  }
+
+  return envelope;
+}
+
+export function decompressResult(envelope, { keyRegistry = null } = {}) {
+  if (!envelope || typeof envelope !== 'object' || envelope.encoding !== 'lapc-json-v1') {
+    throw new Error('Unsupported compression envelope');
+  }
+  if (!envelope.compressed) {
+    return envelope.data;
+  }
+  let keys = envelope.keys;
+  if ((!keys || typeof keys !== 'object') && typeof envelope.keysRef === 'string' && keyRegistry) {
+    keys = keyRegistry[envelope.keysRef];
+  }
+  if (!keys || typeof keys !== 'object') {
+    throw new Error('Invalid or missing key dictionary in envelope');
+  }
+  return decode(envelope.data, keys);
+}
+
+export function tokenSavings(original, candidate, counter = null) {
+  const tc = counter || new TokenCounter();
+  return tc.count(original) - tc.count(candidate);
+}
+
+export function estimateCompressibility(value) {
+  const keyCounter = {};
+  const scalarCounter = {};
+  let homogeneousLists = 0;
+  let totalLists = 0;
+
+  const walk = (node) => {
+    if (Array.isArray(node)) {
+      totalLists += 1;
+      if (node.length > 0 && node.every((item) => item && typeof item === 'object' && !Array.isArray(item))) {
+        const keysets = node.map((item) => JSON.stringify(Object.keys(item).sort()));
+        if (new Set(keysets).size === 1) {
+          homogeneousLists += 1;
+        }
+      }
+      for (const child of node) walk(child);
+      return;
+    }
+
+    if (node && typeof node === 'object') {
+      for (const [key, child] of Object.entries(node)) {
+        const name = String(key);
+        keyCounter[name] = (keyCounter[name] || 0) + 1;
+        walk(child);
+      }
+      return;
+    }
+
+    if (typeof node === 'string' || typeof node === 'number' || typeof node === 'boolean' || node === null) {
+      const marker = JSON.stringify(node);
+      scalarCounter[marker] = (scalarCounter[marker] || 0) + 1;
+    }
+  };
+
+  walk(value);
+
+  const totalKeys = Object.values(keyCounter).reduce((acc, n) => acc + n, 0);
+  const duplicateKeys = Math.max(0, totalKeys - Object.keys(keyCounter).length);
+  const keyRepeatRatio = totalKeys > 0 ? duplicateKeys / totalKeys : 0;
+
+  const totalScalars = Object.values(scalarCounter).reduce((acc, n) => acc + n, 0);
+  const duplicateScalars = Math.max(0, totalScalars - Object.keys(scalarCounter).length);
+  const scalarRepeatRatio = totalScalars > 0 ? duplicateScalars / totalScalars : 0;
+
+  const homogeneousRatio = totalLists > 0 ? homogeneousLists / totalLists : 0;
+  const score = 0.5 * keyRepeatRatio + 0.25 * scalarRepeatRatio + 0.25 * homogeneousRatio;
+  if (score < 0) return 0;
+  if (score > 1) return 1;
+  return score;
+}
+

package/src/state.mjs

@@ -0,0 +1,293 @@
+/**
+ * Session/cache/tool-index state for Ultra Lean MCP Proxy.
+ */
+
+import { createHash } from 'node:crypto';
+
+function isPlainObject(value) {
+  return Object.prototype.toString.call(value) === '[object Object]';
+}
+
+export function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => canonicalize(item));
+  }
+  if (isPlainObject(value)) {
+    const out = {};
+    const keys = Object.keys(value).sort();
+    for (const key of keys) {
+      out[key] = canonicalize(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+export function cloneJson(value) {
+  if (value === undefined) return undefined;
+  return JSON.parse(JSON.stringify(value));
+}
+
+export function stableJsonStringify(value) {
+  return JSON.stringify(canonicalize(value));
+}
+
+export function stableHash(value) {
+  return createHash('sha256').update(stableJsonStringify(value), 'utf-8').digest('hex');
+}
+
+export function argsHash(argumentsValue) {
+  if (argumentsValue === null || argumentsValue === undefined) {
+    return stableHash({});
+  }
+  return stableHash(argumentsValue);
+}
+
+const MUTATING_VERBS = [
+  'create',
+  'update',
+  'delete',
+  'remove',
+  'set',
+  'write',
+  'insert',
+  'patch',
+  'post',
+  'put',
+  'merge',
+  'upload',
+  'commit',
+  'navigate',
+  'open',
+  'close',
+  'click',
+  'type',
+  'press',
+  'select',
+  'hover',
+  'drag',
+  'drop',
+  'scroll',
+  'evaluate',
+  'execute',
+  'goto',
+  'reload',
+  'back',
+  'forward',
+];
+
+export function isMutatingToolName(toolName) {
+  const name = String(toolName || '').toLowerCase();
+  return MUTATING_VERBS.some((verb) => name.includes(verb));
+}
+
+export function makeCacheKey(sessionId, serverName, toolName, argumentsValue) {
+  return `${sessionId}:${serverName}:${toolName}:${argsHash(argumentsValue)}`;
+}
+
+function nowSeconds() {
+  return Date.now() / 1000;
+}
+
+function toolSearchTerms(query) {
+  return String(query || '')
+    .toLowerCase()
+    .match(/[a-zA-Z0-9_]+/g) || [];
+}
+
+export class ProxyState {
+  constructor(maxCacheEntries = 5000) {
+    this.maxCacheEntries = Math.max(1, Number(maxCacheEntries) || 5000);
+    this._cache = new Map(); // key -> {value, expiresAt, createdAt, hits}
+    this._history = new Map(); // key -> json
+    this._tools = [];
+    this._toolsHash = new Map(); // key -> {lastHash, conditionalHits, updatedAt}
+  }
+
+  cacheGet(key) {
+    const entry = this._cache.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt < nowSeconds()) {
+      this._cache.delete(key);
+      return null;
+    }
+    entry.hits += 1;
+    return cloneJson(entry.value);
+  }
+
+  cacheSet(key, value, ttlSeconds) {
+    const now = nowSeconds();
+    this._cache.set(key, {
+      value: cloneJson(value),
+      createdAt: now,
+      expiresAt: now + Math.max(0, Number(ttlSeconds) || 0),
+      hits: 0,
+    });
+    this._evictCacheIfNeeded();
+  }
+
+  cacheInvalidatePrefix(prefix) {
+    let removed = 0;
+    for (const key of this._cache.keys()) {
+      if (key.startsWith(prefix)) {
+        this._cache.delete(key);
+        removed += 1;
+      }
+    }
+    return removed;
+  }
+
+  _evictCacheIfNeeded() {
+    if (this._cache.size <= this.maxCacheEntries) return;
+    const ordered = Array.from(this._cache.entries()).sort((a, b) => {
+      const ah = a[1].hits - b[1].hits;
+      if (ah !== 0) return ah;
+      return a[1].createdAt - b[1].createdAt;
+    });
+    const overflow = this._cache.size - this.maxCacheEntries;
+    for (let i = 0; i < overflow; i++) {
+      this._cache.delete(ordered[i][0]);
+    }
+  }
+
+  historyGet(key) {
+    if (!this._history.has(key)) return null;
+    return cloneJson(this._history.get(key));
+  }
+
+  historySet(key, value) {
+    this._history.set(key, cloneJson(value));
+    if (this._history.size > this.maxCacheEntries * 2) {
+      const firstKey = this._history.keys().next().value;
+      if (firstKey !== undefined) {
+        this._history.delete(firstKey);
+      }
+    }
+  }
+
+  historyInvalidatePrefix(prefix) {
+    let removed = 0;
+    for (const key of this._history.keys()) {
+      if (key.startsWith(prefix)) {
+        this._history.delete(key);
+        removed += 1;
+      }
+    }
+    return removed;
+  }
+
+  setTools(tools) {
+    this._tools = cloneJson(Array.isArray(tools) ? tools : []);
+  }
+
+  getTools() {
+    return cloneJson(this._tools);
+  }
+
+  searchTools(query, topK = 8, includeSchemas = true) {
+    if (!Array.isArray(this._tools) || this._tools.length === 0) {
+      return [];
+    }
+
+    const terms = toolSearchTerms(query);
+    const queryLower = String(query || '').toLowerCase();
+    const ranked = [];
+
+    for (const tool of this._tools) {
+      if (!isPlainObject(tool)) continue;
+      const name = String(tool.name || '');
+      const desc = String(tool.description || '');
+      const schema = (isPlainObject(tool.inputSchema) && tool.inputSchema)
+        || (isPlainObject(tool.input_schema) && tool.input_schema)
+        || {};
+      const properties = isPlainObject(schema.properties) ? schema.properties : {};
+      const paramText = Object.keys(properties).join(' ');
+      const haystack = `${name} ${desc} ${paramText}`.toLowerCase();
+
+      let score = 0;
+      if (queryLower && name.toLowerCase().includes(queryLower)) score += 4;
+      for (const term of terms) {
+        if (name.toLowerCase().includes(term)) score += 2;
+        if (desc.toLowerCase().includes(term)) score += 1;
+        if (paramText.toLowerCase().includes(term)) score += 1.25;
+        if (haystack.includes(term)) score += 0.2;
+      }
+      if (score <= 0) continue;
+      ranked.push([score, tool]);
+    }
+
+    const fallbackRanked = ranked.length > 0
+      ? ranked
+      : this._tools.map((tool) => [0.01, tool]);
+
+    fallbackRanked.sort((a, b) => b[0] - a[0]);
+    const limit = Math.max(1, Number(topK) || 8);
+    const out = [];
+    for (const [score, tool] of fallbackRanked.slice(0, limit)) {
+      const item = {
+        name: tool.name,
+        score: Number(score.toFixed(3)),
+        description: tool.description || '',
+      };
+      if (includeSchemas) {
+        const schema = tool.inputSchema || tool.input_schema;
+        if (schema !== undefined) {
+          item.inputSchema = cloneJson(schema);
+        }
+      }
+      out.push(item);
+    }
+    return out;
+  }
+
+  toolsHashGet(key) {
+    const entry = this._toolsHash.get(key);
+    if (!entry) return null;
+    return {
+      lastHash: entry.lastHash ?? null,
+      conditionalHits: Number(entry.conditionalHits || 0),
+      updatedAt: Number(entry.updatedAt || 0),
+    };
+  }
+
+  toolsHashSetLast(key, toolsHash) {
+    const now = nowSeconds();
+    const current = this._toolsHash.get(key) || {
+      lastHash: null,
+      conditionalHits: 0,
+      updatedAt: 0,
+    };
+    if (current.lastHash !== toolsHash) {
+      current.conditionalHits = 0;
+    }
+    current.lastHash = toolsHash;
+    current.updatedAt = now;
+    this._toolsHash.set(key, current);
+  }
+
+  toolsHashRecordHit(key) {
+    const now = nowSeconds();
+    const current = this._toolsHash.get(key) || {
+      lastHash: null,
+      conditionalHits: 0,
+      updatedAt: 0,
+    };
+    current.conditionalHits += 1;
+    current.updatedAt = now;
+    this._toolsHash.set(key, current);
+    return current.conditionalHits;
+  }
+
+  toolsHashResetHits(key) {
+    const now = nowSeconds();
+    const current = this._toolsHash.get(key) || {
+      lastHash: null,
+      conditionalHits: 0,
+      updatedAt: 0,
+    };
+    current.conditionalHits = 0;
+    current.updatedAt = now;
+    this._toolsHash.set(key, current);
+  }
+}
+

package/src/tools-hash-sync.mjs

@@ -0,0 +1,52 @@
+/**
+ * Helpers for tools_hash_sync MCP extension.
+ */
+
+import { createHash } from 'node:crypto';
+import { canonicalize } from './state.mjs';
+
+const TOOLS_HASH_WIRE_RE = /^([a-z0-9_]+):([0-9a-f]{64})$/;
+
+export function canonicalToolsJson(toolsPayload) {
+  return JSON.stringify(canonicalize(toolsPayload));
+}
+
+export function computeToolsHash(
+  toolsPayload,
+  {
+    algorithm = 'sha256',
+    includeServerFingerprint = false,
+    serverFingerprint = null,
+  } = {}
+) {
+  if (algorithm !== 'sha256') {
+    throw new Error(`Unsupported tools hash algorithm: ${algorithm}`);
+  }
+
+  const payload = canonicalize(toolsPayload);
+  let preimage = payload;
+  if (includeServerFingerprint) {
+    preimage = {
+      tools: payload,
+      server_fingerprint: serverFingerprint || '',
+    };
+  }
+  const digest = createHash('sha256').update(JSON.stringify(preimage), 'utf-8').digest('hex');
+  return `sha256:${digest}`;
+}
+
+export function parseIfNoneMatch(value, { expectedAlgorithm = 'sha256' } = {}) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const candidate = value.trim().toLowerCase();
+  const match = candidate.match(TOOLS_HASH_WIRE_RE);
+  if (!match) {
+    return null;
+  }
+  if (match[1] !== expectedAlgorithm) {
+    return null;
+  }
+  return candidate;
+}
+