Kalendis

Kalendis MCP 工具

用于集成 Kalendis 日程安排 API 的 MCP（Model Context Protocol）服务和客户端生成器。

功能

• 🔧 MCP 服务：提供 Kalendis API 工具，可与 Claude、Cursor 等配合使用
• 🚀 客户端生成器：为后端和前端应用生成 TypeScript 客户端
• 🛣️ 路由生成器：为 Next.js、Fastify、NestJS 和 Express 创建 API 路由处理程序
• 🔐 安全：使用环境变量管理 API 密钥
• 📝 类型安全：提供完整的 TypeScript 支持和生成的类型

安装

npm install @kalendis/mcp

快速入门

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 Agent 可以使用以下工具：

• generate-backend-client：生成用于直接调用 API 的 TypeScript 客户端
• generate-frontend-client：为前端应用生成 TypeScript 客户端
• generate-api-routes：为 Next.js、Express、Fastify 或 NestJS 生成 API 路由处理程序
• list-endpoints：列出所有可用的 Kalendis API 端点

客户端生成

后端客户端

生成可直接调用 Kalendis API 的客户端：

// 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: '[email protected]' });

前端客户端

生成可调用后端 API 端点的客户端：

// Generated frontend client usage
import api from './generated/frontend-client';

// Calls your backend endpoints (e.g., /api/users)
const users = await api.getUsers();

API 路由

Next.js 路由

生成 App Router API 路由：

// app/api/users/route.ts
export async function GET(request: Request) {
  // Implementation using backend client
}

Express 路由

生成 Express 路由处理程序：

// routes/api.ts
router.get('/users', async (req, res) => {
  // Implementation using backend client
});

Fastify 路由

生成包含路由处理程序的 Fastify 插件：

// routes/kalendis.ts
export default async function routes(fastify: FastifyInstance) {
  fastify.get('/api/users', async (request, reply) => {
    // Implementation using backend client
    return users;
  });
}

NestJS 模块

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

// 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 端点覆盖范围

该工具支持全部 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 - 更新账户

环境配置

该工具支持三种环境：

• development：https://sandbox.api.kalendis.dev
• production：https://api.kalendis.dev

身份验证

对 Kalendis 日程安排服务的所有 API 调用都需要通过 x-api-key 标头进行身份验证。

实例化生成的客户端时，需要提供 API 密钥：

// You control how to manage your API key
const client = new KalendisClient({
  apiKey: process.env.KALENDIS_API_KEY, // or from config, secrets manager, etc.
});

生成的 API 路由处理程序默认使用环境变量，但你可以自定义：

# Example: Set in your application's environment
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. Fork 此仓库
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 上提交问题
• 电子邮件：[email protected]