TypeScript MCP Server

TypeScript MCP サーバー

給与管理向けに、TypeScript と Express を使用して実装された Model Context Protocol（MCP）サーバーです。

MCP とは？

Model Context Protocol（MCP）を使用すると、AI モデルが標準化された方法で外部システムとやり取りできます。LLM がタスクを実行するために使用できるリソース、ツール、プロンプトを定義するためのフレームワークを提供します。

詳しくは、Model Context Protocol リポジトリをご覧ください。

特徴

• LLM とのやり取りのための MCP プロトコルを実装
• 給与管理ツールと従業員情報へのアクセスを提供
• HTTP の処理に Express を使用
• リアルタイム通信のための Server-Sent Events（SSE）をサポート
• テスト用のクライアント例を同梱

要件

• Node.js 18+
• npm または yarn

インストール

1. リポジトリをクローンします
2. 依存関係をインストールします：

npm install

3. .env.example テンプレートを基に .env ファイルを作成します：

cp .env.example .env

4. .env ファイルに API の設定を記述します：

# API configuration
BASE_URL=http://app.localopfin.com
PORT=8089

サーバーの起動

次のコマンドで開発サーバーを起動します：

npm run dev

本番環境の場合：

npm run build
npm start

サーバーはデフォルトでポート 8089 で起動します。.env ファイルで PORT 環境変数を設定すると、ポートを変更できます。

認証

このサーバーは API リクエストに対して、次の 2 種類の認証方式をサポートしています：

1. authId と authKey を使用する API 認証
2. partnerKey と clientKey を使用するパートナー認証

独自の認証要件に合わせるには、src/api.ts ファイルを変更してください。

API エンドポイント

• GET /sse：MCP 通信用の Server-Sent Events エンドポイント
• POST /messages：クライアントが MCP サーバーにメッセージを送信するためのエンドポイント

利用可能なリソース

• greeting://welcome：静的なウェルカムメッセージ
• users://{userId}：ユーザーデータを返す動的なリソース

利用可能なツール

• view-people：従業員 ID を使用して特定の人物の情報を表示します（authId と authKey による認証が必要）
• view-all-people：絞り込みとページネーションを任意で指定して、すべての人物を表示します（authId/authKey による API 認証、または partnerKey/clientKey によるパートナー認証をサポート）
• getEmployeeInfo：従業員 ID に基づき、従業員の基本情報（氏名、部署、役職）を返す、簡易的な従業員情報取得ツールです
• calculatePayroll：勤務時間と時給に基づいて従業員の給与を計算します（総支給額、20% の税金、手取り額を算出します）

利用可能なインターフェース

このプロジェクトには、API レスポンス用の型付きインターフェースが含まれています：

• ApiResponse<T>：data、error、status フィールドを含む汎用 API レスポンスラッパー
• ApiConfig：baseUrl と任意の headers を指定する API クライアント設定
• ApiCredentials：authId と authKey を使用する API ベースの認証用
• PartnerCredentials：partnerKey と clientKey を使用するパートナーベースの認証用

これらのインターフェースにより、API データを扱う際の型安全性を確保できます。

利用可能なプロンプト

• ask-question：質問するためのプロンプトテンプレート

サンプルクライアントでのテスト

このリポジトリには、MCP サーバーへの接続方法と、そのリソース、ツール、プロンプトの使用方法を示すサンプルクライアントが含まれています。

サンプルクライアントを実行するには（サーバーがすでに起動している状態で）：

npm run client

実行すると、次の処理が行われます：

1. MCP サーバーに接続します
2. 利用可能なリソース、ツール、プロンプトを一覧表示します
3. greeting リソースを読み取ります
4. 利用可能なツールを使用します
5. ask-question プロンプトを取得します

LLM での使用

この MCP サーバーは、MCP プロトコルをサポートする LLM クライアントで使用できます。LLM クライアントをこのサーバーに接続する方法については、MCP のドキュメントを参照してください。

ライセンス

MIT