url-safety-validator-mcp 1.2.0 → 1.2.2

package/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git push *)",
+      "Bash(railway up *)",
+      "Bash(curl -sf https://url-safety-validator-mcp-production.up.railway.app/health)",
+      "Bash(curl -si -X OPTIONS https://url-safety-validator-mcp-production.up.railway.app/health -H \"Origin: https://bizfile.forsenia.in\")",
+      "Bash(curl -si https://url-safety-validator-mcp-production.up.railway.app/health)"
+    ]
+  }
+}

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to URL Safety Validator MCP are documented here.
 
+## [1.2.2] — 2026-04-25
+
+### Fixed
+- CRITICAL: Stripe webhook now sends API key via Resend email on `checkout.session.completed` -- paying customers were not receiving their keys
+- `agent_action` field added to `check_url` result (BLOCK / FLAG_AND_PROCEED / ALLOW) -- field was promised in tool description but missing from response
+- `agent_action` and `likely_cause` added to all error responses
+- `/stats` endpoint now returns `tool_usage` and `recent_calls` fields -- dashboard was showing `--` for both
+
+### Improved
+- `check_url` tool description updated: source hostnames, latency signal, corrected agent_action guidance
+- `serverInfo` description added to both HTTP and stdio initialize responses -- improves Smithery and Claude Desktop discoverability
+- `source_url` corrected from kordagencies.com to webrisk.googleapis.com
+
 ## [1.0.0] — 2026-04-22
 
 ### Initial Release

package/package.json

@@ -1,14 +1,12 @@
 {
   "name": "url-safety-validator-mcp",
-  "version": "1.2.0",
+  "mcpName": "io.github.OjasKord/url-safety-validator-mcp",
+  "version": "1.2.2",
   "description": "AI-powered URL safety validator MCP server. SAFE/SUSPICIOUS/DANGEROUS verdict for agents.",
   "main": "src/server.js",
   "scripts": {
     "start": "node src/server.js"
   },
-  "license": "UNLICENSED",
-  "homepage": "https://kordagencies.com",
-  "mcpName": "io.github.OjasKord/url-safety-validator-mcp",
   "keywords": [
     "mcp",
     "agent",
@@ -19,8 +17,28 @@
     "malware",
     "security",
     "threat-intelligence",
-    "web-risk"
+    "web-risk",
+    "url-checker",
+    "link-safety",
+    "phishing-detection",
+    "google-web-risk",
+    "safe-browsing",
+    "malware-detection",
+    "url-scanner",
+    "cybersecurity"
   ],
-  "author": "Kord Agencies Pte Ltd",
+  "author": "Kord Agencies Pte Ltd <ojas@kordagencies.com>",
+  "license": "UNLICENSED",
+  "homepage": "https://kordagencies.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OjasKord/url-safety-validator-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/OjasKord/url-safety-validator-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "dependencies": {}
 }

package/server.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.OjasKord/url-safety-validator-mcp",
-  "version": "1.1.0",
+  "title": "URL Safety Validator MCP",
   "description": "AI URL safety validator: SAFE/SUSPICIOUS/DANGEROUS verdict, trust score, threat intel.",
