カスタム Zendesk MCP サーバーの作成

MCP サーバーを作成し、Zendesk インスタンスと連携する Squid エージェントに接続する

作成するもの

• Zendesk と連携するカスタム Squid MCP サーバーに接続するシンプルなエージェント
• チケットの作成、チケットのステータス更新、チケットへのコメントの追加

このチュートリアルでは以下の機能を使用します:

AI Abilities	Internal Connectors
Model Context Protocol ability	Model Context Protocol server

学習内容

• Squid の backend SDK を使用して MCP サーバーを作成し、エージェントに接続する方法

必要なもの

• The Squid CLI
• Squid Console のアカウント
• Zendesk アカウント
• TypeScript の基本的な知識

Squid アプリの作成

1. Squid Console に移動し、Zendesk MCP Tutorial という名前の新しい Squid アプリケーションを作成します。
2. アプリケーションの概要ページで、Backend project セクションまでスクロールします。Initialize Backend をクリックし、初期化コマンドをコピーします。
3. プロジェクトを作成したいディレクトリで、ターミナルにコピーした初期化コマンドを実行します。

Zendesk プロジェクトの設定

スタート用の Squid backend を作成したので、これをカスタマイズして Zendesk と接続する MCP サーバーを作成します。

Zendesk と連携する方法は複数ありますが、このチュートリアルでは Zendesk API を呼び出すために Node Zendesk API client を利用します。

1. お好みの IDE でプロジェクトを開きます。クライアントをインストールするには、ターミナルで以下のコマンドを実行してください:

   npm install node-zendesk

   また、次の設定を含むように tsconfig.json ファイルを更新する必要があります:

   {
     "compilerOptions": {
       "module": "NodeNext",
       "moduleResolution": "nodenext"
     }
   }

2. src/service/example-service.ts の名前を zendesk-mcp.service.ts に変更し、クラス名を ZendeskMcpService に更新します。

3. src/service/index.ts ファイルを更新し、新しいサービスをエクスポートします:

   export * from './zendesk-mcp.service.ts';

4. src ディレクトリに providers という新しいディレクトリを作成します。providers ディレクトリ内に zendesk.provider.ts という新しいファイルを作成します。このファイルには、Node Zendesk クライアントを使用して Zendesk API と連携するロジックが含まれます。基本的な関数として、チケットへのコメント追加およびステータス更新を行う replyToTicket と、チケットを作成するための createTicket が含まれています。src/providers/zendesk.provider.ts に以下のコードを追加してください:

   import { createClient, ZendeskClient } from 'node-zendesk';
   import {
     CreateOrUpdateTicket,
     Status,
     Ticket,
     TicketComment,
   } from 'node-zendesk/clients/core/tickets';
   
   export class ZendeskProvider {
     private readonly zendeskClient: ZendeskClient;
   
     constructor(username: string, token: string, subdomain: string) {
       this.zendeskClient = createClient({ username, token, subdomain });
     }
   
     async replyToTicket(
       ticketId: number,
       replyText: string,
       isReplyToCustomer: boolean,
       reassignToEmail: string | undefined,
       status: Status | undefined,
     ): Promise<TicketComment | undefined> {
       const comment: Partial<TicketComment> = {
         html_body: replyText,
         public: isReplyToCustomer,
       };
   
       const response = await this.zendeskClient.tickets.update(ticketId, {
         ticket: { comment, status: status, assignee_email: reassignToEmail },
       });
   
       return response.result.comment;
     }
   
     async createTicket(
       subject: string,
       text: string,
       requesterId: number,
     ): Promise<Ticket | undefined> {
       const ticketData: CreateOrUpdateTicket = {
         ticket: {
           subject,
           description: text,
           requester_id: requesterId,
         },
       };
   
       const response = await this.zendeskClient.tickets.create(ticketData);
       return response.result;
     }
   }

   さらに、MCP サーバーのセキュリティを強化するため、@mcpAuthorizer デコレータを使用してアクセスを認可されたユーザーのみに制限します。createTicket メソッドの下に、以下のコードを追加してください:

   import { mcpAuthorizer } from '@squidcloud/backend';
   
   export class ZendeskProvider {
     // existing code...
   
     @mcpAuthorizer()
     async authorizeMcp(request: McpAuthorizationRequest): Promise<boolean> {
       const authHeader = request.headers['authorization'];
       if (!authHeader) return false;
   
       const [scheme, token] = authHeader.split(' ');
       return scheme === 'Bearer' && token === 'some_secure_auth_value';
     }
   }

