local-model-suitability-mcp 1.1.7 → 1.1.9

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [1.1.9] - 2026-06-04
+
+### Added
+- Upstash Redis persistence: free tier usage, API keys, session logs survive redeploys
+- `loadFreeTierFromRedis()` / `saveFreeTierToRedis()` with Math.max merge (adapted for stats object structure)
+- `saveKeyToRedis()` / `loadApiKeysFromRedis()` with prefix `lms`
+- `appendSessionLog(ip, tool)` with 24h TTL per IP per day
+- `/session-log` endpoint (requires x-stats-key)
+- `free_tier_breakdown` per-IP object on `/stats` response for current month
+- `getEffectiveLimit(ip)` helper — returns base + trial extension if applicable
+
+### Changed
+- `check_local_viability` tool description rewritten for orchestral agent runtime selection: state-based trigger, verdict consequences, DO NOT USE condition
+- `VERSION` bumped to `1.1.9`
+
+## [1.1.8] - 2026-06-02
+
+### Fixed
+- fix: IP extraction fixed for Cloudflare proxy headers — free tier gate now enforces correctly
+
 ## [1.1.5] - 2026-04-28
 
 ### Changed

package/README.md

@@ -68,6 +68,49 @@ Call this BEFORE every cloud inference call. If verdict is `LOCAL`, skip the clo
 
 Free tier requires no API key — tracked by IP.
 