-  "title": "URL Safety Validator",
+  "version": "1.2.2",
   "websiteUrl": "https://kordagencies.com",
   "repository": {
     "url": "https://github.com/OjasKord/url-safety-validator-mcp",
@@ -12,36 +12,15 @@
   "packages": [
     {
       "registryType": "npm",
-      "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "url-safety-validator-mcp",
-      "version": "1.1.0",
+      "version": "1.2.2",
       "transport": { "type": "stdio" },
       "environmentVariables": [
-        {
-          "name": "ANTHROPIC_API_KEY",
-          "description": "Anthropic API key for AI trust scoring",
-          "isRequired": true,
-          "isSecret": true
-        },
-        {
-          "name": "GOOGLE_WEB_RISK_API_KEY",
-          "description": "Google Web Risk API key (commercial). Server degrades gracefully without it.",
-          "isRequired": false,
-          "isSecret": true
-        },
-        {
-          "name": "GOOGLE_SAFE_BROWSING_API_KEY",
-          "description": "Google Safe Browsing API key (free tier available).",
-          "isRequired": false,
-          "isSecret": true
-        }
+        { "name": "ANTHROPIC_API_KEY", "description": "Anthropic API key for AI trust scoring", "isRequired": true, "isSecret": true },
+        { "name": "GOOGLE_WEB_RISK_API_KEY", "description": "Google Web Risk API key (commercial). Degrades gracefully without it.", "isRequired": false, "isSecret": true },
+        { "name": "GOOGLE_SAFE_BROWSING_API_KEY", "description": "Google Safe Browsing API key (free tier available).", "isRequired": false, "isSecret": true }
       ]
     }
   ],
-  "remotes": [
-    {
-      "type": "streamable-http",
-      "url": "https://url-safety-validator-mcp-production.up.railway.app"
-    }
-  ]
+  "remotes": [{ "type": "streamable-http", "url": "https://url-safety-validator-mcp-production.up.railway.app" }]
 }

package/src/server.js

@@ -5,13 +5,14 @@ const fs = require('fs');
 const crypto = require('crypto');
 const { Readable } = require('stream');
 
-const VERSION = '1.2.0';
+const VERSION = '1.2.2';
 const PORT = process.env.PORT || 3000;
 const STATS_KEY = process.env.STATS_KEY || 'ojas2026';
 const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY || '';
 const GOOGLE_WEB_RISK_API_KEY = process.env.GOOGLE_WEB_RISK_API_KEY || '';
 const GOOGLE_SAFE_BROWSING_API_KEY = process.env.GOOGLE_SAFE_BROWSING_API_KEY || '';
 const STRIPE_WEBHOOK_SECRET = process.env.STRIPE_WEBHOOK_SECRET || '';
+const RESEND_API_KEY = process.env.RESEND_API_KEY || '';
 const PERSIST_FILE = '/tmp/urlsafety_stats.json';
 
 const LEGAL_DISCLAIMER = 'Results sourced from Google Web Risk, Google Safe Browsing, and AI analysis. We do not log or store your query content. Results are for informational purposes only and do not constitute security advice. Verdict is a risk signal -- not a guarantee of safety or danger. Provider maximum liability is limited to subscription fees paid in the preceding 3 months. Full terms: kordagencies.com/terms.html';
@@ -21,6 +22,7 @@ const FREE_LIMIT = 10;
 // ─── Stats ────────────────────────────────────────────────────────────────────
 let stats = { free_tier_calls_by_ip: {}, total_checks: 0, safe_count: 0, suspicious_count: 0, dangerous_count: 0, started_at: new Date().toISOString() };
 const apiKeys = new Map();
