freshcontext-mcp 0.1.8 → 0.2.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

@@ -0,0 +1,243 @@
+/**
+ * Jobs adapter v2 — 4 sources, freshness badges, location + keyword filtering.
+ *
+ * Sources (all no-auth):
+ *   - Remotive       — remote jobs, location filterable
+ *   - RemoteOK       — pure remote, salary data, unix timestamps
+ *   - The Muse       — structured jobs, location + category
+ *   - HN Who is Hiring — community-sourced, raw but real
+ *
+ * Every listing gets a freshness badge:
+ *   🟢 < 7 days     — FRESH, apply now
+ *   🟡 7–30 days    — still good
+ *   🔴 31–90 days   — apply with caution
+ *   ⛔ > 90 days    — likely expired, shown last
+ *
+ * This adapter was the whole reason freshcontext exists.
+ */
+// ─── 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 ?? 8000;
+    const location = options.location ?? "";
+    const remoteOnly = options.remoteOnly ?? false;
+    const maxAgeDays = options.maxAgeDays ?? 60;
+    const keywords = options.keywords ?? [];
+    const perSource = Math.floor(maxLength / 4);
+    const [remotiveRes, remoteOkRes, museRes, hnRes] = await Promise.allSettled([
+        fetchRemotive(query, location, maxAgeDays, keywords, perSource),
+        fetchRemoteOK(query, location, maxAgeDays, keywords, perSource),
+        remoteOnly ? Promise.reject("skipped (remote_only mode)") : fetchMuse(query, location, maxAgeDays, keywords, perSource),
+        fetchHNHiring(query, location, maxAgeDays, keywords, perSource),
+    ]);
+    const pool = [];
+    const harvest = (res, label) => {
+        if (res.status === "fulfilled")
+            pool.push(...res.value.listings);
+        // silently skip rejected sources — don't clutter output
+    };
+    harvest(remotiveRes, "Remotive");
+    harvest(remoteOkRes, "RemoteOK");
+    harvest(museRes, "The Muse");
+    harvest(hnRes, "HN");
+    if (!pool.length) {
+        return {
+            raw: `No job listings found for "${query}"${location ? ` in ${location}` : ""}.\n\nTips:\n• Try broader terms e.g. "engineer" instead of "senior TypeScript engineer"\n• Set location to "remote" for worldwide results\n• Increase max_age_days`,
+            content_date: null,
+            freshness_confidence: "low",
+        };
+    }
+    // Sort: freshest first, expired listings last
+    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 header = [
+        `# Job Search: "${query}"${location ? ` · ${location}` : ""}${remoteOnly ? " · remote only" : ""}`,
+        `Retrieved: ${new Date().toISOString()}`,
+        `Found: ${pool.length} listings — 🟢 ${freshCount} fresh  🟡 ${goodCount} recent  🔴 ${staleCount} older`,
+        `⚠️  Listings sorted freshest first. Check the date badge before you apply.`,
+        keywords.length ? `🔍 Watching for: ${keywords.map(k => `⚡${k}`).join(", ")}` : null,
+        "",
+    ].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,
+        content_date: newestDate,
+        freshness_confidence: freshestDays <= 7 ? "high" : freshestDays <= 30 ? "medium" : "low",
+    };
+}
+// ─── Source: Remotive ─────────────────────────────────────────────────────────
+async function fetchRemotive(query, location, maxAgeDays, keywords, maxLength) {
+    const url = `https://remotive.com/api/remote-jobs?search=${encodeURIComponent(query)}&limit=15`;
+    const res = await fetch(url, {
+        headers: { "User-Agent": "freshcontext-mcp/0.2.0", "Accept": "application/json" },
+    });
+    if (!res.ok)
+        throw new Error(`Remotive ${res.status}`);
+    const data = await res.json();
+    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, maxLength) {
+    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.2.0", "Accept": "application/json" },
+    });
+    if (!res.ok)
+        throw new Error(`RemoteOK ${res.status}`);
+    const raw = await res.json();
+    // First element is a legal notice object, skip it
+    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 } = freshnessDate(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 };
+}
+// ─── Source: The Muse ─────────────────────────────────────────────────────────
+async function fetchMuse(query, location, maxAgeDays, keywords, maxLength) {
+    const locParam = location && location.toLowerCase() !== "remote"
+        ? `&location=${encodeURIComponent(location)}`
+        : "&location=Flexible%20%2F%20Remote";
+    const url = `https://www.themuse.com/api/public/jobs?category=${encodeURIComponent(query)}${locParam}&page=0&descending=true`;
+    const res = await fetch(url, {
+        headers: { "User-Agent": "freshcontext-mcp/0.2.0", "Accept": "application/json" },
+    });
+    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 } = freshnessDate(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 ─────────────────────────────────────────────────
+async function fetchHNHiring(query, location, maxAgeDays, keywords, maxLength) {
+    const searchQ = [query, location, "hiring"].filter(Boolean).join(" ");
+    const url = `https://hn.algolia.com/api/v1/search?query=${encodeURIComponent(searchQ)}&tags=comment&hitsPerPage=10`;
+    const res = await fetch(url, { headers: { "User-Agent": "freshcontext-mcp/0.2.0" } });
+    if (!res.ok)
+        throw new Error(`HN ${res.status}`);
+    const data = await res.json();
+    const listings = (data.hits ?? [])
+        .filter(h => {
+        const t = (h.comment_text ?? "").toLowerCase();
+        return t.includes("hiring") || t.includes("remote") || t.includes("full-time") || t.includes("apply");
+    })
+        .map(h => {
+        const { badge, days } = freshnessDate(h.created_at);
+        if (days > maxAgeDays)
+            return null;
+        const excerpt = (h.comment_text ?? "")
+            .replace(/<[^>]+>/g, " ")
+            .replace(/\s+/g, " ")
+            .trim()
+            .slice(0, 350);
+        const text = highlightKeywords([
+            `[HN Hiring] Posted by ${h.author}`,
+            `${badge}`,
+            excerpt + (excerpt.length >= 350 ? "…" : ""),
+            `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 };
+}
+// ─── Shared date helper ───────────────────────────────────────────────────────
+function freshnessDate(dateStr) {
+    return freshnessBadge(dateStr ?? null);
+}

package/dist/server.js

@@ -8,6 +8,7 @@ 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 { jobsAdapter } from "./adapters/jobs.js";
 import { stampFreshness, formatForLLM } from "./tools/freshnessStamp.js";
 import { formatSecurityError } from "./security.js";
 const server = new McpServer({
@@ -152,6 +153,35 @@ server.registerTool("extract_landscape", {
     ].join("\n\n");
     return { content: [{ type: "text", text: combined }] };
 });
+// ─── Tool: search_jobs ───────────────────────────────────────────────────────
+server.registerTool("search_jobs", {
+    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', '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, location, remote_only, max_age_days, keywords, max_length }) => {
+    try {
+        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) }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: formatSecurityError(err) }] };
+    }
+});
 // ─── Start ───────────────────────────────────────────────────────────────────
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

@@ -1,54 +1,54 @@
-{
-  "name": "freshcontext-mcp",
-  "mcpName": "io.github.PrinceGabriel-lgtm/freshcontext",
-  "version": "0.1.8",
-  "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.2.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"
+  }
+}