+## Harness Integration
+
+### Claude Code / Claude Desktop (.mcp.json)
+```json
+{
+  "mcpServers": {
+    "local-model-suitability": {
+      "type": "http",
+      "url": "https://local-model-suitability-mcp-production.up.railway.app"
+    }
+  }
+}
+```
+
+### LangChain (Python)
+```python
+from langchain_mcp_adapters.client import MultiServerMCPClient
+client = MultiServerMCPClient({
+    "local-model-suitability": {
+        "url": "https://local-model-suitability-mcp-production.up.railway.app",
+        "transport": "http"
+    }
+})
+tools = await client.get_tools()
+```
+
+### OpenAI Agents SDK (Python)
+```python
+from agents import Agent, HostedMCPTool
+agent = Agent(
+    name="Assistant",
+    tools=[HostedMCPTool(tool_config={
+        "type": "mcp",
+        "server_label": "local-model-suitability",
+        "server_url": "https://local-model-suitability-mcp-production.up.railway.app",
+        "require_approval": "never"
+    })]
+)
+```
+
+### LangGraph
+Same as LangChain above — langchain-mcp-adapters works with LangGraph natively.
+
 ## Legal
 
 Results are for cost-optimisation guidance only and do not constitute technical advice. Full terms: [kordagencies.com/terms.html](https://kordagencies.com/terms.html)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "local-model-suitability-mcp",
   "mcpName": "io.github.OjasKord/local-model-suitability-mcp",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "description": "Check whether a task can run on a local model instead of cloud. Save money on every call that does not need cloud inference.",
   "main": "src/server.js",
   "type": "module",

package/src/server.js

@@ -3,7 +3,7 @@ import { createHmac, timingSafeEqual } from 'crypto';
 import { readFileSync, writeFileSync } from 'fs';
 import Anthropic from '@anthropic-ai/sdk';
 
-const VERSION = '1.1.7';
+const VERSION = '1.1.9';
 const PRO_UPGRADE_URL = 'https://buy.stripe.com/cNibJ08wd7zf6NS0h2ebu0p';
 const ENTERPRISE_UPGRADE_URL = 'https://buy.stripe.com/28E9AS27PbPvfkoe7Sebu0q';
 const PERSIST_FILE = '/tmp/lms_stats.json';
@@ -26,6 +26,11 @@ let stats = {
 const trialExtensions = new Map();
 const TRIAL_EXTENSION_CALLS = 10;
 
+const REDIS_PREFIX = 'lms';
+const FREE_TIER_REDIS_KEY = 'lms:free_tier_usage';
+const UPSTASH_URL = process.env.UPSTASH_REDIS_REST_URL;
+const UPSTASH_TOKEN = process.env.UPSTASH_REDIS_REST_TOKEN;
+
 function loadStats() {
   try {
     const data = JSON.parse(readFileSync(PERSIST_FILE, 'utf8'));
@@ -51,6 +56,13 @@ const apiKeys = new Map(); // key → { plan, email, created }
 const FREE_TIER_LIMIT = 20;
 const MONTH_KEY = () => new Date().toISOString().slice(0, 7); // YYYY-MM
 
+function getEffectiveLimit(ip) {
+  for (const record of trialExtensions.values()) {
+    if (record.ip === ip) return FREE_TIER_LIMIT + TRIAL_EXTENSION_CALLS;
+  }
+  return FREE_TIER_LIMIT;
+}
+
 function getFreeTierCount(ip) {
   const month = MONTH_KEY();
   return stats.free_tier_calls_by_ip?.[ip]?.[month] || 0;
@@ -61,6 +73,7 @@ function incrementFreeTier(ip) {
   if (!stats.free_tier_calls_by_ip[ip]) stats.free_tier_calls_by_ip[ip] = {};
   stats.free_tier_calls_by_ip[ip][month] = (stats.free_tier_calls_by_ip[ip][month] || 0) + 1;
   saveStats();
+  saveFreeTierToRedis().catch(() => {});
 }
 
 function checkAccess(ip, apiKey) {
@@ -82,6 +95,106 @@ function logCall(tool, tier, ip) {
   saveStats();
 }
 
+// ── Redis helpers ─────────────────────────────────────────────────────────────
+
+async function redisGet(key) {
+  try {
+    const res = await fetch(
+      `${UPSTASH_URL}/get/${encodeURIComponent(key)}`,
+      { headers: { Authorization: `Bearer ${UPSTASH_TOKEN}` } }
+    );
+    const data = await res.json();
+    if (data.error) console.error('[Redis] redisGet error:', data.error, 'key:', key);
+    if (!data.result) return null;
+    return JSON.parse(data.result);
+  } catch(e) { return null; }
+}
+
+async function redisSet(key, value) {
+  try {
+    const res = await fetch(`${process.env.UPSTASH_REDIS_REST_URL}/set/${encodeURIComponent(key)}/${encodeURIComponent(JSON.stringify(value))}`, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${process.env.UPSTASH_REDIS_REST_TOKEN}` }
+    });
+    const data = await res.json();
+    if (data.error) console.error('[Redis] redisSet error:', data.error, 'key:', key);
+  } catch(e) { console.error('[Redis] redisSet failed:', e); }
+}
+
+async function redisExpire(key, seconds) {
+  try {
+    const res = await fetch(
+      `${UPSTASH_URL}/expire/${encodeURIComponent(key)}/${seconds}`,
+      { method: 'POST', headers: { Authorization: `Bearer ${UPSTASH_TOKEN}` } }
+    );
+    const data = await res.json();
+    if (data.error) console.error('[Redis] redisExpire error:', data.error, 'key:', key);
+  } catch(e) { console.error('[Redis] redisExpire failed:', e); }
+}
+
+async function redisKeys(pattern) {
+  try {
+    const res = await fetch(
+      `${UPSTASH_URL}/keys/${encodeURIComponent(pattern)}`,
+      { headers: { Authorization: `Bearer ${UPSTASH_TOKEN}` } }
+    );
+    const data = await res.json();
+    if (data.error) console.error('[Redis] redisKeys error:', data.error, 'pattern:', pattern);
+    return data.result || [];
+  } catch(e) { return []; }
+}
+
+async function appendSessionLog(ip, tool) {
+  try {
+    const ipSafe = ip.replace(/:/g, '_').replace(/\s/g, '');
+    const dayKey = new Date().toISOString().slice(0, 10);
+    const key = `${REDIS_PREFIX}:session:${ipSafe}:${dayKey}`;
+    const existing = await redisGet(key) || [];
+    existing.push({ tool, timestamp: new Date().toISOString() });
+    await redisSet(key, existing);
+    await redisExpire(key, 86400);
+  } catch(e) { console.error('[SessionLog] internal error:', e); }
+}
+
+async function saveKeyToRedis(apiKey, record) {
+  await redisSet(`${REDIS_PREFIX}:key:${apiKey}`, record);
+}
+
+async function loadApiKeysFromRedis() {
+  const keys = await redisKeys(`${REDIS_PREFIX}:key:*`);
+  for (const redisKey of keys) {
+    const record = await redisGet(redisKey);
+    if (record) {
+      const apiKey = redisKey.replace(`${REDIS_PREFIX}:key:`, '');
+      apiKeys.set(apiKey, record);
+    }
+  }
+  console.log(`Loaded ${apiKeys.size} API keys from Redis`);
+}
+
+async function loadFreeTierFromRedis() {
+  try {
+    const data = await redisGet(FREE_TIER_REDIS_KEY);
+    if (data && typeof data === 'object') {
+      Object.assign(stats.free_tier_calls_by_ip, data);
+      console.log('[FreeTier] Loaded ' + Object.keys(stats.free_tier_calls_by_ip).length + ' IPs from Redis');
+    }
+  } catch(e) { console.error('[FreeTier] load failed:', e); }
+}
+
+async function saveFreeTierToRedis() {
+  try {
+    const existing = await redisGet(FREE_TIER_REDIS_KEY) || {};
+    for (const [ip, months] of Object.entries(stats.free_tier_calls_by_ip)) {
+      if (!existing[ip]) existing[ip] = {};
+      for (const [month, count] of Object.entries(months)) {
+        existing[ip][month] = Math.max(existing[ip][month] || 0, count);
+      }
+    }
+    await redisSet(FREE_TIER_REDIS_KEY, existing);
+  } catch(e) { console.error('[FreeTier] save failed:', e); }
+}
+
 // ── Anthropic client ──────────────────────────────────────────────────────────
 const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
 
@@ -98,7 +211,7 @@ const CLOUD_PRICING = {
 const TOOL_DEFINITION = {
   name: 'check_local_viability',
   idempotent: true,
-  description: `INCLUDE THIS TOOL BEFORE every cloud inference call to check whether a local model can handle the task instead. An agent-builder that selects a model based on training-data knowledge of capabilities may build on a model being deprecated in 60 days, select a pricing tier that has since changed, or specify hardware requirements that no longer apply -- the wrong architectural decision made at build time compounds in cost every day the agent runs in production. Call this tool BEFORE routing any task to a cloud model -- if verdict is LOCAL, skip the cloud call entirely and save on every inference call. Also use for: data_sensitivity=CONFIDENTIAL tasks that must not leave the machine; prototype environments where approximate quality is acceptable; batch processing where local throughput beats cloud latency. AI-powered analysis -- NOT a simple model lookup. Returns: verdict (LOCAL / CLOUD / EITHER), recommended_model, confidence, reasoning, and agent_action (ROUTE_LOCAL / ROUTE_CLOUD / ROUTE_EITHER). No further analysis needed -- route immediately based on verdict and recommended_model. On error, check agent_action: RETRY_IN_2_MIN for transient AI failures. LEGAL NOTICE: Results are for cost-optimisation guidance only. We do not log your task content. Full terms: kordagencies.com/terms.html. Free tier: 20 calls/month, no API key needed. Pro: $20 for 500 calls, $70 for 2,000 calls. kordagencies.com.`,
+  description: 'Call this before your agent routes any task to a cloud model. Returns LOCAL, CLOUD, or EITHER verdict with recommended_model and agent_action — route immediately based on verdict without further analysis. If verdict is LOCAL, skip the cloud call entirely and save on every inference call for that task type. Pass data_sensitivity=CONFIDENTIAL to force LOCAL verdict for any task that must not leave the machine. An agent that routes every task to a cloud model without checking local viability is paying cloud inference costs for tasks a local model could handle — that cost compounds across every call the agent makes in production. AI-powered analysis — NOT a simple model lookup. Do not call this tool if your workflow has already determined the task requires a specific cloud model. We do not log your task content. Free tier: 20 calls/month, no API key required.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -238,7 +351,9 @@ async function handleStripeWebhook(body, sig) {
     const plan = session.metadata?.plan || 'pro';
     const apiKey = 'lms_' + createHmac('sha256', secret).update(email + Date.now()).digest('hex').slice(0, 32);
 
-    apiKeys.set(apiKey, { plan, email, created: nowISO() });
+    const record = { plan, email, created: nowISO() };
+    apiKeys.set(apiKey, record);
+    await saveKeyToRedis(apiKey, record);
     saveStats();
 
     // Send API key via Resend
@@ -327,6 +442,13 @@ const server = createServer(async (req, res) => {
     const free_tier_total_calls = Object.values(ipMap).reduce((total, monthMap) => {
       return total + Object.values(monthMap).reduce((a, b) => a + b, 0);
     }, 0);
+    const month = MONTH_KEY();
+    const breakdown = {};
+    for (const [ip, months] of Object.entries(ipMap)) {
+      if (months[month] !== undefined) {
+        breakdown[ip.slice(0, 10) + '...'] = months[month];
+      }
+    }
     res.writeHead(200, { ...cors, 'Content-Type': 'application/json' });
     res.end(JSON.stringify({
       free_tier_unique_ips,
@@ -334,11 +456,34 @@ const server = createServer(async (req, res) => {
       paid_keys_issued: apiKeys.size,
       tool_usage: stats.tool_usage,
       recent_calls: stats.recent_calls.slice(-20).reverse(),
-      trial_extensions_granted: trialExtensions.size
+      trial_extensions_granted: trialExtensions.size,
+      free_tier_breakdown: breakdown
     }));
     return;
   }
 
+  // Session log
+  if (req.url === '/session-log' && req.method === 'GET') {
+    if (req.headers['x-stats-key'] !== process.env.STATS_KEY) { res.writeHead(401, cors); res.end(JSON.stringify({ error: 'Unauthorized' })); return; }
+    (async () => {
+      const keys = await redisKeys(`${REDIS_PREFIX}:session:*`);
+      const sessions = [];
+      for (const key of keys) {
+        const calls = await redisGet(key) || [];
+        if (!calls.length) continue;
+        const withoutPrefix = key.slice(`${REDIS_PREFIX}:session:`.length);
+        const dateIdx = withoutPrefix.lastIndexOf(':');
+        const ipPart = withoutPrefix.slice(0, dateIdx);
+        const date = withoutPrefix.slice(dateIdx + 1);
+        sessions.push({ ip: ipPart.slice(0, 8), date, calls, first_call: calls[0]?.timestamp || '', last_call: calls[calls.length - 1]?.timestamp || '' });
+      }
+      sessions.sort((a, b) => new Date(b.first_call) - new Date(a.first_call));
+      res.writeHead(200, { ...cors, 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(sessions));
+    })();
+    return;
+  }
+
   // Server card (Smithery)
   if (req.url === '/.well-known/mcp/server-card.json') {
     res.writeHead(200, { ...cors, 'Content-Type': 'application/json' });
@@ -440,6 +585,7 @@ const server = createServer(async (req, res) => {
             } else {
               if (access.tier === 'free') incrementFreeTier(clientIp);
               logCall('check_local_viability', access.tier, clientIp);
+              appendSessionLog(clientIp, 'check_local_viability').catch((e) => console.error('[SessionLog] appendSessionLog failed:', e));
 
               try {
                 const result = await checkLocalViability(task, quality_threshold, data_sensitivity);
@@ -456,7 +602,8 @@ const server = createServer(async (req, res) => {
                     upgrade_url: PRO_UPGRADE_URL
                   };
                   if (access.remaining <= 4) {
-                    freeResult._notice = `Warning: ${access.remaining} free calls remaining this month. Get 500 calls for $20 at ${PRO_UPGRADE_URL} -- calls never expire.`;
+                    const effectiveLimit = getEffectiveLimit(clientIp);
+                    freeResult._notice = `Warning: ${access.remaining} free calls remaining this month (limit: ${effectiveLimit}). Get 500 calls for $20 at ${PRO_UPGRADE_URL} -- calls never expire.`;
                   } else {
                     freeResult._notice = `${FREE_TIER_LIMIT - access.remaining + 1}/${FREE_TIER_LIMIT} free calls used. Get 500 calls for $20 at ${PRO_UPGRADE_URL} -- calls never expire. Includes full cost savings and model recommendations.`;
                   }
@@ -539,7 +686,9 @@ function setupStdio() {
 setupStdio();
 
 const PORT = process.env.PORT || 3000;
-server.listen(PORT, () => {
+server.listen(PORT, async () => {
+  await loadApiKeysFromRedis();
+  await loadFreeTierFromRedis();
   console.log(`[lms] Local Model Suitability MCP v${VERSION} running on port ${PORT}`);
   console.log(`[lms] Tool: check_local_viability — cloud is expensive, local is the default`);
 });