freshcontext-mcp 0.3.18 → 0.3.19

package/README.md

@@ -6,7 +6,7 @@ Claude had no idea. It presented everything with the same confidence.
 
 That's the problem freshcontext fixes.
 
-This repository is the integrated FreshContext MCP/Core package. Core is the context-integrity layer that scores, ranks, explains, and wraps retrieved context before it reaches an LLM or agent; MCP is the primary reference/interface implementation.
+This repository is the integrated FreshContext Core/MCP package. FreshContext is the context judgment layer between retrieval and reasoning. Core is the reusable engine that scores, ranks, explains, and turns candidate context into decision-ready context; MCP is the first live host/interface over that engine.
 
 [![npm version](https://img.shields.io/npm/v/freshcontext-mcp)](https://www.npmjs.com/package/freshcontext-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -30,7 +30,16 @@ That's not hallucination. That's correct summarization of corrupted retrieval.
 
 ## The layer
 
-FreshContext is a **temporal correction layer for retrieval systems**. One math correction applied before context reaches the LLM:
+FreshContext is **context integrity infrastructure for AI agents and retrieval systems**. It sits between retrieval and reasoning:
+
+```text
+candidate context
+  -> FreshContext Core
+  -> decision-ready context
+  -> model / agent / app
+```
+
+FreshContext evaluates freshness, source profile, confidence, utility, provenance material, and failure honesty before context reaches the LLM. The temporal core uses Decay-Adjusted Relevancy:
 
 ```
 R_t = R_0 · e^(−λt)
@@ -41,9 +50,9 @@ R_t = R_0 · e^(−λt)
 - `t` — hours elapsed since publication
 - `R_t` — decay-adjusted relevancy at query time
 
-That's the whole fix. No model swap. No re-embedding. No re-indexing. The layer drops onto whatever retrieval pipeline you already have.
+That's the core correction. No model swap. No re-embedding. No re-indexing. The layer drops onto whatever retrieval pipeline you already have.
 
-**The layer is the product.** The 21 tools shipped with this repo are reference adapters demonstrating compatibility — useful, but commodity. The DAR engine, the freshness envelope, and the FreshContext Specification are the moat.
+**The layer is the product.** The named adapters shipped with this repo demonstrate compatibility across different source classes. The DAR engine, the freshness envelope, Source Profiles, and the FreshContext Specification are the moat.
 
 ---
 
@@ -70,17 +79,62 @@ The FreshContext Specification v1.2 is published as an open standard under MIT l
 
 ## Architecture boundary
 
-FreshContext Core is the reusable center of the current integrated package. It owns freshness scoring, envelope formatting, failure guards, shared types, rank/explain primitives, and the context-conditioned utility primitive.
+FreshContext Core is the reusable center of the current integrated package. It owns signal normalization, freshness scoring, Source Profiles, decision output, envelope formatting, failure guards, shared types, rank/explain primitives, and the context-conditioned utility primitive.
 
-MCP is the primary reference/interface implementation over Core. Claude Desktop is supported, but not required. The 21 MCP tools in this repo are reference adapters and a live interface for using the system.
+MCP is the primary reference/interface implementation over Core. Claude Desktop is supported, but not required. The MCP tool surface exposes named reference adapters and a live interface for using the system.
 
 The production Cloudflare Worker now uses Core-backed envelope generation. Worker-specific concerns remain outside Core: MCP transport, runtime guards, KV cache policy, cache metadata injection, JSON parse/replace cache helpers, D1 feeds, cron, rate limiting, and Store/feed scoring/provenance.
 
+See [Core / MCP Boundary](./docs/CORE_MCP_BOUNDARY.md) for the current package boundary and the staged path toward a future standalone Core package.
+
 ---
 
-## The intelligence feed
+## Primary MCP interface
 
-Beyond the per-call envelope, the production FreshContext deployment exposes a continuous, decay-scored, deduplicated feed:
+The clearest MCP path is `evaluate_context`.
+
+It accepts candidate context from any retriever, agent, database, local script, note parser, or adapter output:
+
+```json
+{
+  "profile": "academic_research",
+  "intent": "citation_check",
+  "signals": [
+    {
+      "title": "Example source",
+      "content": "Candidate context text...",
+      "source": "https://example.com/source",
+      "source_type": "arxiv",
+      "published_at": "2026-05-24T12:00:00.000Z",
+      "retrieved_at": "2026-05-24T13:00:00.000Z",
+      "semantic_score": 0.92
+    }
+  ]
+}
+```
+
+FreshContext returns decision-first output:
+
+- Decision
+- Meaning
+- Action
+- Warnings
+- Source
+- Freshness
+- Rank score
+- Utility
+- Confidence
+- Why
+
+`evaluate_context` does not fetch URLs, crawl, scrape, browse, read folders, or call adapters. It only evaluates candidate context the caller provides.
+
+Current boundary: `evaluate_context` is part of the published npm/local stdio MCP server. The hosted Cloudflare Worker endpoint is a separate deployment surface and may lag npm package interfaces until a dedicated Worker sync pass.
+
+---
+
+## Advanced Worker/feed surface
+
+Beyond the per-call Core/MCP paths, the production Worker deployment exposes a continuous, decay-scored, deduplicated feed. This is an advanced deployment surface, not the required way to use FreshContext Core:
 
 ```
 GET /v1/intel/feed/:profile_id?limit=20&min_rt=0
@@ -94,7 +148,7 @@ Production endpoint: `https://freshcontext-mcp.gimmanuel73.workers.dev`
 
 ## Reference adapters
 
-The repo ships 21 tools demonstrating how to make any data source FreshContext-compatible. Useful as drop-in tools, but the value is the layer above them.
+The repo ships named reference adapters that demonstrate how different source classes can become FreshContext-compatible. Each adapter keeps its own name because it represents a source boundary; the adapter count is operational proof, not the product headline.
 
 ### Intelligence
 | Adapter | What it returns |
@@ -128,7 +182,7 @@ The repo ships 21 tools demonstrating how to make any data source FreshContext-c
 | `extract_finance_landscape` | 5 | Finance + HN + Reddit + GitHub + changelog |
 | `extract_company_landscape` | 5 | The full picture on any company |
 
-### Unique — not available in any other MCP server
+### Official, regulatory, and procurement sources
 | Adapter | Source | What it returns |
 |---|---|---|
 | `extract_changelog` | GitHub Releases / npm / auto-discover | Update history from any repo, package, or website |
@@ -290,6 +344,14 @@ Minimal shape:
 
 This local demo does not fetch URLs, crawl, or read folders. It evaluates candidate context you provide and returns decision-first output: Decision, Meaning, Action, Warnings, and supporting metrics.
 
+In an MCP client, use `evaluate_context` when you already have candidate context from another retriever, database, agent, or script:
+
+```text
+Use evaluate_context with profile "academic_research", intent "citation_check", and these candidate signals: [...]
+```
+
+Use the named reference adapters when you want FreshContext's current MCP package to fetch public source examples for you.
+
 **Should I build this idea?**
 ```
 Use extract_idea_landscape with idea "procurement intelligence saas"
@@ -343,26 +405,29 @@ Production: `https://freshcontext-mcp.gimmanuel73.workers.dev`
 ## Roadmap
 
 - [x] FreshContext Specification v1.2 published (MIT, open standard)
-- [x] DAR engine with proprietary λ constants (v0.3.18)
+- [x] DAR engine with proprietary λ constants (v0.3.19)
 - [x] Ha-Pri v1 provenance signatures on stored signals
 - [x] Semantic deduplication via fingerprinting
 - [x] Live before/after demo at `/demo`
 - [x] METHODOLOGY.md — formal IP and engineering documentation
-- [x] 21 reference tools across intelligence, competitive research, market data, and composites
+- [x] Named reference adapters across intelligence, competitive research, market data, and composites
+- [x] Generic MCP `evaluate_context` tool for caller-provided candidate context
 - [x] Core-backed envelope generation shared by npm/MCP and the Cloudflare Worker
 - [x] Cloudflare Workers deployment — global edge, KV cache, KV rate limiting
-- [x] Listed on official MCP Registry, Apify Store, npm
+- [x] Published on npm and listed for MCP usage; Apify/feed assets are separated from the normal MCP runtime package
 - [ ] Ha-Pri v2 hardened canonical content hash verification
 - [x] GitHub Actions release workflow — manual or `v*` tag-triggered npm publish path
 - [ ] Webhook triggers — push high-entropy signals on threshold
 - [ ] Dashboard — React frontend for the D1 intelligence pipeline
 - [ ] GKG upgrade for `extract_gdelt` — tone scores, goldstein scale, event codes
 
+Future work is organized in [FreshContext Future Lanes](./docs/FUTURE_LANES.md). Roadmap items are not live product claims until implemented and validated.
+
 ---
 
 ## Contributing
 
-PRs welcome. New adapters are the highest-value contribution — see `src/adapters/` for the pattern and [`FRESHCONTEXT_SPEC.md`](./FRESHCONTEXT_SPEC.md) for the contract any adapter must fulfil.
+PRs welcome. The highest-value contributions improve the caller-provided context path, decision output, host integrations, and FreshContext-compatible signal quality. New reference adapters are useful when they preserve source boundaries and emit timestamped, failure-honest context — see `src/adapters/` for examples and [`FRESHCONTEXT_SPEC.md`](./FRESHCONTEXT_SPEC.md) for the compatibility contract.
 
 If you're building something FreshContext-compatible, open an issue and we'll add you to the ecosystem list.
 
@@ -377,7 +442,6 @@ If you're building something FreshContext-compatible, open an issue and we'll ad
 - [Dependency diligence notes](./docs/DEPENDENCY_DILIGENCE.md)
 - [Release integrity notes](./docs/RELEASE_INTEGRITY.md)
 - [Release notes](./docs/RELEASE_NOTES.md)
-- [Operational demo runbook](./docs/OPERATIONAL_DEMO_RUNBOOK.md)
 
 ---
 
@@ -392,4 +456,4 @@ MIT
 
 ---
 
-**Also on:** [Apify Store](https://apify.com/prince_gabriel/freshcontext-mcp) · [MCP Registry](https://registry.modelcontextprotocol.io) · [npm](https://www.npmjs.com/package/freshcontext-mcp)
+**Also on:** [MCP Registry](https://registry.modelcontextprotocol.io) · [npm](https://www.npmjs.com/package/freshcontext-mcp)

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.19",
 });
-// ─── 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).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,127 @@
+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",
+];
+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 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.`);
+    }
+    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.");
+    }
+    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/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.
 
@@ -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
 }
 ```
 
@@ -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:
@@ -108,7 +110,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.

package/docs/FUTURE_LANES.md

@@ -0,0 +1,173 @@
+# FreshContext Future Lanes
+
+This document keeps future FreshContext work organized without turning roadmap ideas into public claims.
+
+FreshContext is live today as an integrated MCP/Core package. Future work should stay in lanes, start with audits, and avoid feature sprawl.
+
+The current package boundary is documented in [Core / MCP Boundary](./CORE_MCP_BOUNDARY.md). Treat MCP as the first live host over FreshContext Core, not as the whole product identity.
+
+## Current Live Boundary
+
+Live today:
+
+- npm package: `freshcontext-mcp@0.3.19`
+- MCP stdio server
+- `evaluate_context` MCP tool for caller-provided candidate context
+- 21 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:
+
+- Operator / `retrieve(...)`
+- browser crawling
+- automatic local file, folder, or PDF scanning
+- hosted dashboard or billing
+- hard Ha-Pri v2 production enforcement
+- standalone Core SDK package
+- full adapter ingestion
+
+## Lane 1: Client Setup Reliability
+
+Goal:
+
+```text
+Make Claude, Codex, and MCP-compatible clients connect reliably to the published package.
+```
+
+Start with setup guide audits, Claude Desktop local/global package paths, Codex local MCP config paths, stale global package fixes, and smoke command expectations.
+
+Do not claim ChatGPT/OpenAI connector compatibility until a separate compatibility audit is done.
+
+## Lane 2: Generic Context Evaluation
+
+Goal:
+
+```text
+Let any caller provide candidate context and get decision-ready output.
+```
+
+Current live MCP path:
+
+```text
+evaluate_context
+```
+
+Hard boundary:
+
+```text
+No fetching, crawling, browsing, folder reading, or retrieval orchestration.
+Only evaluate caller-provided candidate context.
+```
+
+Next work in this lane should focus on CLI, SDK, and REST ergonomics over the same caller-provided signal shape.
+
+## Lane 3: Multi-Agent Context Handoff Proof
+
+Goal:
+
+```text
+Show FreshContext as an independent context judgment layer between agents.
+```
+
+Proof shape:
+
+```text
+agent A produces candidate context
+-> FreshContext evaluates it
+-> agent B receives decision-ready context
+```
+
+Do not build a full multi-agent framework. Prove the handoff boundary.
+
+## Lane 4: Core SDK Extraction Audit
+
+Goal:
+
+```text
+Decide whether Core should become a standalone package.
+```
+
+Audit current Core exports, dependency boundaries, package shape, browser/node compatibility, public API stability, and what remains MCP-only.
+
+No extraction without a compatibility plan. Keep `freshcontext-mcp` stable until a standalone Core package has compatibility tests and a migration path.
+
+## Lane 5: Local/User Data Intake Audit
+
+Goal:
+
+```text
+Explore student, research, and local-PC workflows safely.
+```
+
+Candidate sources include notes, PDFs, local JSON/CSV, citation exports, and database rows.
+
+Hard boundary:
+
+```text
+Consent-first design. No automatic folder scanning or background file reading.
+```
+
+## Lane 6: Decision Layer Upgrade
+
+Goal:
+
+```text
+Make decisions more useful without silently changing ranking.
+```
+
+Possible inputs include context utility, control signal, future context signal, confidence tiers, and source-profile-specific thresholds.
+
+Do not make `utility.score` affect ranking by default without a dedicated ranking policy pass.
+
+## Lane 7: Ha-Pri v2 Production Path
+
+Goal:
+
+```text
+Turn Ha-Pri v2 from pure Core helper/design into production enforcement where appropriate.
+```
+
+Audit canonical content material, storage path, verification timing, failure mode, D1/Worker compatibility, and migration plan.
+
+Do not claim hard tamper enforcement until the read/write path exists.
+
+## Lane 8: GDELT GKG / Richer Source Intelligence
+
+Goal:
+
+```text
+Upgrade GDELT intelligence with richer global knowledge graph signals.
+```
+
+Possible fields include tone, Goldstein scale, event codes, actor geography, theme density, and source timeline.
+
+Do not mix this with generic context evaluation or local intake.
+
+## Lane 9: Operator / Retrieve Orchestration
+
+Goal:
+
+```text
+Coordinate retrieval only after the decision layer and adapter boundaries are mature.
+```
+
+Operator may later select adapters, call retrievers, refresh stale sources, and package best context.
+
+Not now. Operator is a later workflow layer over Core and adapters.
+
+## Operating Rule
+
+Every lane starts with:
+
+```text
+audit -> small patch -> validation -> stop
+```
+
+Do not combine lanes because the architecture is tempting.
+

package/docs/RELEASE_INTEGRITY.md

@@ -22,6 +22,7 @@ This document describes release hardening practices for future FreshContext pack
   - Confirm fresh consumer `npm audit --omit=dev` is clean.
 - Run a stale-claim scan across public docs and package-facing files.
 - Run a secret scan before sharing archives, diligence folders, or package artifacts.
+- Keep operational demo runbooks, buyer scripts, outreach plans, diligence checklists, and negotiation materials outside the public npm package.
 
 ## Package Exclusion Checks
 
@@ -34,6 +35,7 @@ Confirm release artifacts do not include:
 - Local database snapshots or SQL dumps.
 - Private sale, buyer, target, outreach, or diligence documents.
 - Private data-room folders.
+- Operational demo runbooks intended for buyer calls or internal screen-share rehearsal.
 - Local logs.
 - Old package tarballs.
 

package/docs/RELEASE_NOTES.md

@@ -1,8 +1,25 @@
 # FreshContext Release Notes
 
+## 0.3.19
+
+FreshContext 0.3.19 syncs the public MCP package with the new generic `evaluate_context` interface.
+
+### Context Evaluation Front Door
+
+- Adds `evaluate_context` as the primary MCP tool for caller-provided candidate context.
+- Returns decision-first output for agents and users: decision, meaning, action, warnings, source, freshness, rank score, utility, confidence, and explanation.
+- Keeps the boundary explicit: `evaluate_context` does not fetch, crawl, scrape, browse, read folders, or call adapters.
+- Updates stdio smoke and Trust Scanner claim checks to expect 22 MCP tools: `evaluate_context` plus 21 read-only reference adapters.
+
+### Public Framing
+
+- Reframes the MCP package around FreshContext as context integrity infrastructure, not a 21-tool toolbox.
+- Keeps the 21 adapter tools as read-only reference adapters and proof surfaces.
+- Updates package-facing docs/spec language to point first at `candidate context -> FreshContext Core -> decision-ready context`.
+
 ## 0.3.18
 
-FreshContext 0.3.18 prepares the next npm package release without changing the deployed Worker or publishing automatically.
+FreshContext 0.3.18 made the MCP/Core package easier to install, validate, and explain without changing the deployed Worker runtime.
 
 ### Core and Context Evaluation
 
@@ -32,7 +49,7 @@ FreshContext 0.3.18 prepares the next npm package release without changing the d
 
 ### Boundaries
 
-- No npm publish in this preparation pass.
-- No git tag in this preparation pass.
-- No deployment in this preparation pass.
-- No Worker, REST handler, Core runtime, MCP tool schema, or adapter behavior changes are included in the version bump itself.
+- No Worker deploy is part of the npm package release.
+- No hosted dashboard, billing system, Operator mode, browser crawling, or local file scanning is included.
+- No Worker, REST handler, MCP tool schema, or existing adapter behavior changes are included in the package release itself.
+- Future work is tracked in [`FUTURE_LANES.md`](./FUTURE_LANES.md).

package/docs/SOURCE_PROFILES.md

@@ -31,7 +31,7 @@ MCP, REST, SDK, CLI, and future operator workflows are hosts over Core. They sho
 
 Adapters provide candidate context. They fetch, search, scrape, read, or receive source data, then turn that data into FreshContext-compatible signals.
 
-The 21 MCP tools in this repository are reference adapters, source-profile examples, and proof surfaces. They are useful, but they are not the product identity.
+The named MCP tools in this repository are reference adapters, source-profile examples, and proof surfaces. They are useful, but they are not the product identity.
 
 They demonstrate that FreshContext can evaluate different information classes:
 
@@ -88,7 +88,7 @@ It does not add `retrieve(...)`, Operator mode, adapter selection, local file se
 
 ## Adapter Registry Metadata
 
-As of Pass 8-S, the 21 MCP tools are also represented as adapter metadata. The registry maps each current tool name to a future adapter identity, Source Profile, output mode, runtime kind, and migration risk.
+As of Pass 8-S, the 21 named adapter tools are also represented as adapter metadata. The registry maps each adapter tool name to a future adapter identity, Source Profile, output mode, runtime kind, and migration risk. The generic `evaluate_context` MCP tool is not an adapter; it is a host interface over caller-provided candidate context.
 
 This registry is metadata-only. It does not change MCP behavior, adapter implementation behavior, Worker behavior, REST behavior, Core evaluation behavior, or runtime transport. It exists to make future extraction deliberate instead of ad hoc.
 
@@ -423,5 +423,5 @@ Sharper agent-facing sentence:
 FreshContext decides what context deserves to reach the model.
 ```
 
-Use the 21 tools as proof of breadth, not as the headline.
+Use named reference adapters as proof of breadth, not as the headline.
 

package/package-script-guard.mjs

@@ -101,6 +101,7 @@ const commands = {
       "tests/coreApiContract.test.ts",
       "tests/corePipeline.test.ts",
       "tests/decision.test.ts",
+      "tests/evaluateContextTool.test.ts",
       "tests/restHandler.test.ts",
       "tests/sourceProfiles.test.ts",
       "tests/adapterRegistry.test.ts",

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "freshcontext-mcp",
   "mcpName": "io.github.PrinceGabriel-lgtm/freshcontext",
-  "version": "0.3.18",
-  "description": "Real-time web intelligence for AI agents. 21 tools, no required API keys. Every result timestamped with a freshness score.",
+  "version": "0.3.19",
+  "description": "Context integrity infrastructure for AI agents and retrieval systems. Score, explain, and wrap candidate context before it reaches the model.",
   "keywords": [
     "mcp",
     "mcp-server",
     "ai-agents",
     "llm",
     "freshness",
-    "web-scraping",
-    "github-analytics",
-    "hackernews",
-    "yc",
+    "context-integrity",
+    "retrieval",
+    "provenance",
+    "source-profiles",
+    "rag",
     "typescript",
     "context",
     "model-context-protocol"
@@ -37,10 +38,11 @@
     "!dist/apify.js",
     "docs/API_DESIGN.md",
     "docs/CODEX_MCP_USAGE.md",
+    "docs/CORE_MCP_BOUNDARY.md",
     "docs/CORE_API.md",
     "docs/DEPENDENCY_DILIGENCE.md",
+    "docs/FUTURE_LANES.md",
     "docs/HA_PRI_V2_DESIGN.md",
-    "docs/OPERATIONAL_DEMO_RUNBOOK.md",
     "docs/RELEASE_INTEGRITY.md",
     "docs/RELEASE_NOTES.md",
     "docs/SIGNAL_CONTRACT.md",

package/server.json

@@ -1,18 +1,18 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
   "name": "io.github.PrinceGabriel-lgtm/freshcontext",
-  "description": "Freshness-aware AI retrieval with 21 MCP tools for timestamped, decay-ranked live signals.",
+  "description": "Context integrity infrastructure for AI agents and retrieval systems. Evaluates caller-provided and adapter-sourced context before it reaches the model.",
   "repository": {
     "url": "https://github.com/PrinceGabriel-lgtm/freshcontext-mcp",
     "source": "github"
   },
-  "version": "0.3.18",
+  "version": "0.3.19",
   "website_url": "https://freshcontext-site.pages.dev",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "freshcontext-mcp",
-      "version": "0.3.18",
+      "version": "0.3.19",
       "transport": {
         "type": "stdio"
       }

package/docs/OPERATIONAL_DEMO_RUNBOOK.md

@@ -1,458 +0,0 @@
-# FreshContext Operational Demo Runbook
-
-This runbook is for a live call, screen share, buyer demo, agent-builder conversation, or handoff where you need to show what FreshContext can do today.
-
-It is intentionally practical. It does not describe future Operator mode as if it already exists.
-
-## The Short Explanation
-
-FreshContext is a context gateway between retrieval and reasoning.
-
-```text
-Raw candidate context goes in.
-FreshContext evaluates freshness, usefulness, traceability, and uncertainty.
-Decision-ready context comes out.
-```
-
-Use this sentence when someone asks what it is:
-
-```text
-FreshContext tells an agent or human whether a source should be used, cited, refreshed, verified, watched, treated as background, or excluded.
-```
-
-Use this sentence when someone asks why it matters:
-
-```text
-Search and retrieval find matching information; FreshContext decides what context deserves to reach the model first.
-```
-
-## Current Operational Shape
-
-FreshContext has four working lanes today:
-
-| Lane | What It Does Today | Demo Status |
-|---|---|---|
-| Core | Normalizes signals, scores freshness, ranks, explains, prepares envelopes/provenance, and interprets decisions | Working |
-| MCP package | Exposes 21 reference tools to MCP clients over stdio | Working |
-| BYOC local demos | Lets a user provide JSON source lists and get decision-first output | Working |
-| arXiv signal proof | Shows extracted adapter signals flowing into Core decisions | Working |
-
-Two companion systems support operational trust:
-
-| Companion | Role |
-|---|---|
-| Trust Scanner | Checks package, release, public-claim, and integrity risk |
-| Ops Pulse | Checks Cloudflare/runtime/D1/cron/observability health for deployed systems |
-
-## What FreshContext Is Not Yet
-
-Do not overclaim these in a live talk:
-
-- It is not full Operator mode yet.
-- It does not crawl the web by itself in the BYOC demo.
-- It does not silently read local folders.
-- It does not replace legal, medical, tax, employment, academic, or investment review.
-- It does not production-enforce Ha-Pri v2 yet.
-- It does not make `utility.score` replace default ranking.
-- It does not require publishing or deploying to demonstrate the current local flow.
-
-## Screen-Share Prep
-
-Open two terminals:
-
-1. FreshContext MCP repo:
-
-```powershell
-cd "C:\Users\Immanuel Gabriel\Downloads\freshcontext-mcp"
-```
-
-2. Ops Pulse repo:
-
-```powershell
-cd "C:\Users\Immanuel Gabriel\Downloads\freshcontext-ops-pulse"
-```
-
-Optional files to open beside the terminal:
-
-- `README.md`
-- `docs/OPERATIONAL_DEMO_RUNBOOK.md`
-- `examples/sources.academic.example.json`
-- `examples/sources.jobs.example.json`
-- `docs/SOURCE_PROFILES.md`
-- `docs/CORE_API.md`
-
-## Preflight Before A Call
-
-Run this before the call, not during the first minute of the call:
-
-```powershell
-cd "C:\Users\Immanuel Gabriel\Downloads\freshcontext-mcp"
-
-git status --short --branch
-npm run build
-npm test
-npm run smoke:stdio
-npm run trust:scan:json
-```
-
-Expected healthy signs:
-
-```text
-working tree clean
-tests pass
-smoke: 21 tools, v0.3.18
-trust scan: 0 effective fail findings
-```
-
-For Ops Pulse:
-
-```powershell
-cd "C:\Users\Immanuel Gabriel\Downloads\freshcontext-ops-pulse"
-
-git status --short --branch
-npm run check
-npm run build
-```
-
-Expected healthy signs:
-
-```text
-working tree clean
-typecheck passes
-build passes
-```
-
-## Best Live Demo Path
-
-Use the local demos first. They are deterministic and do not need live network access.
-
-### 1. Show Bring Your Own Context
-
-Academic/citation example:
-
-```powershell
-cd "C:\Users\Immanuel Gabriel\Downloads\freshcontext-mcp"
-npm run demo:evaluate:file -- examples/sources.academic.example.json
-```
-
-Say:
-
-```text
-This is the simple user path. The user gives FreshContext candidate sources. FreshContext does not fetch or crawl here. It evaluates what was provided and returns decision-first context.
-```
-
-Point out:
-
-- `Decision`
-- `Meaning`
-- `Action`
-- `Warnings`
-- `Freshness`
-- `Rank score`
-- `Utility`
-- `Confidence`
-- `Why`
-
-The important visible result is not the number. It is the action label:
-
-```text
-Cite as primary
-Cite as supporting
-Needs verification
-Exclude
-```
-
-### 2. Show A Normal-User Example
-
-Jobs/opportunities example:
-
-```powershell
-npm run demo:evaluate:file -- examples/sources.jobs.example.json
-```
-
-Say:
-
-```text
-The same Core works for a different source profile and intent. Academic sources age slowly; jobs age quickly. FreshContext changes the decision meaning without needing a new product.
-```
-
-Point out decisions like:
-
-```text
-Use first
-Needs refresh
-Exclude
-```
-
-### 3. Show Adapter-To-Core Proof
-
-arXiv fixture-backed adapter proof:
-
-```powershell
-npm run demo:arxiv
-```
-
-Say:
-
-```text
-This closes the adapter loop. arXiv-style XML becomes FreshContext signals, then Core evaluates those signals, then the decision helper explains what to do with them.
-```
-
-Use this exact flow:
-
-```text
-arXiv XML
--> searchArxivSignals(...)
--> evaluateSignals(...)
--> interpretEvaluations(...)
--> decision-ready output
-```
-
-This is the bridge from reference MCP tools to source-aware adapter assets.
-
-### 4. Show MCP Runtime Health
-
-Only run this if network conditions are fine, because representative MCP smoke can touch live source paths:
-
-```powershell
-npm run smoke:stdio
-```
-
-Expected:
-
-```json
-{
-  "ok": true,
-  "package_version": "0.3.18",
-  "server_version": "0.3.18",
-  "tool_count": 21
-}
-```
-
-Say:
-
-```text
-This proves the MCP package still exposes the reference tool surface. But the product is not the number of tools. The tools are proof surfaces and adapter candidates over the Core judgment layer.
-```
-
-### 5. Show Trust Scanner
-
-```powershell
-npm run trust:scan:json
-```
-
-Say:
-
-```text
-This protects release and public-claim integrity. The line that matters for the gate is effective fail count: zero.
-```
-
-You do not need to read every raw finding live. The scanner intentionally reports review items and downgrades known non-blockers.
-
-### 6. Show Ops Pulse Health
-
-In the Ops Pulse repo:
-
-```powershell
-cd "C:\Users\Immanuel Gabriel\Downloads\freshcontext-ops-pulse"
-npm run check
-npm run build
-```
-
-Say:
-
-```text
-Ops Pulse is separate from FreshContext Core. It is the operational health companion for Cloudflare/runtime/D1/cron/observability workflows.
-```
-
-## Bring Your Own Context File Shape
-
-Minimal JSON shape:
-
-```json
-{
-  "profile": "academic_research",
-  "intent": "citation_check",
-  "signals": [
-    {
-      "title": "Example source",
-      "content": "Raw retrieved content or notes...",
-      "source": "https://example.com/source",
-      "source_type": "arxiv",
-      "published_at": "2026-05-24T12:00:00.000Z",
-      "retrieved_at": "2026-05-24T13:00:00.000Z",
-      "semantic_score": 0.92
-    }
-  ]
-}
-```
-
-Run a custom file:
-
-```powershell
-npm run demo:evaluate:file -- path\to\sources.json
-```
-
-Important boundary:
-
-```text
-The file demo evaluates candidate context you provide. It does not fetch URLs, crawl websites, read folders, or run Operator mode.
-```
-
-## How To Explain The Framework
-
-Use this architecture:
-
-```text
-Adapters / retrievers / databases / agents
--> FreshContext Signal Contract
--> Source Profile
--> Core evaluation
--> Decision Helper
--> MCP / REST / SDK / CLI / agent output
-```
-
-The deeper system split is:
-
-```text
-Core = deterministic context intelligence
-Source Profiles = how source classes age and fail
-Adapters = source intake
-Hosts = MCP, REST, SDK, CLI
-Operator = future retrieval workflow over Core
-Trust Scanner = release/package/public-claim integrity
-Ops Pulse = runtime health diagnostics
-```
-
-## How Agents Would Use This
-
-For Codex, Claude, multi-agent workflows, or database-backed assistants, FreshContext should sit between retrieval and final reasoning:
-
-```text
-Agent retrieves 30 candidate items.
-FreshContext normalizes and evaluates them.
-FreshContext returns ranked decisions and warnings.
-Agent uses the best context first and avoids stale/failed/unknown sources.
-```
-
-That means FreshContext is not trying to be another chat agent. It is the layer an agent uses before deciding what to trust.
-
-In a multi-agent system:
-
-```text
-Research agent finds candidates.
-FreshContext scores and labels candidates.
-Writing agent receives only decision-ready context.
-Review agent sees warnings, provenance, and excluded sources.
-```
-
-For database workflows:
-
-```text
-Database query returns rows or documents.
-FreshContext evaluates dates, confidence, failure states, and source profile.
-Application stores or displays the ranked decision result.
-```
-
-## What To Say If Someone Says "Is This Just Docs?"
-
-Say:
-
-```text
-No. The docs describe the boundaries, but the local commands run the actual Core pipeline. The BYOC demo reads user-provided source JSON, evaluates it, ranks it, and prints decisions. The arXiv demo proves an adapter signal path reaches Core decisions. The MCP smoke proves the package exposes 21 working tools.
-```
-
-Then run:
-
-```powershell
-npm run demo:evaluate:file -- examples/sources.jobs.example.json
-```
-
-The output is the answer.
-
-## Current Demo Script
-
-Use this order in a live talk:
-
-1. One sentence:
-
-```text
-FreshContext decides what context deserves to reach the model.
-```
-
-2. Run academic BYOC:
-
-```powershell
-npm run demo:evaluate:file -- examples/sources.academic.example.json
-```
-
-3. Run jobs BYOC:
-
-```powershell
-npm run demo:evaluate:file -- examples/sources.jobs.example.json
-```
-
-4. Run arXiv adapter proof:
-
-```powershell
-npm run demo:arxiv
-```
-
-5. Run MCP smoke if the network is stable:
-
-```powershell
-npm run smoke:stdio
-```
-
-6. Close with:
-
-```text
-The product is the judgment layer. The tools are reference adapters. The next growth path is more adapters, CLI/SDK usability, and eventually Operator mode.
-```
-
-## Current Release Boundary
-
-Current prepared package version:
-
-```text
-freshcontext-mcp@0.3.18
-```
-
-Current state:
-
-```text
-release prep merged
-package ready for release execution gate
-npm publish not done
-deploy not done
-git tag not created
-```
-
-Do not publish, deploy, or tag during a demo.
-
-## Troubleshooting
-
-If the old ChatGPT handoff chat will not open:
-
-```text
-Do not depend on it. Use this runbook plus the local docs and repo state.
-```
-
-If `npm run smoke:stdio` fails during a live call:
-
-```text
-Switch to the offline demos: demo:evaluate:file and demo:arxiv.
-```
-
-If someone asks whether FreshContext gives advice:
-
-```text
-No. It gives context judgment: citation readiness, freshness, usefulness, traceability, and uncertainty. Humans and domain systems still own final decisions.
-```
-
-If someone asks what is next:
-
-```text
-Release execution gate, then CLI/SDK usability, then more adapter extraction, then Operator mode.
-```
-