freshcontext-mcp 0.3.14 → 0.3.16

package/dist/server.js

@@ -11,6 +11,7 @@ import { packageTrendsAdapter } from "./adapters/packageTrends.js";
 import { redditAdapter } from "./adapters/reddit.js";
 import { productHuntAdapter } from "./adapters/productHunt.js";
 import { financeAdapter } from "./adapters/finance.js";
+import { arxivAdapter } from "./adapters/arxiv.js";
 import { jobsAdapter } from "./adapters/jobs.js";
 import { changelogAdapter } from "./adapters/changelog.js";
 import { govContractsAdapter } from "./adapters/govcontracts.js";
@@ -88,7 +89,7 @@ server.registerTool("extract_yc", {
 }, async ({ url, max_length }) => {
     try {
         const result = await ycAdapter({ url, maxLength: max_length });
-        const ctx = stampFreshness(result, { url, maxLength: max_length }, "ycombinator");
+        const ctx = stampFreshness(result, { url, maxLength: max_length }, "yc");
         return { content: [{ type: "text", text: formatForLLM(ctx) }] };
     }
     catch (err) {
@@ -106,7 +107,7 @@ server.registerTool("search_repos", {
 }, async ({ query, max_length }) => {
     try {
         const result = await repoSearchAdapter({ url: query, maxLength: max_length });
-        const ctx = stampFreshness(result, { url: query, maxLength: max_length }, "github_search");
+        const ctx = stampFreshness(result, { url: query, maxLength: max_length }, "reposearch");
         return { content: [{ type: "text", text: formatForLLM(ctx) }] };
     }
     catch (err) {
@@ -124,13 +125,97 @@ server.registerTool("package_trends", {
 }, async ({ packages, max_length }) => {
     try {
         const result = await packageTrendsAdapter({ url: packages, maxLength: max_length });
-        const ctx = stampFreshness(result, { url: packages, maxLength: max_length }, "package_registry");
+        const ctx = stampFreshness(result, { url: packages, maxLength: max_length }, "packagetrends");
         return { content: [{ type: "text", text: formatForLLM(ctx) }] };
     }
     catch (err) {
         return { content: [{ type: "text", text: formatSecurityError(err) }] };
     }
 });
+// ─── Tool: extract_arxiv ─────────────────────────────────────────────────────
+server.registerTool("extract_arxiv", {
+    description: "Search arXiv for research papers via the official API. Pass a topic, keyword, or full arXiv API URL. Returns titles, authors, publication dates, primary category, and abstracts — all timestamped.",
+    inputSchema: z.object({
+        url: z.string().describe("Search query e.g. 'temporal retrieval', or a full arXiv API URL"),
+        max_length: z.number().optional().default(6000),
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ url, max_length }) => {
+    try {
+        const result = await arxivAdapter({ url, maxLength: max_length });
+        const ctx = stampFreshness(result, { url, maxLength: max_length }, "arxiv");
+        return { content: [{ type: "text", text: formatForLLM(ctx) }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: formatSecurityError(err) }] };
+    }
+});
+// ─── Tool: extract_finance ───────────────────────────────────────────────────
+server.registerTool("extract_finance", {
+    description: "Live stock data via Yahoo Finance — price, change, market cap, P/E, 52w range, sector, business summary. Accepts up to 5 comma-separated tickers. Returns timestamped freshcontext.",
+    inputSchema: z.object({
+        url: z.string().describe("Ticker symbol(s) e.g. 'AAPL' or 'MSFT,GOOG,PLTR'"),
+        max_length: z.number().optional().default(5000),
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ url, max_length }) => {
+    try {
+        const result = await financeAdapter({ url, maxLength: max_length });
+        const ctx = stampFreshness(result, { url, maxLength: max_length }, "finance");
+        return { content: [{ type: "text", text: formatForLLM(ctx) }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: formatSecurityError(err) }] };
+    }
+});
+// ─── Tool: extract_reddit ────────────────────────────────────────────────────
+server.registerTool("extract_reddit", {
+    description: "Extract posts and community sentiment from Reddit via the public JSON API. Accepts a subreddit URL (https://www.reddit.com/r/MachineLearning/.json), a search URL, or a subreddit shorthand ('r/MachineLearning'). Returns titles, authors, scores, comment counts, and per-post timestamps.",
+    inputSchema: z.object({
+        url: z.string().describe("Subreddit URL, search URL, or 'r/<subreddit>' shorthand"),
+        max_length: z.number().optional().default(6000),
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ url, max_length }) => {
+    try {
+        const result = await redditAdapter({ url, maxLength: max_length });
+        const ctx = stampFreshness(result, { url, maxLength: max_length }, "reddit");
+        return { content: [{ type: "text", text: formatForLLM(ctx) }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: formatSecurityError(err) }] };
+    }
+});
+// ─── Tool: extract_producthunt ───────────────────────────────────────────────
+server.registerTool("extract_producthunt", {
+    description: "Recent Product Hunt launches by keyword or topic. Uses the Product Hunt GraphQL API (with HTML scrape fallback). Returns names, taglines, vote counts, comment counts, topics, and launch dates — all timestamped.",
+    inputSchema: z.object({
+        url: z.string().describe("Search query e.g. 'mcp ai agents' or a Product Hunt topic URL"),
+        max_length: z.number().optional().default(6000),
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ url, max_length }) => {
+    try {
+        const result = await productHuntAdapter({ url, maxLength: max_length });
+        const ctx = stampFreshness(result, { url, maxLength: max_length }, "producthunt");
+        return { content: [{ type: "text", text: formatForLLM(ctx) }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: formatSecurityError(err) }] };
+    }
+});
+function sectionWithFreshnessCheck(label, result, adapterName, minScore, errorWord = "Unavailable") {
+    if (result.status !== "fulfilled") {
+        return `## ${label}\n[${errorWord}: ${result.reason}]`;
+    }
+    if (minScore !== undefined && minScore > 0) {
+        const ctx = stampFreshness(result.value, { url: "", maxLength: 0 }, adapterName);
+        if (ctx.freshness_score !== null && ctx.freshness_score < minScore) {
+            return `## ${label}\n[Stale — freshness_score: ${ctx.freshness_score}/100 is below min_freshness_score threshold of ${minScore}. Content date: ${result.value.content_date ?? "unknown"}. Re-query for fresher data.]`;
+        }
+    }
+    return `## ${label}\n${result.value.raw}`;
+}
 // ─── Tool: extract_landscape ─────────────────────────────────────────────────
 server.registerTool("extract_landscape", {
     description: "Composite intelligence tool. Given a project idea or keyword, simultaneously queries YC startups, GitHub repos, HN, Reddit, Product Hunt, and package registries to answer: Who is building this? Is it funded? What's getting traction? Returns a unified 6-source timestamped landscape report.",
@@ -237,37 +322,31 @@ server.registerTool("extract_gov_landscape", {
         query: z.string().describe("Company name (e.g. 'Palantir'), keyword (e.g. 'artificial intelligence'), or NAICS code (e.g. '541511'). For GitHub and changelog sections, also optionally provide a GitHub URL."),
         github_url: z.string().optional().describe("Optional GitHub repo URL for the company (e.g. 'https://github.com/palantir/palantir-java-format'). If omitted, GitHub and changelog sections use the query as a search term."),
         max_length: z.number().optional().default(12000),
+        min_freshness_score: z.number().optional().describe("Filter sections below this freshness_score (0–100). E.g. 70 = only recently retrieved data."),
     }),
     annotations: { readOnlyHint: true, openWorldHint: true },
-}, async ({ query, github_url, max_length }) => {
+}, async ({ query, github_url, max_length, min_freshness_score }) => {
     const perSection = Math.floor((max_length ?? 12000) / 4);
-    // All four sources fire in parallel — if one fails the others still return
     const [contractsResult, hnResult, repoResult, changelogResult] = await Promise.allSettled([
-        // 1. The anchor: who is actually winning federal money in this space
         govContractsAdapter({ url: query, maxLength: perSection }),
-        // 2. Dev community signal: does anyone in tech know about these companies
         hackerNewsAdapter({
             url: `https://hn.algolia.com/api/v1/search?query=${encodeURIComponent(query)}&tags=story&hitsPerPage=10`,
             maxLength: perSection,
         }),
-        // 3. GitHub activity: are they actually building, or contract farmers
         repoSearchAdapter({ url: github_url ?? query, maxLength: perSection }),
-        // 4. Release velocity: how fast are they shipping product
         changelogAdapter({ url: github_url ?? query, maxLength: perSection }),
     ]);
-    const section = (label, result) => result.status === "fulfilled"
-        ? `## ${label}\n${result.value.raw}`
-        : `## ${label}\n[Unavailable: ${result.reason}]`;
     const combined = [
         `# Government Intelligence Landscape: "${query}"`,
         `Generated: ${new Date().toISOString()}`,
         `Sources: USASpending.gov · Hacker News · GitHub · Changelog`,
+        min_freshness_score ? `min_freshness_score: ${min_freshness_score}` : null,
         "",
-        section("🏛️ Federal Contract Awards (USASpending.gov)", contractsResult),
-        section("💬 Developer Community Awareness (Hacker News)", hnResult),
-        section("📦 GitHub Repository Activity", repoResult),
-        section("🔄 Product Release Velocity (Changelog)", changelogResult),
-    ].join("\n\n");
+        sectionWithFreshnessCheck("🏛️ Federal Contract Awards (USASpending.gov)", contractsResult, "govcontracts", min_freshness_score),
+        sectionWithFreshnessCheck("💬 Developer Community Awareness (Hacker News)", hnResult, "hackernews", min_freshness_score),
+        sectionWithFreshnessCheck("📦 GitHub Repository Activity", repoResult, "reposearch", min_freshness_score),
+        sectionWithFreshnessCheck("🔄 Product Release Velocity (Changelog)", changelogResult, "changelog", min_freshness_score),
+    ].filter(Boolean).join("\n\n");
     return { content: [{ type: "text", text: combined }] };
 });
 // ─── Tool: extract_finance_landscape ─────────────────────────────────────────
@@ -282,43 +361,35 @@ server.registerTool("extract_finance_landscape", {
         company_name: z.string().optional().describe("Company name for HN/Reddit/GitHub searches e.g. 'Palantir'. If omitted, derived from the ticker."),
         github_query: z.string().optional().describe("GitHub search query or repo URL for the company's tech ecosystem e.g. 'palantir' or 'https://github.com/palantir/foundry'. If omitted, uses company_name."),
         max_length: z.number().optional().default(12000),
+        min_freshness_score: z.number().optional().describe("Filter sections below this freshness_score (0–100). E.g. 70 = only recently retrieved data."),
     }),
     annotations: { readOnlyHint: true, openWorldHint: true },
-}, async ({ tickers, company_name, github_query, max_length }) => {
+}, async ({ tickers, company_name, github_query, max_length, min_freshness_score }) => {
     const perSection = Math.floor((max_length ?? 12000) / 5);
-    // Derive a search term: prefer explicit company_name, fall back to first ticker
     const searchTerm = company_name ?? tickers.split(",")[0].trim();
     const repoQuery = github_query ?? searchTerm;
-    // All five sources fire in parallel
     const [priceResult, hnResult, redditResult, repoResult, changelogResult] = await Promise.allSettled([
-        // 1. The anchor: live price, market cap, P/E, 52w range
         financeAdapter({ url: tickers, maxLength: perSection }),
-        // 2. Developer sentiment: what engineers think of this company's tech
         hackerNewsAdapter({
             url: `https://hn.algolia.com/api/v1/search?query=${encodeURIComponent(searchTerm)}&tags=story&hitsPerPage=10`,
             maxLength: perSection,
         }),
-        // 3. Broader community: investor and tech community discussion on Reddit
         redditAdapter({ url: `https://www.reddit.com/search.json?q=${encodeURIComponent(searchTerm)}&sort=new&limit=15`, maxLength: perSection }),
-        // 4. Repo ecosystem: how many GitHub projects orbit this company's technology
         repoSearchAdapter({ url: repoQuery, maxLength: perSection }),
-        // 5. Release velocity: is the company actually shipping product right now
         changelogAdapter({ url: repoQuery, maxLength: perSection }),
     ]);
-    const section = (label, result) => result.status === "fulfilled"
-        ? `## ${label}\n${result.value.raw}`
-        : `## ${label}\n[Unavailable: ${result.reason}]`;
     const combined = [
         `# Finance + Developer Intelligence: "${tickers}"${company_name ? ` (${company_name})` : ""}`,
         `Generated: ${new Date().toISOString()}`,
         `Sources: Yahoo Finance · Hacker News · Reddit · GitHub · Changelog`,
+        min_freshness_score ? `min_freshness_score: ${min_freshness_score}` : null,
         "",
-        section("📈 Market Data (Yahoo Finance)", priceResult),
-        section("💬 Developer Sentiment (Hacker News)", hnResult),
-        section("🗣️ Community Discussion (Reddit)", redditResult),
-        section("📦 Repo Ecosystem (GitHub)", repoResult),
-        section("🔄 Product Release Velocity (Changelog)", changelogResult),
-    ].join("\n\n");
+        sectionWithFreshnessCheck("📈 Market Data (Yahoo Finance)", priceResult, "finance", min_freshness_score),
+        sectionWithFreshnessCheck("💬 Developer Sentiment (Hacker News)", hnResult, "hackernews", min_freshness_score),
+        sectionWithFreshnessCheck("🗣️ Community Discussion (Reddit)", redditResult, "reddit", min_freshness_score),
+        sectionWithFreshnessCheck("📦 Repo Ecosystem (GitHub)", repoResult, "reposearch", min_freshness_score),
+        sectionWithFreshnessCheck("🔄 Product Release Velocity (Changelog)", changelogResult, "changelog", min_freshness_score),
+    ].filter(Boolean).join("\n\n");
     return { content: [{ type: "text", text: combined }] };
 });
 // ─── Tool: extract_sec_filings ─────────────────────────────────────────────
@@ -377,37 +448,31 @@ server.registerTool("extract_company_landscape", {
         ticker: z.string().optional().describe("Stock ticker for finance data e.g. 'PLTR'. Leave blank for private companies."),
         github_url: z.string().optional().describe("Optional GitHub repo or org URL e.g. 'https://github.com/palantir'. Improves changelog accuracy."),
         max_length: z.number().optional().default(15000),
+        min_freshness_score: z.number().optional().describe("Filter sections below this freshness_score (0–100). E.g. 70 = only recently retrieved data."),
     }),
     annotations: { readOnlyHint: true, openWorldHint: true },
-}, async ({ company, ticker, github_url, max_length }) => {
+}, async ({ company, ticker, github_url, max_length, min_freshness_score }) => {
     const perSection = Math.floor((max_length ?? 15000) / 5);
     const repoQuery = github_url ?? company;
     const [secResult, contractsResult, gdeltResult, changelogResult, financeResult] = await Promise.allSettled([
-        // 1. What did they legally just disclose
         secFilingsAdapter({ url: company, maxLength: perSection }),
-        // 2. Who is giving them government money
         govContractsAdapter({ url: company, maxLength: perSection }),
-        // 3. What is global news saying right now
         gdeltAdapter({ url: company, maxLength: perSection }),
-        // 4. Are they actually shipping product
         changelogAdapter({ url: repoQuery, maxLength: perSection }),
-        // 5. What is the market pricing in
         financeAdapter({ url: ticker ?? company, maxLength: perSection }),
     ]);
-    const section = (label, result) => result.status === "fulfilled"
-        ? `## ${label}\n${result.value.raw}`
-        : `## ${label}\n[Unavailable: ${result.reason}]`;
     const combined = [
         `# Company Intelligence Landscape: "${company}"${ticker ? ` (${ticker})` : ""}`,
         `Generated: ${new Date().toISOString()}`,
         `Sources: SEC EDGAR · USASpending.gov · GDELT · Changelog · Yahoo Finance`,
+        min_freshness_score ? `min_freshness_score: ${min_freshness_score}` : null,
         "",
-        section("📋 SEC 8-K Filings — Legal Disclosures", secResult),
-        section("🏛️ Federal Contract Awards (USASpending.gov)", contractsResult),
-        section("🌍 Global News Intelligence (GDELT)", gdeltResult),
-        section("🔄 Product Release Velocity (Changelog)", changelogResult),
-        section("📈 Market Data (Yahoo Finance)", financeResult),
-    ].join("\n\n");
+        sectionWithFreshnessCheck("📋 SEC 8-K Filings — Legal Disclosures", secResult, "sec_filings", min_freshness_score),
+        sectionWithFreshnessCheck("🏛️ Federal Contract Awards (USASpending.gov)", contractsResult, "govcontracts", min_freshness_score),
+        sectionWithFreshnessCheck("🌍 Global News Intelligence (GDELT)", gdeltResult, "gdelt", min_freshness_score),
+        sectionWithFreshnessCheck("🔄 Product Release Velocity (Changelog)", changelogResult, "changelog", min_freshness_score),
+        sectionWithFreshnessCheck("📈 Market Data (Yahoo Finance)", financeResult, "finance", min_freshness_score),
+    ].filter(Boolean).join("\n\n");
     return { content: [{ type: "text", text: combined }] };
 });
 // ─── Tool: extract_gebiz ────────────────────────────────────────────────────
