freshcontext-mcp 0.3.16 → 0.3.18

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/adapters/repoSearch.js

@@ -22,7 +22,7 @@ export async function repoSearchAdapter(options) {
     const res = await fetch(apiUrl, {
         headers: {
             Accept: "application/vnd.github.v3+json",
-            "User-Agent": "freshcontext-mcp/0.1.0",
+            "User-Agent": "freshcontext-mcp/0.3.17 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
         },
     });
     if (!res.ok) {

package/dist/adapters/secFilings.js

@@ -12,7 +12,7 @@
  */
 const HEADERS = {
     "Accept": "application/json",
-    "User-Agent": "freshcontext-mcp/1.0 contact@freshcontext.dev",
+    "User-Agent": "freshcontext-mcp/0.3.17 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
 };
 async function fetchSecFilings(query, maxResults = 10) {
     const today = new Date().toISOString().slice(0, 10);

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";
+}

package/dist/core/decision.js

@@ -0,0 +1,176 @@
+import { getSourceProfile } from "./sourceProfiles.js";
+const CITATION_INTENTS = new Set(["citation_check", "student_research"]);
+const STRICT_REFRESH_PROFILES = new Set(["market_finance", "jobs_opportunities"]);
+function resolveSourceProfile(profile) {
+    if (!profile)
+        return undefined;
+    return typeof profile === "string" ? getSourceProfile(profile) : profile;
+}
+function profileId(profile) {
+    return profile?.profile_id;
+}
+function unique(values) {
+    return [...new Set(values.filter(Boolean))];
+}
+function hasFailureReason(evaluation) {
+    return evaluation.reasons.some((reason) => /\b(?:failed|failure|timeout|error|blocked|upstream)\b/i.test(reason));
+}
+function isCitationIntent(intent) {
+    return intent !== undefined && CITATION_INTENTS.has(intent);
+}
+function nonAdviceWarnings(intent) {
+    switch (intent) {
+        case "citation_check":
+        case "student_research":
+            return ["FreshContext judges citation readiness and context usefulness; it does not certify truth."];
+        case "medical_literature_triage":
+            return ["FreshContext provides literature triage only; it is not medical advice."];
+        case "market_watch":
+            return ["FreshContext provides market signal triage only; it is not investment advice."];
+        case "business_due_diligence":
+            return ["FreshContext supports context triage only; it is not legal, tax, or investment advice."];
+        case "job_search":
+            return ["FreshContext provides opportunity triage only; it is not employment or legal advice."];
+        default:
+            return [];
+    }
+}
+function decisionResult(decision, reasons, warnings) {
+    const copyReasons = unique(reasons);
+    const copyWarnings = unique(warnings);
+    switch (decision) {
+        case "use_first":
+            return {
+                decision,
+                label: "Use first",
+                meaning: "This is strong, current context for the task.",
+                action: "Use this near the top of the context bundle.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+        case "cite_as_primary":
+            return {
+                decision,
+                label: "Cite as primary",
+                meaning: "This source is relevant, current, and traceable enough to use as main evidence.",
+                action: "Use it as primary citation evidence, while keeping normal source-review standards.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+        case "cite_as_supporting":
+            return {
+                decision,
+                label: "Cite as supporting",
+                meaning: "This source is useful evidence, but should not be the only or latest support.",
+                action: "Use it as supporting evidence and pair it with stronger or newer sources.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+        case "use_as_background":
+            return {
+                decision,
+                label: "Use as background",
+                meaning: "This source is relevant context, but not strong enough for latest-evidence claims.",
+                action: "Use it for framing, history, or background rather than as the main current source.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+        case "needs_verification":
+            return {
+                decision,
+                label: "Needs verification",
+                meaning: "This source may be useful, but its date, confidence, or traceability is uncertain.",
+                action: "Verify the source details before citing it, acting on it, or sending it to a model as trusted context.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+        case "needs_refresh":
+            return {
+                decision,
+                label: "Needs refresh",
+                meaning: "This source may be useful, but it is too stale or date-uncertain for this source type.",
+                action: "Refresh or re-query this source before relying on it as current context.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+        case "watch_only":
+            return {
+                decision,
+                label: "Watch only",
+                meaning: "This is an interesting signal, but not strong enough to prioritize.",
+                action: "Monitor it or keep it as a weak signal; do not use it as main evidence.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+        case "exclude":
+            return {
+                decision,
+                label: "Exclude",
+                meaning: "This source is failed, too weak, or unsafe to include as useful context.",
+                action: "Keep it out of the final context bundle unless a human explicitly reviews it.",
+                reasons: copyReasons,
+                warnings: copyWarnings,
+            };
+    }
+}
+export function interpretEvaluation(evaluation, options = {}) {
+    const sourceProfile = resolveSourceProfile(options.sourceProfile);
+    const sourceProfileId = profileId(sourceProfile);
+    const intentProfile = options.intentProfile;
+    const reasons = unique([
+        evaluation.explanation,
+        ...evaluation.signal.reasons,
+        ...evaluation.utility.reasons,
+        ...evaluation.reasons,
+    ]);
+    const warnings = [...nonAdviceWarnings(intentProfile)];
+    const finalScore = evaluation.ranked.final_score;
+    const utilityScore = evaluation.utility.score;
+    const freshnessScore = evaluation.freshness_score;
+    const confidence = evaluation.ranked.confidence;
+    const isFailed = evaluation.signal.status === "failed"
+        || (confidence === "low" && hasFailureReason(evaluation));
+    if (sourceProfile) {
+        reasons.push(`source profile ${sourceProfile.profile_id} uses ${sourceProfile.date_policy} date policy`);
+    }
+    if (intentProfile) {
+        reasons.push(`intent profile ${intentProfile} selected`);
+    }
+    if (isFailed) {
+        return decisionResult("exclude", reasons, warnings);
+    }
+    if (sourceProfileId
+        && STRICT_REFRESH_PROFILES.has(sourceProfileId)
+        && (freshnessScore === null || freshnessScore < 50)) {
+        return decisionResult("needs_refresh", reasons, warnings);
+    }
+    if (evaluation.signal.date_confidence === "unknown") {
+        if (sourceProfileId === "academic_research" && finalScore >= 0.75) {
+            return decisionResult(isCitationIntent(intentProfile) ? "cite_as_supporting" : "use_as_background", reasons, warnings);
+        }
+        return decisionResult("needs_verification", reasons, warnings);
+    }
+    if (finalScore >= 0.85
+        && freshnessScore !== null
+        && freshnessScore >= 70
+        && utilityScore >= 60
+        && confidence === "high") {
+        if (sourceProfile?.authority_hint === "high" && isCitationIntent(intentProfile)) {
+            return decisionResult("cite_as_primary", reasons, warnings);
+        }
+        return decisionResult("use_first", reasons, warnings);
+    }
+    if (finalScore >= 0.55 && freshnessScore !== null && freshnessScore < 50) {
+        return decisionResult(isCitationIntent(intentProfile) ? "cite_as_supporting" : "use_as_background", reasons, warnings);
+    }
+    if (finalScore < 0.35 && utilityScore < 30) {
+        return decisionResult(confidence === "low" ? "exclude" : "watch_only", reasons, warnings);
+    }
+    if (finalScore >= 0.55) {
+        return decisionResult("use_as_background", reasons, warnings);
+    }
+    return decisionResult("watch_only", reasons, warnings);
+}
+export function interpretEvaluations(evaluations, options = {}) {
+    return evaluations.map((evaluation) => interpretEvaluation(evaluation, options));
+}

package/dist/core/envelope.js

@@ -0,0 +1,59 @@
+import { calculateFreshnessScore, isMeaningfullyFutureDate, scoreLabel } from "./decay.js";
+import { looksLikeFailedAdapterContent } from "./guards.js";
+export function stampFreshness(result, options, adapter) {
+    const retrieved_at = new Date().toISOString();
+    const failedContent = looksLikeFailedAdapterContent(result.raw);
+    const content_date = failedContent ? null : result.content_date;
+    const futureDated = !failedContent && isMeaningfullyFutureDate(content_date, retrieved_at);
+    const freshness_confidence = failedContent || futureDated ? "low" : result.freshness_confidence;
+    const freshness_score = calculateFreshnessScore(content_date, retrieved_at, adapter);
+    return {
+        content: result.raw.slice(0, options.maxLength ?? 8000),
+        source_url: options.url,
+        content_date,
+        retrieved_at,
+        freshness_confidence,
+        freshness_score,
+        adapter,
+    };
+}
+export function toStructuredJSON(ctx) {
+    return {
+        freshcontext: {
+            source_url: ctx.source_url,
+            content_date: ctx.content_date,
+            retrieved_at: ctx.retrieved_at,
+            freshness_confidence: ctx.freshness_confidence,
+            freshness_score: ctx.freshness_score,
+            adapter: ctx.adapter,
+        },
+        content: ctx.content,
+    };
+}
+export function formatForLLM(ctx, options = {}) {
+    const publishedLabel = options.publishedLabel ?? "Published";
+    const unknownDateText = options.unknownDateText ?? "Publish date: unknown";
+    const dateInfo = ctx.content_date
+        ? `${publishedLabel}: ${ctx.content_date}`
+        : unknownDateText;
+    const scoreLine = ctx.freshness_score !== null
+        ? `Score: ${ctx.freshness_score}/100 (${scoreLabel(ctx.freshness_score)})`
+        : `Score: unknown`;
+    const textEnvelope = [
+        `[FRESHCONTEXT]`,
+        `Source: ${ctx.source_url}`,
+        `${dateInfo}`,
+        `Retrieved: ${ctx.retrieved_at}`,
+        `Confidence: ${ctx.freshness_confidence}`,
+        `${scoreLine}`,
+        `---`,
+        ctx.content,
+        `[/FRESHCONTEXT]`,
+    ].join("\n");
+    const jsonBlock = [
+        `[FRESHCONTEXT_JSON]`,
+        JSON.stringify(toStructuredJSON(ctx), null, 2),
+        `[/FRESHCONTEXT_JSON]`,
+    ].join("\n");
+    return `${textEnvelope}\n\n${jsonBlock}`;
+}

package/dist/core/explain.js

@@ -0,0 +1,28 @@
+function sourceLabel(input) {
+    return input.source_type || input.source || "source";
+}
+export function explainSignal(input) {
+    const source = sourceLabel(input);
+    if (input.freshness_score === null) {
+        if (input.semantic_score < 0.5) {
+            return `Low confidence: weak semantic match and missing freshness data for ${source}.`;
+        }
+        return `Missing freshness data for ${source}; ranked mostly by semantic relevance.`;
+    }
+    if (input.semantic_score < 0.5) {
+        if (input.freshness_score >= 70) {
+            return `Fresh signal from ${source}, but semantic relevance is weak.`;
+        }
+        return `Weak semantic match with limited freshness for ${source}.`;
+    }
+    if (input.freshness_score >= 90) {
+        return `Strong semantic match and current freshness for ${source}.`;
+    }
+    if (input.freshness_score >= 70) {
+        return `Relevant signal with reliable freshness for ${source}.`;
+    }
+    if (input.freshness_score >= 50) {
+        return `Relevant signal, but freshness should be verified for ${source}.`;
+    }
+    return `Relevant signal, but stale for ${source}.`;
+}

package/dist/core/guards.js

@@ -0,0 +1,17 @@
+export function looksLikeFailedAdapterContent(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return true;
+    if (/^\[(?:error|security)\]/i.test(trimmed))
+        return true;
+    if (/^(?:error|failed|upstream|timeout)\b/i.test(trimmed))
+        return true;
+    const meaningful = trimmed
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (!meaningful.length)
+        return true;
+    const failureLines = meaningful.filter((line) => /\b(?:error|failed|failure|timeout|401|403|404|429|5\d\d)\b/i.test(line));
+    return failureLines.length === meaningful.length;
+}

package/dist/core/index.js

@@ -0,0 +1,11 @@
+export { LAMBDA, calculateFreshnessScore, scoreLabel } from "./decay.js";
+export { looksLikeFailedAdapterContent } from "./guards.js";
+export { stampFreshness, toStructuredJSON, formatForLLM } from "./envelope.js";
+export { explainSignal } from "./explain.js";
+export { rankSignals, rankSignal, clampScore } from "./rank.js";
+export { calculateContextUtility } from "./utility.js";
+export { SIGNAL_CONTRACT_VERSION, normalizeSignal } from "./signal.js";
+export { evaluateSignal, evaluateSignals } from "./pipeline.js";
+export { interpretEvaluation, interpretEvaluations } from "./decision.js";
+export { BUILT_IN_SOURCE_PROFILES, getSourceProfile, listSourceProfiles } from "./sourceProfiles.js";
+export { canonicalizeHaPriContent, sha256Hex, calculateHaPriV2, verifyHaPriV2, } from "./provenance.js";