freshcontext-mcp 0.1.1 → 0.1.3

package/README.md

@@ -1,60 +1,92 @@
 # freshcontext-mcp
 
-> Real-time web extraction MCP server with guaranteed freshness timestamps for AI agents.
+> 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" 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.
+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.
 
-## The Fix
+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.
 
-Every piece of data extracted by `freshcontext-mcp` is wrapped in a `FreshContext` envelope:
+## The Fix: 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"
-}
+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-03T10:14:00Z
+Confidence: high
+---
+... content ...
+[/FRESHCONTEXT]
 ```
 
-The AI agent always knows *when it's looking at*, not just *what*.
+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.
+
+---
+
+## Tools
+
+### 🔬 Intelligence Tools
 
-## Adapters
+| 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 |
 
-| 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 |
+### 🚀 Competitive Intelligence Tools
 
-## Setup
+| Tool | Description |
+|---|---|
+| `extract_yc` | Scrape YC company listings by keyword — find who's funded in your space |
+| `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 |
+
+### 🗺️ Composite Tool
+
+| Tool | Description |
+|---|---|
+| `extract_landscape` | **One call. Full picture.** Queries YC startups + GitHub repos + HN sentiment + package ecosystem simultaneously. Returns a unified landscape report. |
+
+---
+
+## Quick Start
+
+### Install via npm
 
 ```bash
-git clone https://github.com/YOUR_USERNAME/freshcontext-mcp
-cd freshcontext-mcp
-npm install
-npx playwright install chromium
-npm run build
+npx freshcontext-mcp
 ```
 
-## Test locally
+### Or clone and run locally
 
 ```bash
-npm run inspect
+git clone https://github.com/PrinceGabriel-lgtm/freshcontext-mcp
+cd freshcontext-mcp
+npm install
+npx playwright install chromium
+npm run build
 ```
 
-## Connect to Claude
+### 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`
+
 ```json
 {
   "mcpServers": {
-    "freshcontext": {
+    "freshcontext-local": {
       "command": "node",
       "args": ["/absolute/path/to/freshcontext-mcp/dist/server.js"]
     }
@@ -62,10 +94,131 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
+Restart Claude Desktop. You'll see the freshcontext tools available in your session.
+
+### Or use the Cloudflare edge deployment (no install needed)
+
+```json
+{
+  "mcpServers": {
+    "freshcontext-cloud": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://freshcontext-worker.gimmanuel73.workers.dev/mcp"]
+    }
+  }
+}
+```
+
+---
+
+## 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.
+
+### Analyse a specific repo
+
+```
+Use extract_github on https://github.com/anthropics/anthropic-sdk-python
+```
+
+### Find research papers on a topic
+
+```
+Use extract_scholar on https://scholar.google.com/scholar?q=llm+context+freshness
+```
+
+### Check package ecosystem health
+
+```
+Use package_trends with packages "npm:@modelcontextprotocol/sdk,pypi:langchain"
+```
+
+---
+
+## 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
+
+This makes freshness **verifiable**, not assumed.
+
+---
+
+## Deployment
+
+### Local (Playwright-based)
+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.
+
+```bash
+cd worker
+npm install
+npx wrangler secret put CF_API_TOKEN
+npx wrangler deploy
+```
+
+---
+
+## Project Structure
+
+```
+freshcontext-mcp/
+├── src/
+│   ├── server.ts              # MCP server, all tool registrations
+│   ├── types.ts               # FreshContext interfaces
+│   ├── 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
+│   └── tools/
+│       └── freshnessStamp.ts  # FreshContext envelope builder
+└── worker/                    # Cloudflare Workers deployment
+    └── src/worker.ts
+```
+
+---
+
 ## Roadmap
 
-- [ ] Twitter/X public feed adapter
-- [ ] Dev.to / Hashnode adapter  
-- [ ] Supabase changelog adapter
-- [ ] Cloudflare Worker deployment
-- [ ] Caching layer with TTL
+- [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
+- [ ] Product Hunt launches adapter
+- [ ] Crunchbase/funding signals 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 }`.
+
+---
+
+## License
+
+MIT

package/dist/adapters/github.js

@@ -1,5 +1,8 @@
 import { chromium } from "playwright";
+import { validateUrl } from "../security.js";
 export async function githubAdapter(options) {
+    const safeUrl = validateUrl(options.url, "github");
+    options = { ...options, url: safeUrl };
     const browser = await chromium.launch({ headless: true });
     const page = await browser.newPage();
     // Spoof a real browser UA to avoid bot detection

package/dist/adapters/hackernews.js

@@ -1,6 +1,8 @@
 import { chromium } from "playwright";
+import { validateUrl } from "../security.js";
 export async function hackerNewsAdapter(options) {
-    // If it's an Algolia API URL or search query, use the REST API directly (no browser)
+    // Validate URL — allow both HN and Algolia domains
+    validateUrl(options.url, "hackernews");
     const url = options.url;
     if (url.includes("hn.algolia.com/api/") || url.startsWith("hn-search:")) {
         const query = url.startsWith("hn-search:")

package/dist/adapters/packageTrends.js

@@ -1,8 +1,8 @@
+import { sanitizePackages } from "../security.js";
 // 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();
+    // Sanitize package input
+    const raw_input = sanitizePackages(options.url.replace(/^https?:\/\//, "").trim());
     // Parse ecosystem prefix
     const parts = raw_input.split(",").map((s) => s.trim());
     const results = [];

package/dist/adapters/repoSearch.js

@@ -1,8 +1,9 @@
+import { sanitizeQuery } from "../security.js";
 // 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;
+    // Sanitize query input
+    const query_input = sanitizeQuery(options.url);
+    let query = query_input;
     // If it's a full URL, extract the query param
     try {
         const parsed = new URL(options.url);

package/dist/adapters/scholar.js

@@ -1,5 +1,8 @@
 import { chromium } from "playwright";
+import { validateUrl } from "../security.js";
 export async function scholarAdapter(options) {
+    const safeUrl = validateUrl(options.url, "scholar");
+    options = { ...options, url: safeUrl };
     const browser = await chromium.launch({ headless: true });
     const page = await browser.newPage();
     await page.setExtraHTTPHeaders({

package/dist/adapters/yc.js

@@ -1,5 +1,8 @@
 import { chromium } from "playwright";
+import { validateUrl } from "../security.js";
 export async function ycAdapter(options) {
+    const safeUrl = validateUrl(options.url, "yc");
+    options = { ...options, url: safeUrl };
     const browser = await chromium.launch({ headless: true });
     const page = await browser.newPage();
     // YC company directory is React-rendered — wait for network to settle

package/dist/security.js

@@ -0,0 +1,117 @@
+/**
+ * freshcontext-mcp security module
+ * Input sanitization, domain allowlists, and request validation
+ */
+// ─── Allowed domains per adapter ────────────────────────────────────────────
+export const ALLOWED_DOMAINS = {
+    github: ["github.com", "raw.githubusercontent.com"],
+    scholar: ["scholar.google.com"],
+    hackernews: ["news.ycombinator.com", "hn.algolia.com"],
+    yc: ["www.ycombinator.com", "ycombinator.com"],
+    repoSearch: [], // uses GitHub API directly, no browser
+    packageTrends: [], // uses npm/PyPI APIs directly, no browser
+};
+// ─── Blocked IP ranges and internal hostnames ────────────────────────────────
+const BLOCKED_PATTERNS = [
+    /^localhost$/i,
+    /^127\.\d+\.\d+\.\d+$/,
+    /^10\.\d+\.\d+\.\d+$/,
+    /^172\.(1[6-9]|2\d|3[01])\.\d+\.\d+$/,
+    /^192\.168\.\d+\.\d+$/,
+    /^169\.254\.\d+\.\d+$/, // AWS metadata
+    /^0\.0\.0\.0$/,
+    /^::1$/,
+    /^fc00:/i,
+    /^fe80:/i,
+];
+// ─── Max length limits ────────────────────────────────────────────────────────
+export const MAX_URL_LENGTH = 500;
+export const MAX_QUERY_LENGTH = 200;
+export const MAX_PACKAGES_LENGTH = 300;
+// ─── Validation errors ───────────────────────────────────────────────────────
+export class SecurityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SecurityError";
+    }
+}
+// ─── URL validator ───────────────────────────────────────────────────────────
+export function validateUrl(rawUrl, adapterName) {
+    // Length check
+    if (!rawUrl || rawUrl.trim().length === 0) {
+        throw new SecurityError("URL cannot be empty");
+    }
+    if (rawUrl.length > MAX_URL_LENGTH) {
+        throw new SecurityError(`URL exceeds maximum length of ${MAX_URL_LENGTH} characters`);
+    }
+    // Must be a valid URL
+    let parsed;
+    try {
+        parsed = new URL(rawUrl.trim());
+    }
+    catch {
+        throw new SecurityError(`Invalid URL format: ${rawUrl}`);
+    }
+    // Must use http or https
+    if (!["http:", "https:"].includes(parsed.protocol)) {
+        throw new SecurityError(`Protocol not allowed: ${parsed.protocol}. Only http/https permitted.`);
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    // Block internal/private IPs and hostnames
+    for (const pattern of BLOCKED_PATTERNS) {
+        if (pattern.test(hostname)) {
+            throw new SecurityError(`Access to internal/private addresses is not permitted: ${hostname}`);
+        }
+    }
+    // Domain allowlist check (skip if allowlist is empty — means no browser used)
+    const allowedDomains = ALLOWED_DOMAINS[adapterName];
+    if (allowedDomains && allowedDomains.length > 0) {
+        const isAllowed = allowedDomains.some((domain) => hostname === domain || hostname.endsWith(`.${domain}`));
+        if (!isAllowed) {
+            throw new SecurityError(`Domain not allowed for ${adapterName} adapter: ${hostname}. ` +
+                `Allowed domains: ${allowedDomains.join(", ")}`);
+        }
+    }
+    return parsed.toString();
+}
+// ─── Query string sanitizer ──────────────────────────────────────────────────
+export function sanitizeQuery(query, maxLength = MAX_QUERY_LENGTH) {
+    if (!query || query.trim().length === 0) {
+        throw new SecurityError("Query cannot be empty");
+    }
+    const trimmed = query.trim().slice(0, maxLength);
+    // Strip null bytes and control characters
+    const cleaned = trimmed.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "");
+    if (cleaned.length === 0) {
+        throw new SecurityError("Query contains no valid characters after sanitization");
+    }
+    return cleaned;
+}
+// ─── Package name sanitizer ──────────────────────────────────────────────────
+export function sanitizePackages(input) {
+    if (!input || input.trim().length === 0) {
+        throw new SecurityError("Package name cannot be empty");
+    }
+    if (input.length > MAX_PACKAGES_LENGTH) {
+        throw new SecurityError(`Package input exceeds maximum length of ${MAX_PACKAGES_LENGTH} characters`);
+    }
+    // Only allow valid npm/PyPI package name characters, commas, colons (for npm:/pypi: prefix)
+    const cleaned = input
+        .trim()
+        .replace(/[^a-zA-Z0-9@/._\-,:]/g, "")
+        .slice(0, MAX_PACKAGES_LENGTH);
+    if (cleaned.length === 0) {
+        throw new SecurityError("Package name contains no valid characters after sanitization");
+    }
+    return cleaned;
+}
+// ─── Error formatter ─────────────────────────────────────────────────────────
+export function formatSecurityError(err) {
+    if (err instanceof SecurityError) {
+        return `[Security] ${err.message}`;
+    }
+    if (err instanceof Error) {
+        return `[Error] ${err.message}`;
+    }
+    return "[Error] Unknown error occurred";
+}

package/dist/server.js

@@ -8,6 +8,7 @@ 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 { formatSecurityError } from "./security.js";
 const server = new McpServer({
     name: "freshcontext-mcp",
     version: "0.1.0",
@@ -21,9 +22,14 @@ server.registerTool("extract_github", {
     }),
     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) }] };
+    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", {
@@ -34,9 +40,14 @@ server.registerTool("extract_scholar", {
     }),
     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) }] };
+    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", {
@@ -47,9 +58,14 @@ server.registerTool("extract_hackernews", {
     }),
     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) }] };
+    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", {
@@ -60,9 +76,14 @@ server.registerTool("extract_yc", {
     }),
     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) }] };
+    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", {
@@ -73,9 +94,14 @@ server.registerTool("search_repos", {
     }),
     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) }] };
+    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", {
@@ -86,9 +112,14 @@ server.registerTool("package_trends", {
     }),
     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) }] };
+    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", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "freshcontext-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Real-time web extraction MCP server with freshness timestamps for AI agents",
   "keywords": [
     "mcp",

package/src/adapters/github.ts

@@ -1,7 +1,11 @@
 import { chromium } from "playwright";
 import { AdapterResult, ExtractOptions } from "../types.js";
+import { validateUrl } from "../security.js";
 
 export async function githubAdapter(options: ExtractOptions): Promise<AdapterResult> {
+  const safeUrl = validateUrl(options.url, "github");
+  options = { ...options, url: safeUrl };
+
   const browser = await chromium.launch({ headless: true });
   const page = await browser.newPage();
 

package/src/adapters/hackernews.ts

@@ -1,8 +1,10 @@
 import { chromium } from "playwright";
 import { AdapterResult, ExtractOptions } from "../types.js";
+import { validateUrl } from "../security.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)
+  // Validate URL — allow both HN and Algolia domains
+  validateUrl(options.url, "hackernews");
   const url = options.url;
 
   if (url.includes("hn.algolia.com/api/") || url.startsWith("hn-search:")) {

package/src/adapters/packageTrends.ts

@@ -1,10 +1,10 @@
 import { AdapterResult, ExtractOptions } from "../types.js";
+import { sanitizePackages } from "../security.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();
+  // Sanitize package input
+  const raw_input = sanitizePackages(options.url.replace(/^https?:\/\//, "").trim());
 
   // Parse ecosystem prefix
   const parts = raw_input.split(",").map((s) => s.trim());

package/src/adapters/repoSearch.ts

@@ -1,10 +1,11 @@
 import { AdapterResult, ExtractOptions } from "../types.js";
+import { sanitizeQuery } from "../security.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;
+  // Sanitize query input
+  const query_input = sanitizeQuery(options.url);
+  let query = query_input;
 
   // If it's a full URL, extract the query param
   try {

package/src/adapters/scholar.ts

@@ -1,7 +1,11 @@
 import { chromium } from "playwright";
 import { AdapterResult, ExtractOptions } from "../types.js";
+import { validateUrl } from "../security.js";
 
 export async function scholarAdapter(options: ExtractOptions): Promise<AdapterResult> {
+  const safeUrl = validateUrl(options.url, "scholar");
+  options = { ...options, url: safeUrl };
+
   const browser = await chromium.launch({ headless: true });
   const page = await browser.newPage();
 

package/src/adapters/yc.ts

@@ -1,7 +1,11 @@
 import { chromium } from "playwright";
 import { AdapterResult, ExtractOptions } from "../types.js";
+import { validateUrl } from "../security.js";
 
 export async function ycAdapter(options: ExtractOptions): Promise<AdapterResult> {
+  const safeUrl = validateUrl(options.url, "yc");
+  options = { ...options, url: safeUrl };
+
   const browser = await chromium.launch({ headless: true });
   const page = await browser.newPage();
 

package/src/security.ts

@@ -0,0 +1,161 @@
+/**
+ * freshcontext-mcp security module
+ * Input sanitization, domain allowlists, and request validation
+ */
+
+// ─── Allowed domains per adapter ────────────────────────────────────────────
+
+export 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"],
+  repoSearch: [], // uses GitHub API directly, no browser
+  packageTrends: [], // uses npm/PyPI APIs directly, no browser
+};
+
+// ─── Blocked IP ranges and internal hostnames ────────────────────────────────
+
+const BLOCKED_PATTERNS = [
+  /^localhost$/i,
+  /^127\.\d+\.\d+\.\d+$/,
+  /^10\.\d+\.\d+\.\d+$/,
+  /^172\.(1[6-9]|2\d|3[01])\.\d+\.\d+$/,
+  /^192\.168\.\d+\.\d+$/,
+  /^169\.254\.\d+\.\d+$/, // AWS metadata
+  /^0\.0\.0\.0$/,
+  /^::1$/,
+  /^fc00:/i,
+  /^fe80:/i,
+];
+
+// ─── Max length limits ────────────────────────────────────────────────────────
+
+export const MAX_URL_LENGTH = 500;
+export const MAX_QUERY_LENGTH = 200;
+export const MAX_PACKAGES_LENGTH = 300;
+
+// ─── Validation errors ───────────────────────────────────────────────────────
+
+export class SecurityError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SecurityError";
+  }
+}
+
+// ─── URL validator ───────────────────────────────────────────────────────────
+
+export function validateUrl(
+  rawUrl: string,
+  adapterName: keyof typeof ALLOWED_DOMAINS
+): string {
+  // Length check
+  if (!rawUrl || rawUrl.trim().length === 0) {
+    throw new SecurityError("URL cannot be empty");
+  }
+  if (rawUrl.length > MAX_URL_LENGTH) {
+    throw new SecurityError(
+      `URL exceeds maximum length of ${MAX_URL_LENGTH} characters`
+    );
+  }
+
+  // Must be a valid URL
+  let parsed: URL;
+  try {
+    parsed = new URL(rawUrl.trim());
+  } catch {
+    throw new SecurityError(`Invalid URL format: ${rawUrl}`);
+  }
+
+  // Must use http or https
+  if (!["http:", "https:"].includes(parsed.protocol)) {
+    throw new SecurityError(
+      `Protocol not allowed: ${parsed.protocol}. Only http/https permitted.`
+    );
+  }
+
+  const hostname = parsed.hostname.toLowerCase();
+
+  // Block internal/private IPs and hostnames
+  for (const pattern of BLOCKED_PATTERNS) {
+    if (pattern.test(hostname)) {
+      throw new SecurityError(
+        `Access to internal/private addresses is not permitted: ${hostname}`
+      );
+    }
+  }
+
+  // Domain allowlist check (skip if allowlist is empty — means no browser used)
+  const allowedDomains = ALLOWED_DOMAINS[adapterName];
+  if (allowedDomains && allowedDomains.length > 0) {
+    const isAllowed = allowedDomains.some(
+      (domain) => hostname === domain || hostname.endsWith(`.${domain}`)
+    );
+    if (!isAllowed) {
+      throw new SecurityError(
+        `Domain not allowed for ${adapterName} adapter: ${hostname}. ` +
+          `Allowed domains: ${allowedDomains.join(", ")}`
+      );
+    }
+  }
+
+  return parsed.toString();
+}
+
+// ─── Query string sanitizer ──────────────────────────────────────────────────
+
+export function sanitizeQuery(query: string, maxLength = MAX_QUERY_LENGTH): string {
+  if (!query || query.trim().length === 0) {
+    throw new SecurityError("Query cannot be empty");
+  }
+
+  const trimmed = query.trim().slice(0, maxLength);
+
+  // Strip null bytes and control characters
+  const cleaned = trimmed.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "");
+
+  if (cleaned.length === 0) {
+    throw new SecurityError("Query contains no valid characters after sanitization");
+  }
+
+  return cleaned;
+}
+
+// ─── Package name sanitizer ──────────────────────────────────────────────────
+
+export function sanitizePackages(input: string): string {
+  if (!input || input.trim().length === 0) {
+    throw new SecurityError("Package name cannot be empty");
+  }
+
+  if (input.length > MAX_PACKAGES_LENGTH) {
+    throw new SecurityError(
+      `Package input exceeds maximum length of ${MAX_PACKAGES_LENGTH} characters`
+    );
+  }
+
+  // Only allow valid npm/PyPI package name characters, commas, colons (for npm:/pypi: prefix)
+  const cleaned = input
+    .trim()
+    .replace(/[^a-zA-Z0-9@/._\-,:]/g, "")
+    .slice(0, MAX_PACKAGES_LENGTH);
+
+  if (cleaned.length === 0) {
+    throw new SecurityError("Package name contains no valid characters after sanitization");
+  }
+
+  return cleaned;
+}
+
+// ─── Error formatter ─────────────────────────────────────────────────────────
+
+export function formatSecurityError(err: unknown): string {
+  if (err instanceof SecurityError) {
+    return `[Security] ${err.message}`;
+  }
+  if (err instanceof Error) {
+    return `[Error] ${err.message}`;
+  }
+  return "[Error] Unknown error occurred";
+}

package/src/server.ts

@@ -8,6 +8,7 @@ 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",
@@ -27,9 +28,13 @@ server.registerTool(
     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) }] };
+    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) }] };
+    }
   }
 );
 
@@ -46,9 +51,13 @@ server.registerTool(
     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) }] };
+    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) }] };
+    }
   }
 );
 
@@ -65,9 +74,13 @@ server.registerTool(
     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) }] };
+    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) }] };
+    }
   }
 );
 
@@ -84,9 +97,13 @@ server.registerTool(
     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) }] };
+    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) }] };
+    }
   }
 );
 
@@ -103,9 +120,13 @@ server.registerTool(
     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) }] };
+    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) }] };
+    }
   }
 );
 
@@ -122,9 +143,13 @@ server.registerTool(
     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) }] };
+    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) }] };
+    }
   }
 );