npm package: @neabyte/websearch-mcp
Description: MCP server for web search and web fetch tools
Author: NeaByteLab
Latest version: 0.1.0

<div align="center">

# WebSearch MCP

MCP server for web search and web fetch tools.

[![Node](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org)
[![Deno](https://img.shields.io/badge/deno-compatible-ffcb00?logo=deno&logoColor=000000)](https://deno.com)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

</div>

## Features

- **Two tools**
  - **`web_search`**: find relevant URLs for a query
  - **`web_fetch`**: fetch latest page content (markdown/text)
- **Cost-aware workflow**: recall → search → selective fetch (save quota)
- **Docs-first answers**: answers can cite freshly fetched official pages

Official reference: [Ollama Web Search](https://docs.ollama.com/capabilities/web-search)

## Installation

> [!NOTE]
> **Prerequisites:** Node.js for npm install. `OLLAMA_API_KEY` is required for `web_search`.

**npm:**

```bash
npm install -g @neabyte/websearch-mcp
```

## Quick Start

### Run MCP Server (Stdio)

Run the server (example for MCP clients using stdio):

```bash
websearch-mcp
```

If you want to set the API key for Ollama web search:

```bash
export OLLAMA_API_KEY="..."
websearch-mcp
```

## Editor Integration (Cursor / VSCode)

You can integrate this MCP server directly into editors (Cursor/VSCode) via **stdio** MCP
configuration. Two common options:

- **Global install**: `npm install -g @neabyte/websearch-mcp` then run `websearch-mcp`
- **No global install**: use `npx -y @neabyte/websearch-mcp` (recommended for editors)

### Example (Recommended): `npx` Stdio + Env

Paste this MCP server config in your editor (example JSON used by many MCP clients):

```json
{
  "mcpServers": {
    "websearch-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@neabyte/websearch-mcp"],
      "env": {
        "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY"
      }
    }
  }
}
```

> `OLLAMA_API_KEY` is required for `web_search`. `web_fetch` can run without a key.

### Smoke Test Prompt

After the server is registered in your editor, try a prompt like this:

```text
Use installed MCP Servers: `websearch-mcp` - `web_fetch` to fetch https://reactnative.dev/docs/environment-setup. Summarize the macOS install steps.
```

### Example Prompts

**Direct fetch (when the URL is known):**

```text
Use installed MCP Servers: `websearch-mcp` - `web_fetch` to fetch the official React Native documentation pages. Question: How to install in macOS?
```

**Search → fetch (when the URL is unknown):**

```text
Use installed MCP Servers: `websearch-mcp` - `web_search` to find official React Native docs URLs for "environment setup macOS". Then use `web_fetch` on the most relevant official doc page URLs. Question: How to install React Native in macOS?
```

## Concept: LLM Knowledge → Latest Docs

This approach uses two steps:

- **Recall**: the LLM proposes likely official URLs from its knowledge
- **Fetch**: the LLM calls `web_fetch` to retrieve the latest content

This is useful for fast-changing documentation, because the final answer is grounded in pages fetched
at tool-call time.

## Strategy: Save Quota

Ollama can get expensive if you `web_fetch` many pages. A cost-aware pattern is:

- **Recall first**: ask for a shortlist of likely official URLs
- **Search if needed**: use `web_search` to find fresh candidates
- **Fetch selectively**: fetch only 1–3 most relevant pages

With this pattern, you only spend fetch calls on pages you actually cite.

## Examples (Screenshots)

### Web Fetch (Single Tool)

| Prompt                                     | Output                                     |
| ------------------------------------------ | ------------------------------------------ |
| <img src="./preview/1.png" height="360" /> | <img src="./preview/2.png" height="360" /> |

- **Prompt**: ask the model to use `websearch-mcp` + `web_fetch` to fetch official React Native docs
- **Output**: the model fetches `reactnative.dev` and summarizes install steps

### Web Search → Web Fetch (Double Tool)

Even if `web_search` has its own quota/limits, the “double tool” pattern can reduce total cost by
shortlisting URLs first and fetching only what you need.

```text
Use websearch-mcp web_search with query: "latest crypto payment gateway 2026".
Then use websearch-mcp web_fetch to fetch the official pages from the top results.
Answer with a short list of the latest crypto payment gateways and include the source links.
```

<img src="./preview/3.png" height="520" />

## Build & Test

From the repo root (requires [Deno](https://deno.com/)).

**Check** — format, lint, and typecheck source:

```bash
deno task check
```

**Unit Tests**:

```bash
deno task test
```

- Tests live under `tests/`

## License

This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for details.