freshcontext-mcp 0.3.13 → 0.3.15

package/dist/server.js

@@ -9,6 +9,7 @@ import { ycAdapter } from "./adapters/yc.js";
 import { repoSearchAdapter } from "./adapters/repoSearch.js";
 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 { jobsAdapter } from "./adapters/jobs.js";
 import { changelogAdapter } from "./adapters/changelog.js";
@@ -130,6 +131,18 @@ server.registerTool("package_trends", {
         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.",
@@ -236,37 +249,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, "github_search", 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 ─────────────────────────────────────────
@@ -281,43 +288,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, "github_search", 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 ─────────────────────────────────────────────
@@ -376,37 +375,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 ────────────────────────────────────────────────────
@@ -430,6 +423,59 @@ server.registerTool("extract_gebiz", {
         return { content: [{ type: "text", text: formatSecurityError(err) }] };
     }
 });
+// ─── Tool: extract_idea_landscape ───────────────────────────────────────────
+// Idea validation composite — 6 sources that answer: should I build this?
+// HN pain points + YC funded competitors + GitHub crowding + job market signal
+// + package ecosystem adoption + Product Hunt recent launches.
+// The job market section is the key differentiator — companies paying salaries
+// around a problem is the strongest signal a real market exists.
+server.registerTool("extract_idea_landscape", {
+    description: "Idea validation composite tool for developers and founders. Given a project idea or keyword, simultaneously queries 6 sources to answer: Is this problem real? Is the market crowded? Is there funding? Are companies hiring? What just launched? Sources: (1) Hacker News — what developers are actively complaining about and discussing, (2) YC companies — who has already received funding in this space, (3) GitHub repos — how crowded the open source landscape is, (4) Job listings — hiring signal showing real company spend around this problem, (5) npm/PyPI package trends — ecosystem adoption and velocity, (6) Product Hunt — what just launched and how it was received. Returns a unified 6-source idea validation report.",
+    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, min_freshness_score }) => {
+    const perSection = Math.floor((max_length ?? 14000) / 6);
+    const [hnResult, ycResult, repoResult, jobsResult, pkgResult, phResult] = await Promise.allSettled([
+        hackerNewsAdapter({
+            url: `https://hn.algolia.com/api/v1/search?query=${encodeURIComponent(idea)}&tags=story&hitsPerPage=10`,
+            maxLength: perSection,
+        }),
+        ycAdapter({
+            url: `https://www.ycombinator.com/companies?query=${encodeURIComponent(idea)}`,
+            maxLength: perSection,
+        }),
+        repoSearchAdapter({ url: idea, maxLength: perSection }),
+        jobsAdapter({ url: idea, maxLength: perSection }),
+        packageTrendsAdapter({ url: idea, maxLength: perSection }),
+        productHuntAdapter({ url: idea, maxLength: perSection }),
+    ]);
+    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?`,
+        `Funding signal (YC): Has this already attracted institutional money?`,
+        `Crowding signal (GitHub): How many repos exist — empty = opportunity, crowded = validation.`,
+        `Market signal (Jobs): Companies hiring around this = real budget allocated = real market.`,
+        `Ecosystem signal (npm/PyPI): Are packages being built and adopted?`,
+        `Launch signal (Product Hunt): What just shipped — community reception and timing.`,
+        "",
+        sectionWithFreshnessCheck("🗣️ Pain Signal — Developer Discussions (Hacker News)", hnResult, "hackernews", min_freshness_score),
+        sectionWithFreshnessCheck("💰 Funding Signal — Backed Companies (YC)", ycResult, "ycombinator", min_freshness_score),
+        sectionWithFreshnessCheck("📦 Crowding Signal — Open Source Landscape (GitHub)", repoResult, "github_search", min_freshness_score),
+        sectionWithFreshnessCheck("💼 Market Signal — Hiring Activity (Job Listings)", jobsResult, "jobs", min_freshness_score),
+        sectionWithFreshnessCheck("🔧 Ecosystem Signal — Package Adoption (npm/PyPI)", pkgResult, "package_registry", 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 ───────────────────────────────────────────────────────────────────
 async function main() {
     const transport = new StdioServerTransport();

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');
+}

package/freshcontext.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://freshcontext-site.pages.dev/freshcontext.schema.json",
+  "title": "FreshContext",
+  "description": "The FreshContext Specification v1.1 — structured envelope for AI-retrieved web data. https://github.com/PrinceGabriel-lgtm/freshcontext-mcp",
+  "type": "object",
+  "required": ["freshcontext"],
+  "properties": {
+    "freshcontext": {
+      "type": "object",
+      "description": "The freshness metadata envelope for a single retrieved result.",
+      "required": ["source_url", "retrieved_at", "freshness_confidence", "adapter"],
+      "properties": {
+        "source_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The canonical URL of the original source from which content was retrieved."
+        },
+        "content_date": {
+          "type": ["string", "null"],
+          "description": "Best estimate of when the content was originally published. ISO 8601 date (YYYY-MM-DD) or ISO 8601 datetime. Null if unknown.",
+          "examples": ["2026-03-05", "2026-03-05T09:19:00.000Z", null]
+        },
+        "retrieved_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Exact ISO 8601 datetime (with timezone) when this data was fetched.",
+          "examples": ["2026-04-05T09:19:00.000Z"]
+        },
+        "freshness_confidence": {
+          "type": "string",
+          "enum": ["high", "medium", "low"],
+          "description": "Confidence level of the content_date estimate. 'high' = structured API field. 'medium' = inferred from page signals. 'low' = unknown or estimated."
+        },
+        "freshness_score": {
+          "type": ["number", "null"],
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Optional numeric freshness score 0-100. Calculated as: max(0, 100 - (days_since_retrieved * decay_rate)). Null if content_date is unknown.",
+          "examples": [94, 72, 45, null]
+        },
+        "adapter": {
+          "type": "string",
+          "description": "Identifier of the adapter (data source) that produced this result.",
+          "examples": [
+            "github",
+            "hackernews",
+            "google_scholar",
+            "arxiv",
+            "reddit",
+            "ycombinator",
+            "producthunt",
+            "github_search",
+            "package_registry",
+            "finance",
+            "jobs",
+            "changelog",
+            "govcontracts",
+            "sec_filings",
+            "gdelt",
+            "gebiz"
+          ]
+        },
+        "decay_rate": {
+          "type": ["number", "null"],
+          "description": "The decay rate used to calculate freshness_score. Domain-specific. Financial=5.0, jobs=3.0, news=2.0, github=1.0, academic=0.3, default=1.5.",
+          "examples": [5.0, 3.0, 2.0, 1.5, 1.0, 0.3, null]
+        }
+      },
+      "additionalProperties": false
+    },
+    "content": {
+      "type": "string",
+      "description": "The retrieved content — raw text, structured data, or formatted output from the adapter."
+    }
+  },
+  "examples": [
+    {
+      "freshcontext": {
+        "source_url": "https://github.com/PrinceGabriel-lgtm/freshcontext-mcp",
+        "content_date": "2026-04-05",
+        "retrieved_at": "2026-04-05T09:19:00.000Z",
+        "freshness_confidence": "high",
+        "freshness_score": 94,
+        "adapter": "github",
+        "decay_rate": 1.0
+      },
+      "content": "freshcontext-mcp — Real-time web intelligence for AI agents..."
+    },
+    {
+      "freshcontext": {
+        "source_url": "https://efts.sec.gov/LATEST/search-index?q=Palantir&forms=8-K",
+        "content_date": "2026-02-03",
+        "retrieved_at": "2026-04-05T09:19:00.000Z",
+        "freshness_confidence": "high",
+        "freshness_score": 38,
+        "adapter": "sec_filings",
+        "decay_rate": 1.5
+      },
+      "content": "Palantir Technologies — 8-K filing: Q4 2025 earnings..."
+    }
+  ]
+}

package/input_schema.json

@@ -1,45 +1,44 @@
 {
-  "title": "FreshContext MCP Input",
+  "title": "FreshContext Input",
   "type": "object",
   "schemaVersion": 1,
   "properties": {
     "tool": {
       "title": "Tool",
       "type": "string",
-      "description": "The FreshContext tool to run.",
+      "description": "The FreshContext tool to run. See README for full descriptions.",
       "enum": [
-        "extract_github",
         "extract_hackernews",
-        "extract_scholar",
+        "extract_github",
+        "extract_govcontracts",
+        "extract_sec_filings",
+        "extract_gdelt",
+        "extract_gebiz",
+        "extract_finance",
+        "extract_changelog",
         "extract_arxiv",
+        "extract_scholar",
         "extract_reddit",
         "extract_yc",
         "extract_producthunt",
         "search_repos",
         "package_trends",
-        "extract_finance",
-        "extract_landscape"
+        "search_jobs"
       ],
-      "default": "extract_landscape",
+      "default": "extract_hackernews",
       "editor": "select"
     },
     "url": {
-      "title": "URL",
-      "type": "string",
-      "description": "URL to extract from. Required for: extract_github, extract_hackernews, extract_scholar, extract_reddit. E.g. https://github.com/owner/repo",
-      "editor": "textfield"
-    },
-    "query": {
-      "title": "Query",
+      "title": "URL or Query",
       "type": "string",
-      "description": "Search query. Required for: extract_landscape, search_repos, extract_yc, extract_producthunt, package_trends, extract_finance.",
+      "description": "The main input for the tool. For extract_github: full GitHub URL. For extract_hackernews: HN URL or search URL. For extract_govcontracts/extract_sec_filings/extract_gdelt/extract_gebiz/extract_finance: company name, keyword, or ticker. For search_repos/package_trends/search_jobs: search keyword.",
       "editor": "textfield"
     },
     "max_length": {
       "title": "Max content length",
       "type": "integer",
-      "description": "Maximum characters returned per result. Default: 6000.",
-      "default": 6000,
+      "description": "Maximum characters returned. Default: 8000.",
+      "default": 8000,
       "minimum": 500,
       "maximum": 20000,
       "editor": "number"

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "freshcontext-mcp",
   "mcpName": "io.github.PrinceGabriel-lgtm/freshcontext",
-  "version": "0.3.13",
-  "description": "Real-time web extraction MCP server with freshness timestamps for AI agents",
+  "version": "0.3.15",
+  "description": "Real-time web intelligence for AI agents. 20 tools, no API keys. Every result timestamped with a freshness score.",
   "keywords": [
     "mcp",
     "mcp-server",

package/server.json

@@ -1,19 +1,19 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
   "name": "io.github.PrinceGabriel-lgtm/freshcontext",
-  "description": "Real-time web intelligence for AI agents. 15 tools, no API keys. GitHub, HN, Reddit, arXiv, govcontracts, changelog, gov landscape & finance landscape — every result timestamped with a freshness score.",
+  "description": "Real-time web intelligence for AI agents. 20 tools, no API keys. GitHub, HN, Reddit, arXiv, SEC filings, US gov contracts, GDELT global news, Singapore GeBIZ, changelog & more — every result timestamped with a freshness score.",
   "repository": {
     "url": "https://github.com/PrinceGabriel-lgtm/freshcontext-mcp",
     "source": "github"
   },
-  "version": "0.3.11",
+  "version": "0.3.15",
   "website_url": "https://freshcontext-site.pages.dev",
   "packages": [
     {
       "registry_type": "npm",
       "registry_base_url": "https://registry.npmjs.org",
       "identifier": "freshcontext-mcp",
-      "version": "0.3.11",
+      "version": "0.3.15",
       "transport": {
         "type": "stdio"
       }