freshcontext-mcp 0.1.3 → 0.1.5

package/README.md

@@ -21,14 +21,14 @@ Every piece of data extracted by `freshcontext-mcp` is wrapped in a structured e
 [FRESHCONTEXT]
 Source: https://github.com/owner/repo
 Published: 2024-11-03
-Retrieved: 2026-03-03T10:14:00Z
+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. This is the difference between a hallucinated recency claim and a verifiable one.
+The AI agent always knows **when it's looking at data**, not just what the data says.
 
 ---
 
@@ -60,13 +60,33 @@ The AI agent always knows **when it's looking at data**, not just what the data
 
 ## Quick Start
 
-### Install via npm
+### Option A — Cloud (no install, works immediately)
 
-```bash
-npx freshcontext-mcp
+No Node, no Playwright, nothing to install. Just add this to your Claude Desktop config and restart.
+
+**Mac:** open `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** open `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "freshcontext": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://freshcontext-mcp.gimmanuel73.workers.dev/mcp"]
+    }
+  }
+}
 ```
 
-### Or clone and run locally
+Restart Claude Desktop. The freshcontext tools will appear in your session.
+
+> **Note:** If `claude_desktop_config.json` doesn't exist yet, create it with the content above.
+
+---
+
+### Option B — Local (full Playwright, faster for heavy use)
+
+**Prerequisites:** Node.js 18+ ([nodejs.org](https://nodejs.org))
 
 ```bash
 git clone https://github.com/PrinceGabriel-lgtm/freshcontext-mcp
@@ -76,39 +96,56 @@ npx playwright install chromium
 npm run build
 ```
 
-### Connect to Claude Desktop
-
-Add to your `claude_desktop_config.json`:
-
-**Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+Then add to your Claude Desktop config:
 
+**Mac** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 ```json
 {
   "mcpServers": {
-    "freshcontext-local": {
+    "freshcontext": {
       "command": "node",
-      "args": ["/absolute/path/to/freshcontext-mcp/dist/server.js"]
+      "args": ["/Users/YOUR_USERNAME/path/to/freshcontext-mcp/dist/server.js"]
     }
   }
 }
 ```
 
-Restart Claude Desktop. You'll see the freshcontext tools available in your session.
-
-### Or use the Cloudflare edge deployment (no install needed)
-
+**Windows** (`%APPDATA%\Claude\claude_desktop_config.json`):
 ```json
 {
   "mcpServers": {
-    "freshcontext-cloud": {
-      "command": "npx",
-      "args": ["-y", "mcp-remote", "https://freshcontext-worker.gimmanuel73.workers.dev/mcp"]
+    "freshcontext": {
+      "command": "node",
+      "args": ["C:\\Users\\YOUR_USERNAME\\path\\to\\freshcontext-mcp\\dist\\server.js"]
     }
   }
 }
 ```
 
+Restart Claude Desktop.
+
+---
+
+### Troubleshooting (Mac)
+
+**"command not found: node"** — Node isn't on your PATH inside Claude Desktop's environment. Use the full path:
+```bash
+which node   # copy this output
+```
+Then replace `"command": "node"` with `"command": "/usr/local/bin/node"` (or whatever `which node` returned).
+
+**"npx: command not found"** — Same issue. Run `which npx` and use the full path for Option A:
+```json
+"command": "/usr/local/bin/npx"
+```
+
+**Config file doesn't exist** — Create it. On Mac:
+```bash
+mkdir -p ~/Library/Application\ Support/Claude
+touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
+```
+Then paste the config JSON above into it.
+
 ---
 
 ## Usage Examples
@@ -162,12 +199,12 @@ This makes freshness **verifiable**, not assumed.
 Uses headless Chromium via Playwright. Full browser rendering for JavaScript-heavy sites.
 
 ### Cloud (Cloudflare Workers)
-The `worker/` directory contains a Cloudflare Workers deployment using the Browser Rendering REST API. No Playwright dependency — runs at the edge globally.
+The `worker/` directory contains a Cloudflare Workers deployment. No Playwright dependency — runs at the edge globally.
 
 ```bash
 cd worker
 npm install
-npx wrangler secret put CF_API_TOKEN
+npx wrangler secret put API_KEY
 npx wrangler deploy
 ```
 
@@ -180,15 +217,16 @@ freshcontext-mcp/
 ├── src/
 │   ├── server.ts              # MCP server, all tool registrations
 │   ├── types.ts               # FreshContext interfaces
+│   ├── security.ts            # Input validation, domain allowlists
 │   ├── adapters/
-│   │   ├── github.ts          # GitHub repo extraction
-│   │   ├── hackernews.ts      # HN front page + Algolia API
-│   │   ├── scholar.ts         # Google Scholar scraping
-│   │   ├── yc.ts              # YC company directory
-│   │   ├── repoSearch.ts      # GitHub Search API
-│   │   └── packageTrends.ts   # npm + PyPI registries
+│   │   ├── github.ts
+│   │   ├── hackernews.ts
+│   │   ├── scholar.ts
+│   │   ├── yc.ts
+│   │   ├── repoSearch.ts
+│   │   └── packageTrends.ts
 │   └── tools/
-│       └── freshnessStamp.ts  # FreshContext envelope builder
+│       └── freshnessStamp.ts
 └── worker/                    # Cloudflare Workers deployment
     └── src/worker.ts
 ```
@@ -205,17 +243,17 @@ freshcontext-mcp/
 - [x] npm/PyPI package trends
 - [x] `extract_landscape` composite tool
 - [x] Cloudflare Workers deployment
+- [x] Worker auth + rate limiting + domain allowlists
 - [ ] Product Hunt launches adapter
-- [ ] Crunchbase/funding signals adapter
+- [ ] Finance/market data adapter
 - [ ] TTL-based caching layer
 - [ ] `freshness_score` numeric metric
-- [ ] Webhook support for real-time updates
 
 ---
 
 ## Contributing
 
-PRs welcome. New adapters are the highest-value contribution — see the existing adapters in `src/adapters/` for the pattern. Each adapter returns `{ raw, content_date, freshness_confidence }`.
+PRs welcome. New adapters are the highest-value contribution — see `src/adapters/` for the pattern. Each adapter returns `{ raw, content_date, freshness_confidence }`.
 
 ---
 

package/dist/server.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "freshcontext-mcp",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Real-time web extraction MCP server with freshness timestamps for AI agents",
   "keywords": [
     "mcp",
@@ -24,6 +24,9 @@
   "license": "MIT",
   "type": "module",
   "main": "dist/server.js",
+  "bin": {
+    "freshcontext-mcp": "dist/server.js"
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsx watch src/server.ts",

package/src/server.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -202,3 +203,4 @@ async function main() {
 }
 
 main().catch(console.error);
+

package/src/server.ts.bak

@@ -0,0 +1,204 @@
+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";
+import { SecurityError, formatSecurityError } from "./security.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 }) => {
+    try {
+      const result = await githubAdapter({ url, maxLength: max_length });
+      const ctx = stampFreshness(result, { url, maxLength: max_length }, "github");
+      return { content: [{ type: "text", text: formatForLLM(ctx) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: formatSecurityError(err) }] };
+    }
+  }
+);
+
+// ─── 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 }) => {
+    try {
+      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) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: formatSecurityError(err) }] };
+    }
+  }
+);
+
+// ─── 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 }) => {
+    try {
+      const result = await hackerNewsAdapter({ url, maxLength: max_length });
+      const ctx = stampFreshness(result, { url, maxLength: max_length }, "hackernews");
+      return { content: [{ type: "text", text: formatForLLM(ctx) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: formatSecurityError(err) }] };
+    }
+  }
+);
+
+// ─── 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 }) => {
+    try {
+      const result = await ycAdapter({ url, maxLength: max_length });
+      const ctx = stampFreshness(result, { url, maxLength: max_length }, "ycombinator");
+      return { content: [{ type: "text", text: formatForLLM(ctx) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: formatSecurityError(err) }] };
+    }
+  }
+);
+
+// ─── 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 }) => {
+    try {
+      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) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: formatSecurityError(err) }] };
+    }
+  }
+);
+
+// ─── 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 }) => {
+    try {
+      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) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: formatSecurityError(err) }] };
+    }
+  }
+);
+
+// ─── 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);

package/worker/src/worker.ts

@@ -3,10 +3,11 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { z } from "zod";
 
-// ─── Types ───────────────────────────────────────────────────────────────────
+// ─── Types ────────────────────────────────────────────────────────────────────
 
 interface Env {
   BROWSER: Fetcher;
+  API_KEY?: string; // Optional: set via `wrangler secret put API_KEY`
 }
 
 interface FreshContext {
@@ -18,9 +19,143 @@ interface FreshContext {
   adapter: string;
 }
 
-// ─── Freshness Stamp ─────────────────────────────────────────────────────────
+// ─── Security ─────────────────────────────────────────────────────────────────
 
-function stamp(content: string, url: string, date: string | null, confidence: "high" | "medium" | "low", adapter: string): string {
+const ALLOWED_DOMAINS: Record<string, string[]> = {
+  github:      ["github.com", "raw.githubusercontent.com"],
+  scholar:     ["scholar.google.com"],
+  hackernews:  ["news.ycombinator.com", "hn.algolia.com"],
+  yc:          ["www.ycombinator.com", "ycombinator.com"],
+};
+
+const PRIVATE_IP_PATTERNS = [
+  /^localhost$/i,
+  /^127\./,
+  /^10\./,
+  /^192\.168\./,
+  /^172\.(1[6-9]|2\d|3[01])\./,
+  /^169\.254\./,
+  /^::1$/,
+  /^fc00:/i,
+  /^fe80:/i,
+];
+
+const MAX_URL_LENGTH    = 500;
+const MAX_QUERY_LENGTH  = 200;
+
+class SecurityError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SecurityError";
+  }
+}
+
+function validateUrl(rawUrl: string, adapter: string): string {
+  if (rawUrl.length > MAX_URL_LENGTH)
+    throw new SecurityError(`URL too long (max ${MAX_URL_LENGTH} chars)`);
+
+  let parsed: URL;
+  try { parsed = new URL(rawUrl); }
+  catch { throw new SecurityError("Invalid URL format"); }
+
+  if (!["http:", "https:"].includes(parsed.protocol))
+    throw new SecurityError("Only http/https URLs are allowed");
+
+  const hostname = parsed.hostname.toLowerCase();
+
+  for (const pattern of PRIVATE_IP_PATTERNS) {
+    if (pattern.test(hostname))
+      throw new SecurityError("Access to private/internal addresses is not allowed");
+  }
+
+  const allowed = ALLOWED_DOMAINS[adapter];
+  if (allowed && allowed.length > 0) {
+    const ok = allowed.some(d => hostname === d || hostname.endsWith(`.${d}`));
+    if (!ok)
+      throw new SecurityError(`URL not allowed for ${adapter}. Allowed domains: ${allowed.join(", ")}`);
+  }
+
+  return rawUrl;
+}
+
+function sanitizeQuery(query: string, maxLen = MAX_QUERY_LENGTH): string {
+  if (query.length > maxLen)
+    throw new SecurityError(`Query too long (max ${maxLen} chars)`);
+  // Strip null bytes and control characters
+  return query.replace(/[\x00-\x1F\x7F]/g, "").trim();
+}
+
+// ─── Rate Limiting (in-memory, per isolate) ───────────────────────────────────
+
+interface RateEntry { count: number; windowStart: number; }
+const rateMap = new Map<string, RateEntry>();
+
+const RATE_LIMIT      = 20;   // max requests
+const RATE_WINDOW_MS  = 60_000; // per 60 seconds
+
+function checkRateLimit(ip: string): void {
+  const now = Date.now();
+  const entry = rateMap.get(ip);
+
+  if (!entry || now - entry.windowStart > RATE_WINDOW_MS) {
+    rateMap.set(ip, { count: 1, windowStart: now });
+    return;
+  }
+
+  if (entry.count >= RATE_LIMIT) {
+    throw new SecurityError(`Rate limit exceeded. Max ${RATE_LIMIT} requests per minute.`);
+  }
+
+  entry.count++;
+}
+
+// Prevent the map from growing unboundedly
+function pruneRateMap(): void {
+  const now = Date.now();
+  for (const [ip, entry] of rateMap) {
+    if (now - entry.windowStart > RATE_WINDOW_MS) rateMap.delete(ip);
+  }
+}
+
+// ─── Auth ─────────────────────────────────────────────────────────────────────
+
+function checkAuth(request: Request, env: Env): void {
+  if (!env.API_KEY) return; // Auth disabled if no key is set
+
+  const authHeader = request.headers.get("Authorization") ?? "";
+  const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
+
+  if (token !== env.API_KEY) {
+    throw new SecurityError("Unauthorized. Provide a valid Bearer token.");
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function getClientIp(request: Request): string {
+  return (
+    request.headers.get("CF-Connecting-IP") ??
+    request.headers.get("X-Forwarded-For")?.split(",")[0]?.trim() ??
+    "unknown"
+  );
+}
+
+function securityErrorResponse(message: string, status: number): Response {
+  return new Response(JSON.stringify({ error: message }), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+// ─── Freshness Stamp ──────────────────────────────────────────────────────────
+
+function stamp(
+  content: string,
+  url: string,
+  date: string | null,
+  confidence: "high" | "medium" | "low",
+  adapter: string
+): string {
   const ctx: FreshContext = {
     content: content.slice(0, 6000),
     source_url: url,
@@ -44,107 +179,133 @@ function stamp(content: string, url: string, date: string | null, confidence: "h
 // ─── Server Factory ───────────────────────────────────────────────────────────
 
 function createServer(env: Env): McpServer {
-  const server = new McpServer({ name: "freshcontext-mcp", version: "0.1.0" });
+  const server = new McpServer({ name: "freshcontext-mcp", version: "0.1.3" });
 
   // ── extract_github ──────────────────────────────────────────────────────────
   server.registerTool("extract_github", {
     description: "Extract real-time data from a GitHub repository — README, stars, forks, last commit, topics. Returns timestamped freshcontext.",
     inputSchema: z.object({
-      url: z.string().url().describe("Full GitHub repo URL"),
+      url: z.string().url().describe("Full GitHub repo URL e.g. https://github.com/owner/repo"),
     }),
     annotations: { readOnlyHint: true, openWorldHint: true },
   }, async ({ url }) => {
-    const browser = await puppeteer.launch(env.BROWSER);
-    const page = await browser.newPage();
-    await page.setUserAgent("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/124.0.0.0 Safari/537.36");
-    await page.goto(url, { waitUntil: "domcontentloaded" });
-
-    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, stars, forks, lastCommit, description, topics, language };
-    })()`);
-
-    await browser.close();
-    const d = data as any;
-    const raw = [`Description: ${d.description ?? "N/A"}`, `Stars: ${d.stars ?? "N/A"} | Forks: ${d.forks ?? "N/A"}`, `Language: ${d.language ?? "N/A"}`, `Last commit: ${d.lastCommit ?? "N/A"}`, `Topics: ${d.topics?.join(", ") ?? "none"}`, `\n--- README ---\n${d.readme ?? "No README"}`].join("\n");
-    return { content: [{ type: "text", text: stamp(raw, url, d.lastCommit ?? null, d.lastCommit ? "high" : "medium", "github") }] };
+    try {
+      const safeUrl = validateUrl(url, "github");
+      const browser = await puppeteer.launch(env.BROWSER);
+      const page = await browser.newPage();
+      await page.setUserAgent("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/124.0.0.0 Safari/537.36");
+      await page.goto(safeUrl, { waitUntil: "domcontentloaded" });
+
+      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, stars, forks, lastCommit, description, topics, language };
+      })()`);
+
+      await browser.close();
+      const d = data as any;
+      const raw = [
+        `Description: ${d.description ?? "N/A"}`,
+        `Stars: ${d.stars ?? "N/A"} | Forks: ${d.forks ?? "N/A"}`,
+        `Language: ${d.language ?? "N/A"}`,
+        `Last commit: ${d.lastCommit ?? "N/A"}`,
+        `Topics: ${d.topics?.join(", ") ?? "none"}`,
+        `\n--- README ---\n${d.readme ?? "No README"}`,
+      ].join("\n");
+      return { content: [{ type: "text", text: stamp(raw, safeUrl, d.lastCommit ?? null, d.lastCommit ? "high" : "medium", "github") }] };
+    } catch (err: any) {
+      return { content: [{ type: "text", text: `[ERROR] ${err.message}` }] };
+    }
   });
 
   // ── extract_hackernews ──────────────────────────────────────────────────────
   server.registerTool("extract_hackernews", {
-    description: "Extract top stories from Hacker News with real-time timestamps.",
-    inputSchema: z.object({ url: z.string().url().describe("HN URL") }),
+    description: "Extract top stories or search results from Hacker News with real-time timestamps.",
+    inputSchema: z.object({ url: z.string().url().describe("HN URL e.g. https://news.ycombinator.com") }),
     annotations: { readOnlyHint: true, openWorldHint: true },
   }, async ({ url }) => {
-    const browser = await puppeteer.launch(env.BROWSER);
-    const page = await browser.newPage();
-    await page.goto(url, { waitUntil: "domcontentloaded" });
-
-    const data = await page.evaluate(`(function() {
-      var items = Array.from(document.querySelectorAll('.athing')).slice(0, 20);
-      return 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;
-        return { title, link, score, age };
-      });
-    })()`);
-
-    await browser.close();
-    const items = data as any[];
-    const raw = items.map((r, i) => `[${i + 1}] ${r.title}\nURL: ${r.link}\nScore: ${r.score ?? "N/A"}\nPosted: ${r.age ?? "unknown"}`).join("\n\n");
-    const newest = items.map(r => r.age).filter(Boolean).sort().reverse()[0] ?? null;
-    return { content: [{ type: "text", text: stamp(raw, url, newest, newest ? "high" : "medium", "hackernews") }] };
+    try {
+      const safeUrl = validateUrl(url, "hackernews");
+      const browser = await puppeteer.launch(env.BROWSER);
+      const page = await browser.newPage();
+      await page.goto(safeUrl, { waitUntil: "domcontentloaded" });
+
+      const data = await page.evaluate(`(function() {
+        var items = Array.from(document.querySelectorAll('.athing')).slice(0, 20);
+        return 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;
+          return { title, link, score, age };
+        });
+      })()`);
+
+      await browser.close();
+      const items = data as any[];
+      const raw = items.map((r, i) =>
+        `[${i + 1}] ${r.title}\nURL: ${r.link}\nScore: ${r.score ?? "N/A"}\nPosted: ${r.age ?? "unknown"}`
+      ).join("\n\n");
+      const newest = items.map(r => r.age).filter(Boolean).sort().reverse()[0] ?? null;
+      return { content: [{ type: "text", text: stamp(raw, safeUrl, newest, newest ? "high" : "medium", "hackernews") }] };
+    } catch (err: any) {
+      return { content: [{ type: "text", text: `[ERROR] ${err.message}` }] };
+    }
   });
 
   // ── extract_scholar ─────────────────────────────────────────────────────────
   server.registerTool("extract_scholar", {
     description: "Extract research results from Google Scholar with publication dates.",
-    inputSchema: z.object({ url: z.string().url().describe("Google Scholar URL") }),
+    inputSchema: z.object({ url: z.string().url().describe("Google Scholar search URL") }),
     annotations: { readOnlyHint: true, openWorldHint: true },
   }, async ({ url }) => {
-    const browser = await puppeteer.launch(env.BROWSER);
-    const page = await browser.newPage();
-    await page.setUserAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/124.0.0.0 Safari/537.36");
-    await page.goto(url, { waitUntil: "domcontentloaded" });
-
-    const data = await page.evaluate(`(function() {
-      var items = Array.from(document.querySelectorAll('.gs_r.gs_or.gs_scl'));
-      return 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 yearMatch = authors ? authors.match(/\\b(19|20)\\d{2}\\b/) : null;
-        var year = yearMatch ? yearMatch[0] : null;
-        return { title, authors, snippet, year };
-      });
-    })()`);
-
-    await browser.close();
-    const items = data as any[];
-    const raw = items.map((r, i) => `[${i + 1}] ${r.title ?? "Untitled"}\nAuthors: ${r.authors ?? "Unknown"}\nYear: ${r.year ?? "Unknown"}\nSnippet: ${r.snippet ?? "N/A"}`).join("\n\n");
-    const years = items.map(r => r.year).filter(Boolean).sort().reverse();
-    const newest = years[0] ?? null;
-    return { content: [{ type: "text", text: stamp(raw, url, newest ? `${newest}-01-01` : null, newest ? "high" : "low", "google_scholar") }] };
+    try {
+      const safeUrl = validateUrl(url, "scholar");
+      const browser = await puppeteer.launch(env.BROWSER);
+      const page = await browser.newPage();
+      await page.setUserAgent("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/124.0.0.0 Safari/537.36");
+      await page.goto(safeUrl, { waitUntil: "domcontentloaded" });
+
+      const data = await page.evaluate(`(function() {
+        var items = Array.from(document.querySelectorAll('.gs_r.gs_or.gs_scl'));
+        return 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 yearMatch = authors ? authors.match(/\\b(19|20)\\d{2}\\b/) : null;
+          var year = yearMatch ? yearMatch[0] : null;
+          return { title, authors, snippet, year };
+        });
+      })()`);
+
+      await browser.close();
+      const items = data as any[];
+      const raw = items.map((r, i) =>
+        `[${i + 1}] ${r.title ?? "Untitled"}\nAuthors: ${r.authors ?? "Unknown"}\nYear: ${r.year ?? "Unknown"}\nSnippet: ${r.snippet ?? "N/A"}`
+      ).join("\n\n");
+      const years = items.map(r => r.year).filter(Boolean).sort().reverse();
+      const newest = years[0] ?? null;
+      return { content: [{ type: "text", text: stamp(raw, safeUrl, newest ? `${newest}-01-01` : null, newest ? "high" : "low", "google_scholar") }] };
+    } catch (err: any) {
+      return { content: [{ type: "text", text: `[ERROR] ${err.message}` }] };
+    }
   });
 
   return server;
@@ -154,6 +315,23 @@ function createServer(env: Env): McpServer {
 
 export default {
   async fetch(request: Request, env: Env): Promise<Response> {
+    // Prune stale rate limit entries occasionally
+    if (Math.random() < 0.05) pruneRateMap();
+
+    try {
+      // 1. Auth check
+      checkAuth(request, env);
+
+      // 2. Rate limit check
+      const ip = getClientIp(request);
+      checkRateLimit(ip);
+
+    } catch (err: any) {
+      const status = err.message.startsWith("Unauthorized") ? 401 : 429;
+      return securityErrorResponse(err.message, status);
+    }
+
+    // 3. Handle MCP request
     const transport = new WebStandardStreamableHTTPServerTransport();
     const server = createServer(env);
     await server.connect(transport);