omnisearch-mcp 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OmniSearch SDK Contributors
+
+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

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+# omnisearch-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Model Context Protocol (MCP) server for multi-provider web search retrieval, powered by [`omnisearch-sdk`](https://www.npmjs.com/package/omnisearch-sdk).
+
+Give Claude Desktop, Cursor, and MCP-compatible AI agent runtimes real-time search across 15+ search providers (Brave, Google, Bing, DuckDuckGo, Tavily, Perplexity, PubMed, Arxiv, GitHub, and more) with automatic fallback and canonical deduplication.
+
+---
+
+## ⚡ Quick Setup
+
+### 1. Claude Desktop Setup
+
+Add to your `claude_desktop_config.json`:
+
+* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "omnisearch": {
+      "command": "npx",
+      "args": ["-y", "omnisearch-mcp"],
+      "env": {
+        "BRAVE_API_KEY": "YOUR_BRAVE_API_KEY",
+        "TAVILY_API_KEY": "YOUR_TAVILY_API_KEY"
+      }
+    }
+  }
+}
+```
+
+> **Note:** If no API keys are provided in `env`, the server automatically defaults to zero-config public providers (DuckDuckGo, PubMed, Arxiv, Semantic Scholar).
+
+---
+
+### 2. Cursor IDE Setup
+
+In Cursor Settings -> **Features** -> **MCP Servers** -> **Add New MCP Server**:
+
+* **Name:** `omnisearch`
+* **Type:** `command`
+* **Command:** `npx -y omnisearch-mcp`
+
+---
+
+## 🛠 Available MCP Tools
+
+The server automatically registers two tools:
+
+### `web_search`
+Search the live web across multiple engines with automatic multi-provider fallback, canonical deduplication, and domain filtering.
+
+| Argument | Type | Description |
+| :--- | :--- | :--- |
+| `query` | `string` | The search query string (**required**). |
+| `maxResults` | `number` | Maximum number of results to return (default: `10`). |
+| `freshness` | `string` | Recency filter: `'day'`, `'week'`, `'month'`, `'year'`. |
+| `includeDomains` | `string[]` | Whitelist specific domains (e.g. `["github.com", "arxiv.org"]`). |
+| `excludeDomains` | `string[]` | Blacklist specific domains (e.g. `["pinterest.com"]`). |
+| `deduplicate` | `boolean` | Enable intelligent canonical URL deduplication (default: `true`). |
+
+### `news_search`
+Search breaking news and recent journalistic coverage across supported news providers.
+
+| Argument | Type | Description |
+| :--- | :--- | :--- |
+| `query` | `string` | The news query string (**required**). |
+| `maxResults` | `number` | Maximum number of results to return (default: `10`). |
+| `freshness` | `string` | Recency filter: `'day'`, `'week'`, `'month'` (default: `'week'`). |
+
+---
+
+## 🌐 Supported Provider Environment Variables
+
+Configure any combination of API keys:
+
+* `BRAVE_API_KEY` - Brave Search API
+* `TAVILY_API_KEY` - Tavily Search API
+* `GOOGLE_API_KEY` & `GOOGLE_CX` - Google Custom Search API
+* `BING_API_KEY` - Azure Bing Search API
+* `YOU_API_KEY` - You.com Search API
+* `EXA_API_KEY` - Exa Neural Search API
+* `PERPLEXITY_API_KEY` - Perplexity Search API
+* `PARALLEL_API_KEY` - Parallel Search API
+* `SERPAPI_API_KEY` - SerpAPI
+* `SEARXNG_BASE_URL` - Self-hosted SearXNG endpoint
+* `GITHUB_TOKEN` - GitHub API Token (optional, raises rate limits)
+
+---
+
+## 📄 License
+
+MIT © [OmniSearch SDK Contributors](https://github.com/gbks121/omnisearch-sdk)

package/dist/index.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+// src/index.ts
+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 {
+  createArxivProvider,
+  createBingProvider,
+  createBraveProvider,
+  createDuckDuckGoProvider,
+  createExaProvider,
+  createGitHubProvider,
+  createGoogleProvider,
+  createParallelProvider,
+  createPerplexityProvider,
+  createPubMedProvider,
+  createSearXNGProvider,
+  createSemanticScholarProvider,
+  createSerpApiProvider,
+  createTavilyProvider,
+  createYouProvider,
+  webSearch
+} from "omnisearch-sdk";
+function getActiveProviders() {
+  const env = process.env;
+  const providers = [];
+  if (env.BRAVE_API_KEY || env.BRAVE_SEARCH_API_KEY) {
+    providers.push(
+      createBraveProvider({ apiKey: env.BRAVE_API_KEY || env.BRAVE_SEARCH_API_KEY })
+    );
+  }
+  if (env.TAVILY_API_KEY) {
+    providers.push(createTavilyProvider({ apiKey: env.TAVILY_API_KEY }));
+  }
+  if (env.EXA_API_KEY) {
+    providers.push(createExaProvider({ apiKey: env.EXA_API_KEY }));
+  }
+  if (env.GOOGLE_API_KEY && env.GOOGLE_CX) {
+    providers.push(createGoogleProvider({ apiKey: env.GOOGLE_API_KEY, cx: env.GOOGLE_CX }));
+  }
+  if (env.PERPLEXITY_API_KEY) {
+    providers.push(createPerplexityProvider({ apiKey: env.PERPLEXITY_API_KEY }));
+  }
+  if (env.BING_API_KEY) {
+    providers.push(createBingProvider({ apiKey: env.BING_API_KEY }));
+  }
+  if (env.YOU_API_KEY) {
+    providers.push(createYouProvider({ apiKey: env.YOU_API_KEY }));
+  }
+  if (env.PARALLEL_API_KEY) {
+    providers.push(createParallelProvider({ apiKey: env.PARALLEL_API_KEY }));
+  }
+  if (env.SERPAPI_API_KEY) {
+    providers.push(createSerpApiProvider({ apiKey: env.SERPAPI_API_KEY }));
+  }
+  if (env.SEARXNG_BASE_URL) {
+    providers.push(createSearXNGProvider({ baseUrl: env.SEARXNG_BASE_URL }));
+  }
+  providers.push(createDuckDuckGoProvider());
+  providers.push(createPubMedProvider());
+  providers.push(createArxivProvider());
+  providers.push(createSemanticScholarProvider());
+  providers.push(createGitHubProvider({ apiKey: env.GITHUB_TOKEN || env.GITHUB_API_KEY }));
+  return providers;
+}
+async function runServer() {
+  const server = new Server(
+    {
+      name: "omnisearch-mcp",
+      version: "1.0.0"
+    },
+    {
+      capabilities: {
+        tools: {}
+      }
+    }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [
+        {
+          name: "web_search",
+          description: "Search the live web across multiple search engines with automatic fallback, deduplication, and domain filtering.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: { type: "string", description: "The search query to execute." },
+              maxResults: {
+                type: "number",
+                description: "Maximum results to return (default 10)."
+              },
+              freshness: {
+                type: "string",
+                enum: ["day", "week", "month", "year"],
+                description: "Filter content published within the last day, week, month, or year."
+              },
+              strategy: {
+                type: "string",
+                enum: ["parallel", "fallback", "race"],
+                description: "Multi-provider execution strategy."
+              },
+              includeDomains: {
+                type: "array",
+                items: { type: "string" },
+                description: "List of domain names to restrict results to."
+              },
+              excludeDomains: {
+                type: "array",
+                items: { type: "string" },
+                description: "List of domain names to exclude from results."
+              }
+            },
+            required: ["query"]
+          }
+        },
+        {
+          name: "news_search",
+          description: "Search breaking and recent news articles across search engines.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: { type: "string", description: "The news search query." },
+              maxResults: { type: "number", description: "Maximum news results to return." },
+              freshness: {
+                type: "string",
+                enum: ["day", "week", "month", "year"],
+                description: "Recency filter for news."
+              }
+            },
+            required: ["query"]
+          }
+        }
+      ]
+    };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const providers = getActiveProviders();
+    if (name === "web_search" || name === "news_search") {
+      const query = args?.query || "";
+      const maxResults = args?.maxResults || 10;
+      const freshness = args?.freshness;
+      const strategy = args?.strategy || "parallel";
+      const searchType = name === "news_search" ? "news" : "web";
+      const includeDomains = args?.includeDomains;
+      const excludeDomains = args?.excludeDomains;
+      try {
+        const results = await webSearch({
+          query,
+          provider: providers,
+          maxResults,
+          freshness,
+          strategy,
+          searchType,
+          includeDomains,
+          excludeDomains,
+          deduplicate: true
+        });
+        const formatted = results.map((r, i) => `${i + 1}. [${r.title}](${r.url})
+   ${r.snippet ?? ""}`).join("\n\n");
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatted || `No results found for "${query}".`
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Search error: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+    throw new Error(`Unknown tool: ${name}`);
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+runServer().catch((error) => {
+  console.error("Fatal MCP Server error:", error);
+  process.exit(1);
+});
+export {
+  runServer
+};

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "omnisearch-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.1",
+  "description": "Model Context Protocol server for OmniSearch SDK",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "omnisearch-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "omnisearch-sdk": "5.0.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "~6.0.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  }
 }