5. Zendesk API を使用するためには、Zendesk API キーを提供する必要があります。Zendesk API キーを作成するには、Zendesk documentation の手順に従ってください。その後、Squid Console の左サイドバーにある Secrets ページに移動します。Store New Secret をクリックし、以下の値を追加してください:

   • Secret key: ZENDESK_API_KEY
   • Value: ご自身の Zendesk API キー

   次に、正しい認証値を含む 2 つ目のシークレットを追加してください:

   • Secret key: MCP_AUTH_VALUE
   • Value: Bearer some_secure_auth_value（またはお好みの安全な値。ただし、上記の authorizeMcp メソッド内の値と一致させる必要があります）

6. base-zendesk.service.ts という新しいサービスファイルを作成します。このファイルには、必要な認証情報で初期化された基本の Zendesk プロバイダーが含まれます。src/service/base-zendesk.service.ts に、以下のコードをご自身の認証情報とともに追加してください:

   import { SquidService } from '@squidcloud/backend';
   import { ZendeskProvider } from '../providers/zendesk.provider';
   
   export class BaseZendeskService extends SquidService {
     protected readonly zendeskProvider = new ZendeskProvider(
       'YOUR_ZENDESK_EMAIL',
       this.secrets['ZENDESK_API_KEY'] as string,
       'YOUR_ZENDESK_SUBDOMAIN', // 例: Zendesk URL が 'mycompany.zendesk.com' の場合、'mycompany'
     );
   }

これらの手順に従うことで、カスタム Zendesk MCP サーバーを作成するための全ての必要なコンポーネントが揃います。

Squid + Zendesk MCP サーバーの作成

1. zendesk-mcp.service.ts ファイルを開き、以下のコードを追加して、チケットの作成や返信に対応するツールを備えた MCP サーバーを作成します。@mcpServer デコレータを使用することで、AI エージェントが利用できる MCP サーバーを作成できます。

   import { mcpServer, mcpTool } from '@squidcloud/backend';
   import { BaseZendeskService } from './base-zendesk.service';
   
   @mcpServer({
     name: 'zendesk-mcp',
     id: 'zendesk-mcp',
     description: 'This MCP knows how to communicate with Zendesk',
     version: '1.0.0'
   })
   export class ZendeskMcpService extends BaseZendeskService {
     
   }

2. @mcpTool デコレータは、AI エージェントが実行できる具体的なアクションを定義します。最初に追加するツールは Zendesk チケットの作成を行います。ZendeskMcpService クラス内に、以下のコードを追加してください:

   export class ZendeskMcpService extends BaseZendeskService {
     @mcpTool({
       description: 'This tool creates a Zendesk ticket',
       inputSchema: {
         type: 'object',
         properties: {
           title: {
             type: 'string',
             description: 'The title of the ticket to create',
           },
           text: {
             type: 'string',
             description: 'The text of the ticket to create',
           },
           userId: {
             type: 'number',
             description: 'The user ID who is requesting to create the ticket',
           }
         },
         required: ['title', 'text', 'userId'],
       },
     })
     async createTicket({ title, text, userId }) {
       return await this.zendeskProvider.createTicket(title, text, userId);
     }
   }

