freshcontext-mcp 0.3.13 → 0.3.15

package/.actor/Dockerfile

@@ -1,16 +1,19 @@
-FROM apify/actor-node:20
+FROM apify/actor-node-playwright-chrome:20
 
 # Copy package files first for better Docker layer caching
 COPY package*.json ./
 
-# Install all dependencies including apify SDK
+# Install dependencies
 RUN npm install --include=dev
 
+# Install Chromium matching the npm-installed Playwright version
+RUN npx playwright install chromium
+
 # Copy source and pre-built dist
 COPY . ./
 
-# Rebuild TypeScript (dist/ from repo is fallback if this fails)
+# Rebuild TypeScript
 RUN npm run build || echo "Build had warnings, using pre-compiled dist/"
 
-# Tell Apify to run the Actor entry point, not the MCP server
+# Run the Actor entry point
 CMD ["node", "dist/apify.js"]

package/.actor/actor.json

@@ -2,7 +2,7 @@
   "actorSpecification": 1,
   "name": "freshcontext-mcp",
   "title": "FreshContext MCP",
-  "version": "0.3.1",
+  "version": "0.21",
   "input": "../input_schema.json",
   "output": "./output_schema.json",
   "dockerfile": "./Dockerfile"

package/CONTEXT_SKILL.md

@@ -0,0 +1,84 @@
+# FreshContext Project Context Skill
+
+## Purpose
+Generate a compressed, structured context map of the FreshContext project state. Used at the start of new sessions to restore working context without re-reading full session saves. Reduces token usage by ~70% compared to full session save parsing.
+
+## When to use
+- Start of any new chat session on the FreshContext project
+- When context window is filling up and compression is needed
+- When asked to "load context", "restore state", or "what are we working on"
+
+## Output format
+
+Generate a context map in this structure:
+
+```
+PROJECT: FreshContext MCP
+STATE: [one line — what's live vs pending]
+
+CORE FILES:
+- worker/src/intelligence.ts  [DAR engine — exponential decay scoring]
+- worker/src/worker.ts        [Cloudflare Worker — all endpoints + cron]
+- worker/src/synthesize.ts    [Claude briefing synthesis — paused, needs key]
+- METHODOLOGY.md              [formal IP documentation]
+- FRESHCONTEXT_SPEC.md        [open standard v1.1]
+
+INFRASTRUCTURE:
+- Worker: https://freshcontext-mcp.gimmanuel73.workers.dev [LIVE]
+- D1: freshcontext-db (d9898d65-f67e-4dcb-abdc-7f7b53f2d444) [LIVE]
+- KV: RATE_LIMITER + CACHE [LIVE]
+- Cron: 0 */6 * * * [RUNNING]
+- npm: freshcontext-mcp@0.3.15 [LIVE]
+
+ENDPOINTS:
+/mcp                      — MCP transport (all tools)
+/briefing                 — GET latest stored briefing
+/briefing/now             — POST force scrape + synthesize
+/watched-queries          — GET list all watched queries
+/v1/intel/feed/:id        — GET DAR-scored intelligence feed
+/debug/db                 — GET D1 counts + recent scores
+/debug/scrape             — GET run one adapter raw
+
+DAR ENGINE (intelligence.ts):
+R_t = R_0 · e^(-λt)
+λ: HN=0.050 Reddit=0.010 Jobs=0.005 Finance=0.001 GitHub=0.0002 Scholar=0.00005
+Outputs: base_score, rt_score, entropy(low/stable/high), ha_pri_sig, published_at, semantic_fingerprint
+
+D1 SCHEMA additions (idempotent on every cron):
+base_score, rt_score, ha_pri_sig, entropy_level, published_at, semantic_fingerprint
+
+KNOWN ISSUES:
+- 12 TS type errors in worker.ts (type:"string" not literal "text") — wrangler deploys fine
+- 130 node_modules conflicts (workers-types vs @types/node) — cosmetic
+- Fix: add "skipLibCheck": true to tsconfig.json
+
+BLOCKED ON:
+- ANTHROPIC_KEY: not set — formatBriefing() fallback active
+- Paddle verification: pending
+
+NEXT BUILD PRIORITIES:
+1. Webhook/trigger system — push signals when rt_score > threshold
+2. Mining/industrial domain watched queries
+3. Profile population (user_profiles table exists, nothing writes to it)
+4. skipLibCheck tsconfig fix
+
+COMMITS (current):
+- d330dc3: DAR engine + intel feed endpoint
+- a965554: ToolResult type fix + SESSION_SAVE_V9
+- b9df76b: semantic deduplication + METHODOLOGY.md
+
+AUTHOR: Immanuel Gabriel · Grootfontein, Namibia · gimmanuel73@gmail.com
+```
+
+## Instructions for Claude
+
+At session start:
+1. Read SESSION_SAVE_V9.md for detailed state
+2. Output the context map above — compressed, no prose
+3. Ask: "What are we working on today?"
+
+Mid-session update: revise only changed fields. Don't regenerate the full map.
+
+## Token budget
+Full session save: ~2,500 tokens. This map: ~400 tokens.
+Use this for orientation. Use session saves only for deep debugging.

package/FRESHCONTEXT_SPEC.md

@@ -1,5 +1,5 @@
 # The FreshContext Specification
-**Version 1.0 — March 2026**
+**Version 1.1 — April 2026**
 *Authored by Immanuel Gabriel (Prince Gabriel) — Grootfontein, Namibia*
 
 ---
