windsurf-rules

App Store MCP Server - Windsurf Rules

Project Overview

• This is a TypeScript/Node.js MCP (Model Context Protocol) server for app store scraping
• Provides 20 MCP tools for Google Play Store and Apple App Store data access
• Uses Express for HTTP server with dual transport support (HTTP and SSE)
• Experimental status project - focus on stability and maintainability over new features

TypeScript Configuration & Style

Strict Type Safety

• Always use strict TypeScript with all strict mode options enabled
• Never use any type - use unknown with proper type guards or define specific types
• Enable and respect all strict compiler options: noImplicitAny, noImplicitReturns, noImplicitThis, noUnusedLocals, noUnusedParameters, noUncheckedIndexedAccess
• Use readonly for immutable properties and arrays when applicable
• Always declare explicit return types for functions and methods

Type Definitions

• Create interfaces for all data structures, especially tool input parameters
• Use JSONSchema7 type from 'json-schema' package for MCP tool schemas
• Follow the pattern: interface for params + JSONSchema7 for input validation
• Group related types in src/types/ directory

Code Style

• Use JSDoc comments for all public classes, methods, and exported functions
• Include @param, @returns, @throws tags in JSDoc where applicable
• Mark private methods with @private JSDoc tag
• Use descriptive variable names with full words (not abbreviations)
• Prefer const over let, never use var

MCP Tool Implementation Pattern

Tool Class Structure

When creating new MCP tools, follow this exact pattern:

/**
 * [Tool Name] MCP Tool
 * [Brief description of what the tool does]
 */
export class [ToolName]Tool implements MCPTool {
  public readonly name = 'tool-name-kebab-case';
  public readonly description = 'Clear description';
  
  public readonly inputSchema: JSONSchema7 = {
    type: 'object',
    properties: { /* schema */ },
    required: ['requiredParam'],
    additionalProperties: false
  };

  async execute(params: [ParamsInterface]): Promise<any> {
    try {
      this.validateParams(params);
      // Execute logic
      return filterAppData(result, params.fullDetail || false);
    } catch (error) {
      return this.handleError(error, context);
    }
  }

  private validateParams(params: any): void {
    // Explicit validation with clear error messages
  }

  private handleError(error: any, context: string): any {
    // Structured error response
  }
}