se-ranking-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an MCP (Model Context Protocol) server that connects AI assistants to SE Ranking's SEO APIs. It provides ~190 tools organized into two API backends:

• Data API (DATA_ prefix, host api.seranking.com): SEO analytics — keyword research, backlinks, domain analysis, SERP, website audits, account/credit info. Requires DATA_API_TOKEN.
• Project API (PROJECT_ prefix, host api4.seranking.com): operations on projects owned by the authenticated account — rank tracking, competitors, backlink monitoring, marketing plan, sub-accounts, AIRT (AI Result Tracker). Requires PROJECT_API_TOKEN.

Tokens are not interchangeable. The Docker quickstart sets only SERANKING_API_TOKEN (Data-only); any PROJECT_* tool needs PROJECT_API_TOKEN set explicitly.

Common Commands

# Build
npm run build

# Run tests (compiles first)
npm test

# Run only E2E tests (requires E2E_ENABLED=true and valid API tokens)
npm run test:e2e

# Watch mode for tests
npm run test:watch

# Lint and format
npm run lint
npm run lint:fix
npm run format

# Type checking
npm run typecheck

# Start servers
npm run start        # Stdio mode (standard MCP)
npm run start-http   # HTTP mode (Express server on port 5000)

Architecture

Tool Pattern

All tools extend BaseTool (src/tools/base-tool.ts) which provides:

• apiType: Set to ApiType.DATA or ApiType.PROJECT (defaults to DATA)
• toolName(name): Prefixes with API type (e.g., DATA_getDomainKeywords)
• registerTool(server): Abstract method each tool implements
• annotations(kind): Returns MCP tool annotations for one of 'read' | 'write' | 'writeIdempotent' | 'destructive'. An ESLint no-restricted-syntax rule blocks any server.registerTool(...) call whose options object doesn't declare annotations — use this.annotations(...) on every new tool.
• HTTP helpers:
  • makeGetRequest(path, params) — GET with query params
  • makeBinaryGetRequest(path, params, mimeType?) — GET that returns a binary blob as an MCP embedded resource (used for ZIP/image responses)
  • makePostRequest(path, queryParams, formParams) — POST multipart/form-data; formParams may contain Blob/File values which are passed through as-is for file uploads
  • makeJsonPostRequest(path, body) — POST with Content-Type: application/json
  • makeBodylessPostRequest(path) — POST with no body and no Content-Type. Use this for endpoints that reject Content-Type: application/json + {} (e.g. reset, recheck, delete on Project API /audit/{id}/…)
  • makePutRequest(path, body) — PUT with JSON body
  • makePatchRequest(path, queryParams, body) — PATCH with JSON body
  • makeDeleteRequest(path, params) — DELETE with query params
  • makeJsonDeleteRequest(path, body) — DELETE with JSON body
• transformFilterParams(): Converts filter_volume_from to filter[volume][from] for API calls