JinDaGe - kalendis-mcp MCP Details

article

README

🚀 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

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。

分叉仓库
创建你的功能分支 (git checkout -b feature/amazing-feature)
提交你的更改 (git commit -m 'Add some amazing feature')
推送到该分支 (git push origin feature/amazing-feature)
打开拉取请求

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

🛠️ 支持

如有问题或疑问：

在 GitHub 上打开一个问题
发送电子邮件至：support@kalendis.dev

kalendis-mcp