3. チケットへの返信とステータス更新を行うツールをもう一つ作成します:

   export class ZendeskMcpService extends BaseZendeskService {
     @mcpTool({
       description: 'This tool replies to a Zendesk ticket',
       inputSchema: {
         type: 'object',
         properties: {
           ticketId: {
             type: 'number',
             description: 'The ID of the ticket to reply to',
           },
           replyText: {
             type: 'string',
             description: 'The text of the reply to the ticket',
           },
           isReplyToCustomer: {
             type: 'boolean',
             description: 'Whether the reply is public (to customer) or private (internal note)',
           },
           status: {
             type: 'string',
             enum: ['new', 'open', 'pending', 'hold', 'solved', 'closed'],
             description: 'The status to set the ticket to',
           },
         },
         required: ['ticketId', 'replyText', 'isReplyToCustomer'],
       },
     })
     async replyToTicket({ ticketId, replyText, isReplyToCustomer, status }) {
       try {
         await this.zendeskProvider.replyToTicket(ticketId, replyText, isReplyToCustomer, undefined, status);
         return { success: true };
       } catch (error) {
         throw new Error(error);
       }
     }
   }

AI エージェントと MCP サーバーの接続

カスタム Zendesk MCP サーバーを作成したので、これを AI エージェントに接続できます。

エージェントにサーバーを公開するため、backend をデプロイする必要があります。

1. まず、実行中のローカル backend をターミナルで CTRL + C を押して停止し、以下のコマンドを実行します:

   squid deploy

2. 次に、Squid Console の Connectors タブに移動し、Available Connectors をクリックします。MCP Connector を見つけ、Add Connector をクリックします。

3. 以下のコネクタの詳細を入力してください:

   • Connector ID: 任意のユニークな ID（例: zendesk-mcp など、簡潔で意味のあるもの）
   • MCP URL: デプロイされた backend によって提供される MCP エンドポイント URL。MCP URL を確認するには、Console の Backend タブに移動し、MCP Servers セクションの MCP URL を参照してください。

   続いて、Authorization をオンにし、以下の詳細を入力してください:

   • Authorization Header: Authorization
   • Authorization Value: 先ほど作成した MCP_AUTH_VALUE シークレットの値

4. Test Connection をクリックして、サーバーへの接続をテストします。接続に失敗した場合は、MCP URL の値を確認してください。接続に成功したら、Add Connector をクリックします。

MCP Connector を追加したので、次はこれを利用する AI エージェントを作成します。

1. Squid Console の Agent Studio タブに移動し、Create New Agent をクリックします。

2. 以下の詳細を入力してください:

   • Agent ID: エージェントの名前（例: Zendesk Agent）
   • Agent Description: エージェントの説明（例: An agent that can create and reply to Zendesk tickets）

   Create をクリックします。

3. エージェントの Overview タブで、Add Abilities をクリックし、MCP ability を選択します。すると、先ほど作成した zendesk-mcp Connector が表示されるドロップダウンが開きます。これを選択し、Add Connector をクリックします。その後、エージェントがいつ MCP サーバーにリクエストを送るべきか具体的な指示を提供できます。以下の指示を追加してください:

   Use this MCP server when prompted to interact with Zendesk

エージェントはこれで Zendesk MCP サーバーを利用できる状態になりました!

エージェントのテスト

エージェントをテストするには、Agent Studio の Test Agent タブに移動します。エージェントに対して、チケットの作成や返信をリクエストすることで対話が可能です。以下は使用例のプロンプトです:

Create a ticket with the following details - 
Title: 'Bug report'
Text: 'User reported login feature is not currently working'
User ID: (Your User ID. Can be found by navigating to your profile in Zendesk and copying the ID value from the URL)

Update ticket ID (the ID of the ticket created in the previous step) to reply to the customer with the following details -
Text: 'The login issue has been resolved. Please try again.'
Status: solved

次のステップ

カスタム Zendesk MCP サーバーを作成し、AI エージェントに接続できたこと、おめでとうございます！この基盤を拡張して、MCP サーバーにより多くのツールを追加したり、AI エージェントの機能を強化したりできます。

• Squid AI エージェントの詳細については、documentation をご覧ください。
• Squid のリアルタイムデータ機能については、Client SDK documentation をご覧ください。
• ご自身のデータソースとの統合方法については、database connectors documentation をご覧ください。