カスタム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 account
• TypeScriptの経験

Squidアプリの作成

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

Zendeskプロジェクトのセットアップ

スターターバックエンドのSquidを手に入れたので、これをカスタマイズしてZendeskに接続するMCPサーバを作成できます。

Zendeskと連携する方法はいくつかありますが、このチュートリアルではNode Zendesk API client を使用してZendesk APIを呼び出します。

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 client を使用してZendesk APIと連携するロジックが含まれます。基本的な関数として、AIエージェントがチケットにコメントを追加しステータスを更新できる 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: Your Zendesk API key

   さらに、正しい認証値を含む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', // 例: 'mycompany' (Zendesk URLが 'mycompany.zendesk.com'の場合)
     );
   }

これらの手順に従うことで、カスタム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. さらに、チケットへの返信とステータス更新ができるツールをもう1つ作成します:

   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エージェントを接続できます。

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

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

   squid deploy

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

3. 以下のコネクタ情報を入力します:

   • Connector ID: 任意の一意のID（例: zendesk-mcp。短く意味のあるIDが望ましい）
   • MCP URL: デプロイしたバックエンドから提供されたMCPエンドポイントURL。MCP URLを確認するには、コンソールの Backend タブに移動し、MCP Servers の下から探してください。

   次に、Authorization をオンにし、以下の詳細を入力します:

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

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

MCPコネクタを追加したので、これを利用する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 アビリティを選択します。すると、先ほど作成した zendesk-mcp コネクタが含まれるドロップダウンが表示されます。これを選択して Add Connector をクリックしてください。その後、エージェントがいつこのMCPサーバを呼び出すべきかについて、以下の指示を追加します:

   Use this MCP server when prompted to interact with Zendesk

これで、エージェントはZendesk MCPサーバを使用する準備が整いました！

エージェントのテスト

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

以下の詳細でチケットを作成してください - 
Title: 'Bug report'
Text: 'User reported login feature is not currently working'
User ID: (あなたのUser ID。Zendeskのプロフィールに移動してURLからIDの値をコピーすることで確認できます)

チケットID（前のステップで作成されたチケットのID）を更新し、以下の詳細で顧客に返信してください -
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 をご覧ください。