freshcontext-mcp 0.3.14 → 0.3.16

package/freshcontext.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://freshcontext-site.pages.dev/freshcontext.schema.json",
+  "title": "FreshContext",
+  "description": "The FreshContext Specification v1.1 — structured envelope for AI-retrieved web data. https://github.com/PrinceGabriel-lgtm/freshcontext-mcp",
+  "type": "object",
+  "required": ["freshcontext"],
+  "properties": {
+    "freshcontext": {
+      "type": "object",
+      "description": "The freshness metadata envelope for a single retrieved result.",
+      "required": ["source_url", "retrieved_at", "freshness_confidence", "adapter"],
+      "properties": {
+        "source_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The canonical URL of the original source from which content was retrieved."
+        },
+        "content_date": {
+          "type": ["string", "null"],
+          "description": "Best estimate of when the content was originally published. ISO 8601 date (YYYY-MM-DD) or ISO 8601 datetime. Null if unknown.",
+          "examples": ["2026-03-05", "2026-03-05T09:19:00.000Z", null]
+        },
+        "retrieved_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Exact ISO 8601 datetime (with timezone) when this data was fetched.",
+          "examples": ["2026-04-05T09:19:00.000Z"]
+        },
+        "freshness_confidence": {
+          "type": "string",
+          "enum": ["high", "medium", "low"],
+          "description": "Confidence level of the content_date estimate. 'high' = structured API field. 'medium' = inferred from page signals. 'low' = unknown or estimated."
+        },
+        "freshness_score": {
+          "type": ["number", "null"],
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Optional numeric freshness score 0-100. Calculated as: max(0, 100 - (days_since_retrieved * decay_rate)). Null if content_date is unknown.",
+          "examples": [94, 72, 45, null]
+        },
+        "adapter": {
+          "type": "string",
+          "description": "Identifier of the adapter (data source) that produced this result.",
+          "examples": [
+            "github",
+            "hackernews",
+            "google_scholar",
+            "arxiv",
+            "reddit",
+            "ycombinator",
+            "producthunt",
+            "github_search",
+            "package_registry",
+            "finance",
+            "jobs",
+            "changelog",
+            "govcontracts",
+            "sec_filings",
+            "gdelt",
+            "gebiz"
+          ]
+        },
+        "decay_rate": {
+          "type": ["number", "null"],
+          "description": "The decay rate used to calculate freshness_score. Domain-specific. Financial=5.0, jobs=3.0, news=2.0, github=1.0, academic=0.3, default=1.5.",
+          "examples": [5.0, 3.0, 2.0, 1.5, 1.0, 0.3, null]
+        }
+      },
+      "additionalProperties": false
+    },
+    "content": {
+      "type": "string",
+      "description": "The retrieved content — raw text, structured data, or formatted output from the adapter."
+    }
+  },
+  "examples": [
+    {
+      "freshcontext": {
+        "source_url": "https://github.com/PrinceGabriel-lgtm/freshcontext-mcp",
+        "content_date": "2026-04-05",
+        "retrieved_at": "2026-04-05T09:19:00.000Z",
+        "freshness_confidence": "high",
+        "freshness_score": 94,
+        "adapter": "github",
+        "decay_rate": 1.0
+      },
+      "content": "freshcontext-mcp — Real-time web intelligence for AI agents..."
+    },
+    {
+      "freshcontext": {
+        "source_url": "https://efts.sec.gov/LATEST/search-index?q=Palantir&forms=8-K",
+        "content_date": "2026-02-03",
+        "retrieved_at": "2026-04-05T09:19:00.000Z",
+        "freshness_confidence": "high",
+        "freshness_score": 38,
+        "adapter": "sec_filings",
+        "decay_rate": 1.5
+      },
+      "content": "Palantir Technologies — 8-K filing: Q4 2025 earnings..."
+    }
+  ]
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "freshcontext-mcp",
   "mcpName": "io.github.PrinceGabriel-lgtm/freshcontext",
