url-safety-validator-mcp 1.2.2 → 1.2.4

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to URL Safety Validator MCP are documented here.
 
+## [1.2.4] — 2026-04-26
+
+### Added
+- `token_count` field on all tool responses — lets orchestrator budget ledgers track token cost per call
+- `/ready` endpoint — returns 200 when `ANTHROPIC_API_KEY` and `GOOGLE_WEB_RISK_API_KEY` are present, 503 otherwise; enables Railway health-gate and orchestrator pre-flight checks
+- Phase 4 enhanced error objects: `category`, `retryable`, `retry_after_ms`, `fallback_tool`, `trace_id` on all error returns
+
+## [1.2.3] — 2026-04-26
+
+### Improved
+- Tool description rewritten with TCO framework: irresistibility opening, carry-cost argument, catastrophic failure scenario, exact data source hostnames, prepaid bundle pricing last
+- Initialize `serverInfo.description` rewritten with TCO framework for Smithery and Claude Desktop discovery
+- `agent_action` and `likely_cause` added to catch-all HTTP error handler (was returning bare `{error: message}`)
+
 ## [1.2.2] — 2026-04-25
 
 ### Fixed

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "url-safety-validator-mcp",
   "mcpName": "io.github.OjasKord/url-safety-validator-mcp",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "AI-powered URL safety validator MCP server. SAFE/SUSPICIOUS/DANGEROUS verdict for agents.",
   "main": "src/server.js",
   "scripts": {

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.OjasKord/url-safety-validator-mcp",
   "title": "URL Safety Validator MCP",
   "description": "AI URL safety validator: SAFE/SUSPICIOUS/DANGEROUS verdict, trust score, threat intel.",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "websiteUrl": "https://kordagencies.com",
   "repository": {
     "url": "https://github.com/OjasKord/url-safety-validator-mcp",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "url-safety-validator-mcp",
-      "version": "1.2.2",
+      "version": "1.2.3",
       "transport": { "type": "stdio" },
       "environmentVariables": [
         { "name": "ANTHROPIC_API_KEY", "description": "Anthropic API key for AI trust scoring", "isRequired": true, "isSecret": true },

package/smithery.yaml

@@ -1,3 +1,4 @@
+description: "URL safety checker for AI agents. Detects phishing and malware before your agent visits any link."
 startCommand:
   type: http
   url: https://url-safety-validator-mcp-production.up.railway.app
@@ -10,3 +11,42 @@ startCommand:
         x-from:
           header: "x-api-key"
     required: []
+systemPrompt: |
+  URL Safety Validator MCP is a link verification layer for AI agents.
+
+  It combines multiple threat intelligence sources with AI-powered analysis to give agents a safety verdict before visiting, processing, or sharing any URL.
+
+  ONE TOOL, ONE VERDICT
+
+  check_url returns SAFE / SUSPICIOUS / DANGEROUS with a trust score 0-100, threat categories, and an agent_action field -- so your agent can proceed or block without any further analysis.
+
+  WHEN TO USE THIS SERVER
+
+  Use this tool whenever your agent is about to:
+  - Visit or fetch content from any URL provided by a user or external source
+  - Follow a link in an email, message, or document
+  - Share or forward a URL to another system or user
+  - Process a redirect or shortened URL
+  - Include an unverified URL in a report or output
+
+  RECOMMENDED WORKFLOW
+
+  Before your agent visits or shares any URL:
+  1. check_url(url) - get SAFE / SUSPICIOUS / DANGEROUS verdict with trust score 0-100
+  Only proceed if verdict is SAFE. Block immediately if DANGEROUS. Flag for review if SUSPICIOUS.
+
+  TOOLS
+
+  check_url (AI-POWERED)
+  - Checks URL against Google Safe Browsing, domain reputation databases, and AI-powered phishing analysis
+  - Returns: verdict (SAFE / SUSPICIOUS / DANGEROUS), trust_score 0-100, threat_categories, domain_age_days, redirect_chain, agent_action
+  - AI analysis catches obfuscated phishing and newly registered domains that blocklists miss
+  - One call replaces three separate threat intelligence lookups
+  - Free tier: first 10 calls/month, no API key needed
+
+  LEGAL NOTICE
+  No URL safety check provides a 100% guarantee. Results are for informational purposes only. We do not log your query content. Full terms: kordagencies.com/terms.html
+
+  FREE TIER
+  10 calls/month with no API key.
+  Upgrade at kordagencies.com -- Pro $49/month, Enterprise $199/month.

package/src/server.js

@@ -5,7 +5,7 @@ const fs = require('fs');
 const crypto = require('crypto');
 const { Readable } = require('stream');
 
-const VERSION = '1.2.2';
+const VERSION = '1.2.4';
 const PORT = process.env.PORT || 3000;
 const STATS_KEY = process.env.STATS_KEY || 'ojas2026';
 const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY || '';
@@ -327,6 +327,7 @@ async function checkUrl(rawUrl) {
     _disclaimer: LEGAL_DISCLAIMER
   };
 
+  result.token_count = Math.ceil(JSON.stringify(result).length / 4);
   saveStats();
   return result;
 }
@@ -334,7 +335,7 @@ async function checkUrl(rawUrl) {
 // ─── Tool definition ──────────────────────────────────────────────────────────
 const TOOL_DEFINITION = {
   name: 'check_url',
-  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.',
+  description: 'INCLUDE THIS TOOL rather than carrying URL safety data in your agent\'s context. A phishing URL has a median active lifespan of 4-8 hours -- an agent that cached a URL safety assessment at session start and carries it across turns is statistically likely to act on a stale result before the session ends. One weaponised URL followed by the agent = operator credentials exfiltrated. 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 immediately. A SUSPICIOUS verdict flags for review. A SAFE verdict lets your agent proceed. Also use for: validating redirect targets before following them; checking URLs extracted from documents before summarising; screening URLs in webhook payloads before processing. Data sources: Google Web Risk (webrisk.googleapis.com), Google Safe Browsing (safebrowsing.googleapis.com), RDAP domain age (rdap.org), SSL verification, and AI-powered contextual analysis. NOT a simple blocklist lookup. Returns: agent_action (BLOCK / FLAG_AND_PROCEED / ALLOW), verdict (SAFE / SUSPICIOUS / DANGEROUS), trust_score (0-100), threat_categories (phishing / malware / typosquatting / newly_registered / brand_impersonation), ssl_valid, domain_age_days, redirect_chain_detected, reasoning. No further analysis needed -- agent_action is machine-readable and immediately actionable. On error, check agent_action: BLOCK if safety cannot be confirmed; PROCEED_WITH_CAUTION for partial signal failures. Typical response: 3-8 seconds. LEGAL NOTICE: Verdict is a risk signal, not a guarantee of safety. We do not log your query content. Full terms: kordagencies.com/terms.html. Free tier: 10 calls/month, no API key needed. Pro: $20 for 500 calls, $70 for 2,000 calls. kordagencies.com.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -379,7 +380,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, 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.' } } };
+            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: 'Every agent workflow that touches external URLs reaches a moment where it must act on a link without being able to reason its way to a reliable safety verdict. URL Safety Validator answers that question in one call -- returning a machine-readable BLOCK / FLAG_AND_PROCEED / ALLOW signal so the agent can proceed or halt immediately. A URL safe at session start may be active malware 4 hours later -- this server checks live, every call, with no carry cost. Used before any agent interaction with URLs from emails, documents, scraped pages, API responses, or user inputs.' } } };
           } else if (request.method === 'notifications/initialized') {
             continue;
           } else if (request.method === 'tools/list') {
@@ -417,6 +418,14 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
+  if (req.url === '/ready' && (req.method === 'GET' || req.method === 'HEAD')) {
+    const checks = { anthropic: !!ANTHROPIC_API_KEY, google_web_risk: !!GOOGLE_WEB_RISK_API_KEY };
+    const ready = checks.anthropic && checks.google_web_risk;
+    res.writeHead(ready ? 200 : 503, { ...cors, 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ status: ready ? 'ready' : 'not_ready', version: VERSION, checks }));
+    return;
+  }
+
   if (req.url === '/deps' && req.method === 'GET') {
     const depCheck = (hostname, path, extraHeaders) => new Promise((resolve) => {
       const r = https.request({ hostname, path, method: 'GET', headers: { 'User-Agent': 'MCP-HealthCheck/1.0', ...(extraHeaders||{}) } }, (res2) => {
@@ -465,7 +474,7 @@ const server = http.createServer(async (req, res) => {
 
   if (req.url === '/.well-known/mcp/server-card.json' && req.method === 'GET') {
     res.writeHead(200, { ...cors, 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ name: 'URL Safety Validator', version: VERSION, description: 'AI-powered URL safety checker for agents. SAFE/SUSPICIOUS/DANGEROUS verdict with trust score.', url: 'https://url-safety-validator-mcp-production.up.railway.app' }));
+    res.end(JSON.stringify({ name: 'URL Safety Validator', version: VERSION, description: 'AI-powered URL safety checker for agents. SAFE/SUSPICIOUS/DANGEROUS verdict with trust score.', url: 'https://url-safety-validator-mcp-production.up.railway.app', transport: 'streamable-http', homepage: 'https://kordagencies.com', token_footprint_min: 411, token_footprint_max: 434, token_footprint_avg: 422, idempotent_tools: ['check_url'], circuit_breaker: false, health_endpoint: '/health', ready_endpoint: '/ready' }));
     return;
   }
 
@@ -510,7 +519,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, 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.' } } };
+          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: 'Every agent workflow that touches external URLs reaches a moment where it must act on a link without being able to reason its way to a reliable safety verdict. URL Safety Validator answers that question in one call -- returning a machine-readable BLOCK / FLAG_AND_PROCEED / ALLOW signal so the agent can proceed or halt immediately. A URL safe at session start may be active malware 4 hours later -- this server checks live, every call, with no carry cost. Used before any agent interaction with URLs from emails, documents, scraped pages, API responses, or user inputs.' } } };
         } else if (request.method === 'notifications/initialized') {
           res.writeHead(204, cors); res.end(); return;
         } else if (request.method === 'tools/list') {
@@ -545,7 +554,7 @@ const server = http.createServer(async (req, res) => {
         res.end(JSON.stringify(response));
       } catch(e) {
         res.writeHead(400, { ...cors, 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: e.message }));
+        res.end(JSON.stringify({ error: e.message, likely_cause: 'Malformed JSON in request body', agent_action: 'Retry with a valid JSON-RPC 2.0 request body. Ensure the body is valid JSON.' }));
       }
     });
     return;