Kalendis MCP

Instructions

Implementation Reference

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

  Registration of the generate-backend-client tool in the TOOLS array, including name, description, and input schema definition.
  { 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 for the generate-backend-client tool: validates arguments and invokes the generator function.
  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/generators/client.ts:215-229 (handler)

  Main implementation of the backend client generator: constructs base client class and dynamically generates API methods 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/generators/client.ts:89-143 (helper)

  Helper function generateBaseClient that generates the base KalendisClient class with authentication and request handling logic.
  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; } }`; }