freshcontext-mcp 0.1.0

package/.env.example

@@ -0,0 +1,8 @@
+# freshcontext-mcp environment variables
+# Copy to .env and fill in
+
+# Optional: GitHub Personal Access Token (increases rate limits for GitHub API fallback)
+GITHUB_TOKEN=
+
+# Optional: Proxy URL if needed for certain extractions
+# PROXY_URL=http://user:pass@host:port

package/README.md

@@ -0,0 +1,71 @@
+# freshcontext-mcp
+
+> Real-time web extraction MCP server with guaranteed freshness timestamps for AI agents.
+
+## The Problem
+
+LLMs hallucinate recency. They'll cite a 2022 job posting as "current" or recall outdated API docs as if they're live. This happens because they have no reliable signal for *when* data was retrieved vs. when it was published.
+
+## The Fix
+
+Every piece of data extracted by `freshcontext-mcp` is wrapped in a `FreshContext` envelope:
+
+```json
+{
+  "content": "...",
+  "source_url": "https://github.com/owner/repo",
+  "content_date": "2024-11-03",
+  "retrieved_at": "2026-03-02T10:14:00Z",
+  "freshness_confidence": "high",
+  "adapter": "github"
+}
+```
+
+The AI agent always knows *when it's looking at*, not just *what*.
+
+## Adapters
+
+| Adapter | Tool Name | What it extracts |
+|---|---|---|
+| GitHub | `extract_github` | README, stars, forks, last commit, topics |
+| Google Scholar | `extract_scholar` | Titles, authors, years, snippets |
+| Hacker News | `extract_hackernews` | Top stories, scores, post timestamps |
+
+## Setup
+
+```bash
+git clone https://github.com/YOUR_USERNAME/freshcontext-mcp
+cd freshcontext-mcp
+npm install
+npx playwright install chromium
+npm run build
+```
+
+## Test locally
+
+```bash
+npm run inspect
+```
+
+## Connect to Claude
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "freshcontext": {
+      "command": "node",
+      "args": ["/absolute/path/to/freshcontext-mcp/dist/server.js"]
+    }
+  }
+}
+```
+
+## Roadmap
+
+- [ ] Twitter/X public feed adapter
+- [ ] Dev.to / Hashnode adapter  
+- [ ] Supabase changelog adapter
+- [ ] Cloudflare Worker deployment
+- [ ] Caching layer with TTL

package/dist/adapters/github.js

@@ -0,0 +1,41 @@
+import { chromium } from "playwright";
+export async function githubAdapter(options) {
+    const browser = await chromium.launch({ headless: true });
+    const page = await browser.newPage();
+    // Spoof a real browser UA to avoid bot detection
+    await page.setExtraHTTPHeaders({
+        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+    });
+    await page.goto(options.url, { waitUntil: "domcontentloaded", timeout: 20000 });
+    // Extract key repo signals — no inner functions to avoid esbuild __name injection
+    const data = await page.evaluate(`(function() {
+    var readme = (document.querySelector('[data-target="readme-toc.content"]') || document.querySelector('.markdown-body') || {}).textContent || null;
+    var starsEl = document.querySelector('[id="repo-stars-counter-star"]') || document.querySelector('.Counter.js-social-count');
+    var stars = starsEl ? starsEl.textContent.trim() : null;
+    var forksEl = document.querySelector('[id="repo-network-counter"]');
+    var forks = forksEl ? forksEl.textContent.trim() : null;
+    var commitEl = document.querySelector('relative-time');
+    var lastCommit = commitEl ? commitEl.getAttribute('datetime') : null;
+    var descEl = document.querySelector('.f4.my-3');
+    var description = descEl ? descEl.textContent.trim() : null;
+    var topics = Array.from(document.querySelectorAll('.topic-tag')).map(function(t) { return t.textContent.trim(); });
+    var langEl = document.querySelector('.color-fg-default.text-bold.mr-1');
+    var language = langEl ? langEl.textContent.trim() : null;
+    return { readme: readme, stars: stars, forks: forks, lastCommit: lastCommit, description: description, topics: topics, language: language };
+  })()`);
+    const typedData = data;
+    await browser.close();
+    const raw = [
+        `Description: ${typedData.description ?? "N/A"}`,
+        `Stars: ${typedData.stars ?? "N/A"} | Forks: ${typedData.forks ?? "N/A"}`,
+        `Language: ${typedData.language ?? "N/A"}`,
+        `Last commit: ${typedData.lastCommit ?? "N/A"}`,
+        `Topics: ${typedData.topics?.join(", ") ?? "none"}`,
+        `\n--- README ---\n${typedData.readme ?? "No README found"}`,
+    ].join("\n");
+    return {
+        raw,
+        content_date: typedData.lastCommit ?? null,
+        freshness_confidence: typedData.lastCommit ? "high" : "medium",
+    };
+}

package/dist/adapters/hackernews.js

@@ -0,0 +1,65 @@
+import { chromium } from "playwright";
+export async function hackerNewsAdapter(options) {
+    // If it's an Algolia API URL or search query, use the REST API directly (no browser)
+    const url = options.url;
+    if (url.includes("hn.algolia.com/api/") || url.startsWith("hn-search:")) {
+        const query = url.startsWith("hn-search:")
+            ? url.replace("hn-search:", "").trim()
+            : url;
+        const apiUrl = url.includes("hn.algolia.com/api/")
+            ? url
+            : `https://hn.algolia.com/api/v1/search?query=${encodeURIComponent(query)}&tags=story&hitsPerPage=20`;
+        const res = await fetch(apiUrl);
+        if (!res.ok)
+            throw new Error(`HN Algolia API error: ${res.status}`);
+        const data = await res.json();
+        const raw = data.hits
+            .map((r, i) => [
+            `[${i + 1}] ${r.title ?? "Untitled"}`,
+            `URL: ${r.url ?? `https://news.ycombinator.com/item?id=${r.objectID}`}`,
+            `Score: ${r.points} points | ${r.num_comments} comments`,
+            `Author: ${r.author} | Posted: ${r.created_at}`,
+        ].join("\n"))
+            .join("\n\n")
+            .slice(0, options.maxLength ?? 4000);
+        const newest = data.hits.map((r) => r.created_at).sort().reverse()[0] ?? null;
+        return { raw, content_date: newest, freshness_confidence: newest ? "high" : "medium" };
+    }
+    // Default: browser-based scrape for HN front page or search pages
+    const browser = await chromium.launch({ headless: true });
+    const page = await browser.newPage();
+    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 20000 });
+    const data = await page.evaluate(`(function() {
+    var items = Array.from(document.querySelectorAll('.athing')).slice(0, 20);
+    var results = items.map(function(el) {
+      var titleLineEl = el.querySelector('.titleline > a');
+      var title = titleLineEl ? titleLineEl.textContent.trim() : null;
+      var link = titleLineEl ? titleLineEl.getAttribute('href') : null;
+      var subtext = el.nextElementSibling;
+      var scoreEl = subtext ? subtext.querySelector('.score') : null;
+      var score = scoreEl ? scoreEl.textContent.trim() : null;
+      var ageEl = subtext ? subtext.querySelector('.age') : null;
+      var age = ageEl ? ageEl.getAttribute('title') : null;
+      var anchors = subtext ? subtext.querySelectorAll('a') : [];
+      var commentLink = anchors.length > 0 ? anchors[anchors.length - 1].textContent.trim() : null;
+      return { title: title, link: link, score: score, age: age, commentLink: commentLink };
+    });
+    return results;
+  })()`);
+    await browser.close();
+    const typedData = data;
+    const raw = typedData
+        .map((r, i) => [
+        `[${i + 1}] ${r.title ?? "Untitled"}`,
+        `URL: ${r.link ?? "N/A"}`,
+        `Score: ${r.score ?? "N/A"} | ${r.commentLink ?? ""}`,
+        `Posted: ${r.age ?? "unknown"}`,
+    ].join("\n"))
+        .join("\n\n");
+    const newestDate = typedData.map((r) => r.age).filter(Boolean).sort().reverse()[0] ?? null;
+    return {
+        raw,
+        content_date: newestDate,
+        freshness_confidence: newestDate ? "high" : "medium",
+    };
+}

