webseek 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dyoshikawa
+
+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,153 @@
+# webseek
+
+Web search using the API keys of multiple providers behind a single, unified
+interface. Bring whichever provider key you already have and search the web —
+either from your terminal (**CLI mode**) or from an MCP client such as an editor
+or agent (**MCP server mode**). Both modes share the same core search logic.
+
+## Providers
+
+`webseek` normalizes two fundamentally different kinds of "web search":
+
+| Provider | Kind                                        | Output                           |
+| -------- | ------------------------------------------- | -------------------------------- |
+| `google` | SERP-style (Google Custom Search)           | a ranked list of links           |
+| `openai` | LLM-grounded (Responses API `web_search`)   | a synthesized answer + citations |
+| `gemini` | LLM-grounded (Grounding with Google Search) | a synthesized answer + citations |
+
+The Gemini provider supports two backends that share the same request/response
+shape: the **Gemini Developer API** (`gemini-api`, default) and **Vertex AI
+express mode** (`vertex-express`).
+
+## Install
+
+```bash
+npm install -g webseek      # install the CLI globally
+npx webseek search "..." -p google   # or run without installing
+```
+
+### Build from source
+
+```bash
+pnpm install
+pnpm build      # dual-format (ESM + CJS) build via tsdown; exposes the `webseek` bin
+```
+
+During development you can run without building via `pnpm dev -- <args>` (runs
+the TypeScript source through `tsx`).
+
+## CLI mode
+
+```bash
+webseek search <query...> --provider <openai|google|gemini> [options]
+```
+
+Options for `search`:
+
+| Flag                    | Description                                 |
+| ----------------------- | ------------------------------------------- |
+| `-p, --provider <name>` | `openai` \| `google` \| `gemini` (required) |
+| `-n, --max-results <n>` | Desired number of results (SERP providers)  |
+| `-m, --model <name>`    | Model override (`openai`, `gemini`)         |
+| `--gemini-backend <b>`  | `gemini-api` (default) \| `vertex-express`  |
+| `--json`                | Emit normalized JSON instead of text        |
+| `--raw`                 | Include the provider's raw response         |
+
+Examples:
+
+```bash
+webseek search "best static site generators 2026" -p google -n 5
+webseek search "summarize the latest TypeScript release" -p openai
+webseek search "who won euro 2024" -p gemini --gemini-backend vertex-express --json
+```
+
+## MCP server mode
+
+Start a [Model Context Protocol](https://modelcontextprotocol.io) server over
+stdio that exposes a single `web_search` tool:
+
+```bash
+webseek mcp
+```
+
+Register it with an MCP client, e.g.:
+
+```jsonc
+{
+  "mcpServers": {
+    "webseek": {
+      "command": "webseek",
+      "args": ["mcp"],
+      "env": { "GEMINI_API_KEY": "..." },
+    },
+  },
+}
+```
+
+The `web_search` tool accepts `{ query, provider, maxResults?, model?, geminiBackend?, includeRaw? }`
+and returns the normalized result as JSON.
+
+## Library (programmatic API)
+
+`webseek` is published as a dual-format package (ESM + CJS), so it can be
+imported as a library in addition to running as a CLI/MCP server:
+
+```ts
+import { runSearch, WebseekError } from "webseek";
+
+const result = await runSearch({ provider: "google", query: "best static site generators 2026" });
+console.log(result.results);
+```
+
+CommonJS consumers can `require` it the same way:
+
+```js
+const { runSearch } = require("webseek");
+```
+
+To embed the `web_search` tool into your own MCP server, use the
+`createWebSearchTool` factory exported from the same entry point.
+
+## Authentication
+
+API keys are read from **environment variables only** (never from flags), so
+they don't leak into shell history or process listings.
+
+| Provider                  | Environment variables                                             |
+| ------------------------- | ----------------------------------------------------------------- |
+| `openai`                  | `OPENAI_API_KEY`                                                  |
+| `google`                  | `GOOGLE_API_KEY`, `GOOGLE_CSE_CX` (Programmable Search Engine ID) |
+| `gemini` (gemini-api)     | `GEMINI_API_KEY` (falls back to `GOOGLE_API_KEY`)                 |
+| `gemini` (vertex-express) | `VERTEX_API_KEY`                                                  |
+
+## Caveats
+
+- **Google Custom Search is closed to new customers.** Existing customers must
+  migrate before 2027-01-01. Treat this provider as the most at-risk.
+- **Google Custom Search returns at most 100 results** (10 per request); large
+  `--max-results` values paginate and consume more quota.
+- **Gemini grounding requires displaying Google Search Suggestions** per its
+  terms. As a CLI we surface the queries the model ran on the `Searches:` line;
+  the source URIs Gemini returns are temporary redirect links.
+
+## Architecture
+
+```
+src/
+  index.ts    public library entry (runSearch, types, createWebSearchTool)
+  cli/        commander program: `search` and `mcp` commands
+  mcp/        MCP server + the web_search tool
+  lib/        runSearch — the shared core called by both CLI and MCP
+  providers/  per-provider implementations (openai, google-cse, gemini)
+  config/     credential + base-URL resolution from env
+  output/     text / JSON formatting
+  utils/      logger, error formatter
+  e2e/        end-to-end tests (spawn the CLI / drive the MCP server)
+```
+
+## Development
+
+```bash
+pnpm cicheck      # format check, lint, typecheck, unit tests, spelling, secrets
+pnpm test:e2e     # end-to-end tests (CLI subprocess + MCP stdio client)
+```

package/dist/cli/index.cjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+const require_tools = require("../tools-Cd93c2_h.cjs");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+let commander = require("commander");
+let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
+let _modelcontextprotocol_sdk_server_stdio_js = require("@modelcontextprotocol/sdk/server/stdio.js");
+//#region src/mcp/server.ts
+/**
+* MCP server mode: exposes the `web_search` tool over the stdio transport so
+* MCP clients (editors, agents) can search the web through this tool.
+*
+* Diagnostics go to stderr only — stdout is reserved for the JSON-RPC stream.
+*/
+async function startMcpServer(params) {
+	const server = new _modelcontextprotocol_sdk_server_mcp_js.McpServer({
+		name: "webseek",
+		version: params.version
+	});
+	const tool = require_tools.createWebSearchTool();
+	server.registerTool(tool.name, tool.config, tool.handler);
+	const transport = new _modelcontextprotocol_sdk_server_stdio_js.StdioServerTransport();
+	await server.connect(transport);
+	params.logger.info("webseek MCP server started (stdio)");
+}
+//#endregion
+//#region src/utils/logger.ts
+function writeErr(message) {
+	process.stderr.write(`${message}\n`);
+}
+function createConsoleLogger(params = {}) {
+	const silent = params.silent ?? process.env.NODE_ENV === "test";
+	const diagnosticsOnly = params.diagnosticsOnly ?? false;
+	return {
+		info: (message) => {
+			if (!silent) writeErr(message);
+		},
+		warn: (message) => {
+			if (!silent) writeErr(`warning: ${message}`);
+		},
+		error: (message) => {
+			writeErr(message);
+		},
+		result: (text) => {
+			if (diagnosticsOnly) {
+				writeErr(text);
+				return;
+			}
+			process.stdout.write(`${text}\n`);
+		}
+	};
+}
+//#endregion
+//#region src/cli/wrap-command.ts
+/**
+* Wraps a commander action so every command shares the same error handling:
+* a logger is created, the handler runs, and any thrown value is formatted to
+* stderr and mapped to a process exit code.
+*/
+/**
+* Returns a commander-compatible action. Commander invokes actions with the
+* command's positionals/options followed by the Command instance, all of which
+* are forwarded to the handler.
+*/
+function wrapCommand(handler) {
+	return async (...args) => {
+		const logger = createConsoleLogger();
+		try {
+			await handler({ logger }, ...args);
+		} catch (error) {
+			logger.error(require_tools.formatError(error));
+			process.exitCode = require_tools.errorExitCode(error);
+		}
+	};
+}
+//#endregion
+//#region src/cli/commands/mcp.ts
+async function runMcpCommand(params) {
+	await startMcpServer({
+		version: params.version,
+		logger: params.logger
+	});
+}
+function registerMcpCommand(params) {
+	params.program.command("mcp").description("Start the MCP server (stdio) exposing the web_search tool").action(wrapCommand(async ({ logger }) => {
+		await runMcpCommand({
+			logger,
+			version: params.version
+		});
+	}));
+}
+//#endregion
+//#region src/output/format.ts
+function formatResult(params) {
+	if (params.json) return formatJson(params.result);
+	return formatText(params.result);
+}
+function formatJson(result) {
+	const payload = {
+		provider: result.provider,
+		query: result.query,
+		results: result.results,
+		answer: result.answer,
+		citations: result.citations,
+		searchQueries: result.searchQueries
+	};
+	if (result.raw !== void 0) payload.raw = result.raw;
+	return JSON.stringify(payload, null, 2);
+}
+function formatText(result) {
+	const lines = [];
+	if (result.answer) lines.push(result.answer.trim(), "");
+	if (result.results.length > 0) {
+		lines.push("Results:");
+		result.results.forEach((item, index) => {
+			lines.push(`${index + 1}. ${item.title || item.url}`);
+			lines.push(`   ${item.url}`);
+			if (item.snippet) lines.push(`   ${item.snippet}`);
+		});
+		lines.push("");
+	}
+	if (result.citations.length > 0) {
+		lines.push("Sources:");
+		result.citations.forEach((citation, index) => {
+			const label = citation.title ? `${citation.title} — ${citation.url}` : citation.url;
+			lines.push(`  [${index + 1}] ${label}`);
+		});
+		lines.push("");
+	}
+	if (result.searchQueries.length > 0) lines.push(`Searches: ${result.searchQueries.join(" | ")}`);
+	return lines.join("\n").trimEnd();
+}
+//#endregion
+//#region src/cli/commands/search.ts
+/**
+* Translate raw CLI args/options into validated `runSearch` parameters. Kept
+* pure (no I/O) so it can be unit-tested directly.
+*/
+function toSearchRequest(params) {
+	const query = params.queryParts.join(" ").trim();
+	if (!query) throw new require_tools.WebseekError({
+		code: "invalid_usage",
+		message: "Missing search query."
+	});
+	return {
+		provider: require_tools.coerceProvider(params.options.provider),
+		query,
+		maxResults: params.options.maxResults === void 0 ? void 0 : require_tools.coerceMaxResults(params.options.maxResults),
+		model: params.options.model,
+		includeRaw: Boolean(params.options.raw),
+		geminiBackend: params.options.geminiBackend === void 0 ? void 0 : require_tools.coerceGeminiBackend(params.options.geminiBackend)
+	};
+}
+async function runSearchCommand(params) {
+	const result = await require_tools.runSearch(toSearchRequest({
+		queryParts: params.queryParts,
+		options: params.options
+	}));
+	params.logger.result(formatResult({
+		result,
+		json: Boolean(params.options.json)
+	}));
+}
+function registerSearchCommand(program) {
+	program.command("search").description("Search the web via a provider").argument("<query...>", "the search query").requiredOption("-p, --provider <name>", "provider: openai | google | gemini").option("-n, --max-results <number>", "desired number of results (SERP providers)").option("-m, --model <name>", "model override (openai, gemini)").option("--gemini-backend <backend>", "gemini backend: gemini-api | vertex-express").option("--json", "emit normalized JSON instead of text").option("--raw", "include the provider's raw response").action(wrapCommand(async ({ logger }, queryParts, options) => {
+		await runSearchCommand({
+			logger,
+			queryParts,
+			options
+		});
+	}));
+}
+//#endregion
+//#region src/cli/index.ts
+/**
+* webseek CLI entry point.
+*
+* Two modes:
+*   webseek search <query> --provider <name>   run a one-off web search
+*   webseek mcp                                start the MCP server (stdio)
+*/
+function readPackageVersion(dir) {
+	try {
+		const pkg = JSON.parse((0, node_fs.readFileSync)((0, node_path.join)(dir, "package.json"), "utf8"));
+		return pkg.name === "webseek" ? pkg.version : void 0;
+	} catch {
+		return;
+	}
+}
+function getVersion() {
+	let dir = __dirname;
+	for (let depth = 0; depth < 6; depth += 1) {
+		const version = readPackageVersion(dir);
+		if (version) return version;
+		dir = (0, node_path.dirname)(dir);
+	}
+	return "0.0.0";
+}
+function buildProgram() {
+	const program = new commander.Command();
+	const version = getVersion();
+	program.name("webseek").description("Unified multi-provider web search (CLI + MCP server)").version(version, "-v, --version", "Show version");
+	registerSearchCommand(program);
+	registerMcpCommand({
+		program,
+		version
+	});
+	return program;
+}
+async function main() {
+	await buildProgram().parseAsync(process.argv);
+}
+main().catch((error) => {
+	process.stderr.write(`${require_tools.formatError(error)}\n`);
+	process.exitCode = 1;
+});
+//#endregion

package/dist/cli/index.d.cts

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

package/dist/cli/index.d.mts

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

package/dist/cli/index.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+import { a as coerceGeminiBackend, c as runSearch, d as formatError, l as WebseekError, o as coerceMaxResults, s as coerceProvider, t as createWebSearchTool, u as errorExitCode } from "../tools-CCqL3Phx.mjs";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { Command } from "commander";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+//#region src/mcp/server.ts
+/**
+* MCP server mode: exposes the `web_search` tool over the stdio transport so
+* MCP clients (editors, agents) can search the web through this tool.
+*
+* Diagnostics go to stderr only — stdout is reserved for the JSON-RPC stream.
+*/
+async function startMcpServer(params) {
+	const server = new McpServer({
+		name: "webseek",
+		version: params.version
+	});
+	const tool = createWebSearchTool();
+	server.registerTool(tool.name, tool.config, tool.handler);
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	params.logger.info("webseek MCP server started (stdio)");
+}
+//#endregion
+//#region src/utils/logger.ts
+function writeErr(message) {
+	process.stderr.write(`${message}\n`);
+}
+function createConsoleLogger(params = {}) {
+	const silent = params.silent ?? process.env.NODE_ENV === "test";
+	const diagnosticsOnly = params.diagnosticsOnly ?? false;
+	return {
+		info: (message) => {
+			if (!silent) writeErr(message);
+		},
+		warn: (message) => {
+			if (!silent) writeErr(`warning: ${message}`);
+		},
+		error: (message) => {
+			writeErr(message);
+		},
+		result: (text) => {
+			if (diagnosticsOnly) {
+				writeErr(text);
+				return;
+			}
+			process.stdout.write(`${text}\n`);
+		}
+	};
+}
+//#endregion
+//#region src/cli/wrap-command.ts
+/**
+* Wraps a commander action so every command shares the same error handling:
+* a logger is created, the handler runs, and any thrown value is formatted to
+* stderr and mapped to a process exit code.
+*/
+/**
+* Returns a commander-compatible action. Commander invokes actions with the
+* command's positionals/options followed by the Command instance, all of which
+* are forwarded to the handler.
+*/
+function wrapCommand(handler) {
+	return async (...args) => {
+		const logger = createConsoleLogger();
+		try {
+			await handler({ logger }, ...args);
+		} catch (error) {
+			logger.error(formatError(error));
+			process.exitCode = errorExitCode(error);
+		}
+	};
+}
+//#endregion
+//#region src/cli/commands/mcp.ts
+async function runMcpCommand(params) {
+	await startMcpServer({
+		version: params.version,
+		logger: params.logger
+	});
+}
+function registerMcpCommand(params) {
+	params.program.command("mcp").description("Start the MCP server (stdio) exposing the web_search tool").action(wrapCommand(async ({ logger }) => {
+		await runMcpCommand({
+			logger,
+			version: params.version
+		});
+	}));
+}
+//#endregion
+//#region src/output/format.ts
+function formatResult(params) {
+	if (params.json) return formatJson(params.result);
+	return formatText(params.result);
+}
+function formatJson(result) {
+	const payload = {
+		provider: result.provider,
+		query: result.query,
+		results: result.results,
+		answer: result.answer,
+		citations: result.citations,
+		searchQueries: result.searchQueries
+	};
+	if (result.raw !== void 0) payload.raw = result.raw;
+	return JSON.stringify(payload, null, 2);
+}
+function formatText(result) {
+	const lines = [];
+	if (result.answer) lines.push(result.answer.trim(), "");
+	if (result.results.length > 0) {
+		lines.push("Results:");
+		result.results.forEach((item, index) => {
+			lines.push(`${index + 1}. ${item.title || item.url}`);
+			lines.push(`   ${item.url}`);
+			if (item.snippet) lines.push(`   ${item.snippet}`);
+		});
+		lines.push("");
+	}
+	if (result.citations.length > 0) {
+		lines.push("Sources:");
+		result.citations.forEach((citation, index) => {
+			const label = citation.title ? `${citation.title} — ${citation.url}` : citation.url;
+			lines.push(`  [${index + 1}] ${label}`);
+		});
+		lines.push("");
+	}
+	if (result.searchQueries.length > 0) lines.push(`Searches: ${result.searchQueries.join(" | ")}`);
+	return lines.join("\n").trimEnd();
+}
+//#endregion
+//#region src/cli/commands/search.ts
+/**
+* Translate raw CLI args/options into validated `runSearch` parameters. Kept
+* pure (no I/O) so it can be unit-tested directly.
+*/
+function toSearchRequest(params) {
+	const query = params.queryParts.join(" ").trim();
+	if (!query) throw new WebseekError({
+		code: "invalid_usage",
+		message: "Missing search query."
+	});
+	return {
+		provider: coerceProvider(params.options.provider),
+		query,
+		maxResults: params.options.maxResults === void 0 ? void 0 : coerceMaxResults(params.options.maxResults),
+		model: params.options.model,
+		includeRaw: Boolean(params.options.raw),
+		geminiBackend: params.options.geminiBackend === void 0 ? void 0 : coerceGeminiBackend(params.options.geminiBackend)
+	};
+}
+async function runSearchCommand(params) {
+	const result = await runSearch(toSearchRequest({
+		queryParts: params.queryParts,
+		options: params.options
+	}));
+	params.logger.result(formatResult({
+		result,
+		json: Boolean(params.options.json)
+	}));
+}
+function registerSearchCommand(program) {
+	program.command("search").description("Search the web via a provider").argument("<query...>", "the search query").requiredOption("-p, --provider <name>", "provider: openai | google | gemini").option("-n, --max-results <number>", "desired number of results (SERP providers)").option("-m, --model <name>", "model override (openai, gemini)").option("--gemini-backend <backend>", "gemini backend: gemini-api | vertex-express").option("--json", "emit normalized JSON instead of text").option("--raw", "include the provider's raw response").action(wrapCommand(async ({ logger }, queryParts, options) => {
+		await runSearchCommand({
+			logger,
+			queryParts,
+			options
+		});
+	}));
+}
+//#endregion
+//#region src/cli/index.ts
+/**
+* webseek CLI entry point.
+*
+* Two modes:
+*   webseek search <query> --provider <name>   run a one-off web search
+*   webseek mcp                                start the MCP server (stdio)
+*/
+function readPackageVersion(dir) {
+	try {
+		const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+		return pkg.name === "webseek" ? pkg.version : void 0;
+	} catch {
+		return;
+	}
+}
+function getVersion() {
+	let dir = import.meta.dirname;
+	for (let depth = 0; depth < 6; depth += 1) {
+		const version = readPackageVersion(dir);
+		if (version) return version;
+		dir = dirname(dir);
+	}
+	return "0.0.0";
+}
+function buildProgram() {
+	const program = new Command();
+	const version = getVersion();
+	program.name("webseek").description("Unified multi-provider web search (CLI + MCP server)").version(version, "-v, --version", "Show version");
+	registerSearchCommand(program);
+	registerMcpCommand({
+		program,
+		version
+	});
+	return program;
+}
+async function main() {
+	await buildProgram().parseAsync(process.argv);
+}
+main().catch((error) => {
+	process.stderr.write(`${formatError(error)}\n`);
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/dist/index.cjs

@@ -0,0 +1,10 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_tools = require("./tools-Cd93c2_h.cjs");
+exports.GEMINI_BACKENDS = require_tools.GEMINI_BACKENDS;
+exports.PROVIDER_NAMES = require_tools.PROVIDER_NAMES;
+exports.WebseekError = require_tools.WebseekError;
+exports.createWebSearchTool = require_tools.createWebSearchTool;
+exports.errorExitCode = require_tools.errorExitCode;
+exports.formatError = require_tools.formatError;
+exports.runSearch = require_tools.runSearch;
+exports.webSearchInputShape = require_tools.webSearchInputShape;