mcp-server-typescript

Implements the Model Context Protocol standard to register SEO tools as discoverable resources that AI agents can invoke. Uses a modular architecture where BaseModule abstract class provides a common interface for tool registration, and McpServer centralizes tool discovery and client connection handling. Each tool is registered with structured metadata (name, description, input schema) that MCP clients can query to understand available capabilities without hardcoding tool knowledge.

Provides access to real-time search engine results from Google, Bing, and Yahoo through the SERP module, which translates MCP tool calls into DataForSEO SERP API requests. The SerpModule extends BaseModule and registers individual tools for different search queries and parameters. Handles authentication via DataForSEOClient, processes API responses, and returns structured SERP data including rankings, snippets, and metadata in a consistent JSON format.

Implements tools that analyze market-level SEO trends by querying DataForSEO Labs data for emerging keywords, trending topics, and market shifts. Tools accept market/industry parameters and return trend analysis including rising keywords, declining topics, seasonal patterns, and market opportunity assessment. Implements time-series analysis on historical keyword data to identify patterns and forecast trends.

Provides BaseTool abstract class and module extension patterns that enable developers to add new tools for DataForSEO APIs not yet implemented in the server. Developers extend BaseTool, implement execute method with API call logic, and register the tool with a module. The framework handles MCP protocol integration, parameter validation, and response formatting automatically. Includes development guide and examples for adding new tools and modules.

Exposes DataForSEO's Keywords Data API through the KeywordsDataModule, enabling AI agents to retrieve keyword research metrics including search volume, CPC, competition level, and trend data. The module registers tools that translate keyword queries into DataForSEO API calls, aggregate metrics across data sources, and return structured keyword intelligence. Handles parameter validation for keyword lists, geographic targeting, and language selection before forwarding to the DataForSEO backend.

Implements the OnPage module to provide website crawling and on-page SEO performance analysis through DataForSEO's OnPage API. Tools in this module accept target URLs and return structured crawl data including page metadata, technical SEO issues, content analysis, and performance metrics. The module handles crawl job submission, polling for completion, and result aggregation into a unified response format that AI agents can interpret for SEO recommendations.

Exposes DataForSEO Labs API through the DataForSEOLabsModule, providing access to proprietary SEO databases including historical SERP data, keyword difficulty scores, backlink metrics, and domain authority estimates. Tools in this module query DataForSEO's aggregated SEO intelligence database rather than real-time crawls, enabling historical analysis and trend identification. Implements caching strategies for frequently-accessed metrics to reduce API calls.

Implements a modular architecture where functionality is organized into independent modules (SERP, KeywordsData, OnPage, DataForSEOLabs) that extend BaseModule abstract class. Each module registers its own set of tools and can be selectively enabled/disabled through configuration without modifying code. The McpServer loads enabled modules at startup and registers their tools, allowing operators to control which DataForSEO APIs are exposed to clients based on subscription tier or security policy.

Implements DataForSEOClient class that handles authentication (username/password credentials), request signing, and HTTP connection management to DataForSEO's API endpoints. The client abstracts authentication complexity from individual tools, implementing credential storage, token refresh (if applicable), and connection pooling to reduce overhead for multiple concurrent requests. All tools use this shared client instance, ensuring consistent authentication and efficient resource utilization.

Implements BaseTool abstract class that provides common parameter validation and request/response handling for all tools. Each tool defines its input schema (required parameters, types, constraints) which is validated before API calls are made. The validation layer catches invalid parameters early, provides clear error messages to clients, and prevents malformed requests from reaching DataForSEO APIs. Response formatting is standardized across all tools to ensure consistent output structure.

Provides a set of tools within the SERP and KeywordsData modules that aggregate competitor research data by combining SERP rankings, keyword metrics, and backlink analysis. Tools accept competitor domain(s) as input and return aggregated intelligence including keywords they rank for, their search visibility, estimated traffic, and content strategy insights. Implements multi-step queries (SERP lookup → keyword metrics → Labs data) to build comprehensive competitor profiles.

Implements a set of keyword research tools that combine search volume, CPC, competition metrics, and trend data to identify high-opportunity keywords. Tools accept seed keywords or topics and return ranked keyword lists with opportunity scores calculated from multiple factors (search volume, competition, trend direction, CPC). Implements filtering and sorting logic to surface keywords matching specific criteria (high volume + low competition, emerging trends, high-value niches).