freshcontext-mcp 0.3.17 → 0.3.18

package/SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Supported Versions
+
+FreshContext currently supports the active `freshcontext-mcp@0.3.x` package line.
+
+Please use the latest published `0.3.x` release when reporting a vulnerability, and include the exact package version, repository, transport, and environment involved.
+
+## Reporting A Vulnerability
+
+FreshContext accepts responsible security reports by email:
+
+- gimmanuel73@gmail.com
+
+Please do not post secrets, tokens, private logs, customer data, exploit payloads, or sensitive operational details in public GitHub issues.
+
+For a useful report, include:
+
+- affected repository or package
+- affected version or commit
+- reproduction steps
+- expected and observed behavior
+- security impact
+- whether the issue affects local MCP usage, hosted Worker usage, examples, docs, packaging, or another surface
+
+Public GitHub issues are fine for non-sensitive bugs, documentation mistakes, stale claims, build failures, and feature requests.
+
+## Scope Notes
+
+FreshContext does not currently offer a formal bug bounty program.
+
+Please do not send live production tokens, private Cloudflare logs, npm tokens, GitHub tokens, MCP registry tokens, customer data, or private account data. If a report requires sensitive evidence, describe the issue first by email so a safer exchange path can be agreed.
+
+This policy does not make claims of certification, compliance, guaranteed response time, or security warranty.

package/TRADEMARKS.md

@@ -0,0 +1,9 @@
+# FreshContext Brand and Trademark Notice
+
+FreshContext is the product and project name used by the project owner for this software, documentation, examples, and related public materials.
+
+No mark registration claim is made in this repository. Any future trademark filing, transfer, assignment, or licensing question should be reviewed separately.
+
+Third-party names, marks, services, and platforms, including Cloudflare, npm, GitHub, Model Context Protocol, MCP, Apify, Claude, OpenAI, Anthropic, and other referenced ecosystems, belong to their respective owners.
+
+Use of third-party names in this repository is descriptive, interoperability-oriented, or reference-oriented. It does not imply endorsement, certification, sponsorship, partnership, or official affiliation unless explicitly stated by the relevant third party.

package/dist/adapters/arxiv.js