-  "version": "0.3.14",
-  "description": "Real-time web extraction MCP server with freshness timestamps for AI agents",
+  "version": "0.3.16",
+  "description": "Real-time web intelligence for AI agents. 20 tools, no API keys. Every result timestamped with a freshness score.",
   "keywords": [
     "mcp",
     "mcp-server",

package/server.json

@@ -1,19 +1,19 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
   "name": "io.github.PrinceGabriel-lgtm/freshcontext",
-  "description": "Real-time web intelligence for AI agents. 15 tools, no API keys. GitHub, HN, Reddit, arXiv, govcontracts, changelog, gov landscape & finance landscape — every result timestamped with a freshness score.",
+  "description": "Real-time web intelligence for AI agents. 20 tools, no API keys. GitHub, HN, Reddit, arXiv, SEC filings, US gov contracts, GDELT global news, Singapore GeBIZ, changelog & more — every result timestamped with a freshness score.",
   "repository": {
     "url": "https://github.com/PrinceGabriel-lgtm/freshcontext-mcp",
     "source": "github"
   },
-  "version": "0.3.11",
+  "version": "0.3.15",
   "website_url": "https://freshcontext-site.pages.dev",
   "packages": [
     {
       "registry_type": "npm",
       "registry_base_url": "https://registry.npmjs.org",
       "identifier": "freshcontext-mcp",
-      "version": "0.3.11",
+      "version": "0.3.15",
       "transport": {
         "type": "stdio"
       }

package/time-check.ps1

@@ -0,0 +1,46 @@
+# time-check.ps1 — Print a session header for Claude conversations
+# Usage: ./time-check.ps1
+# Then paste the output at the start of your message to Claude.
+
+$now = Get-Date
+$utc = $now.ToUniversalTime()
+$dayOfWeek = $now.DayOfWeek
+$weekNumber = (Get-Culture).Calendar.GetWeekOfYear($now, [System.Globalization.CalendarWeekRule]::FirstFourDayWeek, [DayOfWeek]::Monday)
+
+# Sun position approximation for Grootfontein (-19.57°, 18.12°)
+# Simple model: sunrise ~6:00, sunset ~18:30 (varies seasonally, close enough for vibes)
+$hour = $now.Hour
+$timeOfDay = switch ($hour) {
+    {$_ -lt 5}  { "deep night" }
+    {$_ -lt 7}  { "before dawn" }
+    {$_ -lt 9}  { "early morning" }
+    {$_ -lt 12} { "morning" }
+    {$_ -lt 14} { "midday" }
+    {$_ -lt 17} { "afternoon" }
+    {$_ -lt 19} { "early evening" }
+    {$_ -lt 22} { "evening" }
+    default     { "late night" }
+}
+
+# US East Coast equivalent (CAT is UTC+2, ET is UTC-4 or UTC-5 depending on DST)
+# Simple approximation: CAT - 6h ≈ ET in summer, CAT - 7h ≈ ET in winter
+$etHour = ($hour - 6 + 24) % 24
+$etTime = "{0:D2}:{1:D2} ET" -f $etHour, $now.Minute
+
+# Output
+Write-Host ""
+Write-Host "═══════════════════════════════════════════" -ForegroundColor Cyan
+Write-Host "  Session header for Claude (paste this in)" -ForegroundColor Cyan
+Write-Host "═══════════════════════════════════════════" -ForegroundColor Cyan
+Write-Host ""
+Write-Host "Local time: $($now.ToString('yyyy-MM-dd HH:mm')) CAT ($timeOfDay), $dayOfWeek" -ForegroundColor Green
+Write-Host "UTC:        $($utc.ToString('yyyy-MM-dd HH:mm')) UTC" -ForegroundColor Gray
+Write-Host "ET (US):    ~$etTime" -ForegroundColor Gray
+Write-Host "Week:       Week $weekNumber of $($now.Year)" -ForegroundColor Gray
+Write-Host ""
+
+# Also copy to clipboard so you don't have to retype it
+$header = "[$($now.ToString('yyyy-MM-dd HH:mm')) CAT, $dayOfWeek $timeOfDay]"
+$header | Set-Clipboard
+Write-Host "→ Copied to clipboard:  $header" -ForegroundColor Yellow
+Write-Host ""

package/.actor/Dockerfile

@@ -1,16 +0,0 @@
-FROM apify/actor-node-playwright-chrome:20
-
-# Copy package files first for better Docker layer caching
-COPY package*.json ./
-
-# Install dependencies — Playwright and Chromium already in base image
-RUN npm install --include=dev
-
-# Copy source and pre-built dist
-COPY . ./
-
-# Rebuild TypeScript
-RUN npm run build || echo "Build had warnings, using pre-compiled dist/"
-
-# Run the Actor entry point
-CMD ["node", "dist/apify.js"]

package/.actor/actor.json

@@ -1,9 +0,0 @@
-{
-  "actorSpecification": 1,
-  "name": "freshcontext-mcp",
-  "title": "FreshContext MCP",
-  "version": "0.3.1",
-  "input": "../input_schema.json",
-  "output": "./output_schema.json",
-  "dockerfile": "./Dockerfile"
-}

package/.actor/output_schema.json

@@ -1,13 +0,0 @@
-{
-  "actorOutputSchemaVersion": 1,
-  "title": "FreshContext MCP Output",
-  "description": "Timestamped web intelligence results wrapped in FreshContext envelopes.",
-  "properties": {
-    "results": {
-      "type": "string",
-      "title": "Results",
-      "description": "FreshContext envelopes with content, source URL, retrieval timestamp, and freshness confidence.",
-      "template": "{{links.apiDefaultDatasetUrl}}/items"
-    }
-  }
-}

package/ARCHITECTURE_UPGRADE_CHECKLIST.md

@@ -1,88 +0,0 @@
-# FreshContext — Architecture Upgrade Checklist
-**Date started:** 2026-03-19
-**Author:** Prince Gabriel, Grootfontein, Namibia
-
----
-
-## [ ] Upgrade 1 — freshness_score numeric field
-Implement the 0-100 numeric score defined in FRESHCONTEXT_SPEC.md.
-Formula: max(0, 100 - (days_since_retrieved * decay_rate))
-Location: src/tools/freshnessStamp.ts
-Decay rates by adapter: finance=5.0, jobs=3.0, hackernews=2.0, github=1.0, scholar=0.3, default=1.5
-Adds the score to both the text envelope and the JSON form.
-Makes FreshContext fully spec-compliant by your own standard.
-Cost: zero.
-
----
-
-## [x] Upgrade 2 — Cloudflare KV response caching  ← DONE (already implemented in worker.ts)
-Cache adapter results in KV with adapter-specific TTLs so the same query
-hitting the Worker twice doesn't make two upstream API calls.
-Cache key: sha256(tool + ":" + url)
-TTLs: HN/Reddit = 1 hour, GitHub/YC = 6 hours, govcontracts/scholar = 24 hours
-Location: worker/src/index.ts
-Cost: zero. KV free tier is 100k reads/day, 1k writes/day.
-
----
-
-## [x] Upgrade 3 — Apify Actor timeout increase  ← DONE 2026-03-19
-Change the Actor timeout from 300 seconds to 3600 seconds in the Apify UI.
-Apify console → Actor → Settings → Timeout → 3600
-Playwright-based tools (extract_reddit, extract_yc, extract_producthunt) need
-more than 5 minutes to launch Chromium and scrape. They will keep timing out
-until this is changed. This is a UI field change, not a code change.
-Cost: zero.
-
----
-
-## [x] Upgrade 4 — D1 deduplication in the cron job  ← DONE (hash-based dedup already in runScheduledScrape)
-Before inserting a new scrape result, check if the same source_url was already
-stored in the last 24 hours. If yes, skip the insert.
-Prevents the scrape_results table from filling with duplicate data across
-consecutive cron runs, keeping the historical dataset clean for the intelligence
-layer (Layer 7 in the roadmap).
-Location: the cron job handler in the Worker code.
-Cost: zero.
-
----
-
-## [x] Upgrade 5 — Structured JSON response form  ← DONE 2026-03-19
-Add the optional JSON form defined in FRESHCONTEXT_SPEC.md alongside the text
-envelope in every adapter response. The JSON form has: source_url, content_date,
-retrieved_at, freshness_confidence, adapter, freshness_score.
-When a request has Accept: application/json, serve the structured form.
-Both forms can be returned together — text for agents, JSON for programmatic use.
-Location: src/tools/freshnessStamp.ts (same file as Upgrade 1, do together)
-Cost: zero.
-
----
-
-## [x] Upgrade 6 — GitHub Actions CI/CD automation  ← DONE 2026-03-19
-.github/workflows/publish.yml created. Triggers on every push to main.
-Runs npm ci → npm run build → npm publish using NPM_TOKEN secret.
-continue-on-error on publish so doc-only pushes don't fail the workflow.
-First run: green checkmark, 23 seconds.
-Manual PowerShell build/publish commands no longer needed.
-
----
-
-## [x] Upgrade 7 — server.json version sync  ← DONE 2026-03-19
-server.json (MCP Registry listing) shows version 0.3.1 while package.json
-is at 0.3.10. Anyone discovering FreshContext via the MCP Registry sees an
-outdated version number. Fix by updating server.json manually now, then
-optionally add a workflow step that syncs the version automatically on each
-GitHub Actions run.
-Location: server.json — change "version" field to match package.json.
-Cost: zero.
-
----
-
-## Priority order for remaining six upgrades
-
-Do Upgrade 3 first — it is one UI field change and immediately fixes the
-broken Apify Actor runs. Do Upgrades 1 and 5 together second since they
-both touch freshnessStamp.ts and completing them makes FreshContext fully
-spec-compliant. Do Upgrade 2 third — KV caching makes the Worker resilient
-against upstream API instability. Do Upgrade 4 fourth — D1 deduplication
-prepares the dataset for the future intelligence layer. Do Upgrade 7 last —
-a simple version number correction, low urgency but worth keeping clean.

package/ARCHITECTURE_UPGRADE_ROADMAP_V1.md

@@ -1,174 +0,0 @@
-# FreshContext — Architecture Upgrade Roadmap V1
-**Date:** 2026-03-19
-**Author:** Immanuel Gabriel (Prince Gabriel), Grootfontein, Namibia
-
-This document describes every free structural upgrade available to FreshContext,
-prioritised by impact, with implementation notes for each.
-
----
-
-## Upgrade 1 — freshness_score numeric field (HIGHEST PRIORITY)
-
-**What it is:** The FreshContext Specification v1.0 defines an optional freshness_score
-field (0-100) calculated as: max(0, 100 - (days_since_retrieved * decay_rate)).
-Right now every response carries the text envelope and the confidence level (high/medium/low)
-but not the numeric score. This is the one remaining piece that makes FreshContext fully
-spec-compliant by your own standard.
-
-**Why it matters:** Once the score exists, agents can filter results programmatically —
-"only use results with freshness_score > 70" rather than parsing the string confidence
-level. This is the difference between a label and a query parameter. It also strengthens
-the acquisition narrative: the spec is complete, the reference implementation is complete,
-and the standard is fully self-consistent.
-
-**Domain-specific decay rates from the spec:**
-Financial data decays at 5.0 (half-life ~10 days). Job listings at 3.0 (~17 days).
-News and HN at 2.0 (~25 days). GitHub repos at 1.0 (~50 days). Academic papers at 0.3
-(~167 days). General web content defaults to 1.5.
-
-**Where to implement:** In src/tools/freshnessStamp.ts — the function that wraps every
-adapter result already has retrieved_at and content_date. Add a calculateFreshnessScore
-function that takes content_date, decay_rate (looked up by adapter name), and returns
-the numeric score. Add it to both the text envelope and the JSON form.
-
-**Cost:** Zero. Pure TypeScript logic, no new services.
-
----
-
-## Upgrade 2 — Cloudflare KV response caching
-
-**What it is:** When the same query hits an adapter twice within a short window, the
-Worker currently makes two full upstream API calls. KV caching stores the first result
-with a TTL and serves subsequent identical requests from cache — meaning the upstream
-API (USASpending, GitHub, HN, etc.) only gets called once per cache window.
-
-**Why it matters:** This reduces the chance of hitting upstream rate limits, makes
-repeated queries near-instant for users, and reduces Worker CPU time. For adapters like
-extract_govcontracts that call a government API, caching also reduces the risk of
-temporary blocks from aggressive polling.
-
-**Implementation:** In the Worker code (worker/src/index.ts or equivalent), before calling
-the adapter, compute a cache key as sha256(tool + ":" + url). Call env.KV.get(cacheKey).
-If the result exists, return it immediately. If not, run the adapter, then call
-env.KV.put(cacheKey, result, { expirationTtl: ttl }) before returning. Use adapter-specific
-TTLs — 3600 seconds (1 hour) for HN and Reddit, 21600 (6 hours) for GitHub and YC,
-86400 (24 hours) for govcontracts and scholar.
-
-**Cost:** Zero. KV reads are free up to 100,000 per day, writes free up to 1,000 per day
-on Cloudflare's free tier. You are nowhere near those limits.
-
----
-
-## Upgrade 3 — Apify Actor timeout increase
-
-**What it is:** The Apify Actor timeout is currently set to 300 seconds (5 minutes). Tools
-that use Playwright to launch a browser — extract_reddit, extract_yc, extract_producthunt —
-need more time than this to launch Chromium, navigate, wait for the page to render, and
-extract content. They will keep timing out until this setting is increased.
-
-**Where to change it:** Apify console → your Actor → Settings → Timeout. Change from
-300 to 3600 (1 hour). This is a UI change, not a code change.
-
-**Cost:** Zero. The timeout setting is just a number. You won't actually use anywhere
-near 3600 seconds — most tools complete in 10-30 seconds. The setting just prevents Apify
-from killing the process prematurely for the slower Playwright-based tools.
-
----
-
-## Upgrade 4 — D1 deduplication in the cron job
-
-**What it is:** Every 6 hours the cron job runs all 18 watched queries and stores results
-in the scrape_results D1 table. Right now there is no deduplication — if the same article
-or repo appears in two consecutive cron runs, it gets stored twice. Over time this creates
-noise in the dataset and wastes storage.
-
-**Implementation:** Before inserting a new result, run a SELECT to check whether a row
-with the same source_url already exists within the last 24 hours. If it does, skip the
-insert. This is a single SQL WHERE clause addition to the existing insert logic.
-
-**Why it matters:** As you build the intelligence layer (Layer 7 in the roadmap), the
-quality of the historical signal depends on clean, deduplicated data. Starting deduplication
-now means the dataset is clean by the time you need it.
-
-**Cost:** Zero. D1 reads are free up to 25 million rows per day. A deduplication check
-adds one read per result per cron run — trivially within limits.
-
----
-
-## Upgrade 5 — Structured JSON response form in every adapter
-
-**What it is:** The FreshContext Specification defines two valid response formats — the
-text envelope ([FRESHCONTEXT]...[/FRESHCONTEXT]) and an optional structured JSON form with
-a freshcontext object containing source_url, content_date, retrieved_at,
-freshness_confidence, adapter, and freshness_score fields. Right now only the text envelope
-is returned. Adding the JSON form makes FreshContext usable programmatically without
-parsing the text envelope.
-
-**Implementation:** In src/tools/freshnessStamp.ts, after assembling the text envelope,
-also return a structured object. When the Worker serves a response, detect whether the
-request has Accept: application/json and serve the structured form instead of the text
-form if so. Both formats can also be returned together — text for human/agent reading,
-JSON for programmatic use.
-
-**Cost:** Zero. This is a response format change, no new services.
-
----
-
-## Upgrade 6 — GitHub Actions: version bump automation
-
-**What it is:** The current GitHub Actions workflow (publish.yml) runs npm publish on every
-push, but only succeeds if the version in package.json has changed. Right now you manually
-bump the version before pushing. A small addition to the workflow can automate this by
-running npm version patch automatically before the publish step — so every push to main
-creates a new patch version and publishes it without any manual intervention.
-
-**Tradeoff:** This means every push creates a new npm version, which may not always be
-desirable for documentation-only changes. A better approach is to only auto-bump when
-commits touch src/ or .actor/ — which can be detected in the workflow with a path filter.
-
-**Implementation:** Add a paths filter to the workflow trigger so it only runs the publish
-step when source files change. Then add an npm version patch --no-git-tag-version step
-before the publish step. Push the bumped package.json back to the repo using a
-git commit and git push within the workflow (requires GITHUB_TOKEN, which is automatically
-available in all Actions workflows at no cost).
-
-**Cost:** Zero.
-
----
-
-## Upgrade 7 — server.json version sync check
-
-**What it is:** The server.json file (used by the MCP Registry listing) still shows version
-0.3.1 while package.json is at 0.3.10. This discrepancy means anyone who discovers
-FreshContext via the MCP Registry sees an outdated version number. It is a cosmetic issue
-but it affects credibility in a space where people are evaluating tools carefully.
-
-**Implementation:** Add a step to the GitHub Actions workflow that reads the version from
-package.json and uses sed or node -e to update the version field in server.json to match
-before committing. Alternatively, update server.json manually now and keep it in sync
-going forward.
-
-**Cost:** Zero.
-
----
-
-## Priority Order for Implementation
-
-The order that maximises impact relative to effort is as follows. Implement the Apify
-timeout increase first because it is a one-field UI change that immediately fixes the
-broken Actor runs. Implement KV caching second because it makes the Worker more robust
-against upstream API instability and improves response times for repeat queries. Implement
-the freshness_score calculation third because it completes the spec and strengthens every
-conversation about acquisition or partnership. Implement D1 deduplication fourth because
-it improves data quality for the intelligence layer you will eventually build. Implement
-the structured JSON response form fifth as part of the same PR as freshness_score since
-they touch the same file. Implement the GitHub Actions version sync last as a quality-of-life
-automation.
-
-The total engineering cost of all six remaining upgrades is approximately 4-6 hours of
-focused work. All run entirely within free tiers.
-
----
-
-*"The work isn't gone. It's just waiting to be continued."*
-*— Prince Gabriel, Grootfontein, Namibia*

package/FRESHCONTEXT_SPEC.md

@@ -1,178 +0,0 @@
-# The FreshContext Specification
-**Version 1.0 — March 2026**
-*Authored by Immanuel Gabriel (Prince Gabriel) — Grootfontein, Namibia*
-
----
-
-## What This Is
-
-The FreshContext Specification defines a standard envelope format for AI-retrieved web data.
-
-It exists to solve one problem: **AI models present stale data with the same confidence as fresh data, and users have no way to tell the difference.**
-
-FreshContext fixes this by wrapping every piece of retrieved content in a structured envelope that carries three guarantees:
-
-1. **When** the data was retrieved (exact ISO 8601 timestamp)
-2. **Where** it came from (canonical source URL)
-3. **How confident** we are that the content date is accurate (freshness confidence)
-
-Any tool, agent, or system that implements this spec is **FreshContext-compatible**.
-
----
-
-## The Envelope Format
-
-Every FreshContext-compatible response MUST wrap its content in the following envelope:
-
-```
-[FRESHCONTEXT]
-Source: <canonical_url>
-Published: <content_date_or_"unknown">
-Retrieved: <iso8601_timestamp>
-Confidence: <high|medium|low>
----
-<content>
-[/FRESHCONTEXT]
-```
-
-### Field Definitions
-
-| Field | Required | Format | Description |
-|---|---|---|---|
-| `Source` | Yes | Valid URL | The canonical URL of the original source |
-| `Published` | Yes | ISO 8601 date or `"unknown"` | Best estimate of when the content was originally published |
-| `Retrieved` | Yes | ISO 8601 datetime with timezone | Exact timestamp when this data was fetched |
-| `Confidence` | Yes | `high`, `medium`, or `low` | Confidence level of the `Published` date estimate |
-
----
-
-## Confidence Levels
-
-### `high`
-The publication date was sourced from a structured, machine-readable field — an API response, HTML metadata tag, RSS feed, or official timestamp. The date is reliable.
-
-*Examples: GitHub API `pushed_at`, arXiv submission date, Hacker News `created_at`*
-
-### `medium`
-The publication date was inferred from page signals — visible date strings, URL patterns, or content heuristics. Likely correct but not guaranteed.
-
-*Examples: Blog post date parsed from HTML, URL containing `/2025/03/`, footer copyright year*
-
-### `low`
-No reliable date signal was found. The date is an estimate based on indirect signals or is entirely unknown.
-
-*Examples: Static page with no date, scraped content with no metadata, cached result of unknown age*
-
----
-
-## Structured Form (JSON)
-
-Implementations MAY additionally expose freshness metadata as structured JSON alongside the text envelope:
-
-```json
-{
-  "freshcontext": {
-    "source_url": "https://github.com/owner/repo",
-    "content_date": "2026-03-05",
-    "retrieved_at": "2026-03-16T09:19:00.000Z",
-    "freshness_confidence": "high",
-    "adapter": "github",
-    "freshness_score": 94
-  },
-  "content": "..."
-}
-```
-
-### `freshness_score` (optional)
-
-A numeric representation of data freshness from 0–100, calculated as:
-
-```
-freshness_score = max(0, 100 - (days_since_retrieved × decay_rate))
-```
-
-Where `decay_rate` defaults to `1.5` for general web content. Implementations MAY use domain-specific decay rates (e.g., financial data decays faster than academic papers).
-
-| Score | Interpretation |
-|---|---|
-| 90–100 | Retrieved within hours — treat as current |
-| 70–89 | Retrieved within days — reliable for most uses |
-| 50–69 | Retrieved within weeks — verify before acting |
-| Below 50 | Retrieved more than a month ago — use with caution |
-
----
-
-## Adapter Contract
-
-Any data source that feeds into a FreshContext-compatible system is called an **adapter**. Adapters MUST:
-
-1. Return raw content plus a `content_date` (or `null` if unknown)
-2. Set a `freshness_confidence` level based on how the date was determined
-3. Never fabricate or forward-date content timestamps
-4. Clearly identify which source system produced the data via the `adapter` field
-
-Adapters SHOULD:
-
-- Prefer structured API sources over scraped content when both are available
-- Log retrieval errors without silently returning cached or stale data
-- Surface rate-limit or access-denied errors explicitly rather than returning empty content
-
----
-
-## Why This Matters for AI Agents
-
-Large language models have no internal clock. When an agent retrieves web data, it cannot distinguish between something published this morning and something published three years ago — unless that information is explicitly surfaced.
-
-Without FreshContext (or equivalent):
-- An agent recommending job listings may recommend roles that no longer exist
-- An agent summarising market trends may cite conditions from a previous cycle
-- An agent checking a competitor's pricing may act on outdated information
-
-With FreshContext:
-- Every piece of retrieved data carries its own timestamp
-- The agent can reason about data age before acting
-- Users can see exactly how fresh their AI's information is
-
----
-
-## Compatibility
-
-A tool, server, or API is **FreshContext-compatible** if:
-
-- Its responses include the `[FRESHCONTEXT]...[/FRESHCONTEXT]` envelope, OR
-- Its responses include the structured JSON form with `freshcontext.retrieved_at` and `freshcontext.freshness_confidence` fields
-
-Partial implementations that include only `retrieved_at` without `freshness_confidence` are considered **FreshContext-aware** but not fully compatible.
-
----
-
-## Reference Implementation
-
-The canonical reference implementation of this specification is:
-
-**freshcontext-mcp** — an MCP server with 11 adapters covering GitHub, Hacker News, Google Scholar, arXiv, Reddit, YC Companies, Product Hunt, npm/PyPI, financial markets, and a composite landscape tool.
-
-- npm: `freshcontext-mcp`
-- GitHub: https://github.com/PrinceGabriel-lgtm/freshcontext-mcp
-- Cloud endpoint: `https://freshcontext-mcp.gimmanuel73.workers.dev/mcp`
-
----
-
-## Versioning
-
-This document is version 1.0 of the FreshContext Specification.
-
-Future versions will be tagged in this repository. Breaking changes to the envelope format will increment the major version. Additive changes (new optional fields, new confidence levels) will increment the minor version.
-
----
-
-## License
-
-This specification is published under the MIT License.
-Implementations may be proprietary or open source.
-Attribution to the FreshContext Specification is appreciated but not required.
-
----
-
-*"The work isn't gone. It's just waiting to be continued."*
-*— Prince Gabriel, Grootfontein, Namibia*