freshcontext-mcp 0.1.9 → 0.3.0

package/README.md

@@ -1,257 +1,212 @@
-# freshcontext-mcp
-
-> Timestamped web intelligence for AI agents. Every result is wrapped in a **FreshContext envelope** — so your agent always knows *when* it's looking at data, not just *what*.
-
-[![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)
-
----
-
-## The Problem
-
-LLMs hallucinate recency. They'll cite a 2022 job posting as "current", recall outdated API docs as if they're live, or tell you a project is active when it hasn't been touched in two years. This happens because they have no reliable signal for *when* data was retrieved vs. when it was published.
-
-Existing MCP servers return raw content. No timestamp. No confidence signal. No way for the agent to know if it's looking at something from this morning or three years ago.
-
-## The Fix: FreshContext Envelope
-
-Every piece of data extracted by `freshcontext-mcp` is wrapped in a structured envelope:
-
-```
-[FRESHCONTEXT]
-Source: https://github.com/owner/repo
-Published: 2024-11-03
-Retrieved: 2026-03-04T10:14:00Z
-Confidence: high
----
-... content ...
-[/FRESHCONTEXT]
-```
-
-The AI agent always knows **when it's looking at data**, not just what the data says.
-
----
-
-## Tools
-
-### 🔬 Intelligence Tools
-
-| Tool | Description |
-|---|---|
-| `extract_github` | README, stars, forks, language, topics, last commit from any GitHub repo |
-| `extract_hackernews` | Top stories or search results from HN with scores and timestamps |
-| `extract_scholar` | Research paper titles, authors, years, and snippets from Google Scholar |
-| `extract_reddit` | Posts and community sentiment from any subreddit or Reddit search |
-
-### 🚀 Competitive Intelligence Tools
-
-| Tool | Description |
-|---|---|
-| `extract_yc` | Scrape YC company listings by keyword — find who's funded in your space |
-| `extract_producthunt` | Recent Product Hunt launches by keyword or topic |
-| `search_repos` | Search GitHub for similar/competing repos, ranked by stars with activity signals |
-| `package_trends` | npm and PyPI package metadata — version history, release cadence, last updated |
-
-### 📈 Market Data
-
-| Tool | Description |
-|---|---|
-| `extract_finance` | Live stock data via Yahoo Finance — price, market cap, P/E, 52w range, sector, company summary |
-
-### 🗺️ Composite Tool
-
-| Tool | Description |
-|---|---|
-| `extract_landscape` | **One call. Full picture.** Queries YC + GitHub + HN + npm/PyPI simultaneously. Returns a unified timestamped landscape report. |
-
----
-
-## Quick Start
-
-### Option A — Cloud (recommended, no install needed)
-
-Visit **[freshcontext-site.pages.dev](https://freshcontext-site.pages.dev)** for a guided 3-step install with copy-paste config. No terminal, no downloads, no antivirus alerts.
-
-Or add this manually 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 Desktop. The freshcontext tools will appear in your session.
-
-> If `claude_desktop_config.json` doesn't exist yet, create it with the content above.
-
----
-
-### Option B — Local (full Playwright, for heavy use)
-
-**Prerequisites:** 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
-```
-
-Then add to your 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"** — Node isn't on Claude Desktop's PATH. Use the full path:
-```bash
-which node   # copy this output
-```
-Replace `"command": "node"` with `"command": "/usr/local/bin/node"` (or whatever `which node` returned).
-
-**"npx: command not found"** — Same fix. Run `which npx` and use the full path.
-
-**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
-
-### Check if anyone is already building what you're building
-```
-Use extract_landscape with topic "cashflow prediction mcp"
-```
-Returns a unified report: who's funded (YC), what's trending (HN), what repos exist (GitHub), what packages are active (npm/PyPI). All timestamped.
-
-### Get community sentiment on a topic
-```
-Use extract_reddit with url "r/MachineLearning"
-Use extract_hackernews with url "https://hn.algolia.com/api/v1/search?query=mcp+server&tags=story"
-```
-
-### Check a company's stock
-```
-Use extract_finance with url "NVDA,MSFT,GOOG"
-```
-
-### Find what just launched in your space
-```
-Use extract_producthunt with url "AI developer tools"
-```
-
----
-
-## Why FreshContext?
-
-Most AI agents retrieve data but don't timestamp it. This creates a silent failure mode: the agent presents stale information with the same confidence as fresh information. The user has no way to know the difference.
-
-FreshContext treats **retrieval time as first-class metadata**. Every adapter returns:
-
-- `retrieved_at` — exact ISO timestamp of when the data was fetched
-- `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
-
----
-
-## Security
-
-- Input sanitization and domain allowlists on all adapters
-- SSRF prevention (blocked private IP ranges)
-- KV-backed global rate limiting: 60 requests/minute per IP across all edge nodes
-- No credentials required for public data sources
-
----
-
-## Project Structure
-
-```
-freshcontext-mcp/
-├── src/
-│   ├── server.ts              # MCP server, all tool registrations
-│   ├── types.ts               # FreshContext interfaces
-│   ├── security.ts            # Input validation, domain allowlists, SSRF prevention
-│   ├── adapters/
-│   │   ├── github.ts
-│   │   ├── hackernews.ts
-│   │   ├── scholar.ts
-│   │   ├── yc.ts
-│   │   ├── repoSearch.ts
-│   │   ├── packageTrends.ts
-│   │   ├── reddit.ts
-│   │   ├── productHunt.ts
-│   │   └── finance.ts
-│   └── tools/
-│       └── freshnessStamp.ts
-└── worker/                    # Cloudflare Workers deployment (all 10 tools)
-    └── src/worker.ts
-```
-
----
-
-## Roadmap
-
-- [x] GitHub adapter
-- [x] Hacker News adapter
-- [x] Google Scholar adapter
-- [x] YC startup scraper
-- [x] GitHub repo search
-- [x] npm/PyPI package trends
-- [x] `extract_landscape` composite tool
-- [x] Cloudflare Workers deployment
-- [x] Worker auth + KV-backed global rate limiting
-- [x] Reddit community sentiment adapter
-- [x] Product Hunt launches adapter
-- [x] Yahoo Finance market data adapter
-- [ ] `extract_arxiv` — structured arXiv API (more reliable than Scholar)
-- [ ] TTL-based caching layer
-- [ ] `freshness_score` numeric metric
-
----
-
-## Contributing
-
-PRs welcome. New adapters are the highest-value contribution — see `src/adapters/` for the pattern. Each adapter returns `{ raw, content_date, freshness_confidence }`.
-
----
-
-## 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.
+
+---
+
+## 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

package/dist/adapters/jobs.js

@@ -1,139 +1,309 @@
 /**
- * Jobs adapter — two sources, pure fetch, no auth required.
+ * Jobs adapter v3 — 5 sources, freshness badges, location + keyword filtering.
  *
- * Source 1: Remotive API (structured remote jobs, publication_date on every listing)
- *   https://remotive.com/api/remote-jobs?search=QUERY&limit=10
+ * Sources (all no-auth):
+ *   - Remotive       — remote tech jobs, salary data
+ *   - RemoteOK       — pure remote, unix timestamps
+ *   - Arbeitnow      — broad jobs API (tech + non-tech, location-aware)
+ *   - The Muse       — structured listings, level info
+ *   - HN Who is Hiring — monthly thread, community-sourced
  *
- * Source 2: HN "Who is Hiring" comments (community-sourced, timestamped)
- *   Searches Algolia for relevant comments in hiring threads
- *
- * This adapter was the whole reason freshcontext exists.
- * Claude kept returning job listings from 2022. This fixes that.
+ * Freshness badges on every listing:
+ *   🟢 < 7 days     — FRESH, apply now
+ *   🟡 7–30 days    — still good
+ *   🔴 31–90 days   — apply with caution
+ *   ⛔ > 90 days    — likely expired, shown last
  */
+// ─── Freshness Scoring ────────────────────────────────────────────────────────
+function freshnessBadge(dateStr) {
+    if (!dateStr)
+        return { badge: "❓ Unknown date", days: 9999 };
+    const days = Math.floor((Date.now() - new Date(dateStr).getTime()) / 86400000);
+    if (days < 0)
+        return { badge: "🟢 Just posted — FRESH", days: 0 };
+    if (days <= 7)
+        return { badge: `🟢 ${days}d ago — FRESH`, days };
+    if (days <= 30)
+        return { badge: `🟡 ${days}d ago`, days };
+    if (days <= 90)
+        return { badge: `🔴 ${days}d ago — apply with caution`, days };
+    return { badge: `⛔ ${days}d ago — likely expired`, days };
+}
+function matchesLocation(locationField, filterLocation) {
+    if (!filterLocation || filterLocation.toLowerCase() === "worldwide" || filterLocation.toLowerCase() === "remote")
+        return true;
+    const loc = locationField.toLowerCase();
+    const filter = filterLocation.toLowerCase();
+    return (loc.includes(filter) ||
+        filter.includes(loc) ||
+        loc.includes("worldwide") ||
+        loc.includes("anywhere") ||
+        loc.includes("remote"));
+}
+function highlightKeywords(text, keywords) {
+    if (!keywords.length)
+        return text;
+    let result = text;
+    for (const kw of keywords) {
+        const re = new RegExp(`(${kw})`, "gi");
+        result = result.replace(re, "⚡$1");
+    }
+    return result;
+}
+// ─── Main Adapter ─────────────────────────────────────────────────────────────
 export async function jobsAdapter(options) {
     const query = options.url.trim();
-    const maxLength = options.maxLength ?? 6000;
-    const perSource = Math.floor(maxLength / 2);
-    const [remotiveResult, hnResult] = await Promise.allSettled([
-        fetchRemotive(query, perSource),
-        fetchHNHiring(query, perSource),
+    const maxLength = options.maxLength ?? 8000;
+    const location = options.location ?? "";
+    const remoteOnly = options.remoteOnly ?? false;
+    const maxAgeDays = options.maxAgeDays ?? 60;
+    const keywords = options.keywords ?? [];
+    const [remotiveRes, remoteOkRes, arbeitnowRes, museRes, hnRes] = await Promise.allSettled([
+        fetchRemotive(query, location, maxAgeDays, keywords),
+        fetchRemoteOK(query, location, maxAgeDays, keywords),
+        fetchArbeitnow(query, location, maxAgeDays, keywords, remoteOnly),
+        remoteOnly ? Promise.reject("skipped") : fetchMuse(query, location, maxAgeDays, keywords),
+        fetchHNHiring(query, location, maxAgeDays, keywords),
     ]);
-    const sections = [];
-    let newestDate = null;
-    const trackDate = (d) => {
-        if (d && (!newestDate || d > newestDate))
-            newestDate = d;
+    const pool = [];
+    const sourceStats = {};
+    const harvest = (res, label) => {
+        if (res.status === "fulfilled") {
+            pool.push(...res.value.listings);
+            sourceStats[label] = res.value.listings.length;
+        }
+        else {
+            sourceStats[label] = 0;
+        }
     };
-    // ── Remotive ──────────────────────────────────────────────────────────────
-    if (remotiveResult.status === "fulfilled" && remotiveResult.value.raw) {
-        sections.push(`## 🌐 Remote Jobs (Remotive)\n${remotiveResult.value.raw}`);
-        trackDate(remotiveResult.value.content_date);
-    }
-    else if (remotiveResult.status === "rejected") {
-        sections.push(`## 🌐 Remote Jobs (Remotive)\n[Unavailable: ${remotiveResult.reason}]`);
-    }
-    // ── HN Who is Hiring ──────────────────────────────────────────────────────
-    if (hnResult.status === "fulfilled" && hnResult.value.raw) {
-        sections.push(`## 💬 HN "Who is Hiring" (Community)\n${hnResult.value.raw}`);
-        trackDate(hnResult.value.content_date);
-    }
-    else if (hnResult.status === "rejected") {
-        sections.push(`## 💬 HN "Who is Hiring"\n[Unavailable: ${hnResult.reason}]`);
-    }
-    if (!sections.length) {
+    harvest(remotiveRes, "Remotive");
+    harvest(remoteOkRes, "RemoteOK");
+    harvest(arbeitnowRes, "Arbeitnow");
+    harvest(museRes, "The Muse");
+    harvest(hnRes, "HN Hiring");
+    if (!pool.length) {
         return {
-            raw: `No job results found for "${query}". Try broader terms like "typescript", "remote python", or "senior engineer".`,
+            raw: [
+                `No job listings found for "${query}"${location ? ` in ${location}` : ""}.`,
+                "",
+                "Tips:",
+                "• Try broader terms e.g. \"engineer\" instead of \"senior TypeScript engineer\"",
+                "• Set location to \"remote\" for worldwide results",
+                "• Increase max_age_days (default: 60)",
+                "• Note: FIFO/mining/trades jobs are on specialist boards (myJobsNamibia, SEEK, mining-specific sites) — these sources are tech/remote focused",
+            ].join("\n"),
             content_date: null,
             freshness_confidence: "low",
         };
     }
-    const raw = [
-        `# Job Search: "${query}"`,
-        `⚠️  Every listing below includes its publication date. Check it before you apply.`,
+    // Sort: freshest first
+    pool.sort((a, b) => a.days - b.days);
+    const freshCount = pool.filter(l => l.days <= 7).length;
+    const goodCount = pool.filter(l => l.days > 7 && l.days <= 30).length;
+    const staleCount = pool.filter(l => l.days > 30).length;
+    const sourceSummary = Object.entries(sourceStats)
+        .map(([src, n]) => `${src}:${n}`)
+        .join("  ");
+    const header = [
+        `# Job Search: "${query}"${location ? ` · ${location}` : ""}${remoteOnly ? " · remote only" : ""}`,
+        `Retrieved: ${new Date().toISOString()}`,
+        `Found: ${pool.length} listings — 🟢 ${freshCount} fresh  🟡 ${goodCount} recent  🔴 ${staleCount} older`,
+        `Sources: ${sourceSummary}`,
+        `⚠️  Sorted freshest first. Check badge before applying.`,
+        keywords.length ? `🔍 Watching for: ${keywords.map(k => `⚡${k}`).join(", ")}` : null,
         "",
-        ...sections,
-    ].join("\n\n");
+    ].filter(Boolean).join("\n");
+    const body = pool
+        .map(l => l.text)
+        .join("\n\n─────────────────────────────\n\n");
+    const raw = (header + "\n\n" + body).slice(0, maxLength);
+    const freshestDays = pool[0]?.days ?? 9999;
+    const newestDate = freshestDays < 9999
+        ? new Date(Date.now() - freshestDays * 86400000).toISOString().slice(0, 10)
+        : null;
     return {
-        raw: raw.slice(0, maxLength),
+        raw,
         content_date: newestDate,
-        freshness_confidence: newestDate ? "high" : "medium",
+        freshness_confidence: freshestDays <= 7 ? "high" : freshestDays <= 30 ? "medium" : "low",
     };
 }
-// ─── Remotive ─────────────────────────────────────────────────────────────────
-async function fetchRemotive(query, maxLength) {
-    const url = `https://remotive.com/api/remote-jobs?search=${encodeURIComponent(query)}&limit=10`;
+// ─── Source: Remotive ─────────────────────────────────────────────────────────
+async function fetchRemotive(query, location, maxAgeDays, keywords) {
+    const url = `https://remotive.com/api/remote-jobs?search=${encodeURIComponent(query)}&limit=15`;
     const res = await fetch(url, {
-        headers: {
-            "User-Agent": "freshcontext-mcp/0.1.9 (https://github.com/PrinceGabriel-lgtm/freshcontext-mcp)",
-            "Accept": "application/json",
-        },
+        headers: { "User-Agent": "freshcontext-mcp/0.3.0", "Accept": "application/json" },
     });
     if (!res.ok)
-        throw new Error(`Remotive API error: ${res.status}`);
+        throw new Error(`Remotive ${res.status}`);
     const data = await res.json();
-    if (!data.jobs?.length) {
-        return { raw: `No remote listings found for "${query}".`, content_date: null, freshness_confidence: "medium" };
-    }
-    const listings = data.jobs.map((job, i) => {
-        const lines = [
-            `[${i + 1}] ${job.title} — ${job.company_name}`,
-            `Type: ${job.job_type || "N/A"} | Location: ${job.candidate_required_location || "Remote"}`,
-            `Posted: ${job.publication_date}`,
-            job.salary ? `Salary: ${job.salary}` : null,
-            job.tags?.length ? `Tags: ${job.tags.slice(0, 5).join(", ")}` : null,
-            `Apply: ${job.url}`,
-        ].filter(Boolean).join("\n");
-        return lines;
+    const listings = (data.jobs ?? [])
+        .filter(j => matchesLocation(j.candidate_required_location ?? "", location))
+        .map(j => {
+        const { badge, days } = freshnessBadge(j.publication_date);
+        if (days > maxAgeDays)
+            return null;
+        const text = highlightKeywords([
+            `[Remotive] ${j.title} — ${j.company_name}`,
+            badge,
+            `Location: ${j.candidate_required_location || "Remote"} | Type: ${j.job_type || "N/A"}`,
+            j.salary ? `Salary: ${j.salary}` : null,
+            j.tags?.length ? `Tags: ${j.tags.slice(0, 6).join(", ")}` : null,
+            `Apply: ${j.url}`,
+        ].filter(Boolean).join("\n"), keywords);
+        return { text, days, source: "remotive" };
+    })
+        .filter((l) => l !== null)
+        .slice(0, 8);
+    return { listings };
+}
+// ─── Source: RemoteOK ─────────────────────────────────────────────────────────
+async function fetchRemoteOK(query, location, maxAgeDays, keywords) {
+    const tag = query.toLowerCase().replace(/\s+/g, "-");
+    const url = `https://remoteok.com/api?tag=${encodeURIComponent(tag)}`;
+    const res = await fetch(url, {
+        headers: { "User-Agent": "freshcontext-mcp/0.3.0", "Accept": "application/json" },
     });
-    const raw = listings.join("\n\n").slice(0, maxLength);
-    const dates = data.jobs
-        .map(j => j.publication_date)
-        .filter(Boolean)
-        .sort()
-        .reverse();
-    return {
-        raw,
-        content_date: dates[0] ?? null,
-        freshness_confidence: dates[0] ? "high" : "medium",
-    };
+    if (!res.ok)
+        throw new Error(`RemoteOK ${res.status}`);
+    const raw = await res.json();
+    const jobs = raw.filter(j => j.id && j.position);
+    const listings = jobs
+        .filter(j => matchesLocation(j.location ?? "Remote", location))
+        .map(j => {
+        const dateStr = j.date ?? (j.epoch ? new Date(j.epoch * 1000).toISOString() : null);
+        const { badge, days } = freshnessBadge(dateStr);
+        if (days > maxAgeDays)
+            return null;
+        const salary = j.salary_min && j.salary_max
+            ? `$${(j.salary_min / 1000).toFixed(0)}k–$${(j.salary_max / 1000).toFixed(0)}k`
+            : null;
+        const text = highlightKeywords([
+            `[RemoteOK] ${j.position} — ${j.company ?? "Unknown"}`,
+            badge,
+            `Location: ${j.location || "Remote Worldwide"}`,
+            salary ? `Salary: ${salary}` : null,
+            j.tags?.length ? `Tags: ${j.tags.slice(0, 6).join(", ")}` : null,
+            j.url ? `Apply: ${j.url}` : null,
+        ].filter(Boolean).join("\n"), keywords);
+        return { text, days, source: "remoteok" };
+    })
+        .filter((l) => l !== null)
+        .slice(0, 8);
+    return { listings };
 }
-// ─── HN Who is Hiring ─────────────────────────────────────────────────────────
-async function fetchHNHiring(query, maxLength) {
-    const url = `https://hn.algolia.com/api/v1/search?query=${encodeURIComponent(query + " hiring")}&tags=comment&hitsPerPage=8`;
+// ─── Source: Arbeitnow (NEW) ──────────────────────────────────────────────────
+// Free public API — broader than tech boards. Good for non-remote, non-tech roles.
+async function fetchArbeitnow(query, location, maxAgeDays, keywords, remoteOnly) {
+    const params = new URLSearchParams({ search: query });
+    if (remoteOnly)
+        params.set("remote", "true");
+    const url = `https://arbeitnow.com/api/job-board-api?${params.toString()}`;
     const res = await fetch(url, {
-        headers: { "User-Agent": "freshcontext-mcp/0.1.9" },
+        headers: { "User-Agent": "freshcontext-mcp/0.3.0", "Accept": "application/json" },
     });
     if (!res.ok)
-        throw new Error(`HN Algolia error: ${res.status}`);
+        throw new Error(`Arbeitnow ${res.status}`);
     const data = await res.json();
-    const jobHits = data.hits.filter(h => {
-        const t = (h.comment_text ?? "").toLowerCase();
-        return (t.includes("hiring") ||
-            t.includes("remote") ||
-            t.includes("full-time") ||
-            t.includes("salary") ||
-            t.includes("apply"));
+    const listings = (data.data ?? [])
+        .filter(j => matchesLocation(j.location ?? "", location))
+        .map(j => {
+        const dateStr = new Date(j.created_at * 1000).toISOString();
+        const { badge, days } = freshnessBadge(dateStr);
+        if (days > maxAgeDays)
+            return null;
+        const text = highlightKeywords([
+            `[Arbeitnow] ${j.title} — ${j.company_name}`,
+            badge,
+            `Location: ${j.location || "Remote"}${j.remote ? " (Remote OK)" : ""}`,
+            j.job_types?.length ? `Type: ${j.job_types.join(", ")}` : null,
+            j.tags?.length ? `Tags: ${j.tags.slice(0, 6).join(", ")}` : null,
+            `Apply: ${j.url}`,
+        ].filter(Boolean).join("\n"), keywords);
+        return { text, days, source: "arbeitnow" };
+    })
+        .filter((l) => l !== null)
+        .slice(0, 8);
+    return { listings };
+}
+// ─── Source: The Muse ─────────────────────────────────────────────────────────
+// Fixed: now uses `name` param for text search instead of `category`
+async function fetchMuse(query, location, maxAgeDays, keywords) {
+    const locParam = location && location.toLowerCase() !== "remote"
+        ? `&location=${encodeURIComponent(location)}`
+        : "&location=Flexible%20%2F%20Remote";
+    const url = `https://www.themuse.com/api/public/jobs?name=${encodeURIComponent(query)}${locParam}&page=0&descending=true`;
+    const res = await fetch(url, {
+        headers: { "User-Agent": "freshcontext-mcp/0.3.0", "Accept": "application/json" },
     });
-    if (!jobHits.length) {
-        return { raw: `No HN hiring comments found for "${query}".`, content_date: null, freshness_confidence: "medium" };
-    }
-    const listings = jobHits.map((hit, i) => {
-        const text = (hit.comment_text ?? "")
+    if (!res.ok)
+        throw new Error(`The Muse ${res.status}`);
+    const data = await res.json();
+    const listings = (data.results ?? [])
+        .map(j => {
+        const locationStr = j.locations?.map(l => l.name).join(", ") || "Flexible/Remote";
+        const { badge, days } = freshnessBadge(j.publication_date);
+        if (days > maxAgeDays)
+            return null;
+        const level = j.levels?.map(l => l.name).join(", ") || null;
+        const text = highlightKeywords([
+            `[The Muse] ${j.name} — ${j.company?.name ?? "Unknown"}`,
+            badge,
+            `Location: ${locationStr}`,
+            level ? `Level: ${level}` : null,
+            `Apply: ${j.refs?.landing_page ?? "N/A"}`,
+        ].filter(Boolean).join("\n"), keywords);
+        return { text, days, source: "themuse" };
+    })
+        .filter((l) => l !== null)
+        .slice(0, 8);
+    return { listings };
+}
+// ─── Source: HN Who is Hiring ─────────────────────────────────────────────────
+// Fixed: now searches within the actual monthly "Who is Hiring" thread
+// instead of all HN comments. Uses the parent_id filter to target the thread.
+async function fetchHNHiring(query, location, maxAgeDays, keywords) {
+    // Step 1: Find the most recent "Ask HN: Who is hiring?" thread
+    const threadRes = await fetch(`https://hn.algolia.com/api/v1/search?query=Ask+HN+Who+is+hiring&tags=story&hitsPerPage=5`, { headers: { "User-Agent": "freshcontext-mcp/0.3.0" } });
+    if (!threadRes.ok)
+        throw new Error(`HN thread search ${threadRes.status}`);
+    const threadData = await threadRes.json();
+    // Pick most recent hiring thread (they post monthly)
+    const hiringThread = threadData.hits.find(h => h.title?.toLowerCase().includes("who is hiring"));
+    if (!hiringThread)
+        throw new Error("HN hiring thread not found");
+    // Step 2: Search comments within that thread for the query
+    const searchTerms = [query, location].filter(Boolean).join(" ");
+    const commentsRes = await fetch(`https://hn.algolia.com/api/v1/search?query=${encodeURIComponent(searchTerms)}&tags=comment,story_${hiringThread.objectID}&hitsPerPage=10`, { headers: { "User-Agent": "freshcontext-mcp/0.3.0" } });
+    if (!commentsRes.ok)
+        throw new Error(`HN comments ${commentsRes.status}`);
+    const commentsData = await commentsRes.json();
+    const listings = (commentsData.hits ?? [])
+        .filter(h => {
+        const t = (h.comment_text ?? "").toLowerCase();
+        // Must look like a job post, not a meta comment
+        return t.length > 50 && (t.includes("hiring") || t.includes("remote") ||
+            t.includes("full-time") || t.includes("apply") ||
+            t.includes("|") // common delimiter in HN job posts
+        );
+    })
+        .map(h => {
+        const { badge, days } = freshnessBadge(h.created_at);
+        if (days > maxAgeDays)
+            return null;
+        const excerpt = (h.comment_text ?? "")
             .replace(/<[^>]+>/g, " ")
             .replace(/\s+/g, " ")
             .trim()
-            .slice(0, 300);
-        return [
-            `[${i + 1}] Posted by ${hit.author} on ${hit.created_at.slice(0, 10)}`,
-            text + (text.length >= 300 ? "…" : ""),
-            `Source: https://news.ycombinator.com/item?id=${hit.objectID}`,
-        ].join("\n");
-    });
-    const raw = listings.join("\n\n").slice(0, maxLength);
-    const dates = jobHits.map(h => h.created_at).sort().reverse();
-    return {
-        raw,
-        content_date: dates[0]?.slice(0, 10) ?? null,
-        freshness_confidence: dates[0] ? "high" : "medium",
-    };
+            .slice(0, 400);
+        const text = highlightKeywords([
+            `[HN Hiring · ${hiringThread.title}] by ${h.author}`,
+            badge,
+            excerpt + (excerpt.length >= 400 ? "…" : ""),
+            `Source: https://news.ycombinator.com/item?id=${h.objectID}`,
+        ].join("\n"), keywords);
+        return { text, days, source: "hn" };
+    })
+        .filter((l) => l !== null)
+        .slice(0, 6);
+    return { listings };
 }

package/dist/server.js

@@ -155,15 +155,26 @@ server.registerTool("extract_landscape", {
 });
 // ─── Tool: search_jobs ───────────────────────────────────────────────────────
 server.registerTool("search_jobs", {
-    description: "Search for real-time job listings with publication dates on every result — so you never apply to a role that closed 2 years ago. Sources: Remotive (remote jobs) + HN 'Who is Hiring' (community). Returns timestamped freshcontext.",
+    description: "Search for real-time job listings with freshness badges on every result — so you never apply to a role that closed months ago. Sources: Remotive + RemoteOK + The Muse + HN 'Who is Hiring'. Supports location filtering, remote-only mode, keyword spotting (e.g. FIFO), and max age filtering. Returns timestamped freshcontext sorted freshest first.",
     inputSchema: z.object({
-        query: z.string().describe("Job search query e.g. 'typescript remote', 'senior python', 'mcp developer'"),
-        max_length: z.number().optional().default(6000).describe("Max content length"),
+        query: z.string().describe("Job search query e.g. 'typescript', 'mining engineer', 'FIFO operator', 'data analyst'"),
+        location: z.string().optional().describe("Country, city, or 'remote' / 'worldwide' e.g. 'South Africa', 'Australia', 'remote'"),
+        remote_only: z.boolean().optional().default(false).describe("Only return remote-friendly listings"),
+        max_age_days: z.number().optional().default(60).describe("Hide listings older than N days (default 60, use 7 for very fresh only)"),
+        keywords: z.array(z.string()).optional().default([]).describe("Keywords to highlight in results e.g. ['FIFO', 'underground', 'contract']"),
+        max_length: z.number().optional().default(8000),
     }),
     annotations: { readOnlyHint: true, openWorldHint: true },
-}, async ({ query, max_length }) => {
+}, async ({ query, location, remote_only, max_age_days, keywords, max_length }) => {
     try {
-        const result = await jobsAdapter({ url: query, maxLength: max_length });
+        const result = await jobsAdapter({
+            url: query,
+            maxLength: max_length,
+            location: location ?? "",
+            remoteOnly: remote_only,
+            maxAgeDays: max_age_days,
+            keywords: keywords ?? [],
+        });
         const ctx = stampFreshness(result, { url: query, maxLength: max_length }, "jobs");
         return { content: [{ type: "text", text: formatForLLM(ctx) }] };
     }

package/package.json

@@ -1,55 +1,51 @@
-{
-  "name": "freshcontext-mcp",
-  "mcpName": "io.github.PrinceGabriel-lgtm/freshcontext",
-  "version": "0.1.9",
-  "description": "Real-time web extraction MCP server with freshness timestamps for AI agents",
-  "keywords": [
-    "mcp",
-    "mcp-server",
-    "ai-agents",
-    "llm",
-    "freshness",
-    "web-scraping",
-    "github-analytics",
-    "hackernews",
-    "yc",
-    "typescript",
-    "context",
-    "model-context-protocol"
-  ],
-  "homepage": "https://github.com/PrinceGabriel-lgtm/freshcontext-mcp",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/PrinceGabriel-lgtm/freshcontext-mcp.git"
-  },
-  "license": "MIT",
-  "type": "module",
-  "main": "dist/server.js",
-  "bin": {
-    "freshcontext-mcp": "dist/server.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsx watch src/server.ts",
-    "start": "node dist/server.js",
-    "inspect": "npx @modelcontextprotocol/inspector tsx src/server.ts",
-    "test": "jest"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "playwright": "^1.44.0",
-    "zod": "^3.23.0",
-    "dotenv": "^16.4.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "tsx": "^4.0.0",
-    "typescript": "^5.4.0",
-    "jest": "^29.0.0",
-    "@types/jest": "^29.0.0"
-  }
-}
-
-
-
-
+{
+  "name": "freshcontext-mcp",
+  "mcpName": "io.github.PrinceGabriel-lgtm/freshcontext",
+  "version": "0.3.0",
+  "description": "Real-time web extraction MCP server with freshness timestamps for AI agents",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "ai-agents",
+    "llm",
+    "freshness",
+    "web-scraping",
+    "github-analytics",
+    "hackernews",
+    "yc",
+    "typescript",
+    "context",
+    "model-context-protocol"
+  ],
+  "homepage": "https://github.com/PrinceGabriel-lgtm/freshcontext-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PrinceGabriel-lgtm/freshcontext-mcp.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/server.js",
+  "bin": {
+    "freshcontext-mcp": "dist/server.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/server.ts",
+    "start": "node dist/server.js",
+    "inspect": "npx @modelcontextprotocol/inspector tsx src/server.ts",
+    "test": "jest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "playwright": "^1.44.0",
+    "zod": "^3.23.0",
+    "dotenv": "^16.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0",
+    "jest": "^29.0.0",
+    "@types/jest": "^29.0.0"
+  }
+}