+const usageLog = [];
 
 function loadStats() {
   try {
@@ -40,6 +42,26 @@ loadStats();
 
 function nowISO() { return new Date().toISOString(); }
 
+// ─── Email ────────────────────────────────────────────────────────────────────
+async function sendEmail(to, subject, html) {
+  return new Promise((resolve) => {
+    const body = JSON.stringify({ from: 'URL Safety Validator <ojas@kordagencies.com>', to: [to], subject, html });
+    const req = https.request({
+      hostname: 'api.resend.com', path: '/emails', method: 'POST',
+      headers: { 'Authorization': 'Bearer ' + RESEND_API_KEY, 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) }
+    }, res => { let d = ''; res.on('data', c => d += c); res.on('end', () => resolve({ status: res.statusCode, body: d })); });
+    req.on('error', e => resolve({ error: e.message }));
+    req.write(body); req.end();
+  });
+}
+
+async function sendApiKeyEmail(email, apiKey, plan) {
+  const planLabel = plan === 'enterprise' ? 'Enterprise' : 'Pro';
+  const limit = plan === 'enterprise' ? 'Unlimited' : '500';
+  const html = '<!DOCTYPE html><html><body style="font-family:monospace;background:#080A0F;color:#E8EDF5;padding:40px;max-width:600px;margin:0 auto"><div style="border:1px solid rgba(0,229,195,0.3);border-radius:8px;padding:32px"><div style="color:#00E5C3;font-size:13px;letter-spacing:0.2em;text-transform:uppercase;margin-bottom:24px">URL Safety Validator MCP -- ' + planLabel + ' Plan</div><h1 style="font-size:24px;font-weight:700;margin-bottom:8px;color:#FFFFFF">Your API key is ready.</h1><div style="background:#141B24;border:1px solid rgba(255,255,255,0.1);border-radius:6px;padding:20px;margin-bottom:24px"><div style="color:#5A6478;font-size:11px;text-transform:uppercase;margin-bottom:8px">Your API Key</div><div style="color:#00E5C3;font-size:14px;word-break:break-all">' + apiKey + '</div></div><div style="background:#141B24;border:1px solid rgba(255,255,255,0.1);border-radius:6px;padding:20px;margin-bottom:24px"><div style="color:#5A6478;font-size:11px;text-transform:uppercase;margin-bottom:8px">MCP Config</div><div style="color:#86EFAC;font-size:12px">{"url-safety-validator":{"url":"https://url-safety-validator-mcp-production.up.railway.app","headers":{"x-api-key":"' + apiKey + '"}}}</div></div><div style="background:#141B24;border:1px solid rgba(255,255,255,0.1);border-radius:6px;padding:20px;margin-bottom:24px"><div style="color:#E8EDF5;font-size:13px">Plan: ' + planLabel + ' | URL checks: ' + limit + '/month</div></div><div style="background:#0D1219;border-radius:6px;padding:16px;margin-bottom:24px;font-size:11px;color:#5A6478;line-height:1.7">Results are informational only. Verdict is a risk signal not a safety guarantee. Liability capped at 3 months fees. Full terms: kordagencies.com/terms.html</div><p style="color:#5A6478;font-size:12px">Questions? ojas@kordagencies.com</p></div></body></html>';
+  return sendEmail(email, 'Your URL Safety Validator MCP ' + planLabel + ' API Key', html);
+}
+
 // ─── Free/Paid Tier ───────────────────────────────────────────────────────────
 function getMonthKey() {
   const d = new Date();
@@ -208,8 +230,7 @@ Return this exact JSON structure:
 
 Rules:
 - trust_score 0-29 = DANGEROUS, 30-64 = SUSPICIOUS, 65-100 = SAFE
-- If Google Web Risk flagged it OR PhishTank confirmed it, verdict MUST be DANGEROUS
-- If URLhaus found it as malware, verdict MUST be DANGEROUS
+- If Google Web Risk flagged it OR Google Safe Browsing confirmed it, verdict MUST be DANGEROUS
 - Domain age under 30 days = add "newly_registered" to threat_categories and lower trust_score by at least 20
 - No SSL on a login-looking URL = lower score significantly
 - Consider the full picture -- a newly registered domain with no database hits is still SUSPICIOUS not SAFE`;
@@ -240,7 +261,13 @@ Rules:
 async function checkUrl(rawUrl) {
   const parsed = parseUrl(rawUrl);
   if (!parsed.valid) {
-    return { error: 'Invalid URL format. Provide a full URL like https://example.com', url: rawUrl };
+    return {
+      error: 'Invalid URL format. Provide a full URL like https://example.com',
+      url: rawUrl,
+      agent_action: 'Fix the URL format before retrying. Ensure it starts with https:// or http://',
+      likely_cause: 'URL missing protocol prefix or contains invalid characters',
+      _disclaimer: LEGAL_DISCLAIMER
+    };
   }
 
   const { href, hostname, protocol } = parsed;
@@ -281,6 +308,7 @@ async function checkUrl(rawUrl) {
     url: href,
     hostname,
     verdict,
+    agent_action: verdict === 'DANGEROUS' ? 'BLOCK' : verdict === 'SUSPICIOUS' ? 'FLAG_AND_PROCEED' : 'ALLOW',
     trust_score,
     ssl_valid: ssl.valid_ssl,
     domain_age_days: domainAge.available ? domainAge.domain_age_days : null,
@@ -295,7 +323,7 @@ async function checkUrl(rawUrl) {
       google_safe_browsing: safeBrowsing.available ? { flagged: safeBrowsing.flagged, threat_types: safeBrowsing.threat_types } : { available: false, reason: safeBrowsing.reason }
     },
     checked_at: nowISO(),
-    source_url: 'https://kordagencies.com',
+    source_url: 'webrisk.googleapis.com',
     _disclaimer: LEGAL_DISCLAIMER
   };
 
@@ -306,7 +334,7 @@ async function checkUrl(rawUrl) {
 // ─── Tool definition ──────────────────────────────────────────────────────────
 const TOOL_DEFINITION = {
   name: 'check_url',
-  description: 'Call this tool BEFORE your agent fetches, visits, or passes any URL from an untrusted source -- emails, scraped pages, user inputs, API responses, documents. Returns SAFE/SUSPICIOUS/DANGEROUS verdict, AI trust score 0-100, threat categories, SSL status, domain age, and redirect chain detection. AI-powered analysis -- NOT a simple database lookup. Cross-checks Google Web Risk, URLhaus, and PhishTank in one call. LEGAL NOTICE: Verdict is a risk signal, not a guarantee. We do not log your query content. Full terms: kordagencies.com/terms.html. Free tier: first 10 calls/month, no API key needed.',
+  description: 'Call this tool BEFORE your agent fetches, visits, clicks, or passes any URL from an untrusted source -- emails, scraped pages, user inputs, documents, API responses, or redirects. A DANGEROUS verdict halts the workflow. A SUSPICIOUS verdict flags for review. A SAFE verdict lets your agent proceed. Returns: verdict (SAFE / SUSPICIOUS / DANGEROUS), trust_score (0-100), threat_categories (phishing / malware / social engineering), ssl_valid, domain_age_days, redirect_chain_detected, reasoning, and a machine-readable agent_action (BLOCK / FLAG_AND_PROCEED / ALLOW). AI-powered -- NOT a simple blocklist lookup. Cross-checks Google Web Risk (webrisk.googleapis.com) and Google Safe Browsing in real time. One call before any URL interaction eliminates an entire class of agent security failures. On error, check agent_action: BLOCK if safety cannot be confirmed; PROCEED_WITH_CAUTION for partial signal failures where Web Risk and AI both returned SAFE but ancillary checks (domain age, SSL) are unavailable. Typical response: 3-8s (four parallel external checks plus AI scoring). LEGAL NOTICE: Verdict is a risk signal, not a guarantee. We do not log your query content. Full terms: kordagencies.com/terms.html. Free tier: first 10 calls/month, no API key needed.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -332,7 +360,7 @@ function verifyStripeSignature(body, sig, secret) {
 const cors = {
   'Access-Control-Allow-Origin': '*',
   'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-  'Access-Control-Allow-Headers': 'Content-Type, x-api-key, Authorization'
+  'Access-Control-Allow-Headers': 'Content-Type, x-api-key, x-stats-key'
 };
 
 // ─── MCP stdio transport ──────────────────────────────────────────────────────
@@ -351,7 +379,7 @@ function setupStdio() {
           const request = JSON.parse(line);
           let response;
           if (request.method === 'initialize') {
-            response = { jsonrpc: '2.0', id: request.id, result: { protocolVersion: '2024-11-05', capabilities: { tools: {}, resources: {}, prompts: {} }, serverInfo: { name: 'url-safety-validator-mcp', version: VERSION } } };
+            response = { jsonrpc: '2.0', id: request.id, result: { protocolVersion: '2024-11-05', capabilities: { tools: {}, resources: {}, prompts: {} }, serverInfo: { name: 'url-safety-validator-mcp', version: VERSION, description: 'Real-time URL safety checking for AI agents. Cross-checks Google Web Risk and AI analysis before your agent visits, fetches, or passes any URL. One call eliminates an entire class of agent security failures. 1 tool. Free tier: 10 calls/month.' } } };
           } else if (request.method === 'notifications/initialized') {
             continue;
           } else if (request.method === 'tools/list') {
@@ -381,7 +409,7 @@ function setupStdio() {
 
 // ─── HTTP server ──────────────────────────────────────────────────────────────
 const server = http.createServer(async (req, res) => {
-  if (req.method === 'OPTIONS') { res.writeHead(204, cors); res.end(); return; }
+  if (req.method === 'OPTIONS') { res.writeHead(200, cors); res.end(); return; }
 
   if (req.url === '/health' && (req.method === 'GET' || req.method === 'HEAD')) {
     res.writeHead(200, { ...cors, 'Content-Type': 'application/json' });
@@ -404,7 +432,15 @@ const server = http.createServer(async (req, res) => {
         ? depCheck('webrisk.googleapis.com', `/v1/uris:search?threatTypes=MALWARE&uri=https%3A%2F%2Fexample.com&key=${GOOGLE_WEB_RISK_API_KEY}`)
         : Promise.resolve({ ok: false, status: 0, error: 'key not set' }),
       GOOGLE_SAFE_BROWSING_API_KEY
-        ? depCheck('safebrowsing.googleapis.com', `/v4/threatMatches:find?key=${GOOGLE_SAFE_BROWSING_API_KEY}`)
+        ? (() => {
+            const sbBody = JSON.stringify({ client: { clientId: 'kord-dep-check', clientVersion: '1.0' }, threatInfo: { threatTypes: ['MALWARE'], platformTypes: ['ANY_PLATFORM'], threatEntryTypes: ['URL'], threatEntries: [{ url: 'https://example.com' }] } });
+            return new Promise((resolve) => {
+              const r = https.request({ hostname: 'safebrowsing.googleapis.com', path: `/v4/threatMatches:find?key=${GOOGLE_SAFE_BROWSING_API_KEY}`, method: 'POST', headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(sbBody) } }, (res2) => { res2.resume(); resolve({ ok: res2.statusCode < 500, status: res2.statusCode }); });
+              r.on('error', () => resolve({ ok: false, status: 0, error: 'unreachable' }));
+              r.setTimeout(5000, () => { r.destroy(); resolve({ ok: false, status: 0, error: 'timeout' }); });
+              r.write(sbBody); r.end();
+            });
+          })()
         : Promise.resolve({ ok: false, status: 0, error: 'key not set' }),
       depCheck('rdap.org', '/domain/example.com'),
       depCheck('api.anthropic.com', '/v1/models', ANTHROPIC_API_KEY ? { 'x-api-key': ANTHROPIC_API_KEY, 'anthropic-version': '2023-06-01' } : {})
@@ -420,8 +456,10 @@ const server = http.createServer(async (req, res) => {
     const ipMap = stats.free_tier_calls_by_ip || {};
     const free_tier_unique_ips = Object.keys(ipMap).length;
     const free_tier_total_calls = Object.values(ipMap).reduce((t, m) => t + Object.values(m).reduce((a,b) => a+b, 0), 0);
+    const toolCounts = {};
+    usageLog.forEach(e => { toolCounts[e.tool] = (toolCounts[e.tool] || 0) + 1; });
     res.writeHead(200, { ...cors, 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ version: VERSION, total_checks: stats.total_checks, safe_count: stats.safe_count, suspicious_count: stats.suspicious_count, dangerous_count: stats.dangerous_count, free_tier_unique_ips, free_tier_total_calls, paid_keys_issued: apiKeys.size, started_at: stats.started_at }));
+    res.end(JSON.stringify({ version: VERSION, total_checks: stats.total_checks, safe_count: stats.safe_count, suspicious_count: stats.suspicious_count, dangerous_count: stats.dangerous_count, free_tier_unique_ips, free_tier_total_calls, paid_keys_issued: apiKeys.size, started_at: stats.started_at, tool_usage: toolCounts, recent_calls: usageLog.slice(-20).reverse() }));
     return;
   }
 
@@ -444,10 +482,13 @@ const server = http.createServer(async (req, res) => {
         if (event.type === 'checkout.session.completed') {
           const session = event.data.object;
           const key = 'usv_' + crypto.randomBytes(16).toString('hex');
-          const email = session.customer_details?.email || 'unknown';
+          const email = session.customer_details?.email || session.customer_email || 'unknown';
           apiKeys.set(key, { email, created_at: nowISO(), plan: 'pro' });
           saveStats();
-          console.log(`New paid key issued: ${email}`);
+          console.log('[stripe] API key issued to: ' + email);
+          if (email && email !== 'unknown') {
+            sendApiKeyEmail(email, key, 'pro').catch(err => console.error('[stripe] Email send failed:', err.message));
+          }
         }
         res.writeHead(200, cors); res.end(JSON.stringify({ received: true }));
       } catch(e) {
@@ -469,7 +510,7 @@ const server = http.createServer(async (req, res) => {
         let response;
 
         if (request.method === 'initialize') {
-          response = { jsonrpc: '2.0', id: request.id, result: { protocolVersion: '2024-11-05', capabilities: { tools: {}, resources: {}, prompts: {} }, serverInfo: { name: 'url-safety-validator-mcp', version: VERSION } } };
+          response = { jsonrpc: '2.0', id: request.id, result: { protocolVersion: '2024-11-05', capabilities: { tools: {}, resources: {}, prompts: {} }, serverInfo: { name: 'url-safety-validator-mcp', version: VERSION, description: 'Real-time URL safety checking for AI agents. Cross-checks Google Web Risk and AI analysis before your agent visits, fetches, or passes any URL. One call eliminates an entire class of agent security failures. 1 tool. Free tier: 10 calls/month.' } } };
         } else if (request.method === 'notifications/initialized') {
           res.writeHead(204, cors); res.end(); return;
         } else if (request.method === 'tools/list') {
@@ -481,19 +522,17 @@ const server = http.createServer(async (req, res) => {
         } else if (request.method === 'tools/call' && request.params?.name === 'check_url') {
           const url = request.params?.arguments?.url;
           if (!url) {
-            response = { jsonrpc: '2.0', id: request.id, error: { code: -32602, message: 'url parameter required' } };
+            response = { jsonrpc: '2.0', id: request.id, result: { content: [{ type: 'text', text: JSON.stringify({ error: 'url parameter required', agent_action: 'Retry with a url parameter value. Example: {"url":"https://example.com"}', likely_cause: 'Missing required url argument in tool call', _disclaimer: LEGAL_DISCLAIMER }) }] } };
           } else {
             const tier = checkTier(clientIp, apiKey);
             if (!tier.allowed) {
-              response = { jsonrpc: '2.0', id: request.id, result: { content: [{ type: 'text', text: JSON.stringify({ error: 'Free tier limit of 10 calls/month reached. You have seen it work -- upgrade to Pro ($29/month) at kordagencies.com.', upgrade_url: 'https://kordagencies.com' }) }] } };
+              response = { jsonrpc: '2.0', id: request.id, result: { content: [{ type: 'text', text: JSON.stringify({ error: 'Free tier limit of 10 calls/month reached', agent_action: 'Inform user that free quota is exhausted. Upgrade available at kordagencies.com.', upgrade_url: 'https://kordagencies.com', _disclaimer: LEGAL_DISCLAIMER }) }] } };
             } else {
-              if (tier.remaining <= 4 && !tier.paid) {
-                // will add notice to result
-              }
               recordCall(clientIp, apiKey);
               const result = await checkUrl(url);
+              usageLog.push({ tool: 'check_url', ip: clientIp, tier: tier.paid ? 'paid' : 'free', timestamp: nowISO() });
               if (tier.remaining <= 4 && !tier.paid) {
-                result._notice = `Warning: ${tier.remaining - 1} free calls remaining this month. Upgrade to Pro at kordagencies.com to avoid interruption.`;
+                result._notice = 'Warning: ' + (tier.remaining - 1) + ' free calls remaining this month. Upgrade to Pro at kordagencies.com to avoid interruption.';
               }
               response = { jsonrpc: '2.0', id: request.id, result: { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] } };
             }