Kalendis MCP

Instructions

Implementation Reference

• src/generators/client.ts:215-229 (handler)

  Core handler function that generates the complete TypeScript backend client code by combining base client class, request method, and individual API method implementations based on ENDPOINTS.

  export function generateBackendClient(options: GenerateOptions): string {
    const typesPath = options.typesImportPath || '../types';
    const baseClient = generateBaseClient(options.environment, typesPath);
  
    const methods = Object.entries(ENDPOINTS)
      .map(([name, endpoint]) => generateMethod(name, endpoint))
      .join('\n');
  
    return `${baseClient}
  ${methods}
  }
  
  export default KalendisClient;
  `;
  }

• src/server.ts:35-53 (registration)

  Tool registration in the TOOLS array, including name, description, and input schema.

  {
    name: 'generate-backend-client',
    description: 'Generate a TypeScript client that calls Kalendis API directly with x-api-key authentication',
    inputSchema: {
      type: 'object',
      properties: {
        environment: {
          type: 'string',
          enum: ['production', 'staging', 'development'],
          description: 'Target environment (optional, defaults to production)',
        },
        typesImportPath: {
          type: 'string',
          description: 'Import path for types file (optional, defaults to "../types")',
        },
      },
      required: [],
    },
  },

• src/server.ts:105-125 (handler)

  MCP server handler case that validates input and calls the generateBackendClient function to produce the client code.

  case 'generate-backend-client': {
    const environment = args?.environment || 'production';
    if (typeof environment !== 'string' || !['production', 'staging', 'development'].includes(environment)) {
      throw new Error('Valid environment is required (production, staging, development)');
    }
  
    const code = generateBackendClient({
      environment: environment as Environment,
      typesImportPath: args?.typesImportPath as string | undefined,
      framework: 'vanilla', // Not used in backend client
    });
  
    return {
      content: [
        {
          type: 'text',
          text: code,
        },
      ],
    };
  }

• src/server.ts:38-52 (schema)

  Input schema definition for the tool, specifying optional environment and typesImportPath parameters.

  inputSchema: {
    type: 'object',
    properties: {
      environment: {
        type: 'string',
        enum: ['production', 'staging', 'development'],
        description: 'Target environment (optional, defaults to production)',
      },
      typesImportPath: {
        type: 'string',
        description: 'Import path for types file (optional, defaults to "../types")',
      },
    },
    required: [],
  },

• src/generators/client.ts:89-143 (helper)

  Helper function that generates the base KalendisClient class with authentication and generic request method.

  function generateBaseClient(environment: Environment, typesPath: string): string {
    return `import * as Types from '${typesPath}';
  
  class KalendisClient {
    private readonly apiKey: string;
    private readonly baseUrl: string;
  
    constructor(options: { apiKey: string }) {
      if (!options.apiKey) {
        throw new Error('API key is required. Pass it in the constructor: new KalendisClient({ apiKey: "your-key" })');
      }
      this.apiKey = options.apiKey;
      this.baseUrl = process.env.KALENDIS_API_URL || 'https://sandbox.api.kalendis.dev';
    }
  
    private async request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
      const url = \`\${this.baseUrl}\${endpoint}\`;
      
      try {
        const response = await fetch(url, {
          ...options,
          headers: {
            'x-api-key': this.apiKey,
            'Content-Type': 'application/json',
            ...options.headers
          }
        });
  
        if (!response.ok) {
          let errorMessage = \`Kalendis API Error (\${response.status}): \${response.statusText}\`;
          try {
            const error = await response.json();
            errorMessage = \`Kalendis API Error (\${response.status}): \${error.message || error.error || response.statusText}\`;
          } catch {
            // Use default error message if response isn't JSON
          }
          
          if (response.status === 401) {
            throw new Error('Authentication failed: Invalid or missing API key');
          } else if (response.status === 403) {
            throw new Error('Permission denied: Your API key does not have access to this resource');
          }
          
          throw new Error(errorMessage);
        }
  
        return response.json();
      } catch (error) {
        if (error instanceof TypeError && error.message.includes('fetch')) {
          throw new Error(\`Cannot connect to Kalendis API at \${this.baseUrl}. Please ensure the service is running.\`);
        }
        throw error;
      }
    }`;
  }