freshcontext-mcp 0.3.18 → 0.3.20

package/dist/adapters/reddit.js

@@ -1,3 +1,4 @@
+import { sanitizeQuery, validateUrl } from "../security.js";
 /**
  * Reddit adapter — public JSON API, no auth required.
  * Accepts subreddit URLs or search queries.
@@ -6,10 +7,15 @@
  */
 export async function redditAdapter(options) {
     let apiUrl = options.url;
-    // If they pass a plain subreddit name like "r/MachineLearning", build the URL
+    // If they pass a plain subreddit or search query, build a Reddit JSON URL.
     if (!apiUrl.startsWith("http")) {
-        const clean = apiUrl.replace(/^r\//, "");
-        apiUrl = `https://www.reddit.com/r/${clean}/.json?limit=25&sort=hot`;
+        const clean = sanitizeQuery(apiUrl, 120).replace(/^r\//, "").replace(/^\/+|\/+$/g, "");
+        if (/^[A-Za-z0-9_]{2,21}$/.test(clean)) {
+            apiUrl = `https://www.reddit.com/r/${clean}/.json?limit=25&sort=hot`;
+        }
+        else {
+            apiUrl = `https://www.reddit.com/search.json?q=${encodeURIComponent(clean)}&sort=new&limit=25`;
+        }
     }
     // Ensure we hit the JSON endpoint
     if (!apiUrl.includes(".json")) {
@@ -19,7 +25,8 @@ export async function redditAdapter(options) {
     if (!apiUrl.includes("limit=")) {
         apiUrl += (apiUrl.includes("?") ? "&" : "?") + "limit=25";
     }
-    const res = await fetch(apiUrl, {
+    const safeUrl = validateUrl(apiUrl, "reddit");
+    const res = await fetch(safeUrl, {
         headers: {
             "User-Agent": "freshcontext-mcp/0.1.5 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
             "Accept": "application/json",

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.3.17 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
+            "User-Agent": "freshcontext-mcp/0.3.19 (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/0.3.17 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
+    "User-Agent": "freshcontext-mcp/0.3.19 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
 };
 async function fetchSecFilings(query, maxResults = 10) {
     const today = new Date().toISOString().slice(0, 10);

package/dist/core/envelope.js

@@ -1,5 +1,13 @@
 import { calculateFreshnessScore, isMeaningfullyFutureDate, scoreLabel } from "./decay.js";
 import { looksLikeFailedAdapterContent } from "./guards.js";
+export const MAX_ENVELOPE_CONTENT_LENGTH = 20000;
+function clampEnvelopeMaxLength(maxLength) {
+    if (maxLength === 0)
+        return 0;
+    if (maxLength === undefined || !Number.isFinite(maxLength))
+        return 8000;
+    return Math.min(MAX_ENVELOPE_CONTENT_LENGTH, Math.max(1, Math.floor(maxLength)));
+}
 export function stampFreshness(result, options, adapter) {
     const retrieved_at = new Date().toISOString();
     const failedContent = looksLikeFailedAdapterContent(result.raw);
@@ -8,7 +16,7 @@ export function stampFreshness(result, options, adapter) {
     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),
+        content: result.raw.slice(0, clampEnvelopeMaxLength(options.maxLength)),
         source_url: options.url,
         content_date,
         retrieved_at,

package/dist/security.js

@@ -10,9 +10,11 @@ export const ALLOWED_DOMAINS = {
     yc: ["www.ycombinator.com", "ycombinator.com"],
     repoSearch: [], // uses GitHub API directly, no browser
     packageTrends: [], // uses npm/PyPI APIs directly, no browser
-    reddit: [], // uses public Reddit JSON API, no browser
+    reddit: ["www.reddit.com", "reddit.com", "old.reddit.com"],
     finance: [], // uses Stooq quote API, no browser
+    arxiv: ["export.arxiv.org", "arxiv.org"],
     productHunt: ["www.producthunt.com", "producthunt.com"],
+    changelog: [], // accepts public changelog URLs but blocks private/internal targets
 };
 // ─── Blocked IP ranges and internal hostnames ────────────────────────────────
 const BLOCKED_PATTERNS = [

package/dist/server.js

@@ -19,12 +19,50 @@ import { secFilingsAdapter } from "./adapters/secFilings.js";
 import { gdeltAdapter } from "./adapters/gdelt.js";
 import { gebizAdapter } from "./adapters/gebiz.js";
 import { stampFreshness, formatForLLM } from "./tools/freshnessStamp.js";
+import { EvaluateContextInputError, evaluateContextInput, formatEvaluateContextResult, } from "./tools/evaluateContext.js";
 import { formatSecurityError } from "./security.js";
 const server = new McpServer({
     name: "freshcontext-mcp",
-    version: "0.3.18",
+    version: "0.3.20",
 });
-// ─── Tool: extract_github ────────────────────────────────────────────────────
+const signalInputSchema = z.object({
+    id: z.string().optional(),
+    source: z.string().min(1).describe("Source URL, URI, document id, or stable source label."),
+    source_type: z.string().optional().describe("Source type such as arxiv, jobs, official_docs, custom, or user_provided."),
+    title: z.string().optional(),
+    content: z.string().optional(),
+    published_at: z.string().nullable().optional(),
+    content_date: z.string().nullable().optional(),
+    retrieved_at: z.string().nullable().optional(),
+    semantic_score: z.number().optional().describe("Optional relevance score from 0..1. Core clamps out-of-range values."),
+    date_confidence: z.enum(["high", "medium", "low", "unknown"]).optional(),
+    freshness_confidence: z.enum(["high", "medium", "low"]).optional(),
+    status: z.enum(["success", "partial", "stale", "failed", "unknown"]).optional(),
+    metadata: z.record(z.unknown()).optional(),
+}).passthrough();
+// Tool: evaluate_context
+server.registerTool("evaluate_context", {
+    description: "Evaluate caller-provided candidate context and return decision-ready output. This is the primary FreshContext judgment path: it does not fetch, crawl, scrape, browse, read folders, or call adapters.",
+    inputSchema: z.object({
+        profile: z.string().min(1).describe("Source Profile id, e.g. academic_research, jobs_opportunities, market_finance, official_docs, local_custom."),
+        intent: z.string().min(1).describe("Intent Profile id, e.g. citation_check, student_research, developer_adoption, job_search, market_watch, business_due_diligence, medical_literature_triage."),
+        signals: z.array(signalInputSchema).min(1).max(100).describe("Candidate context items provided by the caller. FreshContext evaluates these; it does not retrieve them."),
+        now: z.string().optional().describe("Optional ISO timestamp for deterministic evaluation."),
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: false },
+}, async ({ profile, intent, signals, now }) => {
+    try {
+        const result = evaluateContextInput({ profile, intent, signals, now });
+        return { content: [{ type: "text", text: formatEvaluateContextResult(result) }] };
+    }
+    catch (err) {
+        if (err instanceof EvaluateContextInputError) {
+            return { content: [{ type: "text", text: `[FreshContext evaluate_context error]\n${err.message}` }] };
+        }
+        return { content: [{ type: "text", text: formatSecurityError(err) }] };
+    }
+});
+// ─── Reference adapter: extract_github ───────────────────────────────────────
 server.registerTool("extract_github", {
     description: "Extract real-time data from a GitHub repository — README, stars, forks, language, topics, last commit. Returns timestamped freshcontext.",
     inputSchema: z.object({

package/dist/tools/evaluateContext.js

@@ -0,0 +1,146 @@
+import { evaluateSignals, getSourceProfile, interpretEvaluations, } from "../core/index.js";
+const SUPPORTED_INTENTS = [
+    "citation_check",
+    "student_research",
+    "developer_adoption",
+    "job_search",
+    "market_watch",
+    "business_due_diligence",
+    "medical_literature_triage",
+];
+const MAX_CONTEXT_SIGNALS = 100;
+const MAX_SOURCE_CHARS = 2048;
+const MAX_TITLE_CHARS = 1000;
+const MAX_CONTENT_CHARS = 50000;
+export class EvaluateContextInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EvaluateContextInputError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isIntentProfileId(value) {
+    return SUPPORTED_INTENTS.includes(value);
+}
+function assertMaxLength(value, field, maxLength, index) {
+    if (typeof value === "string" && value.length > maxLength) {
+        const prefix = index === undefined ? "" : `signals[${index}].`;
+        throw new EvaluateContextInputError(`${prefix}${field} exceeds maximum length of ${maxLength} characters.`);
+    }
+}
+function validateSignal(value, index) {
+    if (!isRecord(value)) {
+        throw new EvaluateContextInputError(`signals[${index}] must be an object.`);
+    }
+    if (typeof value.source !== "string" || value.source.trim().length === 0) {
+        throw new EvaluateContextInputError(`signals[${index}].source must be a non-empty string.`);
+    }
+    assertMaxLength(value.source, "source", MAX_SOURCE_CHARS, index);
+    assertMaxLength(value.title, "title", MAX_TITLE_CHARS, index);
+    assertMaxLength(value.content, "content", MAX_CONTENT_CHARS, index);
+    if ((typeof value.title !== "string" || value.title.trim().length === 0)
+        && (typeof value.content !== "string" || value.content.trim().length === 0)) {
+        throw new EvaluateContextInputError(`signals[${index}] must include title or content.`);
+    }
+    return {
+        ...value,
+        source: value.source,
+        title: typeof value.title === "string" ? value.title : undefined,
+        content: typeof value.content === "string" ? value.content : undefined,
+    };
+}
+export function evaluateContextInput(input) {
+    const profile = getSourceProfile(input.profile);
+    if (!profile) {
+        throw new EvaluateContextInputError(`Unknown source profile: ${input.profile}.`);
+    }
+    if (!isIntentProfileId(input.intent)) {
+        throw new EvaluateContextInputError(`Unsupported intent profile: ${input.intent}.`);
+    }
+    if (!Array.isArray(input.signals)) {
+        throw new EvaluateContextInputError("signals must be an array.");
+    }
+    if (input.signals.length === 0) {
+        throw new EvaluateContextInputError("signals must contain at least one candidate context item.");
+    }
+    if (input.signals.length > MAX_CONTEXT_SIGNALS) {
+        throw new EvaluateContextInputError(`signals must contain at most ${MAX_CONTEXT_SIGNALS} candidate context items.`);
+    }
+    if (input.now !== undefined && Number.isNaN(new Date(input.now).getTime())) {
+        throw new EvaluateContextInputError("now must be a valid timestamp string when provided.");
+    }
+    const signals = input.signals.map(validateSignal);
+    const options = input.now ? { now: input.now } : {};
+    const evaluations = evaluateSignals(signals, options);
+    const decisions = interpretEvaluations(evaluations, {
+        sourceProfile: profile,
+        intentProfile: input.intent,
+    });
+    return {
+        profile,
+        intent: input.intent,
+        items: evaluations.map((evaluation, index) => ({
+            evaluation,
+            decision: decisions[index],
+        })),
+    };
+}
+function sourceTitle(evaluation) {
+    if (evaluation.signal.title)
+        return evaluation.signal.title;
+    if (evaluation.signal.content)
+        return evaluation.signal.content.slice(0, 80);
+    return evaluation.signal.source;
+}
+function formatFreshness(score) {
+    return score === null ? "unknown" : `${Math.round(score)}/100`;
+}
+function formatRank(score) {
+    return score.toFixed(3);
+}
+function formatUtility(score) {
+    return `${Number(score.toFixed(1))}/100`;
+}
+function formatList(values) {
+    return values.length > 0 ? values.join("; ") : "None";
+}
+export function formatEvaluateContextResult(result) {
+    const lines = [
+        "FreshContext evaluate_context",
+        "Candidate context -> Core evaluation -> decision-ready context",
+        "",
+        `Profile: ${result.profile.profile_id}`,
+        `Purpose: ${result.profile.purpose}`,
+        `Intent: ${result.intent}`,
+        "",
+    ];
+    result.items.forEach((item, index) => {
+        const { evaluation, decision } = item;
+        lines.push(`${index + 1}. ${sourceTitle(evaluation)}`, `   Decision: ${decision.label}`, `   Meaning: ${decision.meaning}`, `   Action: ${decision.action}`, `   Warnings: ${formatList(decision.warnings)}`, `   Source: ${evaluation.signal.source}`, `   Freshness: ${formatFreshness(evaluation.freshness_score)}`, `   Rank score: ${formatRank(evaluation.ranked.final_score)}`, `   Utility: ${formatUtility(evaluation.utility.score)}`, `   Confidence: ${evaluation.ranked.confidence}`, `   Why: ${evaluation.explanation}`, "");
+    });
+    const structured = {
+        profile: result.profile.profile_id,
+        intent: result.intent,
+        results: result.items.map((item, index) => ({
+            index: index + 1,
+            title: sourceTitle(item.evaluation),
+            source: item.evaluation.signal.source,
+            source_type: item.evaluation.signal.source_type,
+            decision: item.decision.decision,
+            label: item.decision.label,
+            meaning: item.decision.meaning,
+            action: item.decision.action,
+            warnings: item.decision.warnings,
+            reasons: item.decision.reasons,
+            freshness_score: item.evaluation.freshness_score,
+            rank_score: item.evaluation.ranked.final_score,
+            utility_score: item.evaluation.utility.score,
+            confidence: item.evaluation.ranked.confidence,
+            why: item.evaluation.explanation,
+        })),
+    };
+    lines.push("[FRESHCONTEXT_EVALUATION_JSON]", JSON.stringify(structured, null, 2), "[/FRESHCONTEXT_EVALUATION_JSON]");
+    return lines.join("\n");
+}

package/docs/CLIENT_SETUP.md

@@ -0,0 +1,166 @@
+# FreshContext Client Setup
+
+FreshContext is live as an MCP stdio package on npm.
+
+Use this guide when connecting Claude Desktop, Codex, or another MCP-compatible client to the published package.
+
+## What You Should See
+
+FreshContext `0.3.19` exposes:
+
+```text
+22 tools = evaluate_context + 21 read-only reference adapters
+```
+
+The primary interface is:
+
+```text
+evaluate_context
+```
+
+Use it when another retriever, agent, database, note parser, PDF extractor, or local script already has candidate context and needs FreshContext to judge what deserves to reach the model.
+
+## Claude Desktop: Published Package
+
+Add this to your Claude Desktop config, then restart Claude.
+
+macOS:
+
+```text
+~/Library/Application Support/Claude/claude_desktop_config.json
+```
+
+Windows:
+
+```text
+%APPDATA%\Claude\claude_desktop_config.json
+```
+
+Config:
+
+```json
+{
+  "mcpServers": {
+    "freshcontext": {
+      "command": "npx",
+      "args": ["-y", "freshcontext-mcp@latest"]
+    }
+  }
+}
+```
+
+If you previously installed an older global package, refresh it:
+
+```bash
+npm install -g freshcontext-mcp@latest
+```
+
+Then this config is also valid when the global npm bin path is visible to Claude:
+
+```json
+{
+  "mcpServers": {
+    "freshcontext": {
+      "command": "freshcontext-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+## Codex: Local MCP Config
+
+For Codex local MCP config, use the published package through `npx`:
+
+```toml
+[mcp_servers.freshcontext]
+command = "npx"
+args = ["-y", "freshcontext-mcp@latest"]
+```
+
+If you prefer a source checkout while developing FreshContext itself:
+
+```toml
+[mcp_servers.freshcontext]
+command = "node"
+args = ["C:\\Users\\YOUR_USERNAME\\path\\to\\freshcontext-mcp\\dist\\server.js"]
+```
+
+Keep local MCP config files out of git. Do not commit machine-specific paths or credentials.
+
+## Source Checkout Setup
+
+Use this when contributing to FreshContext itself:
+
+```bash
+git clone https://github.com/PrinceGabriel-lgtm/freshcontext-mcp
+cd freshcontext-mcp
+npm install
+npm run build
+npm run smoke:stdio
+```
+
+Expected smoke result:
+
+```json
+{
+  "ok": true,
+  "package_version": "0.3.19",
+  "server_version": "0.3.19",
+  "tool_count": 22
+}
+```
+
+## Remote Worker Boundary
+
+The repository also declares a remote Streamable HTTP MCP endpoint:
+
+```text
+https://freshcontext-mcp.gimmanuel73.workers.dev/mcp
+```
+
+Some clients can use `mcp-remote`:
+
+```json
+{
+  "mcpServers": {
+    "freshcontext-remote": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://freshcontext-mcp.gimmanuel73.workers.dev/mcp"]
+    }
+  }
+}
+```
+
+The npm/local stdio package remains the safest default client path. The hosted Worker endpoint was verified on 2026-06-11 at `0.3.19 / 22 tools` with `evaluate_context` present and returning decision-first output. Because the Worker is a separate deployment surface, re-run remote verification before claiming future package interfaces are live there.
+
+## ChatGPT / OpenAI Connector Boundary
+
+Claude and Codex MCP paths are documented now.
+
+ChatGPT connector compatibility requires a separate search/fetch compatibility audit before being claimed. Do not assume ChatGPT connector support from Claude/Codex MCP compatibility alone.
+
+## Quick Test Prompt
+
+After connecting a client, ask it to use `evaluate_context` with this candidate context:
+
+```json
+{
+  "profile": "academic_research",
+  "intent": "citation_check",
+  "signals": [
+    {
+      "title": "Fresh research source",
+      "content": "A relevant academic source with a reliable publication date.",
+      "source": "https://arxiv.org/abs/2605.12345",
+      "source_type": "arxiv",
+      "published_at": "2026-05-24T12:00:00.000Z",
+      "retrieved_at": "2026-05-24T13:00:00.000Z",
+      "semantic_score": 0.94,
+      "date_confidence": "high"
+    }
+  ]
+}
+```
+
+Expected result: decision-first output with a decision, meaning, action, warnings, supporting scores, and a structured FreshContext evaluation JSON block.

package/docs/CODEX_MCP_USAGE.md

@@ -12,7 +12,7 @@ The verified local server entrypoint is:
 & '<node-executable>' '<repo-root>\dist\server.js'
 ```
 
-The MCP server exposes 21 tools. The local smoke test verifies the package version, server version, expected tool count, and representative tool calls.
+The MCP server exposes 22 tools: the front-door `evaluate_context` tool plus 21 read-only reference adapters. The local smoke test verifies the package version, server version, expected tool count, the generic context-evaluation path, and representative adapter calls.
 
 No credential is required for the local stdio smoke path.
 
@@ -67,7 +67,7 @@ command = "npx"
 args = ["-y", "mcp-remote", "https://freshcontext-mcp.gimmanuel73.workers.dev/mcp"]
 ```
 
-This remote path was identified from repository metadata. The validation in this task verified local stdio only, not remote Codex compatibility, Worker availability, or Codex Cloud support.
+This remote path was verified on 2026-06-11 as a live Worker MCP endpoint exposing `0.3.19 / 22 tools`, including `evaluate_context`. That confirms Worker availability and MCP tool discovery. It does not by itself claim Codex Cloud support or guarantee every MCP client can use the remote bridge without its own client-specific setup check.
 
 ## Verification steps
 
@@ -83,9 +83,9 @@ Expected result:
 ```json
 {
   "ok": true,
-  "package_version": "0.3.18",
-  "server_version": "0.3.18",
-  "tool_count": 21
+  "package_version": "0.3.19",
+  "server_version": "0.3.19",
+  "tool_count": 22
 }
 ```
 
@@ -102,7 +102,7 @@ Expected result: no output and exit code 0.
 - Do not place secrets, credentials, registry tokens, npm tokens, GitHub tokens, or Cloudflare tokens in Codex MCP config.
 - Do not read, edit, print, or commit local token files, local environment files, registry credentials, Cloudflare local state, or Wrangler state.
 - Do not commit local Codex config or machine-specific paths.
-- Prefer the local stdio path for this compatibility check because it is verified by `npm run smoke:stdio`.
+- Prefer the local stdio path for source-checkout compatibility checks because it is verified by `npm run smoke:stdio`.
 - Do not claim Codex Cloud support unless it is separately tested and documented.
 
 ## Troubleshooting
@@ -112,5 +112,5 @@ If Codex cannot start the server:
 - Confirm `dist/server.js` exists. If not, run `npm run build`.
 - Confirm Node is installed with `node -v`. The package requires Node.js 20 or newer.
 - If `node` is not found by Codex, use the full executable path from `node -p "process.execPath"`.
-- Run `npm run smoke:stdio` from the repository root and confirm `tool_count` is 21.
+- Run `npm run smoke:stdio` from the repository root and confirm `tool_count` is 22.
 - If the remote setup fails, verify network access, `npx` availability, and the remote endpoint separately. Do not treat remote failure as evidence that local stdio is broken.

package/docs/CORE_API.md

@@ -1,9 +1,11 @@
 # FreshContext Core API
 
-FreshContext Core is the reusable engine layer in the current integrated MCP/Core package. It owns signal normalization, envelope creation, freshness scoring, failure honesty, rank/explain primitives, the context-utility primitive, and pure provenance helpers.
+FreshContext Core is the reusable engine layer in the current integrated Core/MCP package. It owns signal normalization, envelope creation, freshness scoring, failure honesty, Source Profiles, decision output, rank/explain primitives, the context-utility primitive, and pure provenance helpers.
 
 MCP, Worker HTTP, future REST, and future CLI/SDK surfaces should use Core as the contract center instead of redefining freshness or envelope behavior per host.
 
+For the package-level boundary between Core, MCP, adapters, and deployment surfaces, see [Core / MCP Boundary](./CORE_MCP_BOUNDARY.md).
+
 ## Stable Public Core API
 
 Import stable Core functions from:
@@ -74,9 +76,9 @@ The demo reads caller-provided JSON with `profile`, `intent`, and `signals`, the
 
 These types describe the stable envelope and adapter result contract.
 
-## Signal Contract v1
-
-Signal Contract v1 is the additive Core shape for a retrieved signal before it is ranked, wrapped, stored, or passed to an agent workflow.
+## Signal Contract v1
+
+Signal Contract v1 is the current FreshContext input standard: the stable shape for candidate context before it is ranked, wrapped, stored, judged by `evaluate_context`, or passed to an agent workflow.
 
 Public exports:
 
@@ -88,9 +90,11 @@ Public exports:
 - `SignalContractVersion`
 - `SignalNormalizeOptions`
 
-`published_at` is the canonical signal timestamp. `content_date` is accepted as an adapter/envelope compatibility alias. Normalization clears invalid or meaningfully future-dated timestamps, marks failed/error-looking content as `status: "failed"`, clamps `semantic_score` into `0..1`, and records normalization reasons.
-
-See [Signal Contract v1](./SIGNAL_CONTRACT.md).
+`published_at` is the canonical signal timestamp. `content_date` is accepted as an adapter/envelope compatibility alias. Normalization clears invalid or meaningfully future-dated timestamps, marks failed/error-looking content as `status: "failed"`, clamps `semantic_score` into `0..1`, and records normalization reasons.
+
+Future context signals and control signals are optional future metadata layers, not replacements for Signal Contract v1 and not required public input fields today.
+
+See [Signal Contract v1](./SIGNAL_CONTRACT.md).
 
 ## Source Profiles
 
@@ -108,7 +112,7 @@ Public exports:
 - `SourceFailurePolicy`
 - `SourceSurface`
 
-They reframe the 21 MCP tools as reference adapters and source-profile examples instead of the product identity. They do not implement `retrieve(...)`, Operator mode, adapter selection, crawling, local file search, or any host/runtime behavior.
+They reframe the 21 named adapter tools as reference adapters and source-profile examples instead of the product identity. The MCP server also exposes `evaluate_context` as the generic caller-provided context evaluation path. Source Profiles do not implement `retrieve(...)`, Operator mode, adapter selection, crawling, local file search, or any host/runtime behavior.
 
 ## Decision Helper
 

package/docs/CORE_MCP_BOUNDARY.md

@@ -0,0 +1,106 @@
+# FreshContext Core / MCP Boundary
+
+FreshContext is the context judgment layer between retrieval and reasoning.
+
+The current npm package is intentionally named `freshcontext-mcp` because MCP is the first live interface. That does not make MCP the whole product. MCP is a host layer over the FreshContext Core engine.
+
+## Product Shape
+
+```text
+Candidate context
+  -> FreshContext Core
+  -> decision-ready context
+  -> MCP / Worker / future REST / future SDK / future CLI
+```
+
+FreshContext Core owns the judgment contract:
+
+- signal normalization
+- freshness scoring
+- source profiles
+- context utility sidecar scoring
+- rank and explanation primitives
+- decision helper output
+- envelope and provenance helpers
+
+MCP owns the live reference interface:
+
+- tool registration
+- MCP input schemas
+- stdio transport
+- client-facing tool descriptions
+- formatting Core/adapter output for MCP clients
+
+Adapters own source intake:
+
+- source-specific fetching
+- source-specific parsing
+- timestamp extraction
+- source-specific normalization
+- failure normalization before Core evaluation
+
+Worker/site surfaces own deployment concerns:
+
+- Cloudflare runtime behavior
+- KV/D1/cache/feed concerns
+- hosted demo/site presentation
+- runtime guards and deployment configuration
+
+## Current Live Boundary
+
+Live today:
+
+- npm package: `freshcontext-mcp@0.3.19`
+- MCP stdio server and published binary: `freshcontext-mcp`
+- `evaluate_context` MCP tool for caller-provided candidate context
+- 21 named read-only reference adapters
+- Core signal evaluation
+- Source Profiles
+- Decision Helper
+- adapter registry metadata
+- arXiv signal-to-decision proof
+- bring-your-own-context local demos
+- Trust Scanner release gate
+
+Not live today:
+
+- standalone Core npm package
+- package rename to `freshcontext`
+- Operator / `retrieve(...)`
+- automatic browser crawling
+- automatic local folder/PDF scanning
+- hosted enterprise dashboard or billing
+- hard Ha-Pri v2 production enforcement
+- full adapter ingestion into pure signal paths
+
+## Future Package Split
+
+The safe split path is staged:
+
+1. Keep `freshcontext-mcp` stable for current users.
+2. Maintain Core as a pure internal export surface.
+3. Audit Core dependencies, Node/browser compatibility, and API stability.
+4. Publish a standalone Core package only after compatibility tests exist.
+5. Make `freshcontext-mcp` depend on the standalone Core package.
+6. Consider a repo rename to `freshcontext` only after package/client links are stable.
+
+The expected future shape is:
+
+```text
+freshcontext
+  packages/core      reusable judgment engine
+  packages/adapters  reference source intake assets
+  packages/mcp       MCP host layer
+  packages/cli       future local evaluator
+  docs
+```
+
+## Compatibility Rule
+
+Do not remove the current compatibility lanes until a dedicated migration pass exists:
+
+- `src/types.ts` re-exports legacy adapter types from Core.
+- `src/tools/freshnessStamp.ts` re-exports envelope helpers for older MCP/npm import paths.
+- `dist/server.js` remains the package `main` and MCP binary target.
+
+The architecture direction is clear, but the public runtime should stay boring and stable.