@@ -51,7 +51,7 @@ Confidence: <high|medium|low>
 ### `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`*
+*Examples: GitHub API `pushed_at`, arXiv submission date, Hacker News `created_at`, SEC EDGAR filing date, USASpending.gov award date*
 
 ### `medium`
 The publication date was inferred from page signals — visible date strings, URL patterns, or content heuristics. Likely correct but not guaranteed.
@@ -91,7 +91,22 @@ 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).
+Where `decay_rate` defaults to `1.5` for general web content. Implementations MAY use domain-specific decay rates to reflect how quickly different categories of data become unreliable.
+
+#### Recommended Decay Rates by Domain
+
+| Category | Decay Rate | Approximate Half-life | Examples |
+|---|---|---|---|
+| Financial data | 5.0 | ~10 days | Stock prices, market cap, P/E ratios |
+| Job listings | 3.0 | ~17 days | Remote job boards, HN Who is Hiring |
+| News / HN / Reddit | 2.0 | ~25 days | Top stories, community discussion |
+| Government procurement | 1.5 | ~33 days | USASpending.gov, GeBIZ tenders |
+| GitHub repositories | 1.0 | ~50 days | Stars, forks, last commit, README |
+| Product releases | 1.0 | ~50 days | Changelog entries, npm versions |
+| Academic papers | 0.3 | ~167 days | arXiv submissions, Google Scholar |
+| General web content | 1.5 | ~33 days | Default for unclassified sources |
+
+#### Score Interpretation
 
 | Score | Interpretation |
 |---|---|
@@ -116,6 +131,22 @@ 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
+- Use domain-specific decay rates from the recommended table above
+
+---
+
+## Composite Adapters
+
+A **composite adapter** is a FreshContext-compatible adapter that calls multiple upstream adapters in parallel and combines their results into a single unified response. Each upstream result MUST retain its own FreshContext envelope — the composite wrapper MUST NOT collapse individual timestamps into a single envelope.
+
+Composite adapters SHOULD:
+
+- Fire all upstream calls in parallel (e.g. `Promise.allSettled`)
+- Handle partial failures gracefully — if one upstream fails, return the rest
+- Label each section clearly with its source adapter name
+- Include a composite `retrieved_at` timestamp representing the time the composite call was initiated
+
+*Examples in the reference implementation: `extract_landscape`, `extract_company_landscape`, `extract_idea_landscape`*
 
 ---
 
@@ -127,11 +158,13 @@ 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
+- An agent synthesising news may present last year's controversy as current
 
 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
+- Composite intelligence reports carry per-source freshness signals
 
 ---
 
@@ -144,25 +177,66 @@ A tool, server, or API is **FreshContext-compatible** if:
 
 Partial implementations that include only `retrieved_at` without `freshness_confidence` are considered **FreshContext-aware** but not fully compatible.
 
+### Compatibility Levels
+
+| Level | Requirements |
+|---|---|
+| **FreshContext-compatible** | Full envelope OR full JSON form with `retrieved_at` + `freshness_confidence` |
+| **FreshContext-aware** | Includes `retrieved_at` but not `freshness_confidence` |
+| **FreshContext-scored** | Full compatible + numeric `freshness_score` with domain-specific decay |
+
 ---
 
 ## 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.
+**freshcontext-mcp** — an MCP server with 20 adapters covering:
+
+**Intelligence:** GitHub, Hacker News, Google Scholar, arXiv, Reddit
+
+**Competitive research:** YC Companies, Product Hunt, GitHub repo search, npm/PyPI package trends
+
+**Market data:** Yahoo Finance (up to 5 tickers), job listings (Remotive, RemoteOK, HN Hiring)
+
+**Unique — not available in any other MCP server:**
+- `extract_changelog` — release history from any repo, npm package, or website
+- `extract_govcontracts` — US federal contract awards (USASpending.gov)
+- `extract_sec_filings` — SEC 8-K material event disclosures (EDGAR)
+- `extract_gdelt` — global news intelligence, 100+ languages, updated every 15 minutes
+- `extract_gebiz` — Singapore Government procurement (data.gov.sg)
 
+**Composite landscapes:** `extract_landscape`, `extract_idea_landscape`, `extract_gov_landscape`, `extract_finance_landscape`, `extract_company_landscape`
+
+**Deployment:**
 - npm: `freshcontext-mcp`
 - GitHub: https://github.com/PrinceGabriel-lgtm/freshcontext-mcp
 - Cloud endpoint: `https://freshcontext-mcp.gimmanuel73.workers.dev/mcp`
+- Apify Store: `https://apify.com/prince_gabriel/freshcontext-mcp`
+- MCP Registry: `io.github.PrinceGabriel-lgtm/freshcontext`
+
+---
+
+## Changelog
+
+### Version 1.1 — April 2026
+- Added Composite Adapters section
+- Added domain-specific decay rate table with recommended values
+- Added Compatibility Levels table (compatible / aware / scored)
+- Updated reference implementation to 20 adapters
+- Added `extract_gdelt`, `extract_gebiz`, `extract_sec_filings` to high-confidence examples
+- Added Apify Store and MCP Registry to reference implementation listings
+
+### Version 1.0 — March 2026
+- Initial specification published
 
 ---
 
 ## Versioning
 
-This document is version 1.0 of the FreshContext Specification.
+This document is version 1.1 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.
+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, new recommended values) will increment the minor version.
 
 ---