Kalendis MCP

🚀 Kalendis MCP Tool

KalendisのスケジューリングAPIを統合するためのMCP（Model Context Protocol）サーバーとクライアント生成ツールです。KalendisのAPIをClaudeやCursorなどのAIエージェントと連携させることができます。

✨ 主な機能

• 🔧 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）

下のボタンをクリックして、自動的にCursor IDEにKalendisを追加してください。

手動設定

あるいは、これを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: 'john@example.com' });

フロントエンドクライアント

バックエンドAPIエンドポイントを呼び出すクライアントを生成します。

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

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

高度な使用法

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 - アカウントを更新します。

環境設定

このツールは3つの環境をサポートしています。

• 開発環境：https://sandbox.api.kalendis.dev
• 本番環境：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ファイルを参照してください。

サポート

問題や質問がある場合は、以下の方法で問い合わせてください。

• GitHubでイシューを開く
• メール：support@kalendis.dev