@oevortex/ddg_search 1.0.0

package/LICENSE

@@ -0,0 +1,194 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting the License. You accept and agree to be bound by the
+      terms of this License by copying, modifying, or distributing the
+      Work (or any work based on the Work).
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,224 @@
+<!--
+  DuckDuckGo Search MCP - Modern README
+  Author: @OEvortex | License: Apache 2.0
+-->
+
+<div align="center">
+  <img src="https://img.shields.io/npm/v/@OEvortex/ddg_search.svg" alt="npm version" />
+  <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0" />
+  <img src="https://img.shields.io/badge/YouTube-%40OEvortex-red.svg" alt="YouTube Channel" />
+  <h1>DuckDuckGo Search MCP 🔍</h1>
+  <p>A blazing-fast, privacy-friendly Model Context Protocol (MCP) server for web search and URL content extraction using DuckDuckGo.</p>
+  <a href="https://youtube.com/@OEvortex"><strong>Subscribe for updates & tutorials</strong></a>
+</div>
+
+---
+
+> [!IMPORTANT]
+> DuckDuckGo Search MCP supports two types of compatibility:
+> - <b>Native MCP Compatibility:</b> Use the full power of the Model Context Protocol for maximum flexibility.
+> - <b>OpenAI Compatibility:</b> Use with OpenAI-compatible interfaces and providers.
+>
+> Choose the approach that best fits your needs! For OpenAI compatibility, check the <a href="webscout/Provider/OPENAI/README.md">OpenAI Providers README</a>.
+
+> [!NOTE]
+> DuckDuckGo Search MCP is compatible with Claude, Anthropic, OpenAI, Perplexity, HuggingFace, LLAMA, and 90+ other AI providers. All providers follow similar usage patterns with consistent interfaces.
+
+---
+
+## ✨ Features
+
+<div style="display: flex; flex-wrap: wrap; gap: 1.5em;">
+  <div><b>🌐 Web search</b> using DuckDuckGo HTML</div>
+  <div><b>📄 URL content extraction</b> with smart filtering</div>
+  <div><b>📊 URL metadata extraction</b> (title, description, images)</div>
+  <div><b>⚡ Performance optimized</b> with caching</div>
+  <div><b>🛡️ Security features</b> including rate limiting and rotating user agents</div>
+  <div><b>🔌 MCP-compliant</b> server implementation</div>
+  <div><b>🆓 No API keys required</b> - works out of the box</div>
+</div>
+
+> [!IMPORTANT]
+> Unlike many search tools, this package performs actual web scraping rather than using limited APIs, giving you more comprehensive results.
+
+---
+
+## 🚀 Quick Start
+
+<div style="background: #222; color: #fff; padding: 1em; border-radius: 8px;">
+<b>Run instantly with npx:</b>
+
+```bash
+npx -y @OEvortex/ddg_search
+```
+</div>
+
+> [!TIP]
+> This will download and run the MCP server directly without installation – perfect for quick use with Claude, OpenAI, or other AI assistants.
+
+---
+
+## 🛠️ Installation Options
+
+<details>
+<summary><b>Global Installation</b></summary>
+
+```bash
+npm install -g @OEvortex/ddg_search
+```
+
+Run globally:
+
+```bash
+ddg-search-mcp
+```
+
+</details>
+
+<details>
+<summary><b>Local Installation (Development)</b></summary>
+
+```bash
+git clone https://github.com/OEvortex/ddg_search.git
+cd ddg_search
+npm install
+npm start
+```
+
+</details>
+
+---
+
+## 🧑‍💻 Command Line Options
+
+```bash
+npx -y @OEvortex/ddg_search --help
+```
+
+> [!TIP]
+> Use the <code>--version</code> flag to check which version you're running.
+
+---
+
+## 🤖 Using with Claude, OpenAI, or Other MCP Clients
+
+> [!IMPORTANT]
+> The most common way to use this tool is by integrating it with Claude, OpenAI, or other MCP-compatible AI assistants.
+
+Add the server to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "ddg-search": {
+      "command": "npx",
+      "args": ["-y", "@OEvortex/ddg_search"]
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "ddg-search": {
+      "command": "ddg-search-mcp"
+    }
+  }
+}
+```
+
+> [!TIP]
+> After configuring, restart your Claude Desktop or other MCP client to apply the changes.
+
+---
+
+## 🧰 Tools Overview
+
+<div style="display: flex; flex-wrap: wrap; gap: 2em;">
+  <div>
+    <b>🔍 Web Search Tool</b><br/>
+    <code>web-search</code><br/>
+    <ul>
+      <li><b>query</b> (string, required): The search query</li>
+      <li><b>page</b> (integer, optional, default: 1): Page number</li>
+      <li><b>numResults</b> (integer, optional, default: 10): Number of results (1-20)</li>
+    </ul>
+    <i>Example: Search the web for "climate change solutions"</i>
+  </div>
+  <div>
+    <b>📄 Fetch URL Tool</b><br/>
+    <code>fetch-url</code><br/>
+    <ul>
+      <li><b>url</b> (string, required): The URL to fetch</li>
+      <li><b>maxLength</b> (integer, optional, default: 10000): Max content length</li>
+      <li><b>extractMainContent</b> (boolean, optional, default: true): Extract main content</li>
+      <li><b>includeLinks</b> (boolean, optional, default: true): Include link text</li>
+      <li><b>includeImages</b> (boolean, optional, default: true): Include image alt text</li>
+      <li><b>excludeTags</b> (array, optional): Tags to exclude</li>
+    </ul>
+    <i>Example: Fetch the content from "https://example.com"</i>
+  </div>
+  <div>
+    <b>📊 URL Metadata Tool</b><br/>
+    <code>url-metadata</code><br/>
+    <ul>
+      <li><b>url</b> (string, required): The URL to extract metadata from</li>
+    </ul>
+    <i>Example: Get metadata for "https://example.com"</i>
+  </div>
+</div>
+
+---
+
+## 📁 Project Structure
+
+```text
+bin/              # Command-line interface
+src/
+  index.js        # Main entry point
+  tools/          # Tool definitions and handlers
+    searchTool.js
+    fetchUrlTool.js
+    metadataTool.js
+  utils/
+    search.js     # Search and URL utilities
+package.json
+README.md
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please open issues or submit pull requests.
+
+> [!NOTE]
+> Please follow the existing code style and add tests for new features.
+
+---
+
+## 📺 YouTube Channel
+
+<div align="center">
+  <a href="https://youtube.com/@OEvortex"><img src="https://img.shields.io/badge/YouTube-%40OEvortex-red.svg" alt="YouTube Channel" /></a>
+  <br/>
+  <a href="https://youtube.com/@OEvortex">youtube.com/@OEvortex</a>
+</div>
+
+---
+
+## 📄 License
+
+Apache License 2.0
+
+> [!NOTE]
+> This project is licensed under the Apache License 2.0 – see the <a href="LICENSE">LICENSE</a> file for details.
+
+---
+
+<div align="center">
+  <sub>Made with ❤️ by <a href="https://youtube.com/@OEvortex">@OEvortex</a></sub>
+</div>

