Kalendis MCP

🚀 Kalendis MCP 工具

Kalendis MCP 工具是用於 Kalendis 調度 API 集成的 MCP（模型上下文協議）服務器和客戶端生成器，可幫助開發者更高效地使用 Kalendis 調度 API。

🚀 快速開始

1. 獲取 API 密鑰

在使用 Kalendis MCP 工具之前，你需要一個 API 密鑰。在 kalendis.dev 創建一個免費賬戶 即可開始。你的 API 密鑰將顯示在賬戶儀表板中，這是對 Kalendis 調度 API 請求進行身份驗證所必需的。

2. 配置 MCP 服務器

快速安裝（Cursor IDE）

點擊下面的按鈕，自動將 Kalendis 添加到你的 Cursor IDE：

手動配置

或者，將以下內容添加到你的 MCP 設置中：

{
  "mcpServers": {
    "kalendis": {
      "command": "npx",
      "args": ["-y", "@kalendis/mcp"]
    }
  }
}

3. 可用的 MCP 工具

配置完成後，AI 代理可以使用以下工具：

• generate-backend-client：生成用於直接進行 API 調用的 TypeScript 客戶端
• generate-frontend-client：生成用於前端應用程序的 TypeScript 客戶端
• generate-api-routes：為 Next.js、Express、Fastify 或 NestJS 生成 API 路由處理程序
• list-endpoints：列出所有可用的 Kalendis API 端點

✨ 主要特性

• 🔧 MCP 服務器：公開 Kalendis API 工具，供 Claude、Cursor 等使用
• 🚀 客戶端生成器：為後端和前端應用程序生成 TypeScript 客戶端
• 🛣️ 路由生成器：為 Next.js、Fastify、NestJS 和 Express 創建 API 路由處理程序
• 🔐 安全：使用環境變量進行 API 密鑰管理
• 📝 類型安全：完全支持 TypeScript，並生成類型

📦 安裝指南

npm install @kalendis/mcp

💻 使用示例

基礎用法

後端客戶端

生成一個直接調用 Kalendis API 的客戶端：

// 生成的客戶端使用示例
import KalendisClient from './generated/kalendis-client';

// 使用你的 API 密鑰進行初始化（從環境變量、配置文件等獲取）
const client = new KalendisClient({
  apiKey: process.env.MY_API_KEY, // 你可以選擇環境變量的名稱
});

const users = await client.getUsers();
const user = await client.createUser({ name: 'John Doe', email: 'john@example.com' });

前端客戶端

生成一個調用後端 API 端點的客戶端：

// 生成的前端客戶端使用示例
import api from './generated/frontend-client';

// 調用你的後端端點（例如，/api/users）
const users = await api.getUsers();

高級用法

Next.js 路由

生成 App Router API 路由：

// app/api/users/route.ts
export async function GET(request: Request) {
  // 使用後端客戶端實現
}

Express 路由

生成 Express 路由器處理程序：

// routes/api.ts
router.get('/users', async (req, res) => {
  // 使用後端客戶端實現
});

Fastify 路由

生成帶有路由處理程序的 Fastify 插件：

// routes/kalendis.ts
export default async function routes(fastify: FastifyInstance) {
  fastify.get('/api/users', async (request, reply) => {
    // 使用後端客戶端實現
    return users;
  });
}

NestJS 模塊

生成包含控制器、服務和模塊文件的完整 NestJS 模塊：

// kalendis.controller.ts
@Controller('api')
export class KalendisController {
  @Get('users')
  async getUsers() {
    return this.kalendisService.getUsersByAccountId();
  }
}

// kalendis.service.ts - 包裝後端客戶端
// kalendis.module.ts - 將所有內容連接在一起

📚 詳細文檔

API 端點覆蓋範圍

該工具支持所有 28 個 Kalendis API 端點：

用戶

• GET /v1/users - 獲取所有用戶
• POST /v1/users - 創建用戶
• PUT /v1/users/:id - 更新用戶
• DELETE /v1/users/:id - 刪除用戶

可用性

• GET /v1/availability - 按篩選條件獲取可用性
• GET /v1/availability/all - 獲取所有可用性
• GET /v1/availability/calculated - 獲取計算後的可用性
• GET /v1/availability/recurring - 獲取重複可用性
• GET /v1/availability/matching - 獲取匹配的可用性
• POST /v1/availability - 添加可用性
• PUT /v1/availability/:id - 更新可用性
• DELETE /v1/availability/:id - 刪除可用性

重複可用性

• GET /v1/recurring-availability - 獲取重複可用性
• POST /v1/recurring-availability - 添加重複可用性
• PUT /v1/recurring-availability/:id - 更新重複可用性
• DELETE /v1/recurring-availability/:id - 刪除重複可用性

可用性例外

• GET /v1/availability-exceptions - 獲取例外情況
• POST /v1/availability-exceptions - 添加例外情況
• POST /v1/availability-exceptions/recurring - 添加重複例外情況
• PUT /v1/availability-exceptions/:id - 更新例外情況
• DELETE /v1/availability-exceptions/:id - 刪除例外情況

預訂

• GET /v1/bookings - 獲取預訂
• GET /v1/bookings/:userId - 獲取用戶預訂
• POST /v1/bookings - 創建預訂
• PUT /v1/bookings/:id - 更新預訂
• DELETE /v1/bookings/:id - 刪除預訂

賬戶

• GET /v1/account - 獲取賬戶信息
• PUT /v1/account - 更新賬戶

環境配置

該工具支持三種環境：

• 開發環境：https://sandbox.api.kalendis.dev
• 生產環境：https://api.kalendis.dev

身份驗證

所有對 Kalendis 調度服務的 API 調用都需要通過 x-api-key 標頭進行身份驗證。

生成的客戶端在實例化時需要你提供一個 API 密鑰：

// 你可以控制如何管理 API 密鑰
const client = new KalendisClient({
  apiKey: process.env.KALENDIS_API_KEY, // 或者從配置文件、密鑰管理器等獲取
});

生成的 API 路由處理程序默認使用環境變量，但你可以自定義：

# 示例：在應用程序環境中設置
export KALENDIS_API_KEY="your-api-key-here"

注意：MCP 工具本身不需要或使用 API 密鑰，它只生成代碼。API 密鑰由應用程序中生成的客戶端使用。

錯誤處理

生成的客戶端提供清晰的錯誤消息：

• 401：身份驗證失敗 - API 密鑰無效或缺失
• 403：權限被拒絕 - API 密鑰缺乏所需權限
• 網絡錯誤：清晰的連接失敗消息
• API 錯誤：來自 API 的詳細錯誤消息

🔧 技術細節

本地構建 MCP 工具

git clone https://github.com/kalendis-dev/kalendis-mcp.git
cd kalendis-mcp
npm install
npm run build

🤝 貢獻

歡迎貢獻代碼！請隨時提交拉取請求。

1. 分叉倉庫
2. 創建你的功能分支 (git checkout -b feature/amazing-feature)
3. 提交你的更改 (git commit -m 'Add some amazing feature')
4. 推送到該分支 (git push origin feature/amazing-feature)
5. 打開拉取請求

📄 許可證

本項目採用 MIT 許可證 - 有關詳細信息，請參閱 LICENSE 文件。

🛠️ 支持

如有問題或疑問：

• 在 GitHub 上打開一個問題
• 發送電子郵件至：support@kalendis.dev