freshcontext-mcp 0.1.0

package/src/adapters/github.ts

@@ -0,0 +1,50 @@
+import { chromium } from "playwright";
+import { AdapterResult, ExtractOptions } from "../types.js";
+
+export async function githubAdapter(options: ExtractOptions): Promise<AdapterResult> {
+  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 as { readme: string | null; stars: string | null; forks: string | null; lastCommit: string | null; description: string | null; topics: string[]; language: string | null };
+
+  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/src/adapters/hackernews.ts

@@ -0,0 +1,93 @@
+import { chromium } from "playwright";
+import { AdapterResult, ExtractOptions } from "../types.js";
+
+export async function hackerNewsAdapter(options: ExtractOptions): Promise<AdapterResult> {
+  // 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() as {
+      hits: Array<{
+        title: string;
+        url: string | null;
+        points: number;
+        num_comments: number;
+        author: string;
+        created_at: string;
+        objectID: string;
+      }>;
+    };
+
+    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 as Array<{ title: string | null; link: string | null; score: string | null; age: string | null; commentLink: string | null }>;
+
+  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/src/adapters/packageTrends.ts

@@ -0,0 +1,104 @@
+import { AdapterResult, ExtractOptions } from "../types.js";
+
+// Uses npm registry API + PyPI JSON API (no auth needed)
+export async function packageTrendsAdapter(options: ExtractOptions): Promise<AdapterResult> {
+  // 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: string[] = [];
+  let latestDate: string | null = 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() as {
+            name: string;
+            description?: string;
+            "dist-tags"?: { latest?: string };
+            time?: Record<string, string>;
+            homepage?: string;
+            keywords?: string[];
+            repository?: { url?: string };
+          };
+
+          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() as {
+            info: {
+              name: string;
+              version: string;
+              summary?: string;
+              keywords?: string;
+              home_page?: string;
+              project_urls?: Record<string, string>;
+            };
+            releases?: Record<string, unknown[]>;
+            urls?: Array<{ upload_time: string }>;
+          };
+
+          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/src/adapters/repoSearch.ts

@@ -0,0 +1,78 @@
+import { AdapterResult, ExtractOptions } from "../types.js";
+
+// Uses GitHub Search API (no auth needed for basic search)
+export async function repoSearchAdapter(options: ExtractOptions): Promise<AdapterResult> {
+  // 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() as {
+    total_count: number;
+    items: Array<{
+      full_name: string;
+      description: string | null;
+      html_url: string;
+      stargazers_count: number;
+      forks_count: number;
+      language: string | null;
+      topics: string[];
+      pushed_at: string;
+      created_at: string;
+      open_issues_count: number;
+    }>;
+  };
+
+  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/src/adapters/scholar.ts

@@ -0,0 +1,65 @@
+import { chromium } from "playwright";
+import { AdapterResult, ExtractOptions } from "../types.js";
+
+export async function scholarAdapter(options: ExtractOptions): Promise<AdapterResult> {
+  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 as Array<{ title: string | null; authors: string | null; snippet: string | null; link: string | null; year: string | null }>;
+
+  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) as string[];
+  const newestYear = years.sort().reverse()[0] ?? null;
+
+  return {
+    raw,
+    content_date: newestYear ? `${newestYear}-01-01` : null,
+    freshness_confidence: newestYear ? "high" : "low",
+  };
+}

package/src/adapters/yc.ts

@@ -0,0 +1,99 @@
+import { chromium } from "playwright";
+import { AdapterResult, ExtractOptions } from "../types.js";
+
+export async function ycAdapter(options: ExtractOptions): Promise<AdapterResult> {
+  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 as Array<{
+    name: string | null;
+    description: string | null;
+    batch: string | null;
+    tags: string[];
+    link: string | null;
+  }>;
+
+  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/src/server.ts

@@ -0,0 +1,179 @@
+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: string, result: PromiseSettledResult<{ raw: string; content_date: string | null; freshness_confidence: string }>) =>
+      result.status === "fulfilled"
+        ? `## ${label}\n${result.value.raw}`
+        : `## ${label}\n[Error: ${(result as PromiseRejectedResult).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);