freshcontext-mcp 0.3.19 → 0.3.20

package/dist/tools/evaluateContext.js

@@ -8,6 +8,10 @@ const SUPPORTED_INTENTS = [
     "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);
@@ -20,6 +24,12 @@ function isRecord(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.`);
@@ -27,6 +37,9 @@ function validateSignal(value, index) {
     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.`);
@@ -52,6 +65,12 @@ export function evaluateContextInput(input) {
     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);

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

@@ -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
 
@@ -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

package/docs/CORE_API.md

@@ -76,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:
 
@@ -90,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
 

package/docs/FUTURE_LANES.md

@@ -6,15 +6,16 @@ FreshContext is live today as an integrated MCP/Core package. Future work should
 
 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
+## Current Live Boundary
+
+Live today:
+
+- npm package: `freshcontext-mcp@0.3.19`
+- MCP stdio server
+- `evaluate_context` MCP tool for caller-provided candidate context
+- Signal Contract v1 as the stable candidate-context input shape
+- 21 read-only reference adapters
+- Core signal evaluation
 - Source Profiles
 - Decision Helper
 - adapter registry metadata
@@ -29,12 +30,32 @@ Not live today:
 - 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:
+- standalone Core SDK package
+- full adapter ingestion
+
+## Phase 0: Stabilize The Signal Contract
+
+Goal:
+
+```text
+Treat Signal Contract v1 as the stable input boundary for FreshContext.
+```
+
+Current contract:
+
+```text
+title + content + source + source_type + published_at + retrieved_at + semantic_score
+```
+
+This is live today. It is not the same thing as future context signals or control signals.
+
+Tasks in this lane should document examples, invalid-input behavior, and normalization expectations. Do not expand required fields unless tests prove the new metadata improves decisions.
+
+Future context signals, control signals, ingestion quality signals, structure preservation signals, and provenance confidence signals belong to later Decision Layer upgrades. They should remain optional metadata, not public required fields.
+
+## Lane 1: Client Setup Reliability
+
+Goal:
 
 ```text
 Make Claude, Codex, and MCP-compatible clients connect reliably to the published package.
@@ -113,15 +134,17 @@ Hard boundary:
 Consent-first design. No automatic folder scanning or background file reading.
 ```
 
-## Lane 6: Decision Layer Upgrade
-
-Goal:
+## 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.
+Possible inputs include context utility, control signal, future context signal, ingestion quality, structure preservation, provenance confidence, confidence tiers, and source-profile-specific thresholds.
+
+These are optional future metadata upgrades on top of Signal Contract v1. They should only be exposed when they make decisions clearer without making the caller-facing contract harder to use.
 
 Do not make `utility.score` affect ranking by default without a dedicated ranking policy pass.
 

package/docs/HA_PRI_V2_DESIGN.md

@@ -10,7 +10,13 @@ Ha-Pri v2 is an additive provenance-hardening model for FreshContext Store/Ledge
 
 The goal is to keep Ha-Pri v1 readable while designing a stronger future signature that binds a row to canonical content, semantic identity, source metadata, timestamps, and engine version.
 
-Phase 3-B adds pure Core helper functions and deterministic tests for the v2 model. Phase 3-C adds `examples/ha-pri-v2-example.ts`, a deterministic developer fixture showing `calculateHaPriV2` and `verifyHaPriV2` returning valid, invalid, and unknown verification states. Production Store wiring remains future work. This document does not change the D1 schema, change Worker write paths, migrate old rows, add HMAC secrets, or alter production scoring.
+Phase 3-B adds pure Core helper functions and deterministic tests for the v2 model. Phase 3-C adds `examples/ha-pri-v2-example.ts`, a deterministic developer fixture showing `calculateHaPriV2` and `verifyHaPriV2` returning valid, invalid, and unknown verification states. Production Store wiring remains future work. This document does not change the D1 schema, change Worker write paths, migrate old rows, add HMAC secrets, or alter production scoring.
+
+Pass 11-J adds golden test vectors for the pure Core helpers. Ha-Pri v2 golden vectors prove deterministic Core provenance behavior: canonicalization, SHA-256 hashes, signing payload construction, signature generation, and verification status are stable and repeatable. They do not mean Ha-Pri v2 is production-enforced on Worker/D1 reads.
+
+Plain SHA-256 provides deterministic integrity and audit checks. HMAC or private-key signing would be needed later for stronger origin-authentication guarantees.
+
+Pass 11-K adds a design-only production enforcement plan in `docs/HA_PRI_V2_PRODUCTION_ENFORCEMENT_PLAN.md`. That plan covers the future D1/storage, write-path, read/debug verification, compatibility, backfill, threat model, and rollout path. It does not implement Worker/D1 enforcement.
 
 ## Current Ha-Pri v1 Audit