@@ -1,66 +1,110 @@
-/**
- * arXiv adapter — uses the official arXiv API (no scraping, no auth needed).
- * Accepts a search query or a direct arXiv API URL.
- * Docs: https://arxiv.org/help/api/user-manual
- */
-export async function arxivAdapter(options) {
-    const input = options.url.trim();
-    // Build API URL — if they pass a plain query, construct it
-    const apiUrl = input.startsWith("http")
-        ? input
-        : `https://export.arxiv.org/api/query?search_query=all:${encodeURIComponent(input)}&start=0&max_results=10&sortBy=relevance&sortOrder=descending`;
+const USER_AGENT = "freshcontext-mcp/0.1.7 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)";
+const DEFAULT_ARXIV_SIGNAL_SCORE = 0.8;
+function buildArxivApiUrl(input, maxResults = 10) {
+    const trimmed = input.trim();
+    const safeMaxResults = Number.isFinite(maxResults)
+        ? Math.max(1, Math.min(Math.trunc(maxResults), 50))
+        : 10;
+    return trimmed.startsWith("http")
+        ? trimmed
+        : `https://export.arxiv.org/api/query?search_query=all:${encodeURIComponent(trimmed)}&start=0&max_results=${safeMaxResults}&sortBy=relevance&sortOrder=descending`;
+}
+async function fetchArxivXml(apiUrl) {
     const res = await fetch(apiUrl, {
-        headers: { "User-Agent": "freshcontext-mcp/0.1.7 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)" },
+        headers: { "User-Agent": USER_AGENT },
     });
     if (!res.ok)
         throw new Error(`arXiv API error: ${res.status} ${res.statusText}`);
-    const xml = await res.text();
-    // Parse the Atom XML response
-    const entries = [...xml.matchAll(/<entry>([\s\S]*?)<\/entry>/g)];
-    if (!entries.length) {
-        return { raw: "No results found for this query.", content_date: null, freshness_confidence: "low" };
-    }
-    const getTag = (block, tag) => {
-        const m = block.match(new RegExp(`<${tag}[^>]*>([\\s\\S]*?)<\\/${tag}>`, "i"));
-        return m ? m[1].trim().replace(/\s+/g, " ") : "";
-    };
-    const getAttr = (block, tag, attr) => {
-        const m = block.match(new RegExp(`<${tag}[^>]*${attr}="([^"]*)"`, "i"));
-        return m ? m[1].trim() : "";
-    };
-    const papers = entries.map((match, i) => {
+    return res.text();
+}
+function getTag(block, tag) {
+    const m = block.match(new RegExp(`<${tag}[^>]*>([\\s\\S]*?)<\\/${tag}>`, "i"));
+    return m ? m[1].trim().replace(/\s+/g, " ") : "";
+}
+function getAttr(block, tag, attr) {
+    const m = block.match(new RegExp(`<${tag}[^>]*${attr}="([^"]*)"`, "i"));
+    return m ? m[1].trim() : "";
+}
+function normalizeArxivUrl(id) {
+    return id.replace("http://arxiv.org/abs/", "https://arxiv.org/abs/");
+}
+function parseArxivEntries(xml) {
+    return [...xml.matchAll(/<entry>([\s\S]*?)<\/entry>/g)].map((match) => {
         const block = match[1];
-        const title = getTag(block, "title").replace(/\n/g, " ");
-        const summary = getTag(block, "summary").slice(0, 300).replace(/\n/g, " ");
-        const published = getTag(block, "published").slice(0, 10); // YYYY-MM-DD
-        const updated = getTag(block, "updated").slice(0, 10);
-        const id = getTag(block, "id").replace("http://arxiv.org/abs/", "https://arxiv.org/abs/");
-        // Authors — can be multiple
         const authorMatches = [...block.matchAll(/<author>([\s\S]*?)<\/author>/g)];
         const authors = authorMatches
             .map(a => getTag(a[1], "name"))
             .filter(Boolean)
-            .slice(0, 4)
-            .join(", ");
-        // Categories
-        const primaryCat = getAttr(block, "arxiv:primary_category", "term") ||
-            getAttr(block, "category", "term");
-        return [
-            `[${i + 1}] ${title}`,
-            `Authors: ${authors || "Unknown"}`,
-            `Published: ${published}${updated !== published ? ` (updated ${updated})` : ""}`,
-            primaryCat ? `Category: ${primaryCat}` : null,
-            `Abstract: ${summary}…`,
-            `Link: ${id}`,
-        ].filter(Boolean).join("\n");
+            .slice(0, 4);
+        return {
+            title: getTag(block, "title").replace(/\n/g, " "),
+            summary: getTag(block, "summary").replace(/\n/g, " "),
+            published: getTag(block, "published"),
+            updated: getTag(block, "updated"),
+            id: normalizeArxivUrl(getTag(block, "id")),
+            authors,
+            category: getAttr(block, "arxiv:primary_category", "term") ||
+                getAttr(block, "category", "term"),
+        };
     });
+}
+function formatArxivEntry(entry, index) {
+    const published = entry.published.slice(0, 10);
+    const updated = entry.updated.slice(0, 10);
+    const authors = entry.authors.join(", ");
+    const summary = entry.summary.slice(0, 300);
+    return [
+        `[${index + 1}] ${entry.title}`,
+        `Authors: ${authors || "Unknown"}`,
+        `Published: ${published}${updated !== published ? ` (updated ${updated})` : ""}`,
+        entry.category ? `Category: ${entry.category}` : null,
+        `Abstract: ${summary}\u00e2\u20ac\u00a6`,
+        `Link: ${entry.id}`,
+    ].filter(Boolean).join("\n");
+}
+/**
+ * arXiv adapter uses the official arXiv API.
+ * Accepts a search query or a direct arXiv API URL.
+ * Docs: https://arxiv.org/help/api/user-manual
+ */
+export async function arxivAdapter(options) {
+    const input = options.url.trim();
+    const apiUrl = buildArxivApiUrl(input);
+    const xml = await fetchArxivXml(apiUrl);
+    const entries = parseArxivEntries(xml);
+    if (!entries.length) {
+        return { raw: "No results found for this query.", content_date: null, freshness_confidence: "low" };
+    }
+    const papers = entries.map(formatArxivEntry);
     const raw = papers.join("\n\n").slice(0, options.maxLength ?? 6000);
-    // Most recent publication date
     const dates = entries
-        .map(m => getTag(m[1], "published").slice(0, 10))
+        .map(entry => entry.published.slice(0, 10))
         .filter(Boolean)
         .sort()
         .reverse();
     const content_date = dates[0] ?? null;
     return { raw, content_date, freshness_confidence: content_date ? "high" : "medium" };
 }
+export async function searchArxivSignals(input) {
+    const query = input.query.trim();
+    const apiUrl = buildArxivApiUrl(query, input.maxResults);
+    const xml = await fetchArxivXml(apiUrl);
+    const entries = parseArxivEntries(xml);
+    const retrievedAt = input.retrievedAt ?? new Date().toISOString();
+    const semanticScore = input.semanticScore ?? DEFAULT_ARXIV_SIGNAL_SCORE;
+    return entries.map((entry) => ({
+        title: entry.title,
+        content: entry.summary,
+        source: entry.id,
+        source_type: "arxiv",
+        published_at: entry.published || null,
+        retrieved_at: retrievedAt,
+        semantic_score: semanticScore,
+        metadata: {
+            authors: entry.authors,
+            category: entry.category || null,
+            updated_at: entry.updated || null,
+            query,
+        },
+    }));
+}

package/dist/adapters/hackernews.js

@@ -54,22 +54,22 @@ export async function hackerNewsAdapter(options) {
     const browser = await chromium.launch({ headless: true });
     const page = await browser.newPage();
     await page.goto(url, { waitUntil: "domcontentloaded", timeout: 20000 });
-    const data = await page.evaluate(`(function() {
-    var items = Array.from(document.querySelectorAll('.athing')).slice(0, 20);
-    var results = items.map(function(el) {
-      var titleLineEl = el.querySelector('.titleline > a');
-      var title = titleLineEl ? titleLineEl.textContent.trim() : null;
-      var link = titleLineEl ? titleLineEl.getAttribute('href') : null;
-      var subtext = el.nextElementSibling;
-      var scoreEl = subtext ? subtext.querySelector('.score') : null;
-      var score = scoreEl ? scoreEl.textContent.trim() : null;
-      var ageEl = subtext ? subtext.querySelector('.age') : null;
-      var age = ageEl ? ageEl.getAttribute('title') : null;
-      var anchors = subtext ? subtext.querySelectorAll('a') : [];
-      var commentLink = anchors.length > 0 ? anchors[anchors.length - 1].textContent.trim() : null;
-      return { title: title, link: link, score: score, age: age, commentLink: commentLink };
-    });
-    return results;
+    const data = await page.evaluate(`(function() {
+    var items = Array.from(document.querySelectorAll('.athing')).slice(0, 20);
+    var results = items.map(function(el) {
+      var titleLineEl = el.querySelector('.titleline > a');
+      var title = titleLineEl ? titleLineEl.textContent.trim() : null;
+      var link = titleLineEl ? titleLineEl.getAttribute('href') : null;
+      var subtext = el.nextElementSibling;
+      var scoreEl = subtext ? subtext.querySelector('.score') : null;
+      var score = scoreEl ? scoreEl.textContent.trim() : null;
+      var ageEl = subtext ? subtext.querySelector('.age') : null;
+      var age = ageEl ? ageEl.getAttribute('title') : null;
+      var anchors = subtext ? subtext.querySelectorAll('a') : [];
+      var commentLink = anchors.length > 0 ? anchors[anchors.length - 1].textContent.trim() : null;
+      return { title: title, link: link, score: score, age: age, commentLink: commentLink };
+    });
+    return results;
   })()`);
     await browser.close();
     const typedData = data;

package/dist/adapters/registry.js

@@ -0,0 +1,232 @@
+function descriptor(input) {
+    return Object.freeze({
+        ...input,
+        secondary_source_profiles: input.secondary_source_profiles
+            ? Object.freeze([...input.secondary_source_profiles])
+            : undefined,
+    });
+}
+function copyDescriptor(descriptor) {
+    return {
+        ...descriptor,
+        secondary_source_profiles: descriptor.secondary_source_profiles
+            ? [...descriptor.secondary_source_profiles]
+            : undefined,
+    };
+}
+export const BUILT_IN_ADAPTER_REGISTRY = Object.freeze([
+    descriptor({
+        adapter_id: "github",
+        tool_name: "extract_github",
+        source_profile: "code_activity",
+        output_mode: "single",
+        runtime_kind: "browser",
+        risk: "medium",
+        notes: "Repository page extraction uses browser automation; keep behavior compatibility pinned before signal extraction.",
+    }),
+    descriptor({
+        adapter_id: "google_scholar",
+        tool_name: "extract_scholar",
+        source_profile: "academic_research",
+        output_mode: "batch",
+        runtime_kind: "browser",
+        risk: "medium",
+        notes: "Scholar extraction is browser-backed and date precision is usually year-level.",
+    }),
+    descriptor({
+        adapter_id: "hackernews",
+        tool_name: "extract_hackernews",
+        source_profile: "social_pulse",
+        output_mode: "batch",
+        runtime_kind: "mixed",
+        risk: "medium",
+        notes: "Plain query path uses Algolia API; URL extraction can use browser automation.",
+    }),
+    descriptor({
+        adapter_id: "yc",
+        tool_name: "extract_yc",
+        source_profile: "company_intel",
+        output_mode: "batch",
+        runtime_kind: "browser",
+        risk: "medium",
+        notes: "YC company listing extraction is browser-backed.",
+    }),
+    descriptor({
+        adapter_id: "reposearch",
+        tool_name: "search_repos",
+        source_profile: "code_activity",
+        output_mode: "batch",
+        runtime_kind: "api",
+        risk: "low",
+        notes: "GitHub repository search API result set; good early signal-output candidate.",
+    }),
+    descriptor({
+        adapter_id: "packagetrends",
+        tool_name: "package_trends",
+        source_profile: "code_activity",
+        secondary_source_profiles: ["official_docs"],
+        output_mode: "batch",
+        runtime_kind: "api",
+        risk: "low",
+        notes: "Registry metadata for npm and PyPI packages.",
+    }),
+    descriptor({
+        adapter_id: "arxiv",
+        tool_name: "extract_arxiv",
+        source_profile: "academic_research",
+        output_mode: "batch",
+        runtime_kind: "api",
+        risk: "low",
+        notes: "Official API with clear paper timestamps; recommended first extraction target.",
+    }),
+    descriptor({
+        adapter_id: "finance",
+        tool_name: "extract_finance",
+        source_profile: "market_finance",
+        output_mode: "batch",
+        runtime_kind: "api",
+        risk: "medium",
+        notes: "Quote freshness and partial-failure semantics need careful compatibility coverage.",
+    }),
+    descriptor({
+        adapter_id: "reddit",
+        tool_name: "extract_reddit",
+        source_profile: "social_pulse",
+        output_mode: "batch",
+        runtime_kind: "api",
+        risk: "medium",
+        notes: "Public JSON API with community-content volatility.",
+    }),
+    descriptor({
+        adapter_id: "producthunt",
+        tool_name: "extract_producthunt",
+        source_profile: "social_pulse",
+        output_mode: "batch",
+        runtime_kind: "mixed",
+        risk: "medium",
+        notes: "Uses optional API path with browser fallback.",
+    }),
+    descriptor({
+        adapter_id: "landscape",
+        tool_name: "extract_landscape",
+        source_profile: "composite_landscape",
+        secondary_source_profiles: ["company_intel", "code_activity", "social_pulse"],
+        output_mode: "composite",
+        runtime_kind: "composite",
+        risk: "high",
+        notes: "Composite report should preserve section-level source profiles before extraction.",
+    }),
+    descriptor({
+        adapter_id: "jobs",
+        tool_name: "search_jobs",
+        source_profile: "jobs_opportunities",
+        output_mode: "batch",
+        runtime_kind: "api",
+        risk: "medium",
+        notes: "Multi-source job aggregation with filters and strict recency expectations.",
+    }),
+    descriptor({
+        adapter_id: "changelog",
+        tool_name: "extract_changelog",
+        source_profile: "official_docs",
+        secondary_source_profiles: ["code_activity"],
+        output_mode: "batch",
+        runtime_kind: "mixed",
+        risk: "medium",
+        notes: "GitHub releases and registry paths are API-backed; website discovery can use browser automation.",
+    }),
+    descriptor({
+        adapter_id: "govcontracts",
+        tool_name: "extract_govcontracts",
+        source_profile: "government_regulatory",
+        output_mode: "batch",
+        runtime_kind: "api",
+        risk: "medium",
+        notes: "Official API; direct API URL compatibility and award-date semantics need coverage.",
+    }),
+    descriptor({
+        adapter_id: "gov_landscape",
+        tool_name: "extract_gov_landscape",
+        source_profile: "composite_landscape",
+        secondary_source_profiles: ["government_regulatory", "code_activity", "social_pulse", "official_docs"],
+        output_mode: "composite",
+        runtime_kind: "composite",
+        risk: "high",
+        notes: "Composite government report stitches multiple source profiles.",
+    }),
+    descriptor({
+        adapter_id: "finance_landscape",
+        tool_name: "extract_finance_landscape",
+        source_profile: "composite_landscape",
+        secondary_source_profiles: ["market_finance", "social_pulse", "code_activity", "official_docs"],
+        output_mode: "composite",
+        runtime_kind: "composite",
+        risk: "high",
+        notes: "Composite finance report must not collapse market and social freshness into one policy.",
+    }),
+    descriptor({
+        adapter_id: "sec_filings",
+        tool_name: "extract_sec_filings",
+        source_profile: "government_regulatory",
+        output_mode: "batch",
+        runtime_kind: "api",
+        risk: "low",
+        notes: "Official SEC API with clear filing dates.",
+    }),
+    descriptor({
+        adapter_id: "gdelt",
+        tool_name: "extract_gdelt",
+        source_profile: "government_regulatory",
+        secondary_source_profiles: ["company_intel"],
+        output_mode: "batch",
+        runtime_kind: "api",
+        risk: "medium",
+        notes: "Global news intelligence has fast-moving timestamps and broad source variance.",
+    }),
+    descriptor({
+        adapter_id: "company_landscape",
+        tool_name: "extract_company_landscape",
+        source_profile: "composite_landscape",
+        secondary_source_profiles: ["company_intel", "government_regulatory", "market_finance", "official_docs"],
+        output_mode: "composite",
+        runtime_kind: "composite",
+        risk: "high",
+        notes: "Composite company report combines official, market, news, and product velocity signals.",
+    }),
+    descriptor({
+        adapter_id: "gebiz",
+        tool_name: "extract_gebiz",
+        source_profile: "government_regulatory",
+        output_mode: "batch",
+        runtime_kind: "api",
+        risk: "low",
+        notes: "Official data.gov.sg procurement dataset.",
+    }),
+    descriptor({
+        adapter_id: "idea_landscape",
+        tool_name: "extract_idea_landscape",
+        source_profile: "composite_landscape",
+        secondary_source_profiles: ["social_pulse", "company_intel", "code_activity", "jobs_opportunities"],
+        output_mode: "composite",
+        runtime_kind: "composite",
+        risk: "high",
+        notes: "Composite idea validation report stitches social, funding, code, jobs, package, and launch signals.",
+    }),
+]);
+export function listAdapterDescriptors() {
+    return BUILT_IN_ADAPTER_REGISTRY.map(copyDescriptor);
+}
+export function getAdapterDescriptor(adapterIdOrToolName) {
+    const descriptor = BUILT_IN_ADAPTER_REGISTRY.find((item) => item.adapter_id === adapterIdOrToolName || item.tool_name === adapterIdOrToolName);
+    return descriptor ? copyDescriptor(descriptor) : undefined;
+}
+export function listAdaptersBySourceProfile(profileId) {
+    return BUILT_IN_ADAPTER_REGISTRY
+        .filter((item) => item.source_profile === profileId || item.secondary_source_profiles?.includes(profileId))
+        .map(copyDescriptor);
+}
+export function listAdaptersByRisk(risk) {
+    return BUILT_IN_ADAPTER_REGISTRY
+        .filter((item) => item.risk === risk)
+        .map(copyDescriptor);
+}

package/dist/core/decay.js

@@ -0,0 +1,61 @@
+// Spec-compliant exponential DAR model.
+// Higher lambda = data goes stale faster. Half-life formula: t1/2 = ln(2) / lambda.
+// 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,
+};
+export const FUTURE_CLOCK_SKEW_TOLERANCE_MS = 5 * 60 * 1000;
+export function isMeaningfullyFutureDate(content_date, retrieved_at) {
+    if (!content_date)
+        return false;
+    const published = new Date(content_date).getTime();
+    const retrieved = new Date(retrieved_at).getTime();
+    if (isNaN(published) || isNaN(retrieved))
+        return false;
+    return published - retrieved > FUTURE_CLOCK_SKEW_TOLERANCE_MS;
+}
+export function calculateFreshnessScore(content_date, retrieved_at, adapter) {
+    if (!content_date)
+        return null;
+    const published = new Date(content_date).getTime();
+    const retrieved = new Date(retrieved_at).getTime();
+    if (isNaN(published) || isNaN(retrieved))
+        return null;
+    if (published - retrieved > FUTURE_CLOCK_SKEW_TOLERANCE_MS)
+        return null;
+    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)));
+}
+export function scoreLabel(score) {
+    if (score === null)
+        return "unknown";
+    if (score >= 90)
+        return "current";
+    if (score >= 70)
+        return "reliable";
+    if (score >= 50)
+        return "verify before acting";
+    return "use with caution";
+}