freshcontext-mcp 0.3.10 → 0.3.11

package/.actor/Dockerfile

@@ -0,0 +1,14 @@
+FROM apify/actor-node:18
+
+# Copy package files first for better Docker layer caching
+COPY package*.json ./
+
+# Install all dependencies including apify SDK
+RUN npm install --include=dev
+
+# Copy source and build
+COPY . ./
+RUN npm run build
+
+# Tell Apify to run the Actor entry point, not the MCP server
+CMD ["node", "dist/apify.js"]

package/.actor/actor.json

@@ -4,5 +4,6 @@
   "title": "FreshContext MCP",
   "version": "0.3.1",
   "input": "../input_schema.json",
-  "output": "./output_schema.json"
+  "output": "./output_schema.json",
+  "dockerfile": "./Dockerfile"
 }

package/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Build and Publish
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js 18
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        continue-on-error: true

package/ARCHITECTURE_UPGRADE_CHECKLIST.md

@@ -0,0 +1,88 @@
+# 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

@@ -0,0 +1,174 @@
+# 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/README.md

@@ -1,212 +1,239 @@
-# freshcontext-mcp
-
-I asked Claude to help me find a job. It gave me a list of openings. I applied to three of them. Two didn't exist anymore. One had been closed for two years.
-
-Claude had no idea. It presented everything with the same confidence.
-
-That's the problem freshcontext fixes.
-
-[![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)
-
----
-
-## What it does
-
-Every MCP server returns data. freshcontext returns data **plus when it was retrieved and how confident that date is** — wrapped in a FreshContext envelope:
-
-```
-[FRESHCONTEXT]
-Source: https://github.com/owner/repo
-Published: 2024-11-03
-Retrieved: 2026-03-05T09:19:00Z
-Confidence: high
----
-... content ...
-[/FRESHCONTEXT]
-```
-
-Claude now knows the difference between something from this morning and something from two years ago. You do too.
-
----
-
-## 11 tools. No API keys.
-
-### Intelligence
-| Tool | What it gets you |
-|---|---|
-| `extract_github` | README, stars, forks, language, topics, last commit |
-| `extract_hackernews` | Top stories or search results with scores and timestamps |
-| `extract_scholar` | Research papers — titles, authors, years, snippets |
-| `extract_arxiv` | arXiv papers via official API — more reliable than Scholar |
-| `extract_reddit` | Posts and community sentiment from any subreddit |
-
-### Competitive research
-| Tool | What it gets you |
-|---|---|
-| `extract_yc` | YC company listings by keyword — who's funded in your space |
-| `extract_producthunt` | Recent launches by topic |
-| `search_repos` | GitHub repos ranked by stars with activity signals |
-| `package_trends` | npm and PyPI metadata — version history, release cadence |
-
-### Market data
-| Tool | What it gets you |
-|---|---|
-| `extract_finance` | Live stock data — price, market cap, P/E, 52w range |
-
-### Composite
-| Tool | What it gets you |
-|---|---|
-| `extract_landscape` | One call. YC + GitHub + HN + Reddit + Product Hunt + npm in parallel. Full timestamped picture. |
-
----
-
-## Quick Start
-
-### Option A — Cloud (no install)
-
-Add to your Claude Desktop config and restart:
-
-**Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "freshcontext": {
-      "command": "npx",
-      "args": ["-y", "mcp-remote", "https://freshcontext-mcp.gimmanuel73.workers.dev/mcp"]
-    }
-  }
-}
-```
-
-Restart Claude. Done.
-
-> Prefer a guided setup? Visit **[freshcontext-site.pages.dev](https://freshcontext-site.pages.dev)** — 3 steps, no terminal.
-
----
-
-### Option B — Local (full Playwright)
-
-**Requires:** Node.js 18+ ([nodejs.org](https://nodejs.org))
-
-```bash
-git clone https://github.com/PrinceGabriel-lgtm/freshcontext-mcp
-cd freshcontext-mcp
-npm install
-npx playwright install chromium
-npm run build
-```
-
-Add to Claude Desktop config:
-
-**Mac:**
-```json
-{
-  "mcpServers": {
-    "freshcontext": {
-      "command": "node",
-      "args": ["/Users/YOUR_USERNAME/path/to/freshcontext-mcp/dist/server.js"]
-    }
-  }
-}
-```
-
-**Windows:**
-```json
-{
-  "mcpServers": {
-    "freshcontext": {
-      "command": "node",
-      "args": ["C:\\Users\\YOUR_USERNAME\\path\\to\\freshcontext-mcp\\dist\\server.js"]
-    }
-  }
-}
-```
-
----
-
-### Troubleshooting (Mac)
-
-**"command not found: node"** — Use the full path:
-```bash
-which node  # copy this output, replace "node" in config
-```
-
-**Config file doesn't exist** — Create it:
-```bash
-mkdir -p ~/Library/Application\ Support/Claude
-touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
-```
-
----
-
-## Usage examples
-
-**Is anyone already building what you're building?**
-```
-Use extract_landscape with topic "cashflow prediction saas"
-```
-Returns who's funded, what's trending, what repos exist, what packages are moving — all timestamped.
-
-**What's the community actually saying right now?**
-```
-Use extract_reddit on r/MachineLearning
-Use extract_hackernews to search "mcp server 2026"
-```
-
-**Did that company actually ship recently?**
-```
-Use extract_github on https://github.com/some-org/some-repo
-```
-Check `Published` vs `Retrieved`. If the gap is 18 months, Claude will tell you.
-
----
-
-## How freshness works
-
-Most AI tools retrieve data silently. No timestamp, no signal, no way for the agent to know how old it is.
-
-freshcontext treats **retrieval time as first-class metadata**. Every adapter returns:
-
-- `retrieved_at` — exact ISO timestamp of the fetch
-- `content_date` — best estimate of when the content was originally published
-- `freshness_confidence` — `high`, `medium`, or `low` based on signal quality
-- `adapter` — which source the data came from
-
-When confidence is `high`, the date came from a structured field (API, metadata). When it's `medium` or `low`, freshcontext tells you why.
-
----
-
-## Security
-
-- Input sanitization and domain allowlists on all adapters
-- SSRF prevention (blocked private IP ranges)
-- KV-backed global rate limiting: 60 req/min per IP across all edge nodes
-- No credentials required — all public data sources
-
----
-
-## Roadmap
-
-- [x] GitHub, HN, Scholar, YC, Reddit, Product Hunt, Finance, arXiv adapters
-- [x] `extract_landscape` — 6-source composite tool
-- [x] Cloudflare Workers deployment
-- [x] KV-backed global rate limiting
-- [x] Listed on official MCP Registry
-- [ ] TTL-based caching layer
-- [ ] `freshness_score` numeric metric
-- [ ] Job search adapter (the tool that started all this)
-
----
-
-## Contributing
-
-PRs welcome. New adapters are the highest-value contribution — see `src/adapters/` for the pattern.
-
----
-
-## License
-
-MIT
+# freshcontext-mcp
+
+I asked Claude to help me find a job. It gave me a list of openings. I applied to three of them. Two didn't exist anymore. One had been closed for two years.
+
+Claude had no idea. It presented everything with the same confidence.
+
+That's the problem freshcontext fixes.
+
+[![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)
+
+---
+
+## What it does
+
+Every MCP server returns data. freshcontext returns data **plus when it was retrieved and how confident that date is** — wrapped in a FreshContext envelope:
+
+```
+[FRESHCONTEXT]
+Source: https://github.com/owner/repo
+Published: 2024-11-03
+Retrieved: 2026-03-05T09:19:00Z
+Confidence: high
+---
+... content ...
+[/FRESHCONTEXT]
+```
+
+Claude now knows the difference between something from this morning and something from two years ago. You do too.
+
+---
+
+## 13 tools. No API keys.
+
+### Intelligence
+| Tool | What it gets you |
+|---|---|
+| `extract_github` | README, stars, forks, language, topics, last commit |
+| `extract_hackernews` | Top stories or search results with scores and timestamps |
+| `extract_scholar` | Research papers — titles, authors, years, snippets |
+| `extract_arxiv` | arXiv papers via official API — more reliable than Scholar |
+| `extract_reddit` | Posts and community sentiment from any subreddit |
+
+### Competitive research
+| Tool | What it gets you |
+|---|---|
+| `extract_yc` | YC company listings by keyword — who's funded in your space |
+| `extract_producthunt` | Recent launches by topic |
+| `search_repos` | GitHub repos ranked by stars with activity signals |
+| `package_trends` | npm and PyPI metadata — version history, release cadence |
+
+### Market data
+| Tool | What it gets you |
+|---|---|
+| `extract_finance` | Live stock data — price, market cap, P/E, 52w range |
+
+### Composite
+| Tool | What it gets you |
+|---|---|
+| `extract_landscape` | One call. YC + GitHub + HN + Reddit + Product Hunt + npm in parallel. Full timestamped picture. |
+
+### Update intelligence — unique to FreshContext
+| Tool | What it gets you |
+|---|---|
+| `extract_changelog` | Update history from any GitHub repo, npm package, or website. Accepts a GitHub URL (uses the Releases API), an npm package name, or any website URL — auto-discovers `/changelog`, `/releases`, and `CHANGELOG.md`. Returns version numbers, release dates, and entry content, all timestamped. Use this to check if a dependency is still actively maintained, or to find out exactly when a feature shipped before referencing it. |
+
+### Government intelligence — unique to FreshContext
+| Tool | What it gets you |
+|---|---|
+| `extract_govcontracts` | US federal contract awards pulled live from USASpending.gov — the official US Treasury database, updated daily. Search by company name, keyword, or NAICS code. Returns award amounts, awarding agency, period of performance, and contract description, all timestamped. A company that just won a $10M DoD contract is actively hiring and spending — that is a buying intent signal no other MCP server surfaces. |
+
+---
+
+## Quick Start
+
+### Option A — Cloud (no install)
+
+Add to your Claude Desktop config and restart:
+
+**Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "freshcontext": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://freshcontext-mcp.gimmanuel73.workers.dev/mcp"]
+    }
+  }
+}
+```
+
+Restart Claude. Done.
+
+> Prefer a guided setup? Visit **[freshcontext-site.pages.dev](https://freshcontext-site.pages.dev)** — 3 steps, no terminal.
+
+---
+
+### Option B — Local (full Playwright)
+
+**Requires:** Node.js 18+ ([nodejs.org](https://nodejs.org))
+
+```bash
+git clone https://github.com/PrinceGabriel-lgtm/freshcontext-mcp
+cd freshcontext-mcp
+npm install
+npx playwright install chromium
+npm run build
+```
+
+Add to Claude Desktop config:
+
+**Mac:**
+```json
+{
+  "mcpServers": {
+    "freshcontext": {
+      "command": "node",
+      "args": ["/Users/YOUR_USERNAME/path/to/freshcontext-mcp/dist/server.js"]
+    }
+  }
+}
+```
+
+**Windows:**
+```json
+{
+  "mcpServers": {
+    "freshcontext": {
+      "command": "node",
+      "args": ["C:\\Users\\YOUR_USERNAME\\path\\to\\freshcontext-mcp\\dist\\server.js"]
+    }
+  }
+}
+```
+
+---
+
+### Troubleshooting (Mac)
+
+**"command not found: node"** — Use the full path:
+```bash
+which node  # copy this output, replace "node" in config
+```
+
+**Config file doesn't exist** — Create it:
+```bash
+mkdir -p ~/Library/Application\ Support/Claude
+touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
+```
+
+---
+
+## Usage examples
+
+**Is anyone already building what you're building?**
+```
+Use extract_landscape with topic "cashflow prediction saas"
+```
+Returns who's funded, what's trending, what repos exist, what packages are moving — all timestamped.
+
+**What's the community actually saying right now?**
+```
+Use extract_reddit on r/MachineLearning
+Use extract_hackernews to search "mcp server 2026"
+```
+
+**Did that company actually ship recently?**
+```
+Use extract_github on https://github.com/some-org/some-repo
+```
+Check `Published` vs `Retrieved`. If the gap is 18 months, Claude will tell you.
+
+**Is this dependency still actively maintained?**
+```
+Use extract_changelog with url "https://github.com/org/repo"
+```
+Returns the last 8 releases with exact dates. If the last release was 18 months ago, you'll know before you pin the version.
+
+**Which companies just won government contracts in AI?**
+```
+Use extract_govcontracts with url "artificial intelligence"
+```
+Returns the largest recent federal contract awards matching that keyword — company name, amount, agency, and award date. Pure buying intent signal.
+
+---
+
+## How freshness works
+
+Most AI tools retrieve data silently. No timestamp, no signal, no way for the agent to know how old it is.
+
+freshcontext treats **retrieval time as first-class metadata**. Every adapter returns:
+
+- `retrieved_at` — exact ISO timestamp of the fetch
+- `content_date` — best estimate of when the content was originally published
+- `freshness_confidence` — `high`, `medium`, or `low` based on signal quality
+- `adapter` — which source the data came from
+
+When confidence is `high`, the date came from a structured field (API, metadata). When it's `medium` or `low`, freshcontext tells you why.
+
+---
+
+## Security
+
+- Input sanitization and domain allowlists on all adapters
+- SSRF prevention (blocked private IP ranges)
+- KV-backed global rate limiting: 60 req/min per IP across all edge nodes
+- No credentials required — all public data sources
+
+---
+
+## Roadmap
+
+- [x] GitHub, HN, Scholar, YC, Reddit, Product Hunt, Finance, arXiv adapters
+- [x] `extract_landscape` — 6-source composite tool
+- [x] Cloudflare Workers deployment
+- [x] KV-backed global rate limiting
+- [x] Listed on official MCP Registry
+- [x] `extract_changelog` — update cadence from any repo, package, or website
+- [x] `extract_govcontracts` — US federal contract intelligence via USASpending.gov
+- [x] Listed on Apify Store
+- [x] FreshContext Specification v1.0 published
+- [ ] TTL-based caching layer
+- [ ] `freshness_score` numeric metric (0–100)
+- [ ] `extract_devto` — developer article sentiment
+- [ ] `extract_npm_releases` — package release velocity
+
+---
+
+## Contributing
+
+PRs welcome. New adapters are the highest-value contribution — see `src/adapters/` for the pattern.
+
+---
+
+## License
+
+MIT

package/SESSION_SAVE_ARCHITECTURE_V1.md

@@ -0,0 +1,67 @@
+# FreshContext — Architecture Upgrade Session V1
+**Date:** 2026-03-19
+**Session type:** Infrastructure hardening + automation
+**Status:** 13 tools live. GitHub Actions CI/CD live. Apify Actor published. govcontracts fixed.
+
+---
+
+## What Was Accomplished This Session
+
+### 1. extract_govcontracts — fully repaired
+The adapter was sending wrong field names to USASpending.gov on every call. Root cause:
+every field used underscores ("Award_ID", "Recipient_Name") while the API requires
+space-separated names ("Award ID", "Recipient Name"). After three rounds of diagnosis,
+the correct fix was a full rewrite of govcontracts.ts. Confirmed working — Palantir
+query returned $1.29B across 10 contracts live from the US Treasury.
+
+### 2. README updated to 13 tools
+Updated from "11 tools" to "13 tools". extract_changelog and extract_govcontracts given
+their own dedicated sections with separate headings. Two new usage examples added.
+Roadmap updated to mark both adapters complete and add extract_devto + extract_npm_releases
+as next planned work.
+
+### 3. Apify Actor — Dockerfile added
+Actor was timing out because .actor/actor.json had no Dockerfile reference, so Apify
+launched dist/server.js — the MCP stdio server that waits forever and never exits.
+Fixed by creating .actor/Dockerfile using apify/actor-node:18, installing all deps
+including apify SDK, and running dist/apify.js as the CMD. apify added to dependencies
+in package.json. The apify.ts file was already complete — it just had no path to get called.
+
+### 4. GitHub Actions CI/CD — live and confirmed
+.github/workflows/publish.yml created, triggers on every push to main. Runs npm ci,
+npm run build, npm publish. Uses NPM_TOKEN secret. First run: green checkmark, 23 seconds.
+Manual PowerShell build/publish commands are no longer needed. Bump version, git push, done.
+
+### 5. Outreach — 3 new Gmail drafts
+Apollo.io — government contracts as missing GTM signal.
+Harmonic.ai — contracts + changelog velocity as VC signals.
+GitHub Partnerships — Releases API use case via extract_changelog.
+
+---
+
+## Current Stack State
+
+| Layer | Status | Notes |
+|---|---|---|
+| npm | freshcontext-mcp@0.3.10 | 13 tools, published |
+| Cloudflare Worker | Live | Global edge, KV rate limiting |
+| D1 Database | Live | 18 watched queries, 6h cron |
+| Synthesis | PAUSED | Needs $5 Anthropic credits |
+| Apify Actor | Published | Dockerfile pushed, needs rebuild + test |
+| GitHub Actions | LIVE | Green, 23s |
+| MCP Registry | Listed | server.json version may need update |
+| Payoneer | Approved | Customer ID 102746504 |
+
+---
+
+## Pending Action Items
+
+Apify: Source tab → Build now → test with {"tool":"extract_hackernews","query":"mcp server 2026"}.
+Then test extract_govcontracts with "Palantir" to confirm full end-to-end on Apify.
+Increase Apify Actor timeout from 300s to 3600s in Settings (free, needed for Playwright tools).
+Send three Gmail drafts: Apollo.io, Harmonic.ai, GitHub Partnerships.
+Top up $5 Anthropic credits to re-enable /briefing/now synthesis endpoint.
+
+---
+
+## Next Architecture Upgrades (see ARCHITECTURE_UPGRADE_ROADMAP_V1.md)

package/SESSION_SAVE_ARCHITECTURE_V2.md

@@ -0,0 +1,142 @@
+# FreshContext — Architecture Session V2 Save
+**Date:** 2026-03-19
+**Session type:** Architecture upgrades complete + new composite adapters planned
+**npm version:** 0.3.10 (GitHub Actions publishes automatically on every push now)
+
+---
+
+## What Was Completed This Session
+
+### All 7 Architecture Upgrades — DONE
+
+| # | Upgrade | Status | Notes |
+|---|---|---|---|
+| 1 | freshness_score numeric field | DONE | Implemented in src/tools/freshnessStamp.ts |
+| 2 | Cloudflare KV response caching | DONE | Already in worker.ts — discovered not missing |
+| 3 | Apify Actor timeout increase | DONE | Changed to 3600s in Apify UI |
+| 4 | D1 deduplication in cron job | DONE | Already in runScheduledScrape as hash-based dedup |
+| 5 | Structured JSON response form | DONE | FRESHCONTEXT_JSON block appended to every response |
+| 6 | GitHub Actions CI/CD | DONE | .github/workflows/publish.yml live, 23s green run |
+| 7 | server.json version sync | DONE | Updated to 0.3.10, description to 13 tools |
+
+### Key implementation details
+
+Upgrade 1 — freshnessStamp.ts now calculates max(0, 100 - (days × decayRate)) per adapter.
+Decay rates: finance=5.0, jobs=3.0, hackernews/reddit/producthunt=2.0, yc/govcontracts=1.5,
+github/repoSearch/packageTrends/changelog=1.0, scholar/arxiv=0.3, default=1.5.
+Returns null when content_date is unknown. Returns 0 when score would go negative.
+Score label added: current (90+), reliable (70+), verify before acting (50+), use with caution (<50).
+
+Upgrade 5 — Every response now emits both:
+  [FRESHCONTEXT]...[/FRESHCONTEXT]  ← text envelope for AI agents
+  [FRESHCONTEXT_JSON]...{...}...[/FRESHCONTEXT_JSON]  ← structured JSON for programmatic use
+JSON form contains: source_url, content_date, retrieved_at, freshness_confidence,
+freshness_score, adapter, content. toStructuredJSON() is exported from freshnessStamp.ts.
+
+### Command reference HTML cheat sheet
+FRESHCONTEXT_COMMANDS.html was created and delivered as a downloadable file.
+Dark theme, click-to-copy cards, organized by: Landscape, Intelligence, Competitive,
+Market data, Unique adapters, Power combos. Open in any browser, click a card to copy
+the command, paste into Claude.
+
+---
+
+## Next Session — Two New Composite Adapters
+
+### Adapter 1: extract_gov_landscape
+"Gov contracts for developers"
+
+The idea: a single call that gives a complete government intelligence picture on a
+company or keyword. Not just the contract data, but whether the companies winning
+those contracts are actually shipping code and whether the developer community knows
+about them.
+
+Sources to combine in parallel:
+  - extract_govcontracts — who won, how much, which agency, when
+  - extract_github — are the winning companies actually building (stars, last commit, language)
+  - extract_hackernews — does the dev community know about them
+  - extract_changelog — are they shipping product (release velocity as a health signal)
+
+Input: company name, keyword, or NAICS code (same as extract_govcontracts)
+Output: unified FreshContext envelope with sections for each source, all timestamped
+
+Why it matters: A $50M DoD contract winner with no GitHub commits in 6 months and
+zero HN mentions is a very different company from one that's been pushing code weekly
+and has 3 HN front-page mentions. This composite surfaces that difference in one call.
+
+Location: src/adapters/govLandscape.ts
+Tool name: extract_gov_landscape
+
+### Adapter 2: extract_finance_landscape
+"Finance for developers"
+
+The idea: a stock price is a backward-looking lagging indicator. What a technical
+investor or developer actually needs is price combined with the signals only FreshContext
+can surface — developer community sentiment, engineering velocity, ecosystem activity.
+
+Sources to combine in parallel:
+  - extract_finance — live price, market cap, P/E, 52w range (Yahoo Finance)
+  - extract_hackernews — what are developers saying about this company right now
+  - extract_reddit — investor and developer community sentiment (r/investing + tech subs)
+  - search_repos — how many GitHub repos orbit this company's ecosystem
+  - extract_changelog — is the company actually shipping product (release velocity)
+
+Input: ticker symbol(s) e.g. "PLTR" or "PLTR,MSFT"
+Output: unified FreshContext envelope with sections for each source, all timestamped
+
+Why it matters: Bloomberg Terminal doesn't read GitHub commit history as a company
+health signal. FreshContext does. This composite is something no existing financial
+tool offers — developer-native market intelligence with freshness scores on every source.
+
+Location: src/adapters/financeLandscape.ts
+Tool name: extract_finance_landscape
+
+### Pattern to follow
+Both adapters should follow the exact same structure as extract_landscape in
+src/adapters/landscape.ts — use Promise.allSettled for parallel calls, handle
+partial failures gracefully (if one source fails, the others still return),
+wrap the combined output in a single FreshContext envelope with sections clearly
+labelled per source.
+
+---
+
+## Current Stack State
+
+| Layer | Status |
+|---|---|
+| npm | freshcontext-mcp@0.3.10, auto-publishes via GitHub Actions |
+| Cloudflare Worker | Live, KV caching active, rate limiting active |
+| D1 Database | 18 watched queries, 6h cron, hash-based dedup |
+| Synthesis | PAUSED — needs $5 Anthropic credits at console.anthropic.com |
+| Apify Actor | Published, Dockerfile fixed, timeout 3600s |
+| GitHub Actions | Live — push to main = auto build + publish |
+| MCP Registry | server.json v0.3.10, 13 tools description |
+| Payoneer | Approved — Customer ID 102746504 |
+
+## Outreach Status
+
+| Target | Email | Status |
+|---|---|---|
+| Apify | jan@apify.com | Sent |
+| Clay | kareem@clay.com | Sent |
+| n8n | jan@n8n.io | Sent |
+| Cloudflare Startups | startups@cloudflare.com | Sent — awaiting reply (10 business days) |
+| Anthropic | partnerships@anthropic.com | Sent |
+| Apollo.io | hello@apollo.io | Sent this session |
+| Harmonic.ai | hello@harmonic.ai | Sent this session |
+| GitHub Partnerships | partnerships@github.com | Sent this session |
+
+---
+
+## Resume Prompt for Next Session
+
+"I'm building freshcontext-mcp — 13-tool web intelligence MCP server, fully
+spec-compliant, GitHub Actions CI/CD live, all 7 architecture upgrades complete.
+Next task: build two new composite adapters — extract_gov_landscape (govcontracts +
+github + hackernews + changelog in parallel) and extract_finance_landscape (finance
++ hackernews + reddit + search_repos + changelog in parallel). Both follow the
+extract_landscape pattern in src/adapters/landscape.ts. See SESSION_SAVE_ARCHITECTURE_V2.md
+for full spec."
+
+*"The work isn't gone. It's just waiting to be continued."*
+*— Prince Gabriel, Grootfontein, Namibia*

package/dist/server.js

@@ -8,6 +8,8 @@ import { hackerNewsAdapter } from "./adapters/hackernews.js";
 import { ycAdapter } from "./adapters/yc.js";
 import { repoSearchAdapter } from "./adapters/repoSearch.js";
 import { packageTrendsAdapter } from "./adapters/packageTrends.js";
+import { redditAdapter } from "./adapters/reddit.js";
+import { financeAdapter } from "./adapters/finance.js";
 import { jobsAdapter } from "./adapters/jobs.js";
 import { changelogAdapter } from "./adapters/changelog.js";
 import { govContractsAdapter } from "./adapters/govcontracts.js";
@@ -220,6 +222,101 @@ server.registerTool("extract_govcontracts", {
         return { content: [{ type: "text", text: formatSecurityError(err) }] };
     }
 });
+// ─── Tool: extract_gov_landscape ───────────────────────────────────────────
+// "Gov contracts for developers" — the full picture on any company or keyword
+// in the US federal market. Contracts alone tell you who won money. This tool
+// also tells you whether they're actually shipping, and whether the developer
+// community knows they exist. Unique: no other MCP server has this.
+server.registerTool("extract_gov_landscape", {
+    description: "Composite government intelligence tool. Given a company name, keyword, or NAICS code, simultaneously queries: (1) USASpending.gov for federal contract awards, (2) GitHub for the company's repo activity, (3) Hacker News for developer community awareness, and (4) their product changelog for release velocity. Answers: Who is winning government contracts in this space? Are they actually building? Does the dev community know about them? Returns a unified 4-source timestamped report. Unique — not available in any other MCP server.",
+    inputSchema: z.object({
+        query: z.string().describe("Company name (e.g. 'Palantir'), keyword (e.g. 'artificial intelligence'), or NAICS code (e.g. '541511'). For GitHub and changelog sections, also optionally provide a GitHub URL."),
+        github_url: z.string().optional().describe("Optional GitHub repo URL for the company (e.g. 'https://github.com/palantir/palantir-java-format'). If omitted, GitHub and changelog sections use the query as a search term."),
+        max_length: z.number().optional().default(12000),
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ query, github_url, max_length }) => {
+    const perSection = Math.floor((max_length ?? 12000) / 4);
+    // All four sources fire in parallel — if one fails the others still return
+    const [contractsResult, hnResult, repoResult, changelogResult] = await Promise.allSettled([
+        // 1. The anchor: who is actually winning federal money in this space
+        govContractsAdapter({ url: query, maxLength: perSection }),
+        // 2. Dev community signal: does anyone in tech know about these companies
+        hackerNewsAdapter({
+            url: `https://hn.algolia.com/api/v1/search?query=${encodeURIComponent(query)}&tags=story&hitsPerPage=10`,
+            maxLength: perSection,
+        }),
+        // 3. GitHub activity: are they actually building, or contract farmers
+        repoSearchAdapter({ url: github_url ?? query, maxLength: perSection }),
+        // 4. Release velocity: how fast are they shipping product
+        changelogAdapter({ url: github_url ?? query, maxLength: perSection }),
+    ]);
+    const section = (label, result) => result.status === "fulfilled"
+        ? `## ${label}\n${result.value.raw}`
+        : `## ${label}\n[Unavailable: ${result.reason}]`;
+    const combined = [
+        `# Government Intelligence Landscape: "${query}"`,
+        `Generated: ${new Date().toISOString()}`,
+        `Sources: USASpending.gov · Hacker News · GitHub · Changelog`,
+        "",
+        section("🏛️ Federal Contract Awards (USASpending.gov)", contractsResult),
+        section("💬 Developer Community Awareness (Hacker News)", hnResult),
+        section("📦 GitHub Repository Activity", repoResult),
+        section("🔄 Product Release Velocity (Changelog)", changelogResult),
+    ].join("\n\n");
+    return { content: [{ type: "text", text: combined }] };
+});
+// ─── Tool: extract_finance_landscape ─────────────────────────────────────────
+// "Finance for developers" — a stock price is a lagging indicator. This tool
+// combines price data with the signals only developers can read: GitHub activity,
+// community sentiment, repo ecosystem size, and product release velocity.
+// Unique: Bloomberg Terminal doesn't read commit history as a company health signal.
+server.registerTool("extract_finance_landscape", {
+    description: "Composite financial intelligence tool for developers. Given one or more ticker symbols, simultaneously queries: (1) Yahoo Finance for live price/market data, (2) Hacker News for developer community sentiment, (3) Reddit for investor and tech community discussion, (4) GitHub for repo ecosystem activity around the company's tech, and (5) their product changelog for release velocity as a company health signal. Answers: What's the price? What are developers saying? Is the company actually shipping? Returns a unified 5-source timestamped report. Bloomberg Terminal doesn't give you this.",
+    inputSchema: z.object({
+        tickers: z.string().describe("One or more ticker symbols e.g. 'PLTR' or 'PLTR,MSFT,GOOG'. Up to 5 tickers."),
+        company_name: z.string().optional().describe("Company name for HN/Reddit/GitHub searches e.g. 'Palantir'. If omitted, derived from the ticker."),
+        github_query: z.string().optional().describe("GitHub search query or repo URL for the company's tech ecosystem e.g. 'palantir' or 'https://github.com/palantir/foundry'. If omitted, uses company_name."),
+        max_length: z.number().optional().default(12000),
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ tickers, company_name, github_query, max_length }) => {
+    const perSection = Math.floor((max_length ?? 12000) / 5);
+    // Derive a search term: prefer explicit company_name, fall back to first ticker
+    const searchTerm = company_name ?? tickers.split(",")[0].trim();
+    const repoQuery = github_query ?? searchTerm;
+    // All five sources fire in parallel
+    const [priceResult, hnResult, redditResult, repoResult, changelogResult] = await Promise.allSettled([
+        // 1. The anchor: live price, market cap, P/E, 52w range
+        financeAdapter({ url: tickers, maxLength: perSection }),
+        // 2. Developer sentiment: what engineers think of this company's tech
+        hackerNewsAdapter({
+            url: `https://hn.algolia.com/api/v1/search?query=${encodeURIComponent(searchTerm)}&tags=story&hitsPerPage=10`,
+            maxLength: perSection,
+        }),
+        // 3. Broader community: investor and tech community discussion on Reddit
+        redditAdapter({ url: `https://www.reddit.com/search.json?q=${encodeURIComponent(searchTerm)}&sort=new&limit=15`, maxLength: perSection }),
+        // 4. Repo ecosystem: how many GitHub projects orbit this company's technology
+        repoSearchAdapter({ url: repoQuery, maxLength: perSection }),
+        // 5. Release velocity: is the company actually shipping product right now
+        changelogAdapter({ url: repoQuery, maxLength: perSection }),
+    ]);
+    const section = (label, result) => result.status === "fulfilled"
+        ? `## ${label}\n${result.value.raw}`
+        : `## ${label}\n[Unavailable: ${result.reason}]`;
+    const combined = [
+        `# Finance + Developer Intelligence: "${tickers}"${company_name ? ` (${company_name})` : ""}`,
+        `Generated: ${new Date().toISOString()}`,
+        `Sources: Yahoo Finance · Hacker News · Reddit · GitHub · Changelog`,
+        "",
+        section("📈 Market Data (Yahoo Finance)", priceResult),
+        section("💬 Developer Sentiment (Hacker News)", hnResult),
+        section("🗣️ Community Discussion (Reddit)", redditResult),
+        section("📦 Repo Ecosystem (GitHub)", repoResult),
+        section("🔄 Product Release Velocity (Changelog)", changelogResult),
+    ].join("\n\n");
+    return { content: [{ type: "text", text: combined }] };
+});
 // ─── Start ───────────────────────────────────────────────────────────────────
 async function main() {
     const transport = new StdioServerTransport();

package/dist/tools/freshnessStamp.js

@@ -1,25 +1,109 @@
+// ─── Decay rates per adapter ──────────────────────────────────────────────────
+// From FreshContext Specification v1.0.
+// Higher decay = data goes stale faster. Half-life = 100 / (2 * decayRate) days.
+// finance=5.0 (half-life ~10d), jobs=3.0 (~17d), news/hn=2.0 (~25d),
+// github=1.0 (~50d), scholar/arxiv=0.3 (~167d), default=1.5 (~33d)
+const DECAY_RATES = {
+    finance: 5.0,
+    search_jobs: 3.0,
+    hackernews: 2.0,
+    reddit: 2.0,
+    producthunt: 2.0,
+    yc: 1.5,
+    govcontracts: 1.5,
+    github: 1.0,
+    repoSearch: 1.0,
+    packageTrends: 1.0,
+    changelog: 1.0,
+    scholar: 0.3,
+    arxiv: 0.3,
+};
+// ─── Score calculation ────────────────────────────────────────────────────────
+// Returns null when content_date is unknown — we can't calculate age without a date.
+// Returns 0 when the score would go negative (content is very old).
+function calculateFreshnessScore(content_date, retrieved_at, adapter) {
+    if (!content_date)
+        return null;
+    const published = new Date(content_date).getTime();
+    const retrieved = new Date(retrieved_at).getTime();
+    // Guard against unparseable dates
+    if (isNaN(published) || isNaN(retrieved))
+        return null;
+    const daysSinceRetrieved = (retrieved - published) / (1000 * 60 * 60 * 24);
+    const decayRate = DECAY_RATES[adapter] ?? 1.5;
+    return Math.max(0, Math.round(100 - daysSinceRetrieved * decayRate));
+}
+// ─── Score label ──────────────────────────────────────────────────────────────
+// Human-readable interpretation alongside the number, per the spec.
+function scoreLabel(score) {
+    if (score === null)
+        return "unknown";
+    if (score >= 90)
+        return "current";
+    if (score >= 70)
+        return "reliable";
+    if (score >= 50)
+        return "verify before acting";
+    return "use with caution";
+}
+// ─── Main stamp function ──────────────────────────────────────────────────────
 export function stampFreshness(result, options, adapter) {
+    const retrieved_at = new Date().toISOString();
+    const freshness_score = calculateFreshnessScore(result.content_date, retrieved_at, adapter);
     return {
         content: result.raw.slice(0, options.maxLength ?? 8000),
         source_url: options.url,
         content_date: result.content_date,
-        retrieved_at: new Date().toISOString(),
+        retrieved_at,
         freshness_confidence: result.freshness_confidence,
+        freshness_score,
         adapter,
     };
 }
+// ─── Structured JSON form ─────────────────────────────────────────────────────
+// Returns the spec-compliant JSON object defined in FRESHCONTEXT_SPEC.md.
+// Programmatic consumers can parse this without touching the text envelope.
+export function toStructuredJSON(ctx) {
+    return {
+        freshcontext: {
+            source_url: ctx.source_url,
+            content_date: ctx.content_date,
+            retrieved_at: ctx.retrieved_at,
+            freshness_confidence: ctx.freshness_confidence,
+            freshness_score: ctx.freshness_score,
+            adapter: ctx.adapter,
+        },
+        content: ctx.content,
+    };
+}
+// ─── Text envelope formatter ──────────────────────────────────────────────────
+// Produces the [FRESHCONTEXT]...[/FRESHCONTEXT] envelope defined in the spec,
+// followed by a [FRESHCONTEXT_JSON]...[/FRESHCONTEXT_JSON] block so both the
+// human-readable envelope and the machine-parseable JSON travel together.
 export function formatForLLM(ctx) {
     const dateInfo = ctx.content_date
         ? `Published: ${ctx.content_date}`
         : "Publish date: unknown";
-    return [
+    const scoreLine = ctx.freshness_score !== null
+        ? `Score: ${ctx.freshness_score}/100 (${scoreLabel(ctx.freshness_score)})`
+        : `Score: unknown`;
+    const textEnvelope = [
         `[FRESHCONTEXT]`,
         `Source: ${ctx.source_url}`,
         `${dateInfo}`,
         `Retrieved: ${ctx.retrieved_at}`,
         `Confidence: ${ctx.freshness_confidence}`,
+        `${scoreLine}`,
         `---`,
         ctx.content,
         `[/FRESHCONTEXT]`,
     ].join("\n");
+    // Append the structured JSON block so programmatic consumers
+    // can extract metadata without parsing the text envelope.
+    const jsonBlock = [
+        `[FRESHCONTEXT_JSON]`,
+        JSON.stringify(toStructuredJSON(ctx), null, 2),
+        `[/FRESHCONTEXT_JSON]`,
+    ].join("\n");
+    return `${textEnvelope}\n\n${jsonBlock}`;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "freshcontext-mcp",
   "mcpName": "io.github.PrinceGabriel-lgtm/freshcontext",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "Real-time web extraction MCP server with freshness timestamps for AI agents",
   "keywords": [
     "mcp",
@@ -37,6 +37,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "apify": "^3.0.0",
     "playwright": "^1.44.0",
     "zod": "^3.23.0",
     "dotenv": "^16.4.0"

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. 11 tools, no API keys. GitHub, HN, Reddit, arXiv & more.",
+  "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.",
   "repository": {
     "url": "https://github.com/PrinceGabriel-lgtm/freshcontext-mcp",
     "source": "github"
   },
-  "version": "0.3.1",
+  "version": "0.3.11",
   "website_url": "https://freshcontext-site.pages.dev",
   "packages": [
     {
       "registry_type": "npm",
       "registry_base_url": "https://registry.npmjs.org",
       "identifier": "freshcontext-mcp",
-      "version": "0.3.1",
+      "version": "0.3.11",
       "transport": {
         "type": "stdio"
       }