yandex-webmaster-mcp 1.0.0 → 1.2.0

package/README.md

@@ -23,6 +23,8 @@ MCP server for [Yandex Webmaster API](https://yandex.com/dev/webmaster/doc/en/)
 | `get-diagnostics` | Site health diagnostics |
 | `get-popular-queries` | Popular search queries (shows, clicks, positions) |
 | `get-query-history` | Aggregated query statistics over time |
+| `get-single-query-history` | Statistics over time for one specific query |
+| `get-query-analytics` | Query↔URL intersection report (last ~2 weeks) |
 | `get-indexing-history` | Pages downloaded by robot (by HTTP status) |
 | `get-indexing-samples` | Examples of downloaded pages |
 | `get-insearch-history` | Pages in search results over time |
@@ -36,9 +38,17 @@ MCP server for [Yandex Webmaster API](https://yandex.com/dev/webmaster/doc/en/)
 | `get-sitemaps` | Auto-detected sitemap files |
 | `get-sitemap` | Specific sitemap details |
 | `get-user-sitemaps` | User-added sitemaps |
+| `get-user-sitemap` | Details of a single user-added sitemap |
 | `get-important-urls` | Monitored important pages |
 | `get-important-url-history` | Important page change history |
 | `get-recrawl-quota` | Reindexing quota status |
+| `get-recrawl-queue` | List of pending/recent recrawl tasks |
+| `get-recrawl-task` | Status of a specific recrawl task |
+| `submit-recrawl` | Queue a URL for reindexing (write; uses quota) |
+| `get-feeds` | Data feeds loaded for the site |
+| `get-feed-status` | Status of an async feed upload task |
+| `get-feed-regions` | Regions supported for feed uploads |
+| `get-region-ids` | Static reference of common Yandex region IDs |
 
 ### Installation
 
@@ -143,6 +153,8 @@ Set the token as `YANDEX_WEBMASTER_TOKEN` environment variable.
 | `get-diagnostics` | Диагностика проблем сайта |
 | `get-popular-queries` | Популярные поисковые запросы |
 | `get-query-history` | История статистики запросов |
+| `get-single-query-history` | История статистики по конкретному запросу |
+| `get-query-analytics` | Отчёт пересечения запросов и URL (~2 недели) |
 | `get-indexing-history` | История загрузки страниц роботом |
 | `get-indexing-samples` | Примеры загруженных страниц |
 | `get-insearch-history` | История страниц в поиске |
@@ -156,9 +168,17 @@ Set the token as `YANDEX_WEBMASTER_TOKEN` environment variable.
 | `get-sitemaps` | Обнаруженные файлы Sitemap |
 | `get-sitemap` | Детали конкретного Sitemap |
 | `get-user-sitemaps` | Добавленные пользователем Sitemap |
+| `get-user-sitemap` | Детали конкретного добавленного Sitemap |
 | `get-important-urls` | Мониторинг важных страниц |
 | `get-important-url-history` | История изменений важных страниц |
 | `get-recrawl-quota` | Квота на переобход |
+| `get-recrawl-queue` | Список задач на переобход |
+| `get-recrawl-task` | Статус задачи на переобход |
+| `submit-recrawl` | Отправить URL на переобход (запись; расходует квоту) |
+| `get-feeds` | Загруженные фиды сайта |
+| `get-feed-status` | Статус асинхронной загрузки фида |
+| `get-feed-regions` | Регионы, доступные для загрузки фидов |
+| `get-region-ids` | Справочник частых ID регионов Яндекса |
 
 ### Установка
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yandex-webmaster-mcp",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "MCP server for Yandex Webmaster API - site analytics, indexing status, search queries, and SEO diagnostics",
   "type": "module",
   "main": "src/index.mjs",
@@ -43,7 +43,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.1",
-    "zod": "^4.3.4"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
   }
 }

package/src/index.mjs

@@ -70,7 +70,111 @@ async function runServer() {
     return new Date(date).toISOString();
   }
 