@@ -442,37 +507,30 @@ server.registerTool("extract_idea_landscape", {
     inputSchema: z.object({
         idea: z.string().describe("Your idea, problem space, or keyword. E.g. 'data freshness for AI agents', 'procurement intelligence', 'developer observability'"),
         max_length: z.number().optional().default(14000),
+        min_freshness_score: z.number().optional().describe("Filter sections below this freshness_score (0–100). E.g. 70 = only recently retrieved data."),
     }),
     annotations: { readOnlyHint: true, openWorldHint: true },
-}, async ({ idea, max_length }) => {
+}, async ({ idea, max_length, min_freshness_score }) => {
     const perSection = Math.floor((max_length ?? 14000) / 6);
     const [hnResult, ycResult, repoResult, jobsResult, pkgResult, phResult] = await Promise.allSettled([
-        // 1. Pain signal — what are developers actively complaining about
         hackerNewsAdapter({
             url: `https://hn.algolia.com/api/v1/search?query=${encodeURIComponent(idea)}&tags=story&hitsPerPage=10`,
             maxLength: perSection,
         }),
-        // 2. Funding signal — who has already raised money in this space
         ycAdapter({
             url: `https://www.ycombinator.com/companies?query=${encodeURIComponent(idea)}`,
             maxLength: perSection,
         }),
-        // 3. Crowding signal — how many GitHub repos exist, how active
         repoSearchAdapter({ url: idea, maxLength: perSection }),
-        // 4. Market signal — companies paying salaries = real spend on this problem
         jobsAdapter({ url: idea, maxLength: perSection }),
-        // 5. Ecosystem signal — npm/PyPI adoption and release velocity
         packageTrendsAdapter({ url: idea, maxLength: perSection }),
-        // 6. Launch signal — what just shipped and how the market received it
         productHuntAdapter({ url: idea, maxLength: perSection }),
     ]);
-    const section = (label, result) => result.status === "fulfilled"
-        ? `## ${label}\n${result.value.raw}`
-        : `## ${label}\n[Unavailable: ${result.reason}]`;
     const combined = [
         `# Idea Validation Landscape: "${idea}"`,
         `Generated: ${new Date().toISOString()}`,
         `Sources: Hacker News · YC Companies · GitHub · Job Listings · npm/PyPI · Product Hunt`,
+        min_freshness_score ? `min_freshness_score: ${min_freshness_score}` : null,
         "",
         `## ℹ️ How to read this report`,
         `Pain signal (HN): Are developers actively discussing this problem?`,
@@ -482,13 +540,13 @@ server.registerTool("extract_idea_landscape", {
         `Ecosystem signal (npm/PyPI): Are packages being built and adopted?`,
         `Launch signal (Product Hunt): What just shipped — community reception and timing.`,
         "",
-        section("🗣️ Pain Signal — Developer Discussions (Hacker News)", hnResult),
-        section("💰 Funding Signal — Backed Companies (YC)", ycResult),
-        section("📦 Crowding Signal — Open Source Landscape (GitHub)", repoResult),
-        section("💼 Market Signal — Hiring Activity (Job Listings)", jobsResult),
-        section("🔧 Ecosystem Signal — Package Adoption (npm/PyPI)", pkgResult),
-        section("🚀 Launch Signal — Recent Launches (Product Hunt)", phResult),
-    ].join("\n\n");
+        sectionWithFreshnessCheck("🗣️ Pain Signal — Developer Discussions (Hacker News)", hnResult, "hackernews", min_freshness_score),
+        sectionWithFreshnessCheck("💰 Funding Signal — Backed Companies (YC)", ycResult, "yc", min_freshness_score),
+        sectionWithFreshnessCheck("📦 Crowding Signal — Open Source Landscape (GitHub)", repoResult, "reposearch", min_freshness_score),
+        sectionWithFreshnessCheck("💼 Market Signal — Hiring Activity (Job Listings)", jobsResult, "jobs", min_freshness_score),
+        sectionWithFreshnessCheck("🔧 Ecosystem Signal — Package Adoption (npm/PyPI)", pkgResult, "packagetrends", min_freshness_score),
+        sectionWithFreshnessCheck("🚀 Launch Signal — Recent Launches (Product Hunt)", phResult, "producthunt", min_freshness_score),
+    ].filter(Boolean).join("\n\n");
     return { content: [{ type: "text", text: combined }] };
 });
 // ─── Start ───────────────────────────────────────────────────────────────────

package/dist/tools/freshnessStamp.js

@@ -1,26 +1,34 @@
 // ─── Decay rates per adapter ──────────────────────────────────────────────────
-// From FreshContext Specification v1.0.
-// Higher decay = data goes stale faster. Half-life = 100 / (2 * decayRate) days.
-// finance=5.0 (half-life ~10d), jobs=3.0 (~17d), news/hn=2.0 (~25d),
-// github=1.0 (~50d), scholar/arxiv=0.3 (~167d), default=1.5 (~33d)
-const DECAY_RATES = {
-    finance: 5.0,
-    search_jobs: 3.0,
-    hackernews: 2.0,
-    reddit: 2.0,
-    producthunt: 2.0,
-    yc: 1.5,
-    govcontracts: 1.5,
-    github: 1.0,
-    repoSearch: 1.0,
-    packageTrends: 1.0,
-    changelog: 1.0,
-    scholar: 0.3,
-    arxiv: 0.3,
+// Spec-compliant exponential DAR model.
+// Higher lambda = data goes stale faster. Half-life formula: t½ = ln(2) / λ.
+// Lambda is measured per hour and mirrors the Worker/D1 intelligence engine.
+export const LAMBDA = {
+    hackernews: 0.050,
+    reddit: 0.010,
+    producthunt: 0.010,
+    jobs: 0.005,
+    finance: 0.001,
+    yc: 0.001,
+    packagetrends: 0.0005,
+    github: 0.0002,
+    reposearch: 0.0002,
+    google_scholar: 0.00005,
+    arxiv: 0.00005,
+    changelog: 0.0005,
+    gdelt: 0.020,
+    gebiz: 0.003,
+    govcontracts: 0.001,
+    sec_filings: 0.005,
+    landscape: 0.050,
+    gov_landscape: 0.001,
+    finance_landscape: 0.001,
+    company_landscape: 0.005,
+    idea_landscape: 0.050,
+    default: 0.001,
 };
 // ─── Score calculation ────────────────────────────────────────────────────────
 // Returns null when content_date is unknown — we can't calculate age without a date.
-// Returns 0 when the score would go negative (content is very old).
+// Returns a clamped 0-100 exponential freshness score.
 function calculateFreshnessScore(content_date, retrieved_at, adapter) {
     if (!content_date)
         return null;
@@ -29,9 +37,9 @@ function calculateFreshnessScore(content_date, retrieved_at, adapter) {
     // Guard against unparseable dates
     if (isNaN(published) || isNaN(retrieved))
         return null;
-    const daysSinceRetrieved = (retrieved - published) / (1000 * 60 * 60 * 24);
-    const decayRate = DECAY_RATES[adapter] ?? 1.5;
-    return Math.max(0, Math.round(100 - daysSinceRetrieved * decayRate));
+    const hoursSinceRetrieved = Math.max(0, (retrieved - published) / (1000 * 60 * 60));
+    const lambda = LAMBDA[adapter] ?? LAMBDA.default;
+    return Math.max(0, Math.round(100 * Math.exp(-lambda * hoursSinceRetrieved)));
 }
 // ─── Score label ──────────────────────────────────────────────────────────────
 // Human-readable interpretation alongside the number, per the spec.

package/freshcontext-validate.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+
+/**
+ * freshcontext-validate
+ * CLI validator for FreshContext-compatible responses
+ * Spec: https://github.com/PrinceGabriel-lgtm/freshcontext-mcp/blob/main/FRESHCONTEXT_SPEC.md
+ *
+ * Usage:
+ *   node freshcontext-validate.js '<json_string>'
+ *   node freshcontext-validate.js --stdin
+ *   node freshcontext-validate.js --file <path>
+ *   node freshcontext-validate.js --help
+ *
+ * Compliance levels:
+ *   FreshContext-scored ★★★   — JSON form + numeric freshness_score
+ *   FreshContext-compatible ★★ — JSON/envelope with retrieved_at + confidence
+ *   FreshContext-aware ★       — retrieved_at only, no confidence
+ *   FAIL                       — missing required fields
+ */
+
+const REQUIRED_JSON_FIELDS = ['source_url', 'retrieved_at', 'freshness_confidence', 'adapter'];
+const VALID_CONFIDENCE = ['high', 'medium', 'low'];
+const ENVELOPE_START = '[FRESHCONTEXT]';
+const ENVELOPE_END = '[/FRESHCONTEXT]';
+const REQUIRED_ENVELOPE_FIELDS = ['Source:', 'Published:', 'Retrieved:', 'Confidence:'];
+
+const g = s => `\x1b[32m${s}\x1b[0m`;
+const r = s => `\x1b[31m${s}\x1b[0m`;
+const y = s => `\x1b[33m${s}\x1b[0m`;
+const b = s => `\x1b[34m${s}\x1b[0m`;
+const d = s => `\x1b[2m${s}\x1b[0m`;
+const bold = s => `\x1b[1m${s}\x1b[0m`;
+
+const pass = msg => ({ ok: true, warn: false, msg: `  ${g('✓')} ${msg}` });
+const fail = msg => ({ ok: false, warn: false, msg: `  ${r('✕')} ${msg}` });
+const warn = msg => ({ ok: true, warn: true, msg: `  ${y('!')} ${msg}` });
+
+function validateJSON(obj) {
+  const results = [];
+  const fc = obj.freshcontext;
+  if (!fc) return [fail('No "freshcontext" key found in JSON response')];
+
+  for (const field of REQUIRED_JSON_FIELDS) {
+    if (fc[field] === undefined || fc[field] === null) {
+      results.push(fail(`Missing required field: freshcontext.${field}`));
+    } else {
+      results.push(pass(`freshcontext.${field} = ${d(String(fc[field]).slice(0, 80))}`));
+    }
+  }
+
+  if (fc.retrieved_at) {
+    const dt = new Date(fc.retrieved_at);
+    if (isNaN(dt.getTime())) {
+      results.push(fail(`retrieved_at is not valid ISO 8601: "${fc.retrieved_at}"`));
+    } else {
+      results.push(pass(`retrieved_at is valid ISO 8601`));
+    }
+  }
+
+  if (fc.freshness_confidence && !VALID_CONFIDENCE.includes(fc.freshness_confidence)) {
+    results.push(fail(`freshness_confidence must be high, medium, or low. Got: "${fc.freshness_confidence}"`));
+  }
+
+  if (fc.freshness_score !== undefined && fc.freshness_score !== null) {
+    if (typeof fc.freshness_score !== 'number' || fc.freshness_score < 0 || fc.freshness_score > 100) {
+      results.push(fail(`freshness_score must be 0-100. Got: ${fc.freshness_score}`));
+    } else {
+      const col = fc.freshness_score >= 70 ? g : fc.freshness_score >= 50 ? y : r;
+      results.push(pass(`freshness_score: ${col(fc.freshness_score + '/100')}`));
+    }
+  } else {
+    results.push(warn('freshness_score not present (optional — required for ★★★ level)'));
+  }
+
+  return results;
+}
+
+function validateEnvelope(text) {
+  const results = [];
+  if (!text.includes(ENVELOPE_START)) return [fail(`Missing opening tag: ${ENVELOPE_START}`)];
+  if (!text.includes(ENVELOPE_END)) return [fail(`Missing closing tag: ${ENVELOPE_END}`)];
+  results.push(pass('Envelope tags present'));
+
+  const start = text.indexOf(ENVELOPE_START) + ENVELOPE_START.length;
+  const end = text.indexOf(ENVELOPE_END);
+  const envelope = text.slice(start, end);
+
+  for (const field of REQUIRED_ENVELOPE_FIELDS) {
+    if (!envelope.includes(field)) {
+      results.push(fail(`Missing field: ${field}`));
+    } else {
+      const line = envelope.split('\n').find(l => l.trim().startsWith(field));
+      results.push(pass(`${field.replace(':', '')} — ${d((line || '').trim().slice(0, 70))}`));
+    }
+  }
+
+  const confLine = envelope.split('\n').find(l => l.trim().startsWith('Confidence:'));
+  if (confLine) {
+    const confVal = confLine.split(':')[1]?.trim().toLowerCase();
+    if (!VALID_CONFIDENCE.includes(confVal)) {
+      results.push(fail(`Confidence must be high, medium, or low. Got: "${confVal}"`));
+    }
+  }
+
+  return results;
+}
+
+function complianceLevel(results, hasScore, mode) {
+  const failed = results.filter(res => !res.ok).length;
+  if (failed > 0) return { level: 'FAIL', colour: r };
+  if (mode === 'json' && hasScore) return { level: 'FreshContext-scored \u2605\u2605\u2605', colour: g };
+  return { level: 'FreshContext-compatible \u2605\u2605', colour: g };
+}
+
+function validateString(input, label) {
+  console.log(`\n${bold('freshcontext-validate')} ${d('v1.0.0')}`);
+  console.log(d('\u2500'.repeat(52)));
+  console.log(`${b('Input:')} ${d(label)}\n`);
+
+  let results = [];
+  let hasScore = false;
+  let mode = 'envelope';
+
+  try {
+    const parsed = JSON.parse(input);
+    mode = 'json';
+    console.log(`${d('Mode:')} ${b('JSON structured form')}\n`);
+    results = validateJSON(parsed);
+    hasScore = parsed?.freshcontext?.freshness_score !== undefined
+              && parsed?.freshcontext?.freshness_score !== null;
+  } catch {
+    if (input.includes(ENVELOPE_START)) {
+      console.log(`${d('Mode:')} ${b('Text envelope')}\n`);
+      results = validateEnvelope(input);
+    } else {
+      console.log(r('✕ Input is neither valid JSON nor a FreshContext text envelope.\n'));
+      console.log(d('Expected:'));
+      console.log(`  ${d('JSON:')} {"freshcontext": {"source_url": "...", "retrieved_at": "...", ...}}`);
+      console.log(`  ${d('Envelope:')} [FRESHCONTEXT]\\nSource: ...\\n[/FRESHCONTEXT]`);
+      process.exit(1);
+    }
+  }
+
+  results.forEach(res => console.log(res.msg));
+
+  const passed = results.filter(res => res.ok && !res.warn).length;
+  const failed = results.filter(res => !res.ok).length;
+  const warned = results.filter(res => res.warn).length;
+
+  const { level, colour } = complianceLevel(results, hasScore, mode);
+
+  console.log(`\n${d('\u2500'.repeat(52))}`);
+  console.log(`${d('Checks:')} ${g(passed + ' passed')}${warned ? ', ' + y(warned + ' warnings') : ''}${failed ? ', ' + r(failed + ' failed') : ''}`);
+  console.log(`${d('Result:')} ${colour(bold(level))}\n`);
+
+  if (failed > 0) process.exit(1);
+}
+
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+  console.log(`
+${bold('freshcontext-validate')} ${d('v1.0.0')}
+Validates FreshContext-compatible responses against the spec.
+
+${bold('USAGE')}
+  node freshcontext-validate.js ${d('<json_or_envelope_string>')}
+  node freshcontext-validate.js --file ${d('<path>')}
+  node freshcontext-validate.js --stdin
+  echo '...' | node freshcontext-validate.js --stdin
+
+${bold('COMPLIANCE LEVELS')}
+  ${g('FreshContext-scored \u2605\u2605\u2605')}      Full JSON form + numeric freshness_score
+  ${g('FreshContext-compatible \u2605\u2605')}   JSON/envelope with retrieved_at + confidence
+  ${r('FAIL')}                         Missing required fields
+
+${bold('SPEC')}
+  https://freshcontext-site.pages.dev/spec.html
+  https://github.com/PrinceGabriel-lgtm/freshcontext-mcp/blob/main/FRESHCONTEXT_SPEC.md
+`);
+  process.exit(0);
+}
+
+if (args[0] === '--stdin') {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => data += chunk);
+  process.stdin.on('end', () => validateString(data.trim(), 'stdin'));
+} else if (args[0] === '--file') {
+  const path = args[1];
+  if (!path) { console.error(r('--file requires a path argument')); process.exit(1); }
+  const fs = require('fs');
+  validateString(fs.readFileSync(path, 'utf8').trim(), path);
+} else {
+  validateString(args[0], 'inline input');
+}