package/dist/adapters/packageTrends.js

@@ -0,0 +1,75 @@
+// Uses npm registry API + PyPI JSON API (no auth needed)
+export async function packageTrendsAdapter(options) {
+    // options.url is the package name or a comma-separated list
+    // e.g. "langchain" or "npm:langchain" or "pypi:langchain"
+    const raw_input = options.url.replace(/^https?:\/\//, "").trim();
+    // Parse ecosystem prefix
+    const parts = raw_input.split(",").map((s) => s.trim());
+    const results = [];
+    let latestDate = null;
+    for (const pkg of parts) {
+        const isExplicitPypi = pkg.startsWith("pypi:");
+        const isExplicitNpm = pkg.startsWith("npm:");
+        const pkgName = pkg.replace(/^(pypi:|npm:)/, "");
+        // Try npm
+        if (!isExplicitPypi) {
+            try {
+                const npmRes = await fetch(`https://registry.npmjs.org/${encodeURIComponent(pkgName)}`, {
+                    headers: { Accept: "application/json" },
+                });
+                if (npmRes.ok) {
+                    const npmData = await npmRes.json();
+                    const latestVersion = npmData["dist-tags"]?.latest ?? "unknown";
+                    const modified = npmData.time?.modified ?? null;
+                    const created = npmData.time?.created ?? null;
+                    const versions = Object.keys(npmData.time ?? {}).filter((k) => !["created", "modified"].includes(k)).length;
+                    if (modified && (!latestDate || modified > latestDate))
+                        latestDate = modified;
+                    results.push([
+                        `📦 [npm] ${npmData.name}`,
+                        `Latest version: ${latestVersion}`,
+                        `Total versions: ${versions}`,
+                        `Description: ${npmData.description ?? "N/A"}`,
+                        `Keywords: ${npmData.keywords?.join(", ") ?? "none"}`,
+                        `Created: ${created ?? "unknown"}`,
+                        `Last updated: ${modified ?? "unknown"}`,
+                        `Homepage: ${npmData.homepage ?? "N/A"}`,
+                    ].join("\n"));
+                    continue;
+                }
+            }
+            catch { /* fall through to PyPI */ }
+        }
+        // Try PyPI
+        if (!isExplicitNpm) {
+            try {
+                const pypiRes = await fetch(`https://pypi.org/pypi/${encodeURIComponent(pkgName)}/json`);
+                if (pypiRes.ok) {
+                    const pypiData = await pypiRes.json();
+                    const info = pypiData.info;
+                    const releaseCount = Object.keys(pypiData.releases ?? {}).length;
+                    const latestUpload = pypiData.urls?.[0]?.upload_time ?? null;
+                    if (latestUpload && (!latestDate || latestUpload > latestDate))
+                        latestDate = latestUpload;
+                    results.push([
+                        `🐍 [PyPI] ${info.name}`,
+                        `Latest version: ${info.version}`,
+                        `Total releases: ${releaseCount}`,
+                        `Description: ${info.summary ?? "N/A"}`,
+                        `Keywords: ${info.keywords ?? "none"}`,
+                        `Last release: ${latestUpload ?? "unknown"}`,
+                        `Homepage: ${info.home_page ?? info.project_urls?.Homepage ?? "N/A"}`,
+                    ].join("\n"));
+                    continue;
+                }
+            }
+            catch { /* not found */ }
+        }
+        results.push(`❌ Package not found on npm or PyPI: ${pkgName}`);
+    }
+    return {
+        raw: results.join("\n\n").slice(0, options.maxLength ?? 5000),
+        content_date: latestDate,
+        freshness_confidence: latestDate ? "high" : "low",
+    };
+}

package/dist/adapters/repoSearch.js

@@ -0,0 +1,54 @@
+// Uses GitHub Search API (no auth needed for basic search)
+export async function repoSearchAdapter(options) {
+    // options.url is treated as the search query string
+    // e.g. "mcp server typescript" or a full GitHub search URL
+    let query = options.url;
+    // If it's a full URL, extract the query param
+    try {
+        const parsed = new URL(options.url);
+        if (parsed.hostname === "github.com" && parsed.pathname.includes("/search")) {
+            query = parsed.searchParams.get("q") ?? options.url;
+        }
+        else if (parsed.hostname === "github.com") {
+            // It's a direct URL — not a search
+            query = parsed.pathname.replace("/search", "").trim().replace(/^\//, "");
+        }
+    }
+    catch {
+        // plain string query, use as-is
+    }
+    const apiUrl = `https://api.github.com/search/repositories?q=${encodeURIComponent(query)}&sort=stars&order=desc&per_page=10`;
+    const res = await fetch(apiUrl, {
+        headers: {
+            Accept: "application/vnd.github.v3+json",
+            "User-Agent": "freshcontext-mcp/0.1.0",
+        },
+    });
+    if (!res.ok) {
+        throw new Error(`GitHub Search API error: ${res.status} ${await res.text()}`);
+    }
+    const data = await res.json();
+    const raw = [
+        `Total matching repos: ${data.total_count.toLocaleString()}`,
+        `Top ${data.items.length} by stars:\n`,
+        ...data.items.map((r, i) => [
+            `[${i + 1}] ${r.full_name}`,
+            `⭐ ${r.stargazers_count.toLocaleString()} stars | 🍴 ${r.forks_count} forks | Issues: ${r.open_issues_count}`,
+            `Language: ${r.language ?? "unknown"}`,
+            `Topics: ${r.topics?.join(", ") || "none"}`,
+            `Description: ${r.description ?? "N/A"}`,
+            `Last push: ${r.pushed_at}`,
+            `Created: ${r.created_at}`,
+            `URL: ${r.html_url}`,
+        ].join("\n")),
+    ]
+        .join("\n\n")
+        .slice(0, options.maxLength ?? 6000);
+    // Most recently pushed repo date as content_date
+    const dates = data.items.map((r) => r.pushed_at).sort().reverse();
+    return {
+        raw,
+        content_date: dates[0] ?? null,
+        freshness_confidence: "high",
+    };
+}

package/dist/adapters/scholar.js

@@ -0,0 +1,51 @@
+import { chromium } from "playwright";
+export async function scholarAdapter(options) {
+    const browser = await chromium.launch({ headless: true });
+    const page = await browser.newPage();
+    await page.setExtraHTTPHeaders({
+        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+    });
+    await page.goto(options.url, { waitUntil: "domcontentloaded", timeout: 20000 });
+    const data = await page.evaluate(`(function() {
+    var items = Array.from(document.querySelectorAll('.gs_r.gs_or.gs_scl'));
+    var results = items.map(function(el) {
+      var titleEl = el.querySelector('.gs_rt');
+      var title = titleEl ? titleEl.textContent.trim() : null;
+      var authorsEl = el.querySelector('.gs_a');
+      var authors = authorsEl ? authorsEl.textContent.trim() : null;
+      var snippetEl = el.querySelector('.gs_rs');
+      var snippet = snippetEl ? snippetEl.textContent.trim() : null;
+      var linkEl = el.querySelector('.gs_rt a');
+      var link = linkEl ? linkEl.getAttribute('href') : null;
+      var yearMatch = authors ? authors.match(/\\b(19|20)\\d{2}\\b/) : null;
+      var year = yearMatch ? yearMatch[0] : null;
+      return { title: title, authors: authors, snippet: snippet, link: link, year: year };
+    });
+    return results;
+  })()`);
+    await browser.close();
+    const typedData = data;
+    if (!typedData.length) {
+        return {
+            raw: "No results found on this Scholar page.",
+            content_date: null,
+            freshness_confidence: "low",
+        };
+    }
+    const raw = typedData
+        .map((r, i) => [
+        `[${i + 1}] ${r.title ?? "Untitled"}`,
+        `Authors: ${r.authors ?? "Unknown"}`,
+        `Year: ${r.year ?? "Unknown"}`,
+        `Snippet: ${r.snippet ?? "N/A"}`,
+        `Link: ${r.link ?? "N/A"}`,
+    ].join("\n"))
+        .join("\n\n");
+    const years = typedData.map((r) => r.year).filter(Boolean);
+    const newestYear = years.sort().reverse()[0] ?? null;
+    return {
+        raw,
+        content_date: newestYear ? `${newestYear}-01-01` : null,
+        freshness_confidence: newestYear ? "high" : "low",
+    };
+}

package/dist/adapters/yc.js

@@ -0,0 +1,81 @@
+import { chromium } from "playwright";
+export async function ycAdapter(options) {
+    const browser = await chromium.launch({ headless: true });
+    const page = await browser.newPage();
+    // YC company directory is React-rendered — wait for network to settle
+    await page.goto(options.url, { waitUntil: "networkidle", timeout: 30000 });
+    // Wait for company cards to appear
+    await page.waitForSelector('a[href*="/companies/"]', { timeout: 15000 }).catch(() => null);
+    const data = await page.evaluate(`(function() {
+    // YC company cards — robust multi-strategy extraction
+    var results = [];
+
+    // Strategy 1: structured company divs with name + description + batch
+    var cards = Array.from(document.querySelectorAll('div[class*="_company_"]'));
+
+    if (cards.length === 0) {
+      // Strategy 2: anchor links to /companies/* pages
+      cards = Array.from(document.querySelectorAll('a[href*="/companies/"]'))
+        .filter(function(el) {
+          return el.querySelector('span, p, div');
+        });
+    }
+
+    cards.slice(0, 25).forEach(function(el) {
+      var allText = el.innerText || el.textContent || "";
+      var lines = allText.split('\\n').map(function(l) { return l.trim(); }).filter(Boolean);
+
+      // Try to find structured spans
+      var spans = Array.from(el.querySelectorAll('span'));
+      var name = null, description = null, batch = null;
+      var tags = [];
+
+      spans.forEach(function(s) {
+        var t = s.textContent.trim();
+        if (!t) return;
+        if (s.className && s.className.toString().includes('Name')) name = t;
+        else if (s.className && s.className.toString().includes('Desc')) description = t;
+        else if (s.className && s.className.toString().includes('Batch')) batch = t;
+        else if (s.className && s.className.toString().includes('Tag')) tags.push(t);
+      });
+
+      // Fallback to line parsing
+      if (!name && lines.length > 0) name = lines[0];
+      if (!description && lines.length > 1) description = lines[1];
+
+      var link = el.tagName === 'A'
+        ? el.getAttribute('href')
+        : (el.querySelector('a') ? el.querySelector('a').getAttribute('href') : null);
+
+      if (name && name.length > 1 && name.length < 80) {
+        results.push({ name, description, batch, tags, link });
+      }
+    });
+
+    return results;
+  })()`);
+    await browser.close();
+    const typedData = data;
+    if (!typedData.length) {
+        return {
+            raw: "No YC companies found — page may have changed structure. Try visiting: " + options.url,
+            content_date: null,
+            freshness_confidence: "low",
+        };
+    }
+    const raw = typedData
+        .map((r, i) => [
+        `[${i + 1}] ${r.name ?? "Unknown"}`,
+        `Batch: ${r.batch ?? "Unknown"}`,
+        `Tags: ${r.tags?.join(", ") || "none"}`,
+        `Description: ${r.description ?? "N/A"}`,
+        `Link: ${r.link ? (r.link.startsWith("http") ? r.link : "https://www.ycombinator.com" + r.link) : "N/A"}`,
+    ].join("\n"))
+        .join("\n\n")
+        .slice(0, options.maxLength ?? 6000);
+    return {
+        raw,
+        content_date: new Date().toISOString().split("T")[0],
+        freshness_confidence: "high",
+    };
+}

package/dist/server.js

@@ -0,0 +1,129 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { githubAdapter } from "./adapters/github.js";
+import { scholarAdapter } from "./adapters/scholar.js";
+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 { stampFreshness, formatForLLM } from "./tools/freshnessStamp.js";
+const server = new McpServer({
+    name: "freshcontext-mcp",
+    version: "0.1.0",
+});
+// ─── Tool: extract_github ────────────────────────────────────────────────────
+server.registerTool("extract_github", {
+    description: "Extract real-time data from a GitHub repository — README, stars, forks, language, topics, last commit. Returns timestamped freshcontext.",
+    inputSchema: z.object({
+        url: z.string().url().describe("Full GitHub repo URL e.g. https://github.com/owner/repo"),
+        max_length: z.number().optional().default(6000).describe("Max content length"),
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ url, max_length }) => {
+    const result = await githubAdapter({ url, maxLength: max_length });
+    const ctx = stampFreshness(result, { url, maxLength: max_length }, "github");
+    return { content: [{ type: "text", text: formatForLLM(ctx) }] };
+});
+// ─── Tool: extract_scholar ───────────────────────────────────────────────────
+server.registerTool("extract_scholar", {
+    description: "Extract research results from a Google Scholar search URL. Returns titles, authors, publication years, and snippets — all timestamped.",
+    inputSchema: z.object({
+        url: z.string().url().describe("Google Scholar search URL e.g. https://scholar.google.com/scholar?q=..."),
+        max_length: z.number().optional().default(6000),
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ url, max_length }) => {
+    const result = await scholarAdapter({ url, maxLength: max_length });
+    const ctx = stampFreshness(result, { url, maxLength: max_length }, "google_scholar");
+    return { content: [{ type: "text", text: formatForLLM(ctx) }] };
+});
+// ─── Tool: extract_hackernews ────────────────────────────────────────────────
+server.registerTool("extract_hackernews", {
+    description: "Extract top stories or search results from Hacker News. Real-time dev/tech community sentiment with post timestamps.",
+    inputSchema: z.object({
+        url: z.string().url().describe("HN URL e.g. https://news.ycombinator.com or https://hn.algolia.com/?q=..."),
+        max_length: z.number().optional().default(4000),
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ url, max_length }) => {
+    const result = await hackerNewsAdapter({ url, maxLength: max_length });
+    const ctx = stampFreshness(result, { url, maxLength: max_length }, "hackernews");
+    return { content: [{ type: "text", text: formatForLLM(ctx) }] };
+});
+// ─── Tool: extract_yc ──────────────────────────────────────────────────────────
+server.registerTool("extract_yc", {
+    description: "Scrape YC company listings. Use https://www.ycombinator.com/companies?query=KEYWORD to find startups in a space. Returns name, batch, tags, description per company with freshness timestamp.",
+    inputSchema: z.object({
+        url: z.string().url().describe("YC companies URL e.g. https://www.ycombinator.com/companies?query=mcp"),
+        max_length: z.number().optional().default(6000),
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ url, max_length }) => {
+    const result = await ycAdapter({ url, maxLength: max_length });
+    const ctx = stampFreshness(result, { url, maxLength: max_length }, "ycombinator");
+    return { content: [{ type: "text", text: formatForLLM(ctx) }] };
+});
+// ─── Tool: search_repos ──────────────────────────────────────────────────────
+server.registerTool("search_repos", {
+    description: "Search GitHub for repositories matching a keyword or topic. Returns top results by stars with activity signals. Use to find competitors, similar tools, or related projects.",
+    inputSchema: z.object({
+        query: z.string().describe("Search query e.g. 'mcp server typescript' or 'cashflow prediction python'"),
+        max_length: z.number().optional().default(6000),
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ query, max_length }) => {
+    const result = await repoSearchAdapter({ url: query, maxLength: max_length });
+    const ctx = stampFreshness(result, { url: query, maxLength: max_length }, "github_search");
+    return { content: [{ type: "text", text: formatForLLM(ctx) }] };
+});
+// ─── Tool: package_trends ────────────────────────────────────────────────────
+server.registerTool("package_trends", {
+    description: "Look up npm and PyPI package metadata — version history, release cadence, last updated. Use to gauge ecosystem activity around a tool or dependency. Supports comma-separated list of packages.",
+    inputSchema: z.object({
+        packages: z.string().describe("Package name(s) e.g. 'langchain' or 'npm:zod,pypi:fastapi'"),
+        max_length: z.number().optional().default(5000),
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ packages, max_length }) => {
+    const result = await packageTrendsAdapter({ url: packages, maxLength: max_length });
+    const ctx = stampFreshness(result, { url: packages, maxLength: max_length }, "package_registry");
+    return { content: [{ type: "text", text: formatForLLM(ctx) }] };
+});
+// ─── Tool: extract_landscape ─────────────────────────────────────────────────
+server.registerTool("extract_landscape", {
+    description: "Composite intelligence tool. Given a project idea or keyword, simultaneously queries YC startups, GitHub repos, HN sentiment, and package activity to answer: Who is building this? Is it funded? What's getting traction? Returns a unified timestamped landscape report.",
+    inputSchema: z.object({
+        topic: z.string().describe("Your project idea or keyword e.g. 'mcp server' or 'cashflow prediction'"),
+        max_length: z.number().optional().default(8000),
+    }),
+    annotations: { readOnlyHint: true, openWorldHint: true },
+}, async ({ topic, max_length }) => {
+    const perSection = Math.floor((max_length ?? 8000) / 4);
+    const [ycResult, repoResult, hnResult, pkgResult] = await Promise.allSettled([
+        ycAdapter({ url: `https://www.ycombinator.com/companies?query=${encodeURIComponent(topic)}`, maxLength: perSection }),
+        repoSearchAdapter({ url: topic, maxLength: perSection }),
+        hackerNewsAdapter({ url: `https://hn.algolia.com/api/v1/search?query=${encodeURIComponent(topic)}&tags=story&hitsPerPage=15`, maxLength: perSection }),
+        packageTrendsAdapter({ url: topic, maxLength: perSection }),
+    ]);
+    const section = (label, result) => result.status === "fulfilled"
+        ? `## ${label}\n${result.value.raw}`
+        : `## ${label}\n[Error: ${result.reason}]`;
+    const combined = [
+        `# Landscape Report: "${topic}"`,
+        `Generated: ${new Date().toISOString()}`,
+        "",
+        section("🚀 YC Startups in this space", ycResult),
+        section("📦 Top GitHub repos", repoResult),
+        section("💬 HN sentiment (last month)", hnResult),
+        section("📊 Package ecosystem", pkgResult),
+    ].join("\n\n");
+    return { content: [{ type: "text", text: combined }] };
+});
+// ─── Start ───────────────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("freshcontext-mcp running on stdio");
+}
+main().catch(console.error);

package/dist/tools/freshnessStamp.js

@@ -0,0 +1,25 @@
+export function stampFreshness(result, options, adapter) {
+    return {
+        content: result.raw.slice(0, options.maxLength ?? 8000),
+        source_url: options.url,
+        content_date: result.content_date,
+        retrieved_at: new Date().toISOString(),
+        freshness_confidence: result.freshness_confidence,
+        adapter,
+    };
+}
+export function formatForLLM(ctx) {
+    const dateInfo = ctx.content_date
+        ? `Published: ${ctx.content_date}`
+        : "Publish date: unknown";
+    return [
+        `[FRESHCONTEXT]`,
+        `Source: ${ctx.source_url}`,
+        `${dateInfo}`,
+        `Retrieved: ${ctx.retrieved_at}`,
+        `Confidence: ${ctx.freshness_confidence}`,
+        `---`,
+        ctx.content,
+        `[/FRESHCONTEXT]`,
+    ].join("\n");
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// Core data types for freshcontext-mcp
+export {};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "freshcontext-mcp",
+  "version": "0.1.0",
+  "description": "Real-time web extraction MCP server with freshness timestamps for AI agents",
+  "type": "module",
+  "main": "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"
+  }
+}