freshcontext-mcp 0.1.4 → 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.4",
+  "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);