# Yandex Search.API MCP Server

MCP server for Yandex Search API over REST with 7 tools:
- `web_search`
- `image_search`
- `generative_search`
- `wordstat_get_top`
- `wordstat_get_dynamics`
- `wordstat_get_regions_distribution`
- `wordstat_get_regions_tree`

The server reads credentials from MCP client env config:
- `FOLDER_ID`
- `API_KEY`

For local development, `.env` is loaded automatically.

## Features

- Uses only REST endpoints (`/v2/web/search`, `/v2/image/search`, `/v2/gen/search`, Wordstat REST paths)
- Minimal tool inputs by default to keep model context compact
- `searchType` is available for all relevant tools and defaults to `SEARCH_TYPE_COM`
- Web search always forces `responseFormat: FORMAT_XML`
- Web/image tools decode `rawData` from Base64 and parse XML into structured groups
- Error handling with clear API status and details

## Install

```bash
npm install yandex-searchapi-mcp
```

## MCP client config example

```json
{
  "mcpServers": {
    "yandex-searchapi": {
      "command": "npx",
      "args": ["-y", "yandex-searchapi-mcp"],
      "env": {
        "FOLDER_ID": "your-folder-id",
        "API_KEY": "your-api-key"
      }
    }
  }
}
```

## Tools

### `web_search`

Use this tool when you need classic web search results (links + snippets), not a generated answer.

Inputs:
- `query` (required)
- `searchType` (optional, default `SEARCH_TYPE_COM`)
- `page` (optional)
- `docsOnPage` (optional)
- `familyMode` (optional)
- `fixTypoMode` (optional)

Returns:
- `groups[]` with `documents[]` where each document contains:
  - `url`
  - `title`
  - `language`
  - `passages`
- `requestId`
- `found`

Note: for web search this input is mapped to `groupSpec.groupsOnPage` on the upstream API.

### `image_search`

Use this tool when you need image search results and image metadata (thumbnail/original links and dimensions).

Inputs:
- `query` (required)
- `searchType` (optional, default `SEARCH_TYPE_COM`)
- `page` (optional)
- `site` (optional)
- `docsOnPage` (optional)
- `imageSpec` (optional: `format`, `size`, `orientation`, `color`)

Returns:
- `groups[]` with `documents[]` where each document contains:
  - `url`
  - `extras.image-properties` (if present)
- `requestId`
- `found`

### `generative_search`

Use this tool when you need a ready-to-use grounded answer synthesized from search results.

Inputs:
- `query` (required)
- `searchType` (optional, default `SEARCH_TYPE_COM`)
- `fixMisspell` (optional)
- `getPartialResults` (optional)
- `scope` (optional): `{ type: "site" | "host" | "url", values: string[] }`

Returns only core generative fields (without wrapper objects):
- `message`
- `sources`
- `searchQueries`
- `fixedMisspellQuery`
- `isAnswerRejected`
- `isBulletAnswer`
- `hints`
- `problematicAnswer`

### `wordstat_get_top`

Use this tool to understand what related queries users search for around a keyword.

Inputs:
- `phrase` (required)
- `numPhrases` (optional, default `20`)
- `regions` (optional)
- `devices` (optional)

Returns:
- `totalCount`
- `results`
- `associations`

### `wordstat_get_dynamics`

Use this tool to track demand trends over time for a keyword.

Inputs:
- `phrase` (required)
- `period` (optional, default `PERIOD_WEEKLY`)
- `fromDate` (optional, default `now-30d`, ISO datetime)
- `toDate` (optional, default `now`, ISO datetime)
- `regions` (optional)
- `devices` (optional)

Returns:
- `results`

### `wordstat_get_regions_distribution`

Use this tool to see in which regions/cities a keyword is relatively more popular.

Inputs:
- `phrase` (required)
- `region` (optional, default `REGION_ALL`)
- `devices` (optional)

Returns:
- `results`

### `wordstat_get_regions_tree`

Use this tool to get valid region IDs and names for regional Wordstat filters.

Inputs:
- none

Returns:
- `regions`

## Development

```bash
npm install
npm run build
npm run dev
```