package/bin/cli.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+// Import tool definitions and handlers
+const modulePath = new URL('../src', import.meta.url).pathname;
+
+// Dynamic imports
+async function startServer() {
+  try {
+    // Dynamically import the modules
+    const { searchToolDefinition, searchToolHandler } = await import(`${modulePath}/tools/searchTool.js`);
+    const { fetchUrlToolDefinition, fetchUrlToolHandler } = await import(`${modulePath}/tools/fetchUrlTool.js`);
+    const { metadataToolDefinition, metadataToolHandler } = await import(`${modulePath}/tools/metadataTool.js`);
+
+    // Create the MCP server
+    const server = new Server({
+      id: 'ddg-search-mcp',
+      name: 'DuckDuckGo Search MCP',
+      description: 'A Model Context Protocol server for web search using DuckDuckGo',
+      version: '1.0.0'
+    }, {
+      capabilities: {
+        tools: {}
+      }
+    });
+
+    // Define available tools
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return {
+        tools: [
+          searchToolDefinition,
+          fetchUrlToolDefinition,
+          metadataToolDefinition
+        ]
+      };
+    });
+
+    // Handle tool execution
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      try {
+        const { name, arguments: args } = request.params;
+
+        // Route to the appropriate tool handler
+        switch (name) {
+          case 'web-search':
+            return await searchToolHandler(args);
+
+          case 'fetch-url':
+            return await fetchUrlToolHandler(args);
+
+          case 'url-metadata':
+            return await metadataToolHandler(args);
+
+          default:
+            throw new Error(`Tool not found: ${name}`);
+        }
+      } catch (error) {
+        console.error(`Error handling ${request.params.name} request:`, error);
+        return {
+          isError: true,
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${error.message}`
+            }
+          ]
+        };
+      }
+    });
+
+    // Display promotional message
+    console.error('\n\x1b[36m╔════════════════════════════════════════════════════════════╗');
+    console.error('║                                                            ║');
+    console.error('║  \x1b[1m\x1b[31mDuckDuckGo Search MCP\x1b[0m\x1b[36m by \x1b[1m\x1b[33m@OEvortex\x1b[0m\x1b[36m                     ║');
+    console.error('║                                                            ║');
+    console.error('║  \x1b[0m👉 Subscribe to \x1b[1m\x1b[37myoutube.com/@OEvortex\x1b[0m\x1b[36m for more tools!  ║');
+    console.error('║                                                            ║');
+    console.error('╚════════════════════════════════════════════════════════════╝\x1b[0m\n');
+
+    // Start the server with stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('DuckDuckGo Search MCP server started and listening on stdio');
+  } catch (error) {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+  }
+}
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const helpFlag = args.includes('--help') || args.includes('-h');
+const versionFlag = args.includes('--version') || args.includes('-v');
+
+if (helpFlag) {
+  console.log(`
+DuckDuckGo Search MCP - A Model Context Protocol server for web search
+
+Usage:
+  npx -y @OEvortex/ddg_search [options]
+
+Options:
+  -h, --help     Show this help message
+  -v, --version  Show version information
+
+This MCP server provides the following tools:
+  - web-search: Search the web using DuckDuckGo
+  - fetch-url: Fetch and extract content from a URL
+  - url-metadata: Extract metadata from a URL
+
+Created by @OEvortex
+Subscribe to youtube.com/@OEvortex for more tools and tutorials!
+
+For more information, visit: https://github.com/OEvortex/ddg_search
+  `);
+  process.exit(0);
+}
+
+if (versionFlag) {
+  // Read version from package.json using fs
+  import('fs/promises')
+    .then(async ({ readFile }) => {
+      try {
+        const packageJson = JSON.parse(
+          await readFile(new URL('../package.json', import.meta.url), 'utf8')
+        );
+        console.log(`DuckDuckGo Search MCP v${packageJson.version}\nCreated by @OEvortex - Subscribe to youtube.com/@OEvortex!`);
+        process.exit(0);
+      } catch (err) {
+        console.error('Error reading version information:', err);
+        process.exit(1);
+      }
+    })
+    .catch(err => {
+      console.error('Error importing fs module:', err);
+      process.exit(1);
+    });
+} else {
+  // Start the server
+  startServer();
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@oevortex/ddg_search",
+  "version": "1.0.0",
+  "description": "A Model Context Protocol server for web search using DuckDuckGo",
+  "main": "src/index.js",
+  "bin": {
+    "ddg-search-mcp": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node bin/cli.js",
+    "prepublishOnly": "npm run lint",
+    "lint": "echo \"No linting configured\""
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["mcp", "model-context-protocol", "duckduckgo", "search", "web-search", "claude", "ai", "llm"],
+  "author": "OEvortex",
+  "license": "Apache-2.0",
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.9.0",
+    "axios": "^1.8.4",
+    "cheerio": "^1.0.0",
+    "jsdom": "^26.1.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,78 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+// Import tool definitions and handlers
+import { searchToolDefinition, searchToolHandler } from './tools/searchTool.js';
+import { fetchUrlToolDefinition, fetchUrlToolHandler } from './tools/fetchUrlTool.js';
+import { metadataToolDefinition, metadataToolHandler } from './tools/metadataTool.js';
+
+// Create the MCP server
+const server = new Server({
+  id: 'websearch-mcp',
+  name: 'WebSearch MCP',
+  description: 'A Model Context Protocol server for web search using DuckDuckGo',
+  version: '1.0.0'
+}, {
+  capabilities: {
+    tools: {}
+  }
+});
+
+// Define available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      searchToolDefinition,
+      fetchUrlToolDefinition,
+      metadataToolDefinition
+    ]
+  };
+});
+
+// Handle tool execution
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  try {
+    const { name, arguments: args } = request.params;
+    
+    // Route to the appropriate tool handler
+    switch (name) {
+      case 'web-search':
+        return await searchToolHandler(args);
+      
+      case 'fetch-url':
+        return await fetchUrlToolHandler(args);
+      
+      case 'url-metadata':
+        return await metadataToolHandler(args);
+      
+      default:
+        throw new Error(`Tool not found: ${name}`);
+    }
+  } catch (error) {
+    console.error(`Error handling ${request.params.name} request:`, error);
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: `Error: ${error.message}`
+        }
+      ]
+    };
+  }
+});
+
+// Start the server with stdio transport
+async function main() {
+  try {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('WebSearch MCP server started and listening on stdio');
+  } catch (error) {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+  }
+}
+
+main();

package/src/tools/fetchUrlTool.js

@@ -0,0 +1,118 @@
+import { fetchUrlContent } from '../utils/search.js';
+
+/**
+ * Fetch URL tool definition
+ */
+export const fetchUrlToolDefinition = {
+  name: 'fetch-url',
+  description: 'Fetch the content of a URL and return it as text, with options to control extraction',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      url: {
+        type: 'string',
+        description: 'The URL to fetch'
+      },
+      maxLength: {
+        type: 'integer',
+        description: 'Maximum length of content to return (default: 10000)',
+        default: 10000,
+        minimum: 1000,
+        maximum: 50000
+      },
+      extractMainContent: {
+        type: 'boolean',
+        description: 'Whether to attempt to extract main content (default: true)',
+        default: true
+      },
+      includeLinks: {
+        type: 'boolean',
+        description: 'Whether to include link text (default: true)',
+        default: true
+      },
+      includeImages: {
+        type: 'boolean',
+        description: 'Whether to include image alt text (default: true)',
+        default: true
+      },
+      excludeTags: {
+        type: 'array',
+        description: 'Tags to exclude from extraction (default: script, style, etc.)',
+        items: {
+          type: 'string'
+        }
+      }
+    },
+    required: ['url']
+  },
+  annotations: {
+    title: 'Fetch URL Content',
+    readOnlyHint: true,
+    openWorldHint: true
+  }
+};
+
+/**
+ * Fetch URL tool handler
+ * @param {Object} params - The tool parameters
+ * @returns {Promise<Object>} - The tool result
+ */
+export async function fetchUrlToolHandler(params) {
+  const {
+    url,
+    maxLength = 10000,
+    extractMainContent = true,
+    includeLinks = true,
+    includeImages = true,
+    excludeTags = ['script', 'style', 'noscript', 'iframe', 'svg', 'nav', 'footer', 'header', 'aside']
+  } = params;
+
+  console.log(`Fetching content from URL: ${url} (maxLength: ${maxLength})`);
+
+  try {
+    // Fetch content with specified options
+    const content = await fetchUrlContent(url, {
+      extractMainContent,
+      includeLinks,
+      includeImages,
+      excludeTags
+    });
+
+    // Truncate content if it's too long
+    const truncatedContent = content.length > maxLength
+      ? content.substring(0, maxLength) + '... [Content truncated due to length]'
+      : content;
+
+    // Add metadata about the extraction
+    const metadata = `
+---
+Extraction settings:
+- URL: ${url}
+- Main content extraction: ${extractMainContent ? 'Enabled' : 'Disabled'}
+- Links included: ${includeLinks ? 'Yes' : 'No'}
+- Images included: ${includeImages ? 'Yes (as alt text)' : 'No'}
+- Content length: ${content.length} characters${content.length > maxLength ? ` (truncated to ${maxLength})` : ''}
+---
+`;
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: truncatedContent + metadata
+        }
+      ]
+    };
+  } catch (error) {
+    console.error(`Error fetching URL ${url}:`, error);
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: `Error fetching URL: ${error.message}`
+        }
+      ]
+    };
+  }
+}

package/src/tools/metadataTool.js

@@ -0,0 +1,58 @@
+import { extractUrlMetadata } from '../utils/search.js';
+
+/**
+ * URL metadata tool definition
+ */
+export const metadataToolDefinition = {
+  name: 'url-metadata',
+  description: 'Extract metadata from a URL (title, description, etc.)',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      url: {
+        type: 'string',
+        description: 'The URL to extract metadata from'
+      }
+    },
+    required: ['url']
+  },
+  annotations: {
+    title: 'URL Metadata',
+    readOnlyHint: true,
+    openWorldHint: true
+  }
+};
+
+/**
+ * URL metadata tool handler
+ * @param {Object} params - The tool parameters
+ * @returns {Promise<Object>} - The tool result
+ */
+export async function metadataToolHandler(params) {
+  const { url } = params;
+  console.log(`Extracting metadata from URL: ${url}`);
+  
+  const metadata = await extractUrlMetadata(url);
+  
+  // Format the metadata for display
+  const formattedMetadata = `
+## URL Metadata for ${url}
+
+**Title:** ${metadata.title}
+
+**Description:** ${metadata.description}
+
+**Image:** ${metadata.ogImage || 'None'}
+
+**Favicon:** ${metadata.favicon || 'None'}
+  `.trim();
+  
+  return {
+    content: [
+      {
+        type: 'text',
+        text: formattedMetadata
+      }
+    ]
+  };
+}

package/src/tools/searchTool.js

@@ -0,0 +1,64 @@
+import { searchDuckDuckGo } from '../utils/search.js';
+
+/**
+ * Web search tool definition
+ */
+export const searchToolDefinition = {
+  name: 'web-search',
+  description: 'Search the web using DuckDuckGo and return results',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'The search query'
+      },
+      page: {
+        type: 'integer',
+        description: 'Page number (default: 1)',
+        default: 1,
+        minimum: 1
+      },
+      numResults: {
+        type: 'integer',
+        description: 'Number of results to return (default: 10)',
+        default: 10,
+        minimum: 1,
+        maximum: 20
+      }
+    },
+    required: ['query']
+  },
+  annotations: {
+    title: 'Web Search',
+    readOnlyHint: true,
+    openWorldHint: true
+  }
+};
+
+/**
+ * Web search tool handler
+ * @param {Object} params - The tool parameters
+ * @returns {Promise<Object>} - The tool result
+ */
+export async function searchToolHandler(params) {
+  const { query, page = 1, numResults = 10 } = params;
+  console.log(`Searching for: ${query} (page ${page}, ${numResults} results)`);
+  
+  const results = await searchDuckDuckGo(query, page, numResults);
+  console.log(`Found ${results.length} results`);
+  
+  // Format the results for display
+  const formattedResults = results.map((result, index) => 
+    `${index + 1}. [${result.title}](${result.url})\n   ${result.snippet}`
+  ).join('\n\n');
+  
+  return {
+    content: [
+      {
+        type: 'text',
+        text: formattedResults || 'No results found.'
+      }
+    ]
+  };
+}

package/src/utils/search.js

@@ -0,0 +1,401 @@
+import axios from 'axios';
+import { JSDOM } from 'jsdom';
+
+// Constants
+const RESULTS_PER_PAGE = 10;
+const MAX_CACHE_PAGES = 5;
+
+// Rotating User Agents
+const USER_AGENTS = [
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Edge/120.0.0.0',
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2.1 Safari/605.1.15',
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:122.0) Gecko/20100101 Firefox/122.0',
+  'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
+];
+
+// Cache results to avoid repeated requests
+const resultsCache = new Map();
+const CACHE_DURATION = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Get a random user agent from the list
+ * @returns {string} A random user agent string
+ */
+function getRandomUserAgent() {
+  return USER_AGENTS[Math.floor(Math.random() * USER_AGENTS.length)];
+}
+
+/**
+ * Generate a cache key for a search query and page
+ * @param {string} query - The search query
+ * @param {number} page - The page number
+ * @returns {string} The cache key
+ */
+function getCacheKey(query, page) {
+  return `${query}-${page}`;
+}
+
+/**
+ * Clear old entries from the cache
+ */
+function clearOldCache() {
+  const now = Date.now();
+  for (const [key, value] of resultsCache.entries()) {
+    if (now - value.timestamp > CACHE_DURATION) {
+      resultsCache.delete(key);
+    }
+  }
+}
+
+/**
+ * Extract the direct URL from a DuckDuckGo redirect URL
+ * @param {string} duckduckgoUrl - The DuckDuckGo URL to extract from
+ * @returns {string} The direct URL
+ */
+function extractDirectUrl(duckduckgoUrl) {
+  try {
+    // Handle relative URLs from DuckDuckGo
+    if (duckduckgoUrl.startsWith('//')) {
+      duckduckgoUrl = 'https:' + duckduckgoUrl;
+    } else if (duckduckgoUrl.startsWith('/')) {
+      duckduckgoUrl = 'https://duckduckgo.com' + duckduckgoUrl;
+    }
+
+    const url = new URL(duckduckgoUrl);
+
+    // Extract direct URL from DuckDuckGo redirect
+    if (url.hostname === 'duckduckgo.com' && url.pathname === '/l/') {
+      const uddg = url.searchParams.get('uddg');
+      if (uddg) {
+        return decodeURIComponent(uddg);
+      }
+    }
+
+    // Handle ad redirects
+    if (url.hostname === 'duckduckgo.com' && url.pathname === '/y.js') {
+      const u3 = url.searchParams.get('u3');
+      if (u3) {
+        try {
+          const decodedU3 = decodeURIComponent(u3);
+          const u3Url = new URL(decodedU3);
+          const clickUrl = u3Url.searchParams.get('ld');
+          if (clickUrl) {
+            return decodeURIComponent(clickUrl);
+          }
+          return decodedU3;
+        } catch {
+          return duckduckgoUrl;
+        }
+      }
+    }
+
+    return duckduckgoUrl;
+  } catch {
+    // If URL parsing fails, try to extract URL from a basic string match
+    const urlMatch = duckduckgoUrl.match(/https?:\/\/[^\s<>"]+/);
+    if (urlMatch) {
+      return urlMatch[0];
+    }
+    return duckduckgoUrl;
+  }
+}
+
+/**
+ * Get a favicon URL for a given website URL
+ * @param {string} url - The website URL
+ * @returns {string} The favicon URL
+ */
+function getFaviconUrl(url) {
+  try {
+    const urlObj = new URL(url);
+    return `https://www.google.com/s2/favicons?domain=${urlObj.hostname}&sz=32`;
+  } catch {
+    return ''; // Return empty string if URL is invalid
+  }
+}
+
+/**
+ * Scrapes search results from DuckDuckGo HTML
+ * @param {string} query - The search query
+ * @param {number} page - The page number (default: 1)
+ * @param {number} numResults - Number of results to return (default: 10)
+ * @returns {Promise<Array>} - Array of search results
+ */
+async function searchDuckDuckGo(query, page = 1, numResults = 10) {
+  try {
+    // Clear old cache entries
+    clearOldCache();
+
+    // Calculate start index for pagination
+    const startIndex = (page - 1) * RESULTS_PER_PAGE;
+
+    // Check cache first
+    const cacheKey = getCacheKey(query, page);
+    const cachedResults = resultsCache.get(cacheKey);
+
+    if (cachedResults && Date.now() - cachedResults.timestamp < CACHE_DURATION) {
+      return cachedResults.results.slice(0, numResults);
+    }
+
+    // Get a random user agent
+    const userAgent = getRandomUserAgent();
+
+    // Fetch results
+    const response = await axios.get(
+      `https://duckduckgo.com/html/?q=${encodeURIComponent(query)}&s=${startIndex}`,
+      {
+        headers: {
+          'User-Agent': userAgent
+        }
+      }
+    );
+
+    if (response.status !== 200) {
+      throw new Error('Failed to fetch search results');
+    }
+
+    const html = response.data;
+
+    // Parse results using JSDOM
+    const dom = new JSDOM(html);
+    const document = dom.window.document;
+
+    const results = [];
+    const searchResults = document.querySelectorAll('.result');
+
+    searchResults.forEach((result) => {
+      const titleEl = result.querySelector('.result__title a');
+      const linkEl = result.querySelector('.result__url');
+      const snippetEl = result.querySelector('.result__snippet');
+
+      const title = titleEl?.textContent?.trim();
+      const rawLink = titleEl?.getAttribute('href');
+      const description = snippetEl?.textContent?.trim();
+      const displayUrl = linkEl?.textContent?.trim();
+
+      const directLink = extractDirectUrl(rawLink || '');
+      const favicon = getFaviconUrl(directLink);
+
+      if (title && directLink) {
+        results.push({
+          title,
+          url: directLink,
+          snippet: description || '',
+          favicon: favicon,
+          displayUrl: displayUrl || ''
+        });
+      }
+    });
+
+    // Get paginated results
+    const paginatedResults = results.slice(0, numResults);
+
+    // Cache the results
+    resultsCache.set(cacheKey, {
+      results: paginatedResults,
+      timestamp: Date.now()
+    });
+
+    // If cache is too big, remove oldest entries
+    if (resultsCache.size > MAX_CACHE_PAGES) {
+      const oldestKey = Array.from(resultsCache.keys())[0];
+      resultsCache.delete(oldestKey);
+    }
+
+    return paginatedResults;
+  } catch (error) {
+    console.error('Error searching DuckDuckGo:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Fetches the content of a URL and returns it as text
+ * @param {string} url - The URL to fetch
+ * @param {Object} options - Options for content extraction
+ * @param {boolean} options.extractMainContent - Whether to attempt to extract main content (default: true)
+ * @param {boolean} options.includeLinks - Whether to include link text (default: true)
+ * @param {boolean} options.includeImages - Whether to include image alt text (default: true)
+ * @param {string[]} options.excludeTags - Tags to exclude from extraction
+ * @returns {Promise<string>} - The content of the URL
+ */
+async function fetchUrlContent(url, options = {}) {
+  try {
+    // Default options
+    const {
+      extractMainContent = true,
+      includeLinks = true,
+      includeImages = true,
+      excludeTags = ['script', 'style', 'noscript', 'iframe', 'svg', 'nav', 'footer', 'header', 'aside']
+    } = options;
+
+    // Get a random user agent
+    const userAgent = getRandomUserAgent();
+
+    const response = await axios.get(url, {
+      headers: {
+        'User-Agent': userAgent
+      },
+      timeout: 10000 // 10 second timeout
+    });
+
+    if (response.status !== 200) {
+      throw new Error(`Failed to fetch URL: ${url}`);
+    }
+
+    // If the content is HTML, extract the text content
+    const contentType = response.headers['content-type'] || '';
+    if (contentType.includes('text/html')) {
+      const dom = new JSDOM(response.data);
+      const document = dom.window.document;
+
+      // Remove unwanted elements
+      excludeTags.forEach(tag => {
+        const elements = document.querySelectorAll(tag);
+        elements.forEach(el => el.remove());
+      });
+
+      // Remove ads and other common unwanted elements
+      const unwantedSelectors = [
+        '[id*="ad"]', '[class*="ad"]', '[id*="banner"]', '[class*="banner"]',
+        '[id*="popup"]', '[class*="popup"]', '[class*="cookie"]',
+        '[id*="cookie"]', '[class*="newsletter"]', '[id*="newsletter"]',
+        '[class*="social"]', '[id*="social"]', '[class*="share"]', '[id*="share"]'
+      ];
+
+      unwantedSelectors.forEach(selector => {
+        try {
+          const elements = document.querySelectorAll(selector);
+          elements.forEach(el => el.remove());
+        } catch (e) {
+          // Ignore invalid selectors
+        }
+      });
+
+      // Handle links and images
+      if (!includeLinks) {
+        const links = document.querySelectorAll('a');
+        links.forEach(link => {
+          const span = document.createElement('span');
+          span.textContent = link.textContent;
+          link.parentNode.replaceChild(span, link);
+        });
+      }
+
+      if (!includeImages) {
+        const images = document.querySelectorAll('img');
+        images.forEach(img => img.remove());
+      } else {
+        // Replace images with their alt text
+        const images = document.querySelectorAll('img');
+        images.forEach(img => {
+          const alt = img.getAttribute('alt');
+          if (alt) {
+            const span = document.createElement('span');
+            span.textContent = `[Image: ${alt}]`;
+            img.parentNode.replaceChild(span, img);
+          } else {
+            img.remove();
+          }
+        });
+      }
+
+      // Try to extract main content if requested
+      if (extractMainContent) {
+        // Common content selectors in order of priority
+        const contentSelectors = [
+          'article', 'main', '[role="main"]', '.post-content', '.article-content',
+          '.content', '#content', '.post', '.article', '.entry-content',
+          '.page-content', '.post-body', '.post-text', '.story-body'
+        ];
+
+        for (const selector of contentSelectors) {
+          const mainContent = document.querySelector(selector);
+          if (mainContent) {
+            // Clean up the content
+            return cleanText(mainContent.textContent);
+          }
+        }
+      }
+
+      // If no main content found or not requested, use the body
+      return cleanText(document.body.textContent);
+    }
+
+    // For non-HTML content, return as is
+    return response.data.toString();
+  } catch (error) {
+    console.error('Error fetching URL content:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Cleans up text by removing excessive whitespace and normalizing line breaks
+ * @param {string} text - The text to clean
+ * @returns {string} - The cleaned text
+ */
+function cleanText(text) {
+  return text
+    .replace(/\s+/g, ' ')  // Replace multiple whitespace with single space
+    .replace(/\n\s*\n/g, '\n\n')  // Normalize multiple line breaks
+    .replace(/^\s+|\s+$/g, '')  // Trim start and end
+    .trim();
+}
+
+/**
+ * Extracts metadata from a URL (title, description, etc.)
+ * @param {string} url - The URL to extract metadata from
+ * @returns {Promise<Object>} - The metadata
+ */
+async function extractUrlMetadata(url) {
+  try {
+    // Get a random user agent
+    const userAgent = getRandomUserAgent();
+
+    const response = await axios.get(url, {
+      headers: {
+        'User-Agent': userAgent
+      }
+    });
+
+    if (response.status !== 200) {
+      throw new Error(`Failed to fetch URL: ${url}`);
+    }
+
+    const dom = new JSDOM(response.data);
+    const document = dom.window.document;
+
+    // Extract metadata
+    const title = document.querySelector('title')?.textContent || '';
+    const description = document.querySelector('meta[name="description"]')?.getAttribute('content') ||
+                       document.querySelector('meta[property="og:description"]')?.getAttribute('content') || '';
+    const ogImage = document.querySelector('meta[property="og:image"]')?.getAttribute('content') || '';
+    const favicon = document.querySelector('link[rel="icon"]')?.getAttribute('href') ||
+                  document.querySelector('link[rel="shortcut icon"]')?.getAttribute('href') || '';
+
+    // Resolve relative URLs
+    const resolvedFavicon = favicon ? new URL(favicon, url).href : getFaviconUrl(url);
+    const resolvedOgImage = ogImage ? new URL(ogImage, url).href : '';
+
+    return {
+      title,
+      description,
+      ogImage: resolvedOgImage,
+      favicon: resolvedFavicon,
+      url
+    };
+  } catch (error) {
+    console.error('Error extracting URL metadata:', error.message);
+    throw error;
+  }
+}
+
+export {
+  searchDuckDuckGo,
+  fetchUrlContent,
+  extractUrlMetadata,
+  extractDirectUrl,
+  getFaviconUrl
+};