mcp-web-tools 0.2.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 paifas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# mcp-web-tools
+
+MCP server providing web search tools for AI assistants, powered by [Tavily](https://tavily.com).
+
+## Setup
+
+You need a [Tavily API key](https://tavily.com) (free tier available).
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add mcp-web-tools -e TAVILY_API_KEY=your-api-key -- npx -y mcp-web-tools
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "mcp-web-tools": {
+      "command": "npx",
+      "args": ["-y", "mcp-web-tools"],
+      "env": {
+        "TAVILY_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### OpenCode
+
+Add to `~/.config/opencode/opencode.json` (global) or `.opencode.json` in your project root:
+
+```jsonc
+"mcp-web-tools": {
+  "type": "local",
+  "command": ["npx", "-y", "mcp-web-tools"],
+  "environment": {
+    "TAVILY_API_KEY": "your-api-key"
+  }
+}
+```
+
+## Tools
+
+### `web_search`
+
+Search the web using Tavily. Returns results with titles, URLs, and snippets.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `query` | string | *required* | The search query |
+| `maxResults` | number | 5 | Maximum number of results (1–20) |
+| `searchDepth` | string | `"basic"` | `"basic"`, `"fast"`, `"ultra-fast"` (1 credit) or `"advanced"` (2 credits) |
+| `topic` | string | `"general"` | `"general"`, `"news"`, or `"finance"` |
+| `timeRange` | string | — | `"day"`, `"week"`, `"month"`, or `"year"` |
+| `startDate` | string | — | Start date filter (`YYYY-MM-DD`) |
+| `endDate` | string | — | End date filter (`YYYY-MM-DD`) |
+| `includeDomains` | string[] | — | Only include results from these domains |
+| `excludeDomains` | string[] | — | Exclude results from these domains |
+| `includeAnswer` | boolean | `true` | Include an AI-generated answer summary |
+
+### `credit_balance`
+
+Check your Tavily API credit balance and usage.
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `TAVILY_API_KEY` | Yes | — | Your Tavily API key. Get one at [tavily.com](https://tavily.com) |
+| `WEBTOOLS_MAX_RESULTS` | No | `5` | Default number of results |
+| `WEBTOOLS_SEARCH_DEPTH` | No | `basic` | Default search depth |
+| `WEBTOOLS_CACHE_TTL` | No | `3600` | Cache TTL in seconds (0 to disable) |
+| `WEBTOOLS_DEBUG` | No | — | Set to any value to enable debug logging to stderr |
+
+## Example Output
+
+```
+Node.js 22 introduces require() support for ES modules, a WebSocket client, and updates to the V8 JavaScript engine.
+
+### 1. [Node.js — Node.js 22 is now available!](https://nodejs.org/blog/announcements/v22-release-announce)
+> We're excited to announce the release of Node.js 22! Highlights include require()ing ES modules, a WebSocket client, updates of the V8 JavaScript engine, and more!
+
+*Response time: 1.2s*
+
+---
+
+Sources:
+- [Node.js — Node.js 22 is now available!](https://nodejs.org/blog/announcements/v22-release-announce)
+```
+
+## License
+
+MIT

package/build/config.d.ts

@@ -0,0 +1,9 @@
+export interface ServerConfig {
+    tavilyApiKey: string;
+    defaultMaxResults: number;
+    defaultSearchDepth: "advanced" | "basic" | "fast" | "ultra-fast";
+    cacheTtl: number;
+    serverName: string;
+    serverVersion: string;
+}
+export declare function loadConfig(): ServerConfig;

package/build/config.js

@@ -0,0 +1,36 @@
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function getPackageVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(resolve(__dirname, "../package.json"), "utf-8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export function loadConfig() {
+    const tavilyApiKey = process.env.TAVILY_API_KEY;
+    if (!tavilyApiKey) {
+        throw new Error("TAVILY_API_KEY environment variable is required. Get one at https://tavily.com");
+    }
+    const defaultMaxResults = parseInt(process.env.WEBTOOLS_MAX_RESULTS ?? "5", 10);
+    if (Number.isNaN(defaultMaxResults) || defaultMaxResults < 1) {
+        throw new Error(`Invalid WEBTOOLS_MAX_RESULTS value: "${process.env.WEBTOOLS_MAX_RESULTS}". Must be a positive integer.`);
+    }
+    const defaultSearchDepth = (process.env.WEBTOOLS_SEARCH_DEPTH ?? "basic");
+    const cacheTtl = parseInt(process.env.WEBTOOLS_CACHE_TTL ?? "3600", 10);
+    if (Number.isNaN(cacheTtl) || cacheTtl < 0) {
+        throw new Error(`Invalid WEBTOOLS_CACHE_TTL value: "${process.env.WEBTOOLS_CACHE_TTL}". Must be a non-negative integer (seconds).`);
+    }
+    return {
+        tavilyApiKey,
+        defaultMaxResults,
+        defaultSearchDepth,
+        cacheTtl,
+        serverName: "mcp-web-tools",
+        serverVersion: getPackageVersion(),
+    };
+}

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { registerWebSearchTool } from "./tools/web-search/index.js";
+import { registerWebReaderTool } from "./tools/web-reader/index.js";
+import { registerCreditBalanceTool } from "./tools/credit-balance/index.js";
+async function main() {
+    const config = loadConfig();
+    const server = new McpServer({
+        name: config.serverName,
+        version: config.serverVersion,
+    });
+    registerWebSearchTool(server, config);
+    registerWebReaderTool(server, config);
+    registerCreditBalanceTool(server, config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/build/providers/search-provider.d.ts

@@ -0,0 +1,29 @@
+import type { SearchResponse, ExtractResponse } from "../types.js";
+/** Parameters common to all search providers */
+export interface SearchParams {
+    query: string;
+    maxResults?: number;
+    searchDepth?: "advanced" | "basic" | "fast" | "ultra-fast";
+    topic?: "general" | "news" | "finance";
+    timeRange?: "day" | "week" | "month" | "year";
+    startDate?: string;
+    endDate?: string;
+    includeDomains?: string[];
+    excludeDomains?: string[];
+    includeAnswer?: boolean;
+}
+/** Parameters for extract providers */
+export interface ExtractParams {
+    urls: string[];
+    extractDepth?: "basic" | "advanced";
+    includeImages?: boolean;
+}
+/**
+ * Interface that every search provider must implement.
+ * Tavily is the first; Brave, SearXNG, Google can follow.
+ */
+export interface SearchProvider {
+    readonly name: string;
+    search(params: SearchParams): Promise<SearchResponse>;
+    extract?(params: ExtractParams): Promise<ExtractResponse>;
+}

package/build/providers/search-provider.js

@@ -0,0 +1 @@
+export {};

package/build/providers/tavily/client/index.d.ts

@@ -0,0 +1,88 @@
+/** Tavily API error types */
+export declare class TavilyError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** Raw Tavily search API response */
+export interface TavilySearchResponse {
+    query: string;
+    answer?: string;
+    results: {
+        title: string;
+        url: string;
+        content: string;
+        score: number;
+    }[];
+    response_time?: number;
+}
+/** Raw Tavily extract API response */
+export interface TavilyExtractResponse {
+    results: {
+        url: string;
+        raw_content: string;
+        images?: string[];
+    }[];
+    failed_results: {
+        url: string;
+        error: string;
+    }[];
+    response_time?: number;
+}
+/** Parameters for the Tavily extract request body */
+export interface TavilyExtractParams {
+    urls: string[];
+    extract_depth?: "basic" | "advanced";
+    include_images?: boolean;
+}
+/** Parameters for the Tavily search request body */
+export interface TavilySearchParams {
+    query: string;
+    search_depth?: "advanced" | "basic" | "fast" | "ultra-fast";
+    max_results?: number;
+    topic?: "general" | "news" | "finance";
+    time_range?: "day" | "week" | "month" | "year";
+    start_date?: string;
+    end_date?: string;
+    include_answer?: boolean;
+    include_domains?: string[];
+    exclude_domains?: string[];
+}
+/** Usage response from Tavily API */
+export interface TavilyUsageResponse {
+    key: {
+        usage: number;
+        limit: number;
+        search_usage: number;
+        extract_usage: number;
+        crawl_usage: number;
+        map_usage: number;
+        research_usage: number;
+    };
+    account: {
+        current_plan: string;
+        plan_usage: number;
+        plan_limit: number;
+        paygo_usage: number;
+        paygo_limit: number;
+        search_usage: number;
+        extract_usage: number;
+        crawl_usage: number;
+        map_usage: number;
+        research_usage: number;
+    };
+}
+/**
+ * Low-level HTTP client for the Tavily Search API.
+ */
+export declare class TavilyClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(apiKey: string, timeout?: number);
+    private request;
+    search(params: TavilySearchParams): Promise<TavilySearchResponse>;
+    extract(params: TavilyExtractParams): Promise<TavilyExtractResponse>;
+    getUsage(): Promise<TavilyUsageResponse>;
+}
+/** Debug logger -- outputs to stderr when WEBTOOLS_DEBUG is set */
+export declare function log(message: string): void;

package/build/providers/tavily/client/index.js

@@ -0,0 +1,122 @@
+/** Tavily API error types */
+export class TavilyError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "TavilyError";
+    }
+}
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 1000;
+function isRetryable(status) {
+    return status === 429 || status >= 500;
+}
+/**
+ * Low-level HTTP client for the Tavily Search API.
+ */
+export class TavilyClient {
+    baseUrl = "https://api.tavily.com";
+    apiKey;
+    timeout;
+    constructor(apiKey, timeout = 30_000) {
+        this.apiKey = apiKey;
+        this.timeout = timeout;
+    }
+    async request(endpoint, body) {
+        let lastError;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            if (attempt > 0) {
+                const delay = BASE_DELAY_MS * Math.pow(2, attempt - 1);
+                log(`retry ${attempt}/${MAX_RETRIES} after ${delay}ms`);
+                await sleep(delay);
+            }
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeout);
+            try {
+                const response = await fetch(`${this.baseUrl}${endpoint}`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Authorization: `Bearer ${this.apiKey}`,
+                    },
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    const text = await response.text().catch(() => "");
+                    const msg = response.status === 401
+                        ? `Invalid Tavily API key. ${text}`
+                        : response.status === 429
+                            ? `Tavily API rate limit exceeded. You may have used your monthly quota. ${text}`
+                            : `Tavily API error (${response.status}): ${text}`;
+                    lastError = new TavilyError(msg, response.status);
+                    if (isRetryable(response.status) && attempt < MAX_RETRIES) {
+                        continue;
+                    }
+                    throw lastError;
+                }
+                return (await response.json());
+            }
+            catch (error) {
+                if (error instanceof TavilyError) {
+                    if (isRetryable(error.status) && attempt < MAX_RETRIES) {
+                        lastError = error;
+                        continue;
+                    }
+                    throw error;
+                }
+                if (error instanceof Error && error.name === "AbortError") {
+                    throw new TavilyError("Tavily API request timed out", 408);
+                }
+                throw new TavilyError(`Tavily API request failed: ${error instanceof Error ? error.message : String(error)}`, 500);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        throw lastError;
+    }
+    async search(params) {
+        return this.request("/search", params);
+    }
+    async extract(params) {
+        return this.request("/extract", params);
+    }
+    async getUsage() {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(`${this.baseUrl}/usage`, {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const text = await response.text().catch(() => "");
+                throw new TavilyError(`Failed to fetch usage (${response.status}): ${text}`, response.status);
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof TavilyError)
+                throw error;
+            throw new TavilyError(`Failed to fetch usage: ${error instanceof Error ? error.message : String(error)}`, 500);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Debug logger -- outputs to stderr when WEBTOOLS_DEBUG is set */
+export function log(message) {
+    if (process.env.WEBTOOLS_DEBUG) {
+        const ts = new Date().toISOString().slice(11, 19);
+        process.stderr.write(`[webtools ${ts}] ${message}\n`);
+    }
+}

package/build/providers/tavily/tavily-search.d.ts

@@ -0,0 +1,14 @@
+import type { SearchResponse, ExtractResponse } from "../../types.js";
+import type { SearchProvider, SearchParams, ExtractParams } from "../search-provider.js";
+import { TavilyError } from "./client/index.js";
+/**
+ * Tavily implementation of the SearchProvider interface.
+ */
+export declare class TavilySearchProvider implements SearchProvider {
+    readonly name = "tavily";
+    private readonly client;
+    constructor(apiKey: string);
+    search(params: SearchParams): Promise<SearchResponse>;
+    extract(params: ExtractParams): Promise<ExtractResponse>;
+}
+export { TavilyError };

package/build/providers/tavily/tavily-search.js

@@ -0,0 +1,57 @@
+import { TavilyClient, TavilyError } from "./client/index.js";
+/**
+ * Tavily implementation of the SearchProvider interface.
+ */
+export class TavilySearchProvider {
+    name = "tavily";
+    client;
+    constructor(apiKey) {
+        this.client = new TavilyClient(apiKey);
+    }
+    async search(params) {
+        const response = await this.client.search({
+            query: params.query,
+            search_depth: params.searchDepth,
+            max_results: params.maxResults,
+            topic: params.topic,
+            time_range: params.timeRange,
+            start_date: params.startDate,
+            end_date: params.endDate,
+            include_answer: params.includeAnswer ?? true,
+            include_domains: params.includeDomains,
+            exclude_domains: params.excludeDomains,
+        });
+        return {
+            query: response.query,
+            answer: response.answer,
+            results: response.results.map((r) => ({
+                title: r.title,
+                url: r.url,
+                snippet: r.content,
+                score: r.score,
+            })),
+            responseTime: response.response_time,
+        };
+    }
+    async extract(params) {
+        const response = await this.client.extract({
+            urls: params.urls,
+            extract_depth: params.extractDepth,
+            include_images: params.includeImages,
+        });
+        return {
+            results: response.results.map((r) => ({
+                url: r.url,
+                content: r.raw_content,
+                images: r.images,
+            })),
+            failedResults: response.failed_results.map((f) => ({
+                url: f.url,
+                error: f.error,
+            })),
+            responseTime: response.response_time,
+        };
+    }
+}
+// Re-export for convenience
+export { TavilyError };

package/build/tools/credit-balance/index.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ServerConfig } from "../../config.js";
+export declare function registerCreditBalanceTool(server: McpServer, config: ServerConfig): void;

package/build/tools/credit-balance/index.js

@@ -0,0 +1,37 @@
+import { TavilyClient, TavilyError } from "../../providers/tavily/client/index.js";
+export function registerCreditBalanceTool(server, config) {
+    const client = new TavilyClient(config.tavilyApiKey);
+    server.tool("credit_balance", "Check your Tavily API credit balance.", {}, async () => {
+        try {
+            const usage = await client.getUsage();
+            const remaining = usage.account.plan_limit - usage.account.plan_usage;
+            const percentUsed = usage.account.plan_limit > 0 ? Math.round((usage.account.plan_usage / usage.account.plan_limit) * 100) : 0;
+            const lines = [
+                `Plan: ${usage.account.current_plan} — ${usage.account.plan_usage} / ${usage.account.plan_limit} credits (${percentUsed}% used)`,
+                `Remaining: ${remaining}`,
+                `Breakdown — search: ${usage.account.search_usage}, extract: ${usage.account.extract_usage}`,
+            ];
+            if (remaining < 50) {
+                lines.push("Credits running low. Top up at https://tavily.com");
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        catch (error) {
+            if (error instanceof TavilyError) {
+                return {
+                    content: [{ type: "text", text: `Credit balance error: ${error.message}` }],
+                    isError: true,
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Unexpected error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/web-reader/index.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ServerConfig } from "../../config.js";
+export declare function registerWebReaderTool(server: McpServer, config: ServerConfig): void;

package/build/tools/web-reader/index.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { TavilySearchProvider, TavilyError } from "../../providers/tavily/tavily-search.js";
+import { log } from "../../providers/tavily/client/index.js";
+import { formatExtractResponse } from "../../utils/format/index.js";
+import { cacheKey, cacheGet, cacheSet } from "../../utils/cache/index.js";
+const webReaderSchema = {
+    urls: z.array(z.string()).min(1).max(20).describe("URLs to extract content from (1-20)"),
+    extractDepth: z
+        .enum(["basic", "advanced"])
+        .optional()
+        .describe("Extraction depth: basic (1 credit per 5 URLs, returns raw page HTML as markdown including navigation and boilerplate) or advanced (2 credits per 5 URLs, extracts clean article content with navigation/ads/sidebar/footer stripped)"),
+    includeImages: z.boolean().optional().describe("Include extracted image URLs (default: false)"),
+};
+export function registerWebReaderTool(server, config) {
+    const provider = new TavilySearchProvider(config.tavilyApiKey);
+    server.tool("web_read", "Extract clean content from web pages. Returns page text stripped of navigation, ads, and scripts. Supports up to 20 URLs per request.", webReaderSchema, async (params) => {
+        try {
+            // URL validation
+            for (const url of params.urls) {
+                if (!url.startsWith("http://") && !url.startsWith("https://")) {
+                    return {
+                        content: [{ type: "text", text: `Invalid URL: "${url}". Must start with http:// or https://.` }],
+                        isError: true,
+                    };
+                }
+                try {
+                    new URL(url);
+                }
+                catch {
+                    return {
+                        content: [{ type: "text", text: `Invalid URL format: "${url}".` }],
+                        isError: true,
+                    };
+                }
+            }
+            // Cache lookup
+            const extractParams = {
+                urls: params.urls,
+                extractDepth: params.extractDepth,
+                includeImages: params.includeImages,
+            };
+            const key = cacheKey("extract", extractParams);
+            const cached = cacheGet(key);
+            if (cached) {
+                log("cache hit: extract");
+                const text = formatExtractResponse(cached);
+                return { content: [{ type: "text", text }] };
+            }
+            log(`cache miss: extract ${params.urls.length} url(s)`);
+            // Non-null assertion fix
+            if (!provider.extract) {
+                return {
+                    content: [{ type: "text", text: "Extract not supported by current provider." }],
+                    isError: true,
+                };
+            }
+            const response = await provider.extract(extractParams);
+            cacheSet(key, response, config.cacheTtl);
+            const text = formatExtractResponse(response);
+            return {
+                content: [{ type: "text", text }],
+            };
+        }
+        catch (error) {
+            if (error instanceof TavilyError) {
+                return {
+                    content: [{ type: "text", text: `Extract error: ${error.message}` }],
+                    isError: true,
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Unexpected error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/web-search/index.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ServerConfig } from "../../config.js";
+export declare function registerWebSearchTool(server: McpServer, config: ServerConfig): void;

package/build/tools/web-search/index.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { TavilySearchProvider, TavilyError } from "../../providers/tavily/tavily-search.js";
+import { log } from "../../providers/tavily/client/index.js";
+import { formatSearchResponse } from "../../utils/format/index.js";
+import { cacheKey, cacheGet, cacheSet } from "../../utils/cache/index.js";
+const webSearchSchema = {
+    query: z.string().describe("The search query"),
+    maxResults: z.number().min(1).max(20).optional().describe("Maximum number of results (default: 5)"),
+    searchDepth: z
+        .enum(["advanced", "basic", "fast", "ultra-fast"])
+        .optional()
+        .describe("Search depth: basic/fast/ultra-fast (1 credit) or advanced (2 credits)"),
+    topic: z.enum(["general", "news", "finance"]).optional().describe("Search topic category"),
+    timeRange: z.enum(["day", "week", "month", "year"]).optional().describe("Time range filter for results"),
+    startDate: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in YYYY-MM-DD format")
+        .optional()
+        .describe("Start date filter (YYYY-MM-DD)"),
+    endDate: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in YYYY-MM-DD format")
+        .optional()
+        .describe("End date filter (YYYY-MM-DD)"),
+    includeDomains: z.array(z.string()).optional().describe("Only include results from these domains"),
+    excludeDomains: z.array(z.string()).optional().describe("Exclude results from these domains"),
+    includeAnswer: z.boolean().optional().describe("Include an AI-generated answer (default: true)"),
+};
+export function registerWebSearchTool(server, config) {
+    const provider = new TavilySearchProvider(config.tavilyApiKey);
+    server.tool("web_search", "Search the web using Tavily. Returns results with titles, URLs, and snippets. Supports filtering by domain, topic, time range, and search depth.", webSearchSchema, async (params) => {
+        try {
+            const searchParams = {
+                query: params.query,
+                maxResults: params.maxResults ?? config.defaultMaxResults,
+                searchDepth: params.searchDepth ?? config.defaultSearchDepth,
+                topic: params.topic,
+                timeRange: params.timeRange,
+                startDate: params.startDate,
+                endDate: params.endDate,
+                includeDomains: params.includeDomains,
+                excludeDomains: params.excludeDomains,
+                includeAnswer: params.includeAnswer ?? true,
+            };
+            const key = cacheKey("search", searchParams);
+            const cached = cacheGet(key);
+            if (cached) {
+                log("cache hit: search");
+                const text = formatSearchResponse(cached);
+                return { content: [{ type: "text", text }] };
+            }
+            log(`cache miss: search "${params.query}"`);
+            const response = await provider.search(searchParams);
+            cacheSet(key, response, config.cacheTtl);
+            const text = formatSearchResponse(response);
+            return {
+                content: [{ type: "text", text }],
+            };
+        }
+        catch (error) {
+            if (error instanceof TavilyError) {
+                return {
+                    content: [{ type: "text", text: `Search error: ${error.message}` }],
+                    isError: true,
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Unexpected error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/build/types.d.ts

@@ -0,0 +1,29 @@
+/** Normalized search result from any provider */
+export interface SearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+    score?: number;
+}
+/** Normalized search response */
+export interface SearchResponse {
+    query: string;
+    answer?: string;
+    results: SearchResult[];
+    responseTime?: number;
+}
+/** Normalized extract result */
+export interface ExtractResult {
+    url: string;
+    content: string;
+    images?: string[];
+}
+/** Normalized extract response */
+export interface ExtractResponse {
+    results: ExtractResult[];
+    failedResults: {
+        url: string;
+        error: string;
+    }[];
+    responseTime?: number;
+}

package/build/types.js

@@ -0,0 +1 @@
+export {};

package/build/utils/cache/index.d.ts

@@ -0,0 +1,6 @@
+/** Serialize params with sorted keys for deterministic cache keys. */
+export declare function cacheKey(prefix: string, params: unknown): string;
+/** Get a cached value. Returns undefined on miss or if expired. */
+export declare function cacheGet<T>(key: string): T | undefined;
+/** Store a value with the given TTL in seconds. */
+export declare function cacheSet(key: string, data: unknown, ttlSeconds: number): void;

package/build/utils/cache/index.js

@@ -0,0 +1,23 @@
+const store = new Map();
+/** Serialize params with sorted keys for deterministic cache keys. */
+export function cacheKey(prefix, params) {
+    const sorted = JSON.stringify(params, Object.keys(params).sort());
+    return `${prefix}:${sorted}`;
+}
+/** Get a cached value. Returns undefined on miss or if expired. */
+export function cacheGet(key) {
+    const entry = store.get(key);
+    if (!entry)
+        return undefined;
+    if (Date.now() > entry.expires) {
+        store.delete(key);
+        return undefined;
+    }
+    return entry.data;
+}
+/** Store a value with the given TTL in seconds. */
+export function cacheSet(key, data, ttlSeconds) {
+    if (ttlSeconds <= 0)
+        return;
+    store.set(key, { data, expires: Date.now() + ttlSeconds * 1000 });
+}

package/build/utils/format/index.d.ts

@@ -0,0 +1,9 @@
+import type { SearchResponse, ExtractResponse } from "../../types.js";
+/**
+ * Formats a SearchResponse into a markdown string suitable for MCP tool output.
+ */
+export declare function formatSearchResponse(response: SearchResponse): string;
+/**
+ * Formats an ExtractResponse into a markdown string suitable for MCP tool output.
+ */
+export declare function formatExtractResponse(response: ExtractResponse): string;

package/build/utils/format/index.js

@@ -0,0 +1,53 @@
+/**
+ * Formats a SearchResponse into a markdown string suitable for MCP tool output.
+ */
+export function formatSearchResponse(response) {
+    const parts = [];
+    if (response.answer) {
+        parts.push(response.answer);
+        parts.push("");
+    }
+    for (let i = 0; i < response.results.length; i++) {
+        const result = response.results[i];
+        parts.push(`### ${i + 1}. [${result.title}](${result.url})`);
+        parts.push(`> ${result.snippet}`);
+        parts.push("");
+    }
+    if (response.responseTime != null) {
+        parts.push(`*Response time: ${response.responseTime}ms*`);
+        parts.push("");
+    }
+    parts.push("---");
+    parts.push("");
+    parts.push("Sources:");
+    for (const result of response.results) {
+        parts.push(`- [${result.title}](${result.url})`);
+    }
+    return parts.join("\n");
+}
+/**
+ * Formats an ExtractResponse into a markdown string suitable for MCP tool output.
+ */
+export function formatExtractResponse(response) {
+    const parts = [];
+    for (const result of response.results) {
+        parts.push(`## ${result.url}`);
+        parts.push("");
+        parts.push(result.content);
+        parts.push("");
+    }
+    if (response.failedResults.length > 0) {
+        parts.push("---");
+        parts.push("");
+        parts.push("Failed:");
+        for (const failed of response.failedResults) {
+            parts.push(`- ${failed.url}: ${failed.error}`);
+        }
+        parts.push("");
+    }
+    if (response.responseTime != null) {
+        parts.push(`*Response time: ${response.responseTime}ms*`);
+        parts.push("");
+    }
+    return parts.join("\n");
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "mcp-web-tools",
+  "version": "0.2.6",
+  "description": "MCP server providing web search tools for AI assistants",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "mcp-web-tools": "./build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "dev": "tsx src/index.ts",
+    "start": "node build/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paifas/mcp-web-tools.git"
+  },
+  "homepage": "https://github.com/paifas/mcp-web-tools#readme",
+  "bugs": {
+    "url": "https://github.com/paifas/mcp-web-tools/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "web-search",
+    "tavily",
+    "ai",
+    "claude",
+    "opencode"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.5.2",
+    "@vitest/coverage-v8": "^4.1.4",
+    "eslint": "^10.2.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.1",
+    "vitest": "^4.1.4"
+  }
+}