JobNimbus MCP Server

JobNimbus MCP サーバー

このプロジェクトは、Cursor や Claude などの互換性のある AI アシスタントを介して JobNimbus API と連携するための Model Context Protocol (MCP) サーバーを提供します。

AI エージェントは、JobNimbus API キーを使った安全なアクセスにより、標準化されたツールを通じて JobNimbus のデータ（連絡先、案件、タスク、製品、ワークフロー、請求書）にアクセスし、操作できます。

このサーバーは npm で公開されており、npx を使って簡単に実行できます。

セットアップ手順

お使いの AI アシスタントに応じた以下の手順に従ってください。

Cursor Editor のセットアップ

1. 前提条件：

   • Cursor Editor がインストールされていること。
   • Node.js と npm がインストールされていること（npx の実行に必要です）。
   • JobNimbus API キー。

2. Cursor を設定する：

   • ホームディレクトリに ~/.cursor ディレクトリがない場合は作成します。

   • このディレクトリ内に mcp.json という名前のファイルを作成します（~/.cursor/mcp.json）。

   • 次の設定を ~/.cursor/mcp.json にコピーします。

     {
       "mcpServers": {
         "jobnimbus-local-server": {
           "description": "JobNimbus MCP Server (requires API key)",
           "command": "npx",
           "args": ["jobnimbus-mcp-server"],
           "env": {
             "JOBNIMBUS_API_KEY": "your_api_key_here"
           }
         }
       }
     }
     

   • 重要： ファイル内の "your_api_key_here" を、実際の JobNimbus API キーに置き換えてください。

3. Cursor を再起動する：

   • Cursor エディターを完全に終了してから再起動します。

4. 確認する：

   • Cursor は必要に応じて npx を使い、サーバーを自動的に実行します。
   • Cursor の MCP 設定、またはエージェントがツールを提案したときに、利用可能なツールとして jobnimbus-local-server が表示されます。
   • これで、JobNimbus のツールを使った操作を Cursor に依頼できます（例：「jobnimbus_list_contacts を使って JobNimbus の連絡先を一覧表示して」）。

Claude Desktop App のセットアップ

1. 前提条件：

   • Claude Desktop App がインストールされていること。
   • Node.js と npm がインストールされていること（npx の実行に必要です）。
   • JobNimbus API キー。

2. Claude を設定する：

   • Claude の設定ファイルを見つけます。

     • Mac の場合：~/Library/Application Support/Claude/claude_desktop_config.json
     • Windows の場合：%APPDATA%\Claude\claude_desktop_config.json

   • ファイルがない場合は作成します。すでにある場合は、mcpServers セクションを慎重に統合してください。

   • 次の設定を追加します。

     {
       "mcpServers": {
         "jobnimbus-local-server": {
           "description": "JobNimbus MCP Server (requires API key)",
           "command": "npx",
           "args": ["jobnimbus-mcp-server"],
           "env": {
             "JOBNIMBUS_API_KEY": "your_api_key_here"
           }
         }
       }
     }
     

   • 重要： ファイル内の "your_api_key_here" を、実際の JobNimbus API キーに置き換えてください。

3. Claude アプリを再起動する：

   • Claude デスクトップアプリケーションを完全に終了してから再起動します。

4. 確認する：

   • Claude から、サーバーが提供する JobNimbus のツールを検出して使用できるようになります。

仕組み（両方のアシスタントに共通）：

• 設定により、アシスタントは npx を使って jobnimbus-mcp-server を実行します。
• サーバーパッケージがまだキャッシュされていない場合、npx は npm から最新バージョンを自動的にダウンロードします。
• アシスタントは、env セクションの API キーをサーバープロセスに渡します。

手動での実行（上級者向け／その他のクライアント）

デバッグのため、または stdio に対応する他の MCP クライアントで使うためにサーバーを手動で実行する必要がある場合は、次の手順に従ってください。

1. API キーの環境変数を設定します。

   export JOBNIMBUS_API_KEY=your_actual_api_key_here
   

2. サーバーを実行します。

   npx jobnimbus-mcp-server
   

   サーバーは stdin/stdout を介した MCP 通信を待ち受けます。

実装済みのツール

このサーバーは、JobNimbus API エンドポイントに対応する MCP ツールを実装しています。

連絡先

• jobnimbus_list_contacts：任意のフィルターを指定して連絡先の一覧を取得します
• jobnimbus_get_contact：ID を指定して特定の連絡先を取得します
• jobnimbus_create_contact：新しい連絡先を作成します
• jobnimbus_update_contact：既存の連絡先を更新します

ジョブ

• jobnimbus_list_jobs：任意のフィルターを指定してジョブの一覧を取得します
• jobnimbus_get_job：ID を指定して特定のジョブを取得します
• jobnimbus_create_job：新しいジョブを作成します
• jobnimbus_update_job：既存のジョブを更新します

タスク

• jobnimbus_list_tasks：任意のフィルターを指定してタスクの一覧を取得します
• jobnimbus_get_task：ID を指定して特定のタスクを取得します
• jobnimbus_create_task：新しいタスクを作成します
• jobnimbus_update_task：既存のタスクを更新します

製品

• jobnimbus_list_products：任意のフィルターを指定して製品の一覧を取得します
• jobnimbus_get_product：ID を指定して特定の製品を取得します
• jobnimbus_create_product：新しい製品を作成します
• jobnimbus_update_product：既存の製品を更新します

ワークフロー

• jobnimbus_get_all_workflows：すべてのワークフローとそのステータスを取得します
• jobnimbus_create_workflow：新しいワークフローを作成します
• jobnimbus_create_workflow_status：新しいワークフローステータスを作成します

請求書

• jobnimbus_list_invoices：任意のフィルターを指定して請求書の一覧を取得します
• jobnimbus_get_invoice：ID を指定して特定の請求書を取得します
• jobnimbus_create_invoice：新しい請求書を作成します
• jobnimbus_update_invoice：既存の請求書を更新します
• jobnimbus_send_invoice：請求書をメールで送信します
• jobnimbus_record_invoice_payment：請求書に対する支払いを記録します

開発

サーバーに貢献する場合や変更する場合は、次の手順に従ってください。

1. リポジトリをクローンします：git clone <repository_url>
2. 依存関係をインストールします：cd jobnimbus-mcp-server && npm install
3. src/ ディレクトリ内で変更を加えます。
4. ビルドします：npm run build
5. ローカルでテストします（.env ファイルまたはエクスポート済みの API キーが必要です）：
   • 直接実行：npm start
   • 自動リロードで実行：npm run dev
   • グローバルテスト用にリンクします：npm link（完了したら npm unlink -g jobnimbus-mcp-server を実行してください）

ライセンス

MIT