Kalendis MCP

# Kalendis MCP Tool [](https://www.npmjs.com/package/@kalendis/mcp) [](https://opensource.org/licenses/MIT) MCP (Model Context Protocol) server and client generator for Kalendis scheduling API integration. ## Features - 🔧 **MCP Server**: Exposes Kalendis API tools for use with Claude, Cursor, etc - 🚀 **Client Generator**: Generates TypeScript clients for backend and frontend applications - 🛣️ **Route Generator**: Creates API route handlers for Next.js, Fastify, NestJS and Express - 🔐 **Secure**: Uses environment variables for API key management - 📝 **Type-safe**: Full TypeScript support with generated types ## Installation ```bash npm install @kalendis/mcp ``` ## Quick Start ### 1. Get Your API Key Before using the Kalendis MCP tool, you'll need an API key. [Create a free account at kalendis.dev](https://kalendis.dev) to get started. Your API key will be available in your account dashboard and is required for authenticating requests to the Kalendis scheduling API. ### 2. Configure MCP Server #### Quick Install (Cursor IDE) Click the button below to automatically add Kalendis to your Cursor IDE: [<img src="https://cursor.com/deeplink/mcp-install-dark.png" alt="Add to Cursor" height="40">](cursor://anysphere.cursor-deeplink/mcp/install?name=kalendis&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBrYWxlbmRpcy9tY3AiXX0=) #### Manual Configuration Alternatively, add this to your MCP settings: ```json { "mcpServers": { "kalendis": { "command": "npx", "args": ["-y", "@kalendis/mcp"] } } } ``` ### 3. Available MCP Tools Once configured, the AI agent can use these tools: - **generate-backend-client**: Generate a TypeScript client for direct API calls - **generate-frontend-client**: Generate a TypeScript client for frontend applications - **generate-api-routes**: Generate API route handlers for Next.js, Express, Fastify, or NestJS - **list-endpoints**: List all available Kalendis API endpoints ## Client Generation ### Backend Client Generate a client that calls the Kalendis API directly: ```typescript // Generated client usage import KalendisClient from './generated/kalendis-client'; // Initialize with your API key (from environment variable, config, etc.) const client = new KalendisClient({ apiKey: process.env.MY_API_KEY, // You choose the env var name }); const users = await client.getUsers(); const user = await client.createUser({ name: 'John Doe', email: 'john@example.com' }); ``` ### Frontend Client Generate a client that calls your backend API endpoints: ```typescript // Generated frontend client usage import api from './generated/frontend-client'; // Calls your backend endpoints (e.g., /api/users) const users = await api.getUsers(); ``` ### API Routes #### Next.js Routes Generates App Router API routes: ```typescript // app/api/users/route.ts export async function GET(request: Request) { // Implementation using backend client } ``` #### Express Routes Generates Express router handlers: ```typescript // routes/api.ts router.get('/users', async (req, res) => { // Implementation using backend client }); ``` #### Fastify Routes Generates Fastify plugin with route handlers: ```typescript // routes/kalendis.ts export default async function routes(fastify: FastifyInstance) { fastify.get('/api/users', async (request, reply) => { // Implementation using backend client return users; }); } ``` #### NestJS Module Generates complete NestJS module with controller, service, and module files: ```typescript // kalendis.controller.ts @Controller('api') export class KalendisController { @Get('users') async getUsers() { return this.kalendisService.getUsersByAccountId(); } } // kalendis.service.ts - Wraps the backend client // kalendis.module.ts - Wire everything together ``` ## API Endpoints Coverage The tool supports all 28 Kalendis API endpoints: ### Users - GET /v1/users - Fetch all users - POST /v1/users - Create user - PUT /v1/users/:id - Update user - DELETE /v1/users/:id - Delete user ### Availability - GET /v1/availability - Get availability with filters - GET /v1/availability/all - Get all availability - GET /v1/availability/calculated - Get calculated availability - GET /v1/availability/recurring - Get recurring availability - GET /v1/availability/matching - Get matching availability - POST /v1/availability - Add availability - PUT /v1/availability/:id - Update availability - DELETE /v1/availability/:id - Delete availability ### Recurring Availability - GET /v1/recurring-availability - Get recurring availability - POST /v1/recurring-availability - Add recurring availability - PUT /v1/recurring-availability/:id - Update recurring availability - DELETE /v1/recurring-availability/:id - Delete recurring availability ### Availability Exceptions - GET /v1/availability-exceptions - Get exceptions - POST /v1/availability-exceptions - Add exception - POST /v1/availability-exceptions/recurring - Add recurring exception - PUT /v1/availability-exceptions/:id - Update exception - DELETE /v1/availability-exceptions/:id - Delete exception ### Bookings - GET /v1/bookings - Get bookings - GET /v1/bookings/:userId - Get user bookings - POST /v1/bookings - Create booking - PUT /v1/bookings/:id - Update booking - DELETE /v1/bookings/:id - Delete booking ### Account - GET /v1/account - Get account info - PUT /v1/account - Update account ## Environment Configuration The tool supports three environments: - **development**: `https://sandbox.api.kalendis.dev` - **production**: `https://api.kalendis.dev` ## Authentication All API calls to the Kalendis scheduling service require authentication via the `x-api-key` header. The generated clients require you to provide an API key when instantiating: ```typescript // You control how to manage your API key const client = new KalendisClient({ apiKey: process.env.KALENDIS_API_KEY, // or from config, secrets manager, etc. }); ``` The generated API route handlers use environment variables by default, but you can customize this: ```bash # Example: Set in your application's environment export KALENDIS_API_KEY="your-api-key-here" ``` **Note**: The MCP tool itself doesn't need or use the API key - it only generates code. The API key is used by the generated clients in your application. ## Error Handling The generated clients provide clear error messages: - **401**: Authentication failed - Invalid or missing API key - **403**: Permission denied - API key lacks required permissions - **Network errors**: Clear connection failure messages - **API errors**: Detailed error messages from the API ## Development To build the MCP tool locally: ```bash git clone https://github.com/kalendis-dev/kalendis-mcp.git cd kalendis-mcp npm install npm run build ``` ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add some amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Support For issues or questions: - Open an issue on [GitHub](https://github.com/kalendis-dev/kalendis-mcp/issues) - Email: support@kalendis.dev