-  const server = new McpServer({name:'yandex-webmaster',version:'1.0.0'});
+  // Static reference of common Yandex geo region IDs. Used for the region_ids
+  // parameter of query-analytics and feeds tools. Yandex has thousands of
+  // regions; this is a curated shortlist of the most commonly used ones.
+  const REGION_IDS = [
+    { id: 225, name: 'Russia' },
+    { id: 213, name: 'Moscow' },
+    { id: 2, name: 'Saint Petersburg' },
+    { id: 1, name: 'Moscow and Moscow Oblast' },
+    { id: 10174, name: 'Saint Petersburg and Leningrad Oblast' },
+    { id: 65, name: 'Novosibirsk' },
+    { id: 54, name: 'Yekaterinburg' },
+    { id: 47, name: 'Nizhny Novgorod' },
+    { id: 43, name: 'Kazan' },
+    { id: 56, name: 'Chelyabinsk' },
+    { id: 51, name: 'Samara' },
+    { id: 66, name: 'Omsk' },
+    { id: 39, name: 'Rostov-on-Don' },
+    { id: 172, name: 'Ufa' },
+    { id: 35, name: 'Krasnodar' },
+    { id: 62, name: 'Krasnoyarsk' },
+    { id: 193, name: 'Voronezh' },
+    { id: 63, name: 'Volgograd' },
+    { id: 187, name: 'Ukraine' },
+    { id: 143, name: 'Kyiv' },
+    { id: 149, name: 'Belarus' },
+    { id: 157, name: 'Minsk' },
+    { id: 159, name: 'Kazakhstan' },
+    { id: 162, name: 'Almaty' },
+    { id: 10393, name: 'Nur-Sultan (Astana)' },
+    { id: 983, name: 'Uzbekistan' },
+    { id: 10295, name: 'Armenia' },
+    { id: 10277, name: 'Azerbaijan' },
+    { id: 20544, name: 'Georgia' },
+    { id: 207, name: 'Kyrgyzstan' },
+  ];
+
+  // Static reference of regions available for YML feed uploads (feeds tools).
+  // Per the Yandex docs, feeds only support Russia (225, the default) and the
+  // Russian regions below — there is no API endpoint for this list.
+  // Source: https://yandex.com/dev/webmaster/doc/en/reference/feeds-regions
+  const FEED_REGIONS = [
+    { id: 225, name: 'Россия (default)' },
+    { id: 20, name: 'Архангельск' },
+    { id: 37, name: 'Астрахань' },
+    { id: 197, name: 'Барнаул' },
+    { id: 4, name: 'Белгород' },
+    { id: 77, name: 'Благовещенск' },
+    { id: 191, name: 'Брянск' },
+    { id: 24, name: 'Великий Новгород' },
+    { id: 75, name: 'Владивосток' },
+    { id: 33, name: 'Владикавказ' },
+    { id: 192, name: 'Владимир' },
+    { id: 38, name: 'Волгоград' },
+    { id: 21, name: 'Вологда' },
+    { id: 193, name: 'Воронеж' },
+    { id: 1106, name: 'Грозный' },
+    { id: 54, name: 'Екатеринбург' },
+    { id: 5, name: 'Иваново' },
+    { id: 63, name: 'Иркутск' },
+    { id: 41, name: 'Йошкар-Ола' },
+    { id: 43, name: 'Казань' },
+    { id: 22, name: 'Калининград' },
+    { id: 64, name: 'Кемерово' },
+    { id: 7, name: 'Кострома' },
+    { id: 35, name: 'Краснодар' },
+    { id: 62, name: 'Красноярск' },
+    { id: 53, name: 'Курган' },
+    { id: 8, name: 'Курск' },
+    { id: 9, name: 'Липецк' },
+    { id: 28, name: 'Махачкала' },
+    { id: 1, name: 'Москва и Московская область' },
+    { id: 213, name: 'Москва' },
+    { id: 1092, name: 'Назрань' },
+    { id: 30, name: 'Нальчик' },
+    { id: 47, name: 'Нижний Новгород' },
+    { id: 65, name: 'Новосибирск' },
+    { id: 66, name: 'Омск' },
+    { id: 10, name: 'Орел' },
+    { id: 48, name: 'Оренбург' },
+    { id: 49, name: 'Пенза' },
+    { id: 50, name: 'Пермь' },
+    { id: 25, name: 'Псков' },
+    { id: 39, name: 'Ростов-на-Дону' },
+    { id: 11, name: 'Рязань' },
+    { id: 51, name: 'Самара' },
+    { id: 2, name: 'Санкт-Петербург' },
+    { id: 42, name: 'Саранск' },
+    { id: 12, name: 'Смоленск' },
+    { id: 239, name: 'Сочи' },
+    { id: 36, name: 'Ставрополь' },
+    { id: 973, name: 'Сургут' },
+    { id: 13, name: 'Тамбов' },
+    { id: 14, name: 'Тверь' },
+    { id: 67, name: 'Томск' },
+    { id: 15, name: 'Тула' },
+    { id: 195, name: 'Ульяновск' },
+    { id: 172, name: 'Уфа' },
+    { id: 76, name: 'Хабаровск' },
+    { id: 45, name: 'Чебоксары' },
+    { id: 56, name: 'Челябинск' },
+    { id: 1104, name: 'Черкесск' },
+    { id: 16, name: 'Ярославль' },
+  ];
+
+  const server = new McpServer({ name: 'yandex-webmaster', version: '1.0.0' });
 
   // ============ Core Tools ============
 
@@ -137,6 +241,23 @@ async function runServer() {
     },
   );
 
+  server.registerTool(
+    'get-region-ids',
+    {
+      title: 'Get Region IDs Reference',
+      description:
+        'Returns a static reference list of common Yandex geo region IDs (with names) for use in the region_ids parameter of get-query-analytics and feeds tools. No API call is made.',
+      inputSchema: {},
+    },
+    async () => {
+      const text = REGION_IDS.map((r) => `- ${r.id}: ${r.name}`).join('\n');
+      return {
+        content: [{ type: 'text', text: `Common Yandex region IDs:\n\n${text}` }],
+        structuredContent: { regions: REGION_IDS },
+      };
+    },
+  );
+
   // ============ Statistics & Summary ============
 
   server.registerTool(
@@ -330,6 +451,102 @@ async function runServer() {
     },
   );
 
+  server.registerTool(
+    'get-single-query-history',
+    {
+      title: 'Get Single Query History',
+      description:
+        'Returns statistics over time (shows, clicks, positions) for one specific search query. Use get-popular-queries to obtain a query_id.',
+      inputSchema: {
+        host_id: z.string().describe('Site identifier'),
+        query_id: z.string().describe('Search query identifier (from get-popular-queries)'),
+        device_type: z
+          .enum(['ALL', 'DESKTOP', 'MOBILE', 'TABLET', 'MOBILE_AND_TABLET'])
+          .optional()
+          .describe('Device filter (default: ALL)'),
+        date_from: z.string().optional().describe('Start date (YYYY-MM-DD)'),
+        date_to: z.string().optional().describe('End date (YYYY-MM-DD)'),
+      },
+    },
+    async ({ host_id, query_id, device_type, date_from, date_to }) => {
+      let endpoint = await hostEndpoint(host_id, `/search-queries/${encodeURIComponent(query_id)}/history`);
+      const params = new URLSearchParams();
+      params.set('query_indicator', 'TOTAL_SHOWS');
+      params.append('query_indicator', 'TOTAL_CLICKS');
+      params.append('query_indicator', 'AVG_SHOW_POSITION');
+      if (device_type) params.set('device_type_indicator', device_type);
+      if (date_from) params.set('date_from', formatDate(date_from));
+      if (date_to) params.set('date_to', formatDate(date_to));
+      endpoint += `?${params}`;
+
+      const data = await apiRequest(endpoint);
+
+      const shows = data.indicators?.TOTAL_SHOWS || [];
+      const text = shows
+        .slice(-14)
+        .map((p) => `${p.date.split('T')[0]}: ${p.value.toLocaleString()} shows`)
+        .join('\n');
+
+      return {
+        content: [{ type: 'text', text: `Query history (last 14 days shown):\n\n${text || 'No data'}` }],
+        structuredContent: data,
+      };
+    },
+  );
+
+  server.registerTool(
+    'get-query-analytics',
+    {
+      title: 'Get Query Analytics',
+      description:
+        'Returns the query↔URL intersection report (last ~2 weeks) with shows, clicks, CTR and positions, grouped by URL or query. Supports device, region and custom filters. Note: this endpoint is not part of the public API reference index.',
+      inputSchema: {
+        host_id: z.string().describe('Site identifier'),
+        text_indicator: z
+          .enum(['URL', 'QUERY'])
+          .optional()
+          .describe('Group results by URL or by query text (default: URL)'),
+        device_type_indicator: z
+          .enum(['ALL', 'DESKTOP', 'MOBILE', 'TABLET', 'MOBILE_AND_TABLET'])
+          .optional()
+          .describe('Device filter (default: ALL)'),
+        region_ids: z.array(z.number()).optional().describe('Filter by Yandex region IDs (see get-region-ids)'),
+        limit: z.number().min(1).max(500).optional().describe('Number of rows (default: 20)'),
+        offset: z.number().min(0).optional().describe('Offset for pagination'),
+        filters: z.record(z.any()).optional().describe('Optional API filters object (advanced, passed through as-is)'),
+        sort_by_date: z
+          .record(z.any())
+          .optional()
+          .describe('Optional sort_by_date object (advanced, passed through as-is)'),
+      },
+    },
+    async ({ host_id, text_indicator, device_type_indicator, region_ids, limit, offset, filters, sort_by_date }) => {
+      const endpoint = await hostEndpoint(host_id, '/query-analytics/list');
+      const body = {
+        text_indicator: text_indicator || 'URL',
+        device_type_indicator: device_type_indicator || 'ALL',
+        limit: limit ?? 20,
+        offset: offset ?? 0,
+      };
+      if (region_ids) body.region_ids = region_ids;
+      if (filters) body.filters = filters;
+      if (sort_by_date) body.sort_by_date = sort_by_date;
+
+      const data = await apiRequest(endpoint, { method: 'POST', body });
+
+      const rows = data.text_indicator_to_statistics || data.rows || [];
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Query analytics retrieved (${Array.isArray(rows) ? rows.length : 0} rows). See structuredContent for details.`,
+          },
+        ],
+        structuredContent: data,
+      };
+    },
+  );
+
   // ============ Indexing ============
 
   server.registerTool(
@@ -752,6 +969,32 @@ async function runServer() {
     },
   );
 
+  server.registerTool(
+    'get-user-sitemap',
+    {
+      title: 'Get User-Added Sitemap Info',
+      description: 'Returns detailed information about a single sitemap file that was manually added by the user.',
+      inputSchema: {
+        host_id: z.string().describe('Site identifier'),
+        sitemap_id: z.string().describe('User-added sitemap identifier (from get-user-sitemaps)'),
+      },
+    },
+    async ({ host_id, sitemap_id }) => {
+      const endpoint = await hostEndpoint(host_id, `/user-added-sitemaps/${encodeURIComponent(sitemap_id)}`);
+      const data = await apiRequest(endpoint);
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `User-added sitemap: ${data.sitemap_url}\nAdded: ${data.added_date?.split('T')[0] || 'N/A'}\nURLs: ${data.urls_count ?? 'N/A'}\nErrors: ${data.errors_count ?? 'N/A'}`,
+          },
+        ],
+        structuredContent: data,
+      };
+    },
+  );
+
   // ============ Important URLs ============
 
   server.registerTool(
@@ -840,6 +1083,157 @@ async function runServer() {
     },
   );
 
+  server.registerTool(
+    'get-recrawl-queue',
+    {
+      title: 'Get Recrawl Queue',
+      description: 'Returns the list of pending/recent reindexing (recrawl) tasks submitted for the site.',
+      inputSchema: {
+        host_id: z.string().describe('Site identifier'),
+        limit: z.number().min(1).max(100).optional().describe('Number of tasks (default: 10)'),
+        offset: z.number().min(0).optional().describe('Offset for pagination'),
+      },
+    },
+    async ({ host_id, limit = 10, offset }) => {
+      let endpoint = await hostEndpoint(host_id, '/recrawl/queue');
+      const params = new URLSearchParams();
+      params.set('limit', limit.toString());
+      if (offset) params.set('offset', offset.toString());
+      endpoint += `?${params}`;
+
+      const data = await apiRequest(endpoint);
+
+      const tasks = data.tasks || [];
+      const text = tasks
+        .map((t) => `- ${t.task_id}: ${t.url} [${t.state}] (added: ${t.added_time?.split('T')[0] || 'N/A'})`)
+        .join('\n');
+
+      return {
+        content: [
+          { type: 'text', text: `Recrawl queue (${data.count ?? tasks.length} total):\n\n${text || 'No tasks'}` },
+        ],
+        structuredContent: data,
+      };
+    },
+  );
+
+  server.registerTool(
+    'get-recrawl-task',
+    {
+      title: 'Get Recrawl Task Status',
+      description: 'Returns the status of a specific reindexing (recrawl) task.',
+      inputSchema: {
+        host_id: z.string().describe('Site identifier'),
+        task_id: z.string().describe('Recrawl task identifier (from submit-recrawl or get-recrawl-queue)'),
+      },
+    },
+    async ({ host_id, task_id }) => {
+      const endpoint = await hostEndpoint(host_id, `/recrawl/queue/${encodeURIComponent(task_id)}`);
+      const data = await apiRequest(endpoint);
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Recrawl task ${data.task_id}\nURL: ${data.url}\nState: ${data.state}\nAdded: ${data.added_time?.split('T')[0] || 'N/A'}`,
+          },
+        ],
+        structuredContent: data,
+      };
+    },
+  );
+
+  server.registerTool(
+    'submit-recrawl',
+    {
+      title: 'Submit URL for Recrawl',
+      description:
+        'Queues a URL for reindexing by the Yandex robot. This is a WRITE operation that consumes the daily recrawl quota (check get-recrawl-quota). Returns a task_id that can be tracked via get-recrawl-task.',
+      inputSchema: {
+        host_id: z.string().describe('Site identifier'),
+        url: z.string().describe('Full URL of the page to recrawl (must belong to the site)'),
+      },
+    },
+    async ({ host_id, url }) => {
+      const endpoint = await hostEndpoint(host_id, '/recrawl/queue');
+      const data = await apiRequest(endpoint, { method: 'POST', body: { url } });
+
+      return {
+        content: [{ type: 'text', text: `URL queued for recrawl.\nTask ID: ${data.task_id}\nURL: ${url}` }],
+        structuredContent: data,
+      };
+    },
+  );
+
+  // ============ Feeds ============
+
+  server.registerTool(
+    'get-feeds',
+    {
+      title: 'Get Feeds',
+      description: 'Returns the list of data feeds loaded for the site (enhanced site representation / фиды).',
+      inputSchema: {
+        host_id: z.string().describe('Site identifier'),
+      },
+    },
+    async ({ host_id }) => {
+      const endpoint = await hostEndpoint(host_id, '/feeds/list');
+      const data = await apiRequest(endpoint);
+
+      const feeds = data.feeds || [];
+      const text = feeds.map((f) => `- ${f.url || f.feed_url} [${f.state || f.status || 'N/A'}]`).join('\n');
+
+      return {
+        content: [{ type: 'text', text: `Feeds (${feeds.length}):\n\n${text || 'No feeds'}` }],
+        structuredContent: data,
+      };
+    },
+  );
+
+  server.registerTool(
+    'get-feed-status',
+    {
+      title: 'Get Feed Upload Status',
+      description: 'Returns the status of an asynchronous feed upload task.',
+      inputSchema: {
+        host_id: z.string().describe('Site identifier'),
+        task_id: z.string().describe('Feed upload task identifier'),
+      },
+    },
+    async ({ host_id, task_id }) => {
+      let endpoint = await hostEndpoint(host_id, '/feeds/add/info');
+      const params = new URLSearchParams();
+      params.set('task_id', task_id);
+      endpoint += `?${params}`;
+
+      const data = await apiRequest(endpoint);
+
+      return {
+        content: [
+          { type: 'text', text: `Feed upload status: ${data.state || data.status || 'see structuredContent'}` },
+        ],
+        structuredContent: data,
+      };
+    },
+  );
+
+  server.registerTool(
+    'get-feed-regions',
+    {
+      title: 'Get Feed Regions',
+      description:
+        'Returns the static reference list of regions that can be specified when uploading a YML feed (Russia is the default, id 225). This is a documentation reference, not a live API call.',
+      inputSchema: {},
+    },
+    async () => {
+      const text = FEED_REGIONS.map((r) => `- ${r.id}: ${r.name}`).join('\n');
+      return {
+        content: [{ type: 'text', text: `Feed upload regions:\n\n${text}` }],
+        structuredContent: { regions: FEED_REGIONS },
+      };
+    },
+  );
+
   // Start server
   const transport = new StdioServerTransport();
   await server.connect(transport);