freshcontext-mcp 0.3.17 → 0.3.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,296 +1,395 @@
1
- # freshcontext-mcp
2
-
3
- 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.
4
-
5
- Claude had no idea. It presented everything with the same confidence.
6
-
7
- That's the problem freshcontext fixes.
8
-
9
- [![npm version](https://img.shields.io/npm/v/freshcontext-mcp)](https://www.npmjs.com/package/freshcontext-mcp)
10
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
11
- [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-Listed-blue)](https://registry.modelcontextprotocol.io)
12
-
13
- > **Live demo:** [freshcontext-mcp.gimmanuel73.workers.dev/demo](https://freshcontext-mcp.gimmanuel73.workers.dev/demo) — same model, same query, two completely different answers. Only the temporal layer changed.
14
-
15
- ---
16
-
17
- ## The problem
18
-
19
- Large language models retrieve web data semantically. Cosine similarity finds the documents that match a query best — but cosine doesn't know when a document was written.
20
-
21
- So a 2022 blog post and a 2026 paper can score nearly identically. The model gets a context window full of stale documents and faithfully summarizes 2022 advice for a 2026 question.
22
-
23
- That's not hallucination. That's correct summarization of corrupted retrieval.
24
-
25
- > **Most RAG pipelines rank context correctly semantically but incorrectly temporally.**
26
-
27
- ---
28
-
29
- ## The layer
30
-
31
- FreshContext is a **temporal correction layer for retrieval systems**. One math correction applied before context reaches the LLM:
32
-
33
- ```
34
- R_t = R_0 · e^(−λt)
35
- ```
36
-
37
- - `R_0` — base semantic relevancy (whatever your retriever already gives you)
38
- - `λ` — source-specific decay constant (HN ≈14h half-life, blogs ≈29d, academic papers ≈1.6y)
39
- - `t` — hours elapsed since publication
40
- - `R_t` — decay-adjusted relevancy at query time
41
-
42
- That's the whole fix. No model swap. No re-embedding. No re-indexing. The layer drops onto whatever retrieval pipeline you already have.
43
-
44
- **The layer is the product.** The 21 tools shipped with this repo are reference implementations demonstrating compatibility — useful, but commodity. The DAR engine, the freshness envelope, and the FreshContext Specification are the moat.
45
-
46
- ---
47
-
48
- ## The standard
49
-
50
- Every FreshContext-compatible response wraps content in a structured envelope:
51
-
52
- ```
53
- [FRESHCONTEXT]
54
- Source: https://github.com/owner/repo
55
- Published: 2024-11-03
56
- Retrieved: 2026-03-05T09:19:00Z
57
- Confidence: high
58
- ---
59
- ... content ...
60
- [/FRESHCONTEXT]
61
- ```
62
-
63
- **When** it was retrieved. **Where** it came from. **How confident** we are the date is accurate.
64
-
65
- The FreshContext Specification v1.1 is published as an open standard under MIT licence. Any tool, agent, or system that wraps retrieved data in this envelope is FreshContext-compatible. → [Read the spec](./FRESHCONTEXT_SPEC.md) · [Read the methodology](./METHODOLOGY.md)
66
-
67
- ---
68
-
69
- ## The intelligence feed
70
-
71
- Beyond the per-call envelope, the production FreshContext deployment exposes a continuous, decay-scored, deduplicated feed:
72
-
73
- ```
74
- GET /v1/intel/feed/:profile_id?limit=20&min_rt=0
75
- ```
76
-
77
- Every signal is stamped with `base_score`, `rt_score`, `entropy_level` (low / stable / high), `ha_pri_sig` (SHA-256 provenance), `semantic_fingerprint` (cross-adapter dedup), and `published_at`. Ready for direct LLM or agent consumption no synthesis required.
78
-
79
- Production endpoint: `https://freshcontext-mcp.gimmanuel73.workers.dev`
80
-
81
- ---
82
-
83
- ## Reference adapters
84
-
85
- The repo ships 21 tools demonstrating how to make any data source FreshContext-compatible. Useful as drop-in tools, but the value is the layer above them.
86
-
87
- ### Intelligence
88
- | Adapter | What it returns |
89
- |---|---|
90
- | `extract_github` | README, stars, forks, language, topics, last commit |
91
- | `extract_hackernews` | Top stories or search results with scores and timestamps |
92
- | `extract_scholar` | Research papers — titles, authors, years, snippets |
93
- | `extract_arxiv` | arXiv papers via official API |
94
- | `extract_reddit` | Posts and community sentiment from any subreddit |
95
-
96
- ### Competitive research
97
- | Adapter | What it returns |
98
- |---|---|
99
- | `extract_yc` | YC company listings by keyword |
100
- | `extract_producthunt` | Recent launches by topic |
101
- | `search_repos` | GitHub repos ranked by stars with activity signals |
102
- | `package_trends` | npm and PyPI metadata — version history, release cadence |
103
-
104
- ### Market data
105
- | Adapter | What it returns |
106
- |---|---|
107
- | `extract_finance` | No-key Stooq quote data — close, OHLC, volume, quote timestamp, source. Up to 5 tickers. |
108
- | `search_jobs` | Remote job listings from Remotive, RemoteOK, HN "Who is Hiring" |
109
-
110
- ### Composites — multiple sources, one call
111
- | Adapter | Sources | Purpose |
112
- |---|---|---|
113
- | `extract_landscape` | 6 | YC + GitHub + HN + Reddit + Product Hunt + npm in parallel |
114
- | `extract_idea_landscape` | 6 | HN + YC + GitHub + Jobs + npm + Product Huntfull idea validation |
115
- | `extract_gov_landscape` | 4 | Gov contracts + HN + GitHub + changelog |
116
- | `extract_finance_landscape` | 5 | Finance + HN + Reddit + GitHub + changelog |
117
- | `extract_company_landscape` | 5 | The full picture on any company |
118
-
119
- ### Uniquenot available in any other MCP server
120
- | Adapter | Source | What it returns |
121
- |---|---|---|
122
- | `extract_changelog` | GitHub Releases / npm / auto-discover | Update history from any repo, package, or website |
123
- | `extract_govcontracts` | USASpending.gov | US federal contract awards — company, amount, agency, period |
124
- | `extract_sec_filings` | SEC EDGAR | 8-K filings — legally mandated material event disclosures |
125
- | `extract_gdelt` | GDELT Project | Global news intelligence 100+ languages, 15-min updates |
126
- | `extract_gebiz` | data.gov.sg | Singapore Government procurement tendersopen dataset |
127
-
128
- ---
129
-
130
- ## Quick start
131
-
132
- ### Cloud (no install)
133
-
134
- Add to your Claude Desktop config and restart:
135
-
136
- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
137
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
138
-
139
- ```json
140
- {
141
- "mcpServers": {
142
- "freshcontext": {
143
- "command": "npx",
144
- "args": ["-y", "mcp-remote", "https://freshcontext-mcp.gimmanuel73.workers.dev/mcp"]
145
- }
146
- }
147
- }
148
- ```
149
-
150
- Restart Claude. Done.
151
-
152
- > Prefer a guided setup? Visit **[freshcontext-site.pages.dev](https://freshcontext-site.pages.dev)** — 3 steps, no terminal.
153
-
154
- ### Local (full Playwright)
155
-
156
- **Requires:** Node.js 20+ ([nodejs.org](https://nodejs.org))
157
-
158
- ```bash
159
- git clone https://github.com/PrinceGabriel-lgtm/freshcontext-mcp
160
- cd freshcontext-mcp
161
- npm install
162
- npx playwright install chromium
163
- npm run build
164
- ```
165
-
166
- Add to Claude Desktop config:
167
-
168
- **Mac:**
169
- ```json
170
- {
171
- "mcpServers": {
172
- "freshcontext": {
173
- "command": "node",
174
- "args": ["/Users/YOUR_USERNAME/path/to/freshcontext-mcp/dist/server.js"]
175
- }
176
- }
177
- }
178
- ```
179
-
180
- **Windows:**
181
- ```json
182
- {
183
- "mcpServers": {
184
- "freshcontext": {
185
- "command": "node",
186
- "args": ["C:\\Users\\YOUR_USERNAME\\path\\to\\freshcontext-mcp\\dist\\server.js"]
187
- }
188
- }
189
- }
190
- ```
191
-
192
- #### Mac troubleshooting
193
-
194
- **"command not found: node"** — Use the full path:
195
- ```bash
196
- which node # copy this output, replace "node" in config
197
- ```
198
-
199
- **Config file doesn't exist:**
200
- ```bash
201
- mkdir -p ~/Library/Application\ Support/Claude
202
- touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
203
- ```
204
-
205
- ---
206
-
207
- ## Usage examples
208
-
209
- **Should I build this idea?**
210
- ```
211
- Use extract_idea_landscape with idea "procurement intelligence saas"
212
- ```
213
- Returns funding signal, pain signal, crowding signal, market signal, ecosystem signal, and launch signal — all timestamped.
214
-
215
- **Full company intelligence in one call:**
216
- ```
217
- Use extract_company_landscape with company "Palantir" and ticker "PLTR"
218
- ```
219
- SEC filings + federal contracts + global news + changelog + market data.
220
-
221
- **Did that company just disclose something material?**
222
- ```
223
- Use extract_sec_filings with url "Palantir Technologies"
224
- ```
225
- 8-K filings are legally mandated within 4 business days of any material event CEO change, acquisition, breach, major contract.
226
-
227
- **Is this dependency still actively maintained?**
228
- ```
229
- Use extract_changelog with url "https://github.com/org/repo"
230
- ```
231
- Returns the last 8 releases with exact dates. If the last release was 18 months ago, you'll know before you pin the version.
232
-
233
- ---
234
-
235
- ## Deployment & infrastructure
236
-
237
- The reference implementation runs on Cloudflare's global edge:
238
-
239
- | Endpoint | Method | Purpose |
240
- |---|---|---|
241
- | `/` | GET | Service info + endpoint list |
242
- | `/health` | GET | Liveness check |
243
- | `/mcp` | POST | MCP JSON-RPC transport |
244
- | `/demo` | GET | Live before/after demo (no API key required) |
245
- | `/briefing` | GET | Latest stored briefing |
246
- | `/v1/intel/feed/:profile_id` | GET | DAR-scored intelligence feed |
247
- | `/watched-queries` | GET | List all watched queries |
248
-
249
- - **D1 database** — 18 watched queries running on 6-hour cron with relevancy scoring
250
- - **KV-backed rate limiting** 60 req/min per IP across all edge nodes
251
- - **Defensive valves** — clock-skew rejection (5min tolerance), hard floor at R_t<5, lazy decay at read time
252
- - **Provenance** Ha-Pri SHA-256 audit signatures on every signal
253
- - **Schema migrations** — promise-gated, idempotent, run on first request after deploy
254
-
255
- Production: `https://freshcontext-mcp.gimmanuel73.workers.dev`
256
-
257
- ---
258
-
259
- ## Roadmap
260
-
261
- - [x] FreshContext Specification v1.1 published (MIT, open standard)
262
- - [x] DAR engine with proprietary λ constants (v0.3.17)
263
- - [x] Ha-Pri audit signatures on every signal
264
- - [x] Semantic deduplication via fingerprinting
265
- - [x] Live before/after demo at `/demo`
266
- - [x] METHODOLOGY.md — formal IP and engineering documentation
267
- - [x] 21 reference tools across intelligence, competitive research, market data, and composites
268
- - [x] Cloudflare Workers deployment — global edge, KV cache, KV rate limiting
269
- - [x] Listed on official MCP Registry, Apify Store, npm
270
- - [x] GitHub Actions CI/CD — auto-publish on every push
271
- - [ ] Webhook triggers — push high-entropy signals on threshold
272
- - [ ] Dashboard — React frontend for the D1 intelligence pipeline
273
- - [ ] GKG upgrade for `extract_gdelt` — tone scores, goldstein scale, event codes
274
-
275
- ---
276
-
277
- ## Contributing
278
-
279
- PRs welcome. New adapters are the highest-value contribution — see `src/adapters/` for the pattern and [`FRESHCONTEXT_SPEC.md`](./FRESHCONTEXT_SPEC.md) for the contract any adapter must fulfil.
280
-
281
- If you're building something FreshContext-compatible, open an issue and we'll add you to the ecosystem list.
282
-
283
- ---
284
-
285
- ## License
286
-
287
- MIT
288
-
289
- ---
290
-
291
- *Built by Prince Gabriel Grootfontein, Namibia 🇳🇦*
292
- *"The work isn't gone. It's just waiting to be continued."*
293
-
294
- ---
295
-
296
- **Also on:** [Apify Store](https://apify.com/prince_gabriel/freshcontext-mcp) · [MCP Registry](https://registry.modelcontextprotocol.io) · [npm](https://www.npmjs.com/package/freshcontext-mcp)
1
+ # FreshContext
2
+
3
+ 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.
4
+
5
+ Claude had no idea. It presented everything with the same confidence.
6
+
7
+ That's the problem freshcontext fixes.
8
+
9
+ This repository is the integrated FreshContext MCP/Core package. Core is the context-integrity layer that scores, ranks, explains, and wraps retrieved context before it reaches an LLM or agent; MCP is the primary reference/interface implementation.
10
+
11
+ [![npm version](https://img.shields.io/npm/v/freshcontext-mcp)](https://www.npmjs.com/package/freshcontext-mcp)
12
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
13
+ [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-Listed-blue)](https://registry.modelcontextprotocol.io)
14
+
15
+ > **Live demo:** [freshcontext-mcp.gimmanuel73.workers.dev/demo](https://freshcontext-mcp.gimmanuel73.workers.dev/demo) — same model, same query, two completely different answers. Only the temporal layer changed.
16
+
17
+ ---
18
+
19
+ ## The problem
20
+
21
+ Large language models retrieve web data semantically. Cosine similarity finds the documents that match a query best but cosine doesn't know when a document was written.
22
+
23
+ So a 2022 blog post and a 2026 paper can score nearly identically. The model gets a context window full of stale documents and faithfully summarizes 2022 advice for a 2026 question.
24
+
25
+ That's not hallucination. That's correct summarization of corrupted retrieval.
26
+
27
+ > **Most RAG pipelines rank context correctly semantically but incorrectly temporally.**
28
+
29
+ ---
30
+
31
+ ## The layer
32
+
33
+ FreshContext is a **temporal correction layer for retrieval systems**. One math correction applied before context reaches the LLM:
34
+
35
+ ```
36
+ R_t = R_0 · e^(−λt)
37
+ ```
38
+
39
+ - `R_0` — base semantic relevancy (whatever your retriever already gives you)
40
+ - `λ`source-specific decay constant (HN ≈14h half-life, blogs ≈29d, academic papers ≈1.6y)
41
+ - `t` — hours elapsed since publication
42
+ - `R_t` decay-adjusted relevancy at query time
43
+
44
+ That's the whole fix. No model swap. No re-embedding. No re-indexing. The layer drops onto whatever retrieval pipeline you already have.
45
+
46
+ **The layer is the product.** The 21 tools shipped with this repo are reference adapters demonstrating compatibility — useful, but commodity. The DAR engine, the freshness envelope, and the FreshContext Specification are the moat.
47
+
48
+ ---
49
+
50
+ ## The standard
51
+
52
+ Every FreshContext-compatible response wraps content in a structured envelope:
53
+
54
+ ```
55
+ [FRESHCONTEXT]
56
+ Source: https://github.com/owner/repo
57
+ Published: 2024-11-03
58
+ Retrieved: 2026-03-05T09:19:00Z
59
+ Confidence: high
60
+ ---
61
+ ... content ...
62
+ [/FRESHCONTEXT]
63
+ ```
64
+
65
+ **When** it was retrieved. **Where** it came from. **How confident** we are the date is accurate.
66
+
67
+ The FreshContext Specification v1.2 is published as an open standard under MIT licence. Any tool, agent, or system that wraps retrieved data in this envelope is FreshContext-compatible. → [Read the spec](./FRESHCONTEXT_SPEC.md) · [Read the methodology](./METHODOLOGY.md)
68
+
69
+ ---
70
+
71
+ ## Architecture boundary
72
+
73
+ FreshContext Core is the reusable center of the current integrated package. It owns freshness scoring, envelope formatting, failure guards, shared types, rank/explain primitives, and the context-conditioned utility primitive.
74
+
75
+ MCP is the primary reference/interface implementation over Core. Claude Desktop is supported, but not required. The 21 MCP tools in this repo are reference adapters and a live interface for using the system.
76
+
77
+ The production Cloudflare Worker now uses Core-backed envelope generation. Worker-specific concerns remain outside Core: MCP transport, runtime guards, KV cache policy, cache metadata injection, JSON parse/replace cache helpers, D1 feeds, cron, rate limiting, and Store/feed scoring/provenance.
78
+
79
+ ---
80
+
81
+ ## The intelligence feed
82
+
83
+ Beyond the per-call envelope, the production FreshContext deployment exposes a continuous, decay-scored, deduplicated feed:
84
+
85
+ ```
86
+ GET /v1/intel/feed/:profile_id?limit=20&min_rt=0
87
+ ```
88
+
89
+ Every signal is stamped with `base_score`, `rt_score`, `entropy_level` (low / stable / high), `ha_pri_sig` (Ha-Pri v1 SHA-256 provenance reference), `semantic_fingerprint` (cross-adapter dedup), and `published_at`. Ready for direct LLM or agent consumption — no synthesis required.
90
+
91
+ Production endpoint: `https://freshcontext-mcp.gimmanuel73.workers.dev`
92
+
93
+ ---
94
+
95
+ ## Reference adapters
96
+
97
+ The repo ships 21 tools demonstrating how to make any data source FreshContext-compatible. Useful as drop-in tools, but the value is the layer above them.
98
+
99
+ ### Intelligence
100
+ | Adapter | What it returns |
101
+ |---|---|
102
+ | `extract_github` | README, stars, forks, language, topics, last commit |
103
+ | `extract_hackernews` | Top stories or search results with scores and timestamps |
104
+ | `extract_scholar` | Research papers — titles, authors, years, snippets |
105
+ | `extract_arxiv` | arXiv papers via official API |
106
+ | `extract_reddit` | Posts and community sentiment from any subreddit |
107
+
108
+ ### Competitive research
109
+ | Adapter | What it returns |
110
+ |---|---|
111
+ | `extract_yc` | YC company listings by keyword |
112
+ | `extract_producthunt` | Recent launches by topic |
113
+ | `search_repos` | GitHub repos ranked by stars with activity signals |
114
+ | `package_trends` | npm and PyPI metadataversion history, release cadence |
115
+
116
+ ### Market data
117
+ | Adapter | What it returns |
118
+ |---|---|
119
+ | `extract_finance` | No-key Stooq quote data close, OHLC, volume, quote timestamp, source. Up to 5 tickers. |
120
+ | `search_jobs` | Remote job listings from Remotive, RemoteOK, HN "Who is Hiring" |
121
+
122
+ ### Composites multiple sources, one call
123
+ | Adapter | Sources | Purpose |
124
+ |---|---|---|
125
+ | `extract_landscape` | 6 | YC + GitHub + HN + Reddit + Product Hunt + npm in parallel |
126
+ | `extract_idea_landscape` | 6 | HN + YC + GitHub + Jobs + npm + Product Hunt full idea validation |
127
+ | `extract_gov_landscape` | 4 | Gov contracts + HN + GitHub + changelog |
128
+ | `extract_finance_landscape` | 5 | Finance + HN + Reddit + GitHub + changelog |
129
+ | `extract_company_landscape` | 5 | The full picture on any company |
130
+
131
+ ### Unique — not available in any other MCP server
132
+ | Adapter | Source | What it returns |
133
+ |---|---|---|
134
+ | `extract_changelog` | GitHub Releases / npm / auto-discover | Update history from any repo, package, or website |
135
+ | `extract_govcontracts` | USASpending.gov | US federal contract awards — company, amount, agency, period |
136
+ | `extract_sec_filings` | SEC EDGAR | 8-K filings — legally mandated material event disclosures |
137
+ | `extract_gdelt` | GDELT Project | Global news intelligence — 100+ languages, 15-min updates |
138
+ | `extract_gebiz` | data.gov.sg | Singapore Government procurement tenders — open dataset |
139
+
140
+ ---
141
+
142
+ ## Quick start
143
+
144
+ ### Cloud (no install)
145
+
146
+ Add to your Claude Desktop config and restart:
147
+
148
+ **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
149
+ **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
150
+
151
+ ```json
152
+ {
153
+ "mcpServers": {
154
+ "freshcontext": {
155
+ "command": "npx",
156
+ "args": ["-y", "mcp-remote", "https://freshcontext-mcp.gimmanuel73.workers.dev/mcp"]
157
+ }
158
+ }
159
+ }
160
+ ```
161
+
162
+ Restart Claude. Done.
163
+
164
+ > Prefer a guided setup? Visit **[freshcontext-site.pages.dev](https://freshcontext-site.pages.dev)** — 3 steps, no terminal.
165
+
166
+ ### Local (full Playwright)
167
+
168
+ **Requires:** Node.js 20+ ([nodejs.org](https://nodejs.org))
169
+
170
+ ```bash
171
+ git clone https://github.com/PrinceGabriel-lgtm/freshcontext-mcp
172
+ cd freshcontext-mcp
173
+ npm install
174
+ npx playwright install chromium
175
+ npm run build
176
+ ```
177
+
178
+ Add to Claude Desktop config:
179
+
180
+ **Mac:**
181
+ ```json
182
+ {
183
+ "mcpServers": {
184
+ "freshcontext": {
185
+ "command": "node",
186
+ "args": ["/Users/YOUR_USERNAME/path/to/freshcontext-mcp/dist/server.js"]
187
+ }
188
+ }
189
+ }
190
+ ```
191
+
192
+ **Windows:**
193
+ ```json
194
+ {
195
+ "mcpServers": {
196
+ "freshcontext": {
197
+ "command": "node",
198
+ "args": ["C:\\Users\\YOUR_USERNAME\\path\\to\\freshcontext-mcp\\dist\\server.js"]
199
+ }
200
+ }
201
+ }
202
+ ```
203
+
204
+ #### Mac troubleshooting
205
+
206
+ **"command not found: node"** — Use the full path:
207
+ ```bash
208
+ which node # copy this output, replace "node" in config
209
+ ```
210
+
211
+ **Config file doesn't exist:**
212
+ ```bash
213
+ mkdir -p ~/Library/Application\ Support/Claude
214
+ touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
215
+ ```
216
+
217
+ ---
218
+
219
+ ## Usage examples
220
+
221
+ The `npm run demo:*` commands below are source-checkout workflows for contributors and evaluators using a cloned repository. The published npm package is the MCP server/runtime package and does not include repo-only source examples or tests.
222
+
223
+ From an installed npm package, the supported runtime entrypoints are `npm start` and the `freshcontext-mcp` binary. Repo-only scripts such as tests, demos, smoke checks, and trust scans print a source-checkout notice when their source files are not present.
224
+
225
+ The Apify Actor entrypoint remains available in the source checkout for separate actor packaging, but it is intentionally not part of the published MCP npm runtime package.
226
+
227
+ ### Release trust gate
228
+
229
+ Run the local release gate before a release, package review, demo, or PR review:
230
+
231
+ ```bash
232
+ npm run trust:gate
233
+ ```
234
+
235
+ The gate runs the Trust Scanner with repo-map reporting, npm package-boundary inspection, deterministic claim checks, and `--fail-on fail`. It is local-only, does not publish or deploy, does not send telemetry, and does not replace dedicated security scanners.
236
+
237
+ Generate review reports when you need a shareable summary:
238
+
239
+ ```bash
240
+ npm run trust:report
241
+ npm run trust:report:json
242
+ ```
243
+
244
+ To write a Markdown report file explicitly:
245
+
246
+ ```bash
247
+ npm run trust:report -- --output TRUST_SCAN_REPORT.md
248
+ ```
249
+
250
+ ### Bring your own source list
251
+
252
+ FreshContext can evaluate candidate context you provide as a local JSON file:
253
+
254
+ ```bash
255
+ npm run demo:evaluate:file
256
+ ```
257
+
258
+ To pass a different file:
259
+
260
+ ```bash
261
+ npm run demo:evaluate:file -- path/to/sources.json
262
+ ```
263
+
264
+ Included examples:
265
+
266
+ ```bash
267
+ npm run demo:evaluate:file -- examples/sources.academic.example.json
268
+ npm run demo:evaluate:file -- examples/sources.jobs.example.json
269
+ ```
270
+
271
+ Minimal shape:
272
+
273
+ ```json
274
+ {
275
+ "profile": "academic_research",
276
+ "intent": "citation_check",
277
+ "signals": [
278
+ {
279
+ "title": "...",
280
+ "content": "...",
281
+ "source": "...",
282
+ "source_type": "arxiv",
283
+ "published_at": "...",
284
+ "retrieved_at": "...",
285
+ "semantic_score": 0.92
286
+ }
287
+ ]
288
+ }
289
+ ```
290
+
291
+ This local demo does not fetch URLs, crawl, or read folders. It evaluates candidate context you provide and returns decision-first output: Decision, Meaning, Action, Warnings, and supporting metrics.
292
+
293
+ **Should I build this idea?**
294
+ ```
295
+ Use extract_idea_landscape with idea "procurement intelligence saas"
296
+ ```
297
+ Returns funding signal, pain signal, crowding signal, market signal, ecosystem signal, and launch signal — all timestamped.
298
+
299
+ **Full company intelligence in one call:**
300
+ ```
301
+ Use extract_company_landscape with company "Palantir" and ticker "PLTR"
302
+ ```
303
+ SEC filings + federal contracts + global news + changelog + market data.
304
+
305
+ **Did that company just disclose something material?**
306
+ ```
307
+ Use extract_sec_filings with url "Palantir Technologies"
308
+ ```
309
+ 8-K filings are legally mandated within 4 business days of any material event — CEO change, acquisition, breach, major contract.
310
+
311
+ **Is this dependency still actively maintained?**
312
+ ```
313
+ Use extract_changelog with url "https://github.com/org/repo"
314
+ ```
315
+ Returns the last 8 releases with exact dates. If the last release was 18 months ago, you'll know before you pin the version.
316
+
317
+ ---
318
+
319
+ ## Deployment & infrastructure
320
+
321
+ The reference implementation runs on Cloudflare's global edge:
322
+
323
+ | Endpoint | Method | Purpose |
324
+ |---|---|---|
325
+ | `/` | GET | Service info + endpoint list |
326
+ | `/health` | GET | Liveness check |
327
+ | `/mcp` | POST | MCP JSON-RPC transport |
328
+ | `/demo` | GET | Live before/after demo (no API key required) |
329
+ | `/briefing` | GET | Latest stored briefing |
330
+ | `/v1/intel/feed/:profile_id` | GET | DAR-scored intelligence feed |
331
+ | `/watched-queries` | GET | List all watched queries |
332
+
333
+ - **D1 database** — 18 watched queries running on 6-hour cron with relevancy scoring
334
+ - **KV-backed rate limiting** — 60 req/min per IP across all edge nodes
335
+ - **Defensive valves** — clock-skew rejection (5min tolerance), hard floor at R_t<5, lazy decay at read time
336
+ - **Provenance** — Ha-Pri v1 SHA-256 provenance stamps on stored signals; hard tamper enforcement is a future Ha-Pri v2 path
337
+ - **Schema migrations** — promise-gated, idempotent, run on first request after deploy
338
+
339
+ Production: `https://freshcontext-mcp.gimmanuel73.workers.dev`
340
+
341
+ ---
342
+
343
+ ## Roadmap
344
+
345
+ - [x] FreshContext Specification v1.2 published (MIT, open standard)
346
+ - [x] DAR engine with proprietary λ constants (v0.3.18)
347
+ - [x] Ha-Pri v1 provenance signatures on stored signals
348
+ - [x] Semantic deduplication via fingerprinting
349
+ - [x] Live before/after demo at `/demo`
350
+ - [x] METHODOLOGY.md — formal IP and engineering documentation
351
+ - [x] 21 reference tools across intelligence, competitive research, market data, and composites
352
+ - [x] Core-backed envelope generation shared by npm/MCP and the Cloudflare Worker
353
+ - [x] Cloudflare Workers deployment — global edge, KV cache, KV rate limiting
354
+ - [x] Listed on official MCP Registry, Apify Store, npm
355
+ - [ ] Ha-Pri v2 hardened canonical content hash verification
356
+ - [x] GitHub Actions release workflow — manual or `v*` tag-triggered npm publish path
357
+ - [ ] Webhook triggers — push high-entropy signals on threshold
358
+ - [ ] Dashboard — React frontend for the D1 intelligence pipeline
359
+ - [ ] GKG upgrade for `extract_gdelt` — tone scores, goldstein scale, event codes
360
+
361
+ ---
362
+
363
+ ## Contributing
364
+
365
+ PRs welcome. New adapters are the highest-value contribution — see `src/adapters/` for the pattern and [`FRESHCONTEXT_SPEC.md`](./FRESHCONTEXT_SPEC.md) for the contract any adapter must fulfil.
366
+
367
+ If you're building something FreshContext-compatible, open an issue and we'll add you to the ecosystem list.
368
+
369
+ ---
370
+
371
+ ## Trust and security
372
+
373
+ - [LICENSE](./LICENSE)
374
+ - [SECURITY.md](./SECURITY.md)
375
+ - [NOTICE.md](./NOTICE.md)
376
+ - [TRADEMARKS.md](./TRADEMARKS.md)
377
+ - [Dependency diligence notes](./docs/DEPENDENCY_DILIGENCE.md)
378
+ - [Release integrity notes](./docs/RELEASE_INTEGRITY.md)
379
+ - [Release notes](./docs/RELEASE_NOTES.md)
380
+ - [Operational demo runbook](./docs/OPERATIONAL_DEMO_RUNBOOK.md)
381
+
382
+ ---
383
+
384
+ ## License
385
+
386
+ MIT
387
+
388
+ ---
389
+
390
+ *Built by Prince Gabriel — Grootfontein, Namibia 🇳🇦*
391
+ *"The work isn't gone. It's just waiting to be continued."*
392
+
393
+ ---
394
+
395
+ **Also on:** [Apify Store](https://apify.com/prince_gabriel/freshcontext-mcp) · [MCP Registry](https://registry.modelcontextprotocol.io) · [npm](https://www.npmjs.com/package/freshcontext-mcp)