Kalendis

Kalendis MCP ツール

Kalendis のスケジューリング API と連携するための MCP（Model Context Protocol）サーバーおよびクライアント生成ツールです。

特長

• 🔧 MCP サーバー：Claude、Cursor などで使用できる Kalendis API ツールを公開します
• 🚀 クライアント生成ツール：バックエンドおよびフロントエンドアプリケーション向けの 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 エージェントは以下のツールを使用できます。

• 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 エンドポイントの対応範囲

このツールは、Kalendis の全 28 件の 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 - アカウントを更新

環境設定

このツールは3つの環境に対応しています。

• 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. リポジトリをフォークします
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 の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

サポート

問題や質問がある場合：

• GitHub で Issue を作成してください
• メール：[email protected]