freshcontext-mcp 0.3.17 → 0.3.18

package/dist/core/sourceProfiles.js

@@ -0,0 +1,126 @@
+import { LAMBDA } from "./decay.js";
+function halfLifeHours(lambda) {
+    return Number((Math.log(2) / lambda).toFixed(2));
+}
+function profile(input) {
+    return {
+        ...input,
+        half_life_hours: halfLifeHours(input.default_decay_lambda),
+    };
+}
+function copyProfile(profile) {
+    return {
+        ...profile,
+        source_types: [...profile.source_types],
+        recommended_surfaces: [...profile.recommended_surfaces],
+    };
+}
+export const BUILT_IN_SOURCE_PROFILES = Object.freeze({
+    official_docs: profile({
+        profile_id: "official_docs",
+        source_types: ["official_docs", "changelog", "packagetrends"],
+        purpose: "Official product docs, API docs, standards, changelogs, and canonical source material.",
+        default_decay_lambda: LAMBDA.github,
+        authority_hint: "high",
+        date_policy: "balanced",
+        failure_policy: "warn",
+        recommended_surfaces: ["rest", "sdk", "cli", "operator"],
+    }),
+    code_activity: profile({
+        profile_id: "code_activity",
+        source_types: ["github", "reposearch", "changelog", "packagetrends"],
+        purpose: "Repository activity, release cadence, dependency health, and implementation evidence.",
+        default_decay_lambda: LAMBDA.github,
+        authority_hint: "medium",
+        date_policy: "balanced",
+        failure_policy: "downgrade",
+        recommended_surfaces: ["mcp", "rest", "sdk", "cli", "operator"],
+    }),
+    social_pulse: profile({
+        profile_id: "social_pulse",
+        source_types: ["hackernews", "reddit", "producthunt"],
+        purpose: "Community awareness, social proof, launch momentum, and early-market signal.",
+        default_decay_lambda: LAMBDA.hackernews,
+        authority_hint: "medium",
+        date_policy: "strict",
+        failure_policy: "downgrade",
+        recommended_surfaces: ["mcp", "rest", "sdk", "operator"],
+    }),
+    academic_research: profile({
+        profile_id: "academic_research",
+        source_types: ["google_scholar", "arxiv"],
+        purpose: "Scholarly material, papers, research abstracts, and citation-oriented context.",
+        default_decay_lambda: LAMBDA.arxiv,
+        authority_hint: "high",
+        date_policy: "lenient",
+        failure_policy: "warn",
+        recommended_surfaces: ["mcp", "rest", "sdk", "cli", "operator"],
+    }),
+    market_finance: profile({
+        profile_id: "market_finance",
+        source_types: ["finance", "finance_landscape"],
+        purpose: "Market prices, quotes, financial movement, and finance-specific situational awareness.",
+        default_decay_lambda: LAMBDA.finance,
+        authority_hint: "medium",
+        date_policy: "strict",
+        failure_policy: "exclude",
+        recommended_surfaces: ["mcp", "rest", "sdk", "operator"],
+    }),
+    jobs_opportunities: profile({
+        profile_id: "jobs_opportunities",
+        source_types: ["jobs"],
+        purpose: "Job listings, openings, hiring signals, and opportunity windows.",
+        default_decay_lambda: LAMBDA.jobs,
+        authority_hint: "medium",
+        date_policy: "strict",
+        failure_policy: "downgrade",
+        recommended_surfaces: ["mcp", "rest", "sdk", "cli", "operator"],
+    }),
+    government_regulatory: profile({
+        profile_id: "government_regulatory",
+        source_types: ["govcontracts", "sec_filings", "gebiz", "gdelt", "gov_landscape"],
+        purpose: "Public-sector contracts, official filings, tenders, regulatory disclosures, and global news intelligence.",
+        default_decay_lambda: LAMBDA.govcontracts,
+        authority_hint: "high",
+        date_policy: "strict",
+        failure_policy: "warn",
+        recommended_surfaces: ["mcp", "rest", "sdk", "operator"],
+    }),
+    company_intel: profile({
+        profile_id: "company_intel",
+        source_types: ["yc", "company_landscape"],
+        purpose: "Company research, product velocity, ecosystem activity, and competitive context.",
+        default_decay_lambda: LAMBDA.company_landscape,
+        authority_hint: "medium",
+        date_policy: "balanced",
+        failure_policy: "downgrade",
+        recommended_surfaces: ["mcp", "rest", "sdk", "operator"],
+    }),
+    composite_landscape: profile({
+        profile_id: "composite_landscape",
+        source_types: ["landscape", "idea_landscape", "gov_landscape", "finance_landscape", "company_landscape"],
+        purpose: "Multi-source validation and idea, company, market, government, or finance landscape checks.",
+        default_decay_lambda: LAMBDA.landscape,
+        authority_hint: "medium",
+        date_policy: "balanced",
+        failure_policy: "warn",
+        recommended_surfaces: ["mcp", "rest", "sdk", "operator"],
+    }),
+    local_custom: profile({
+        profile_id: "local_custom",
+        source_types: ["local_custom", "user_provided", "custom"],
+        purpose: "User-provided content and custom signals supplied explicitly by a host or caller.",
+        default_decay_lambda: LAMBDA.default,
+        authority_hint: "medium",
+        date_policy: "balanced",
+        failure_policy: "warn",
+        recommended_surfaces: ["rest", "sdk", "cli", "operator"],
+    }),
+});
+export function listSourceProfiles() {
+    return Object.values(BUILT_IN_SOURCE_PROFILES).map(copyProfile);
+}
+export function getSourceProfile(profileId) {
+    const profile = BUILT_IN_SOURCE_PROFILES[profileId];
+    return profile ? copyProfile(profile) : undefined;
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/utility.js

@@ -0,0 +1,90 @@
+const DATE_CONFIDENCE_FACTORS = {
+    high: 1.0,
+    medium: 0.75,
+    low: 0.4,
+    unknown: 0.0,
+};
+const STATUS_FACTORS = {
+    success: 1.0,
+    partial: 0.65,
+    stale: 0.4,
+    failed: 0.0,
+    unknown: 0.5,
+};
+function clampRelevance(value, reasons) {
+    if (!Number.isFinite(value)) {
+        reasons.push("contextual relevance was not finite; clamped to 0");
+        return 0;
+    }
+    if (value > 100) {
+        reasons.push("contextual relevance exceeded 100; clamped to 100");
+        return 100;
+    }
+    if (value < 0) {
+        reasons.push("contextual relevance was below 0; clamped to 0");
+        return 0;
+    }
+    return value;
+}
+function safeLambda(value, reasons) {
+    if (!Number.isFinite(value) || value < 0) {
+        reasons.push("lambda was invalid; clamped to 0");
+        return 0;
+    }
+    return value;
+}
+function safeAgeHours(value, reasons) {
+    if (!Number.isFinite(value)) {
+        reasons.push("ageHours was not finite; clamped to 0");
+        return 0;
+    }
+    if (value < 0) {
+        reasons.push("ageHours was negative; clamped to 0");
+        return 0;
+    }
+    return value;
+}
+export function calculateContextUtility(input) {
+    const reasons = [];
+    const contextualRelevance = clampRelevance(input.contextualRelevance, reasons);
+    const lambda = safeLambda(input.lambda, reasons);
+    const ageHours = safeAgeHours(input.ageHours, reasons);
+    const dateConfidence = input.dateConfidence ?? "unknown";
+    const status = input.status ?? "unknown";
+    const decayFactor = Math.exp(-lambda * ageHours);
+    const dateConfidenceFactor = DATE_CONFIDENCE_FACTORS[dateConfidence];
+    const statusFactor = STATUS_FACTORS[status];
+    if (dateConfidence === "medium") {
+        reasons.push("timestamp confidence is medium; utility reduced");
+    }
+    else if (dateConfidence === "low") {
+        reasons.push("timestamp confidence is low; utility reduced");
+    }
+    else if (dateConfidence === "unknown") {
+        reasons.push("timestamp confidence is unknown; utility reduced to zero");
+    }
+    if (status === "partial") {
+        reasons.push("signal status is partial; utility reduced");
+    }
+    else if (status === "stale") {
+        reasons.push("signal status is stale; utility reduced");
+    }
+    else if (status === "failed") {
+        reasons.push("signal status is failed; utility reduced to zero");
+    }
+    else if (status === "unknown") {
+        reasons.push("signal status is unknown; utility reduced");
+    }
+    const score = Math.min(100, Math.max(0, contextualRelevance * decayFactor * dateConfidenceFactor * statusFactor));
+    return {
+        score,
+        contextualRelevance,
+        decayFactor,
+        dateConfidenceFactor,
+        statusFactor,
+        lambda,
+        ageHours,
+        status,
+        reasons,
+    };
+}

package/dist/rest/handler.js

@@ -0,0 +1,126 @@
+import { evaluateSignal, evaluateSignals } from "../core/index.js";
+const SERVICE_VERSION = "0.1.0";
+const JSON_CONTENT_TYPE = "application/json";
+const MAX_BODY_BYTES = 256 * 1024;
+function jsonResponse(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": JSON_CONTENT_TYPE },
+    });
+}
+function errorResponse(code, message, status, details = []) {
+    return jsonResponse({ error: { code, message, details } }, status);
+}
+function methodNotAllowed(allowed) {
+    return new Response(JSON.stringify({
+        error: {
+            code: "method_not_allowed",
+            message: `Method not allowed. Use ${allowed}.`,
+            details: [],
+        },
+    }), {
+        status: 405,
+        headers: {
+            "Content-Type": JSON_CONTENT_TYPE,
+            "Allow": allowed,
+        },
+    });
+}
+function isJsonContentType(request) {
+    return (request.headers.get("Content-Type") ?? "").toLowerCase().includes(JSON_CONTENT_TYPE);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function readJsonBody(request) {
+    if (!isJsonContentType(request)) {
+        return {
+            ok: false,
+            response: errorResponse("unsupported_media_type", "POST requests require Content-Type: application/json.", 415),
+        };
+    }
+    const contentLength = request.headers.get("Content-Length");
+    if (contentLength !== null && Number(contentLength) > MAX_BODY_BYTES) {
+        return {
+            ok: false,
+            response: errorResponse("payload_too_large", `Request body exceeds ${MAX_BODY_BYTES} bytes.`, 413),
+        };
+    }
+    const text = await request.text();
+    if (new TextEncoder().encode(text).length > MAX_BODY_BYTES) {
+        return {
+            ok: false,
+            response: errorResponse("payload_too_large", `Request body exceeds ${MAX_BODY_BYTES} bytes.`, 413),
+        };
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (!isRecord(parsed)) {
+            return {
+                ok: false,
+                response: errorResponse("invalid_request", "Request body must be a JSON object.", 400),
+            };
+        }
+        return { ok: true, body: parsed };
+    }
+    catch {
+        return {
+            ok: false,
+            response: errorResponse("invalid_request", "Request body must be valid JSON.", 400),
+        };
+    }
+}
+function optionsFromBody(body) {
+    if (body.options === undefined)
+        return undefined;
+    return isRecord(body.options) ? body.options : {};
+}
+async function handleEvaluate(request) {
+    if (request.method !== "POST")
+        return methodNotAllowed("POST");
+    const parsed = await readJsonBody(request);
+    if (!parsed.ok)
+        return parsed.response;
+    if (!isRecord(parsed.body.signal)) {
+        return errorResponse("invalid_request", "Request body must include signal.", 400);
+    }
+    const result = evaluateSignal(parsed.body.signal, optionsFromBody(parsed.body));
+    return jsonResponse(result);
+}
+async function handleEvaluateBatch(request) {
+    if (request.method !== "POST")
+        return methodNotAllowed("POST");
+    const parsed = await readJsonBody(request);
+    if (!parsed.ok)
+        return parsed.response;
+    if (!Array.isArray(parsed.body.signals)) {
+        return errorResponse("invalid_request", "Request body must include signals array.", 400);
+    }
+    const result = evaluateSignals(parsed.body.signals, optionsFromBody(parsed.body));
+    return jsonResponse({ evaluations: result });
+}
+function handleHealth(request) {
+    if (request.method !== "GET")
+        return methodNotAllowed("GET");
+    return jsonResponse({
+        ok: true,
+        service: "freshcontext-rest",
+        version: SERVICE_VERSION,
+        core_available: true,
+    });
+}
+export async function handleRestRequest(request) {
+    const url = new URL(request.url);
+    try {
+        if (url.pathname === "/v1/health")
+            return handleHealth(request);
+        if (url.pathname === "/v1/evaluate")
+            return handleEvaluate(request);
+        if (url.pathname === "/v1/evaluate-batch")
+            return handleEvaluateBatch(request);
+        return errorResponse("not_found", `Not found: ${url.pathname}.`, 404);
+    }
+    catch {
+        return errorResponse("internal_error", "Unexpected REST host error.", 500);
+    }
+}

package/dist/server.js

@@ -22,7 +22,7 @@ import { stampFreshness, formatForLLM } from "./tools/freshnessStamp.js";
 import { formatSecurityError } from "./security.js";
 const server = new McpServer({
     name: "freshcontext-mcp",
-    version: "0.3.17",
+    version: "0.3.18",
 });
 // ─── Tool: extract_github ────────────────────────────────────────────────────
 server.registerTool("extract_github", {

package/dist/tools/freshnessStamp.js

@@ -1,137 +1 @@
-// ─── Decay rates per adapter ──────────────────────────────────────────────────
-// 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 a clamped 0-100 exponential freshness score.
-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();
-    // Guard against unparseable dates
-    if (isNaN(published) || isNaN(retrieved))
-        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)));
-}
-// ─── Score label ──────────────────────────────────────────────────────────────
-// Human-readable interpretation alongside the number, per the spec.
-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";
-}
-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;
-}
-// ─── Main stamp function ──────────────────────────────────────────────────────
-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 freshness_confidence = failedContent ? "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,
-    };
-}
-// ─── Structured JSON form ─────────────────────────────────────────────────────
-// Returns the spec-compliant JSON object defined in FRESHCONTEXT_SPEC.md.
-// Programmatic consumers can parse this without touching the text envelope.
-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,
-    };
-}
-// ─── Text envelope formatter ──────────────────────────────────────────────────
-// Produces the [FRESHCONTEXT]...[/FRESHCONTEXT] envelope defined in the spec,
-// followed by a [FRESHCONTEXT_JSON]...[/FRESHCONTEXT_JSON] block so both the
-// human-readable envelope and the machine-parseable JSON travel together.
-export function formatForLLM(ctx) {
-    const dateInfo = ctx.content_date
-        ? `Published: ${ctx.content_date}`
-        : "Publish date: unknown";
-    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");
-    // Append the structured JSON block so programmatic consumers
-    // can extract metadata without parsing the text envelope.
-    const jsonBlock = [
-        `[FRESHCONTEXT_JSON]`,
-        JSON.stringify(toStructuredJSON(ctx), null, 2),
-        `[/FRESHCONTEXT_JSON]`,
-    ].join("\n");
-    return `${textEnvelope}\n\n${jsonBlock}`;
-}
+export { LAMBDA, stampFreshness, toStructuredJSON, formatForLLM, } from "../core/index.js";

package/dist/types.js

@@ -1,2 +1 @@
-// Core data types for freshcontext-mcp
 export {};