dyoshikawa/webseek

Profil dyoshikawa

Dernière activité source enregistrée: 2 octobre 2026 à 08:06

Catalogue SkillsMP mis à jour: 26 octobre 2026 à 11:37

skills collectés: 56

Étoiles GitHub: 2
Forks GitHub: 0

README du dépôt

Fichier source du README : README.md

Lire le README source

Afficher le README complet

# 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`). ### Usage and cost Every search reports what it consumed and an estimated cost in USD. The text output ends with a line such as: ``` Usage: 1,100 tokens (1,000 in, 100 out), 1 search, ~$0.0180 ``` JSON output (and the MCP tool result) carries the same data as `usage` and `cost`, plus the `model` that served the search: ```jsonc { "model": "gpt-5.5", "usage": { "inputTokens": 1000, "outputTokens": 100, "totalTokens": 1100, "searchCalls": 1 }, "cost": { "totalUsd": 0.018, "tokensUsd": 0.008, "searchUsd": 0.01 }, } ``` - `usage.inputTokens` includes cached tokens (`usage.cachedInputTokens`) and the search content the model read; `usage.outputTokens` includes reasoning/thinking tokens. SERP providers (`google`) report no tokens. - `usage.searchCalls` counts OpenAI `web_search` calls, Gemini grounding queries, or Google Custom Search requests (one per page of 10 results). - `cost` is computed from built-in list prices: token rates for the model plus the provider's search fee (OpenAI $10 per 1k calls, Gemini 3.x $14 per 1k queries, Gemini 2.5 $35 per 1k grounded prompts, Google Custom Search $5 per 1k queries). It is a list-price estimate, not your bill: free allowances, discounts and long-context rates are **not** applied. `cost` is omitted when the model has no known price or the provider reported no token counts. The CLI and the MCP server also append every successful search to a local usage log, which [`webseek stats`](#usage-stats) totals. ## Install ```bash npm install -g webseek # install the CLI globally npx webseek "..." -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 <query...> --provider <openai|google|gemini> [options] ``` Options: | 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 "best static site generators 2026" -p google -n 5 webseek "summarize the latest TypeScript release" -p openai webseek "who won euro 2024" -p gemini --gemini-backend vertex-express --json ``` `mcp` and `stats` are subcommands: a query whose first word is `mcp` or `stats` must be quoted as a whole (`webseek "stats for the nba" -p openai`), and a query of just that one word cannot be searched from the CLI. ### Usage stats Every successful search — from the CLI or the MCP server — is appended as one JSON line to `usage.jsonl` in the data directory: the time, provider, model, `usage` and `cost`. The query text is **not** stored. `webseek stats` totals the log, with flags modelled on `opencode stats`: ```bash webseek stats # this year so far webseek stats --days 7 --full # the last 7 days with every section webseek stats --all -p openai --models ``` ``` webseek stats · 2026 so far · all providers 3 searches · 4 search calls · 12.9k tokens ~$0.0550 estimated · 1 active day ``` | Flag | Description | | ----------------------- | --------------------------------------------------- | | `--days <n>` | The last N days; `0` means today | | `--year <year>` | A calendar year (default: this year so far) | | `--all` | Lifetime statistics | | `-p, --provider <name>` | Only count one provider | | `--cost` | Cost split (tokens / search fees) and token details | | `--models` | Searches, tokens and cost per model | | `--full` | Every detailed section | | `--limit <n>` | Number of rows in the models section | | `--json` | Statistics as JSON | `--days`, `--year` and `--all` cannot be combined. Costs are the same list-price estimates as in each search's output; searches whose model has no known price are counted but left out of the cost (and reported as unpriced). | Environment variable | Effect | | -------------------- | -------------------------------------------------------------------------------- | | `WEBSEEK_DATA_DIR` | Data directory (default `$XDG_DATA_HOME/webseek`, else `~/.local/share/webseek`) | | `WEBSEEK_USAGE_LOG` | Set to `0`, `false` or `off` to stop recording searches | Delete `usage.jsonl` to reset the statistics. A failure to write the log is reported as a warning on stderr and never fails the search. ## 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"); ``` Each result carries `usage` and, when it can be priced, an estimated `cost` (see [Usage and cost](#usage-and-cost)). To price usage yourself — for example to sum several searches — call `estimateCost` with the provider, the model and a `usage` object; it returns `undefined` when the model has no known price: ```ts import { estimateCost } from "webseek"; const cost = estimateCost({ provider: "openai", model: "gpt-5.5", usage: { inputTokens: 1000, outputTokens: 100, searchCalls: 1 }, }); console.log(cost?.totalUsd.toFixed(3)); // "0.018" ``` Prices are list prices built into the package and change with its releases. To embed the `web_search` tool into your own MCP server, use the `createWebSearchTool` factory exported from the same entry point. Its optional `onResult` callback receives every successful result (the `webseek mcp` server uses it to write the usage log). The library itself never writes the usage log; only the CLI and `webseek mcp` do. ## 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: root search command, `mcp` and `stats` 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) pricing/ list-price table and cost estimation stats/ local usage log, aggregation and the `stats` report 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) ``` ## Releasing Publishing to npm is automated. To cut a new version: 1. Run the `draft-release` skill — it bumps the version on a `release/vX.Y.Z` branch, opens a PR, and creates a **draft** GitHub release. 2. Review and merge the release PR into `main`. Merging the release PR triggers [`.github/workflows/publish.yml`](.github/workflows/publish.yml), which verifies the tag matches `package.json`, pushes the `vX.Y.Z` tag, runs `pnpm publish`, and flips the draft GitHub release public — no manual **Publish release** click is needed. Authentication uses npm **trusted publishing** (OIDC) — no token secret is required, and provenance is generated automatically. Configure the trusted publisher for the package once on npmjs.com, pointing it at this repository's `publish.yml` workflow. To run the whole flow in one shot, use the `goal-release` skill — it runs the `draft-release` skill, waits for the release PR's CI to pass, merges it with the `merge-pr` skill, and waits for the `Publish` workflow to finish.

Chargement du README du dépôt…