freshcontext-mcp 0.3.18 → 0.3.20

package/docs/SIGNAL_CONTRACT.md

@@ -1,8 +1,30 @@
-# FreshContext Signal Contract v1
-
-FreshContext Signal Contract v1 defines the Core shape for a retrieved signal before it is ranked, wrapped, stored, or passed to an agent workflow.
-
-It is an additive Core API. It does not change MCP tool schemas, Worker runtime behavior, D1 schema, Store scoring, feeds, or deployment behavior.
+# FreshContext Signal Contract v1
+
+FreshContext Signal Contract v1 is the current FreshContext input standard: the stable shape for candidate context that should be judged before it reaches a model.
+
+In plain terms:
+
+```text
+candidate context -> Signal Contract v1 -> FreshContext judgment -> decision-ready context
+```
+
+The Signal Contract is live product architecture. It is used by Core normalization, `evaluate_context`, bring-your-own-context demos, reference adapter signal paths, and future batch validation.
+
+Do not rename this with future-signal terminology. Future context signals, control signals, provenance confidence signals, and richer decision metadata are optional future layers on top of this stable input shape. They are not replacements for Signal Contract v1 and are not required fields today.
+
+It is an additive Core API. It does not change MCP tool schemas, Worker runtime behavior, D1 schema, Store scoring, feeds, or deployment behavior.
+
+## Batch Validation Harness
+
+Source checkouts include a small validation harness for testing larger Signal Contract v1 batches:
+
+```bash
+npm run batch:validate -- examples/batches/signal-contract-v1.academic.json
+```
+
+The harness reads caller-provided JSON, evaluates it through Core, summarizes status/date/decision counts, and prints a structured evidence block. It does not add required fields to the Signal Contract and does not fetch, crawl, scan folders, or call reference adapters.
+
+Replay output includes concise decision explanations and small reason-code lists for top results and human-review mismatches. These are reporting aids for auditability: they surface whether relevance, freshness, date confidence, status, utility, score normalization, or Source Profile behavior influenced a treatment label. They do not change Core scoring, ranking, normalization, or decision thresholds, and they do not certify truth.
 
 ## Contract Version
 
@@ -16,9 +38,9 @@ Every normalized signal includes:
 contract_version: "freshcontext.signal.v1"
 ```
 
-## Input Shape
-
-`FreshContextSignalInput` accepts the common fields used by adapters, agents, ranking, and future Store wiring:
+## Input Shape
+
+`FreshContextSignalInput` accepts the common fields used by adapters, agents, ranking, `evaluate_context`, and future Store wiring:
 
 ```ts
 interface FreshContextSignalInput {
@@ -38,7 +60,21 @@ interface FreshContextSignalInput {
 }
 ```
 
-`published_at` is the canonical signal timestamp. `content_date` is accepted as an adapter/envelope compatibility alias.
+`published_at` is the canonical signal timestamp. `content_date` is accepted as an adapter/envelope compatibility alias.
+
+Minimal caller-provided input usually looks like:
+
+```json
+{
+  "title": "Example source",
+  "content": "Candidate context text...",
+  "source": "https://example.com/source",
+  "source_type": "official_docs",
+  "published_at": "2026-06-01T00:00:00.000Z",
+  "retrieved_at": "2026-06-09T00:00:00.000Z",
+  "semantic_score": 0.92
+}
+```
 
 ## Normalized Output
 
@@ -62,16 +98,166 @@ interface FreshContextSignal {
 }
 ```
 
-## Normalization Rules
-
-- Missing or invalid `published_at` / `content_date` becomes `published_at: null`.
+## Normalization Rules
+
+- Missing or invalid `published_at` / `content_date` becomes `published_at: null`.
 - `content_date` maps to `published_at` when `published_at` is absent.
 - Meaningfully future-dated timestamps are cleared and receive `date_confidence: "unknown"`.
 - Small clock skew is tolerated by the same Core freshness policy used by envelope scoring.
 - Failed, empty, timeout, blocked, or error-looking content becomes `status: "failed"`.
 - Missing, invalid, negative, or oversized `semantic_score` is clamped into `0..1`.
-- `metadata` is shallow-copied so normalization does not mutate caller-owned objects.
-- `reasons` records meaningful normalization changes.
+- `metadata` is shallow-copied so normalization does not mutate caller-owned objects.
+- `reasons` records meaningful normalization changes.
+
+## Examples
+
+These examples are intentionally small. They show the current contract shape, not future optional metadata.
+
+### Valid Candidate Signals
+
+Academic research:
+
+```json
+{
+  "title": "A fresh retrieval-augmented generation benchmark",
+  "content": "The paper reports a 2026 benchmark for retrieval-augmented generation systems.",
+  "source": "https://arxiv.org/abs/2606.00001",
+  "source_type": "arxiv",
+  "published_at": "2026-06-01T09:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.94,
+  "metadata": {
+    "profile": "academic_research"
+  }
+}
+```
+
+Official docs:
+
+```json
+{
+  "title": "API changelog",
+  "content": "The official changelog documents the current API behavior.",
+  "source": "https://docs.example.com/changelog",
+  "source_type": "official_docs",
+  "published_at": "2026-06-08T10:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.88
+}
+```
+
+Jobs/opportunities:
+
+```json
+{
+  "title": "AI tools engineer",
+  "content": "A current remote role for an AI tools engineer.",
+  "source": "https://jobs.example.com/ai-tools-engineer",
+  "source_type": "jobs",
+  "published_at": "2026-06-07T08:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.86
+}
+```
+
+Market/finance:
+
+```json
+{
+  "title": "Company quarterly update",
+  "content": "The company reported current quarter revenue and guidance.",
+  "source": "https://investors.example.com/q2-update",
+  "source_type": "finance",
+  "published_at": "2026-06-09T07:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.83
+}
+```
+
+Social pulse:
+
+```json
+{
+  "title": "Developer discussion",
+  "content": "Developers are discussing setup friction and recent adoption.",
+  "source": "https://news.ycombinator.com/item?id=123456",
+  "source_type": "hackernews",
+  "published_at": "2026-06-09T11:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.71
+}
+```
+
+### Invalid Or Risky Candidate Signals
+
+Missing date:
+
+```json
+{
+  "title": "Relevant source with no date",
+  "content": "Useful candidate context, but no publication timestamp is available.",
+  "source": "https://example.com/no-date",
+  "source_type": "official_docs",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.78
+}
+```
+
+Invalid timestamp:
+
+```json
+{
+  "title": "Invalid date source",
+  "content": "Candidate context with malformed date metadata.",
+  "source": "https://example.com/bad-date",
+  "source_type": "official_docs",
+  "published_at": "not-a-date",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.78
+}
+```
+
+Meaningfully future-dated timestamp:
+
+```json
+{
+  "title": "Future-dated source",
+  "content": "Candidate context whose publication timestamp is after retrieval time.",
+  "source": "https://example.com/future-date",
+  "source_type": "official_docs",
+  "published_at": "2026-06-09T12:06:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.78
+}
+```
+
+Failed/error-looking content:
+
+```json
+{
+  "title": "Blocked source",
+  "content": "[Error] upstream timeout",
+  "source": "https://example.com/blocked",
+  "source_type": "official_docs",
+  "published_at": "2026-06-09T10:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 0.91
+}
+```
+
+Out-of-range semantic score:
+
+```json
+{
+  "title": "Overscored source",
+  "content": "Candidate context with an out-of-range relevance score.",
+  "source": "https://example.com/overscored",
+  "source_type": "official_docs",
+  "published_at": "2026-06-09T10:00:00.000Z",
+  "retrieved_at": "2026-06-09T12:00:00.000Z",
+  "semantic_score": 1.7
+}
+```
 
 ## Relationship to Existing Core Types
 
@@ -84,6 +270,16 @@ The signal contract does not replace existing Core types:
 
 The contract gives these surfaces a shared signal vocabulary without requiring Store, Worker, or MCP schema changes.
 
-## Boundary
-
-Signal Contract v1 does not determine truth, certify data, or provide legal, medical, tax, or financial advice. It provides normalized context metadata for freshness, provenance, relevance, and workflow review.
+## Boundary
+
+Signal Contract v1 does not determine truth, certify data, or provide legal, medical, tax, or financial advice. It provides normalized context metadata for freshness, provenance, relevance, and workflow review.
+
+## Future Metadata Boundary
+
+Future context signals, control signals, ingestion quality signals, structure preservation signals, and provenance confidence signals may later improve decisions such as `cite_as_primary`, `needs_refresh`, `needs_verification`, or `exclude`.
+
+Those are roadmap metadata layers. They should remain optional until tests prove they improve decisions. The public input contract should stay boring and stable:
+
+```text
+title + content + source + source_type + published_at + retrieved_at + semantic_score
+```

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
 
 const SOURCE_CHECKOUT_MESSAGE = [
   "This npm script is for the FreshContext source checkout.",
@@ -39,13 +40,19 @@ const commands = {
     command: "tsx",
     args: ["examples/evaluate-with-source-profile.ts"],
   },
-  "demo:evaluate:file": {
-    required: ["examples/evaluate-file.ts", "examples/sources.academic.example.json"],
-    command: "tsx",
-    args: ["examples/evaluate-file.ts", "examples/sources.academic.example.json"],
-    passThroughArgs: true,
-  },
-  "smoke:stdio": {
+  "demo:evaluate:file": {
+    required: ["examples/evaluate-file.ts", "examples/sources.academic.example.json"],
+    command: "tsx",
+    args: ["examples/evaluate-file.ts", "examples/sources.academic.example.json"],
+    passThroughArgs: true,
+  },
+  "batch:validate": {
+    required: ["examples/validate-signal-batch.ts"],
+    command: "tsx",
+    args: ["examples/validate-signal-batch.ts"],
+    passThroughArgs: true,
+  },
+  "smoke:stdio": {
     required: ["scripts/smoke-stdio.mjs"],
     command: "node",
     args: ["scripts/smoke-stdio.mjs"],
@@ -91,16 +98,23 @@ const commands = {
       "tests/freshnessStamp.test.ts",
       "tests/hackernews.test.ts",
       "tests/arxivSignals.test.ts",
-      "tests/arxivDecisionIntegration.test.ts",
-      "tests/core.test.ts",
-      "tests/rank.test.ts",
-      "tests/workerEnvelope.test.ts",
-      "tests/workerCoreEnvelopeParity.test.ts",
+      "tests/arxivDecisionIntegration.test.ts",
+      "tests/core.test.ts",
+      "tests/haPriV2GoldenVectors.test.ts",
+      "tests/signalContractExamples.test.ts",
+      "tests/batchValidationHarness.test.ts",
+      "tests/rank.test.ts",
+      "tests/workerEnvelope.test.ts",
+      "tests/packageScriptGuard.test.mjs",
+      "tests/adapterNetworkBoundary.test.ts",
+      "tests/workerRouteSecurity.test.ts",
+      "tests/workerCoreEnvelopeParity.test.ts",
       "tests/coreEnvelopeOptions.test.ts",
       "tests/mathSpine.test.ts",
       "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",
@@ -117,20 +131,54 @@ if (!config) {
   process.exit(1);
 }
 
-const hasSourceCheckoutFiles = config.required.every((path) => existsSync(path));
-if (!hasSourceCheckoutFiles) {
-  console.log(SOURCE_CHECKOUT_MESSAGE);
-  process.exit(0);
-}
-
-const args = [
-  ...config.args,
-  ...(config.passThroughArgs ? process.argv.slice(3) : []),
-];
-const child = spawnSync(config.command, args, {
-  stdio: "inherit",
-  shell: process.platform === "win32",
-});
+const hasSourceCheckoutFiles = config.required.every((path) => existsSync(path));
+if (!hasSourceCheckoutFiles) {
+  console.log(SOURCE_CHECKOUT_MESSAGE);
+  process.exit(0);
+}
+
+function resolveCommand(command, args) {
+  if (command === "node") return { command: process.execPath, args };
+
+  const localNodeEntrypoints = {
+    tsx: join("node_modules", "tsx", "dist", "cli.mjs"),
+    tsc: join("node_modules", "typescript", "bin", "tsc"),
+  };
+  const nodeEntrypoint = localNodeEntrypoints[command];
+  if (nodeEntrypoint && existsSync(nodeEntrypoint)) {
+    return { command: process.execPath, args: [nodeEntrypoint, ...args] };
+  }
+
+  const localBin = process.platform === "win32"
+    ? join("node_modules", ".bin", `${command}.cmd`)
+    : join("node_modules", ".bin", command);
+
+  if (existsSync(localBin)) return { command: localBin, args };
+  if (process.platform === "win32" && !command.endsWith(".cmd")) {
+    return { command: `${command}.cmd`, args };
+  }
+  return { command, args };
+}
+
+function validatePassThroughArgs(args) {
+  for (const arg of args) {
+    if (arg.includes("\0")) {
+      console.error("FreshContext package script arguments cannot contain null bytes.");
+      process.exit(1);
+    }
+  }
+  return args;
+}
+
+const args = [
+  ...config.args,
+  ...(config.passThroughArgs ? validatePassThroughArgs(process.argv.slice(3)) : []),
+];
+const invocation = resolveCommand(config.command, args);
+const child = spawnSync(invocation.command, invocation.args, {
+  stdio: "inherit",
+  shell: false,
+});
 
 if (child.error) {
   console.error(child.error.message);

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.20",
+  "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"
@@ -35,12 +36,17 @@
     ".env.example",
     "dist/",
     "!dist/apify.js",
+    "FRESHCONTEXT_SPEC.md",
+    "METHODOLOGY.md",
     "docs/API_DESIGN.md",
+    "docs/CLIENT_SETUP.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/HA_PRI_V2_PRODUCTION_ENFORCEMENT_PLAN.md",
     "docs/RELEASE_INTEGRITY.md",
     "docs/RELEASE_NOTES.md",
     "docs/SIGNAL_CONTRACT.md",
@@ -61,6 +67,7 @@
     "demo:arxiv": "node package-script-guard.mjs demo:arxiv",
     "demo:evaluate": "node package-script-guard.mjs demo:evaluate",
     "demo:evaluate:file": "node package-script-guard.mjs demo:evaluate:file",
+    "batch:validate": "node package-script-guard.mjs batch:validate",
     "smoke:stdio": "node package-script-guard.mjs smoke:stdio",
     "trust:gate": "node package-script-guard.mjs trust:gate",
     "trust:report": "node package-script-guard.mjs trust:report",

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.20",
   "website_url": "https://freshcontext-site.pages.dev",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "freshcontext-mcp",
-      "version": "0.3.18",
+      "version": "0.3.20",
       "transport": {
         "type": "stdio"
       }