BuyICT MCP Server

Instructions

Implementation Reference

• src/servicenow-client.ts:119-155 (handler)

  The core handler function for the search_opportunities tool, which fetches the opportunities page from ServiceNow and extracts the relevant widget data containing opportunities.
  async searchOpportunities( params: OpportunitySearchParams ): Promise<OpportunitySearchResult> { // TODO: Implement actual API call once we discover the correct endpoint // For now, this is a placeholder that returns the structure console.warn( 'searchOpportunities is not fully implemented yet. ' + 'Need to discover the correct API endpoint for fetching opportunity data.' ); // Try fetching the page to get widget data const pageData = await this.fetchOpportunitiesPage(); // Extract widget data const opportunitiesWidget = this.findWidget(pageData, 'Opportunities V2'); if (opportunitiesWidget?.data) { const widgetData = opportunitiesWidget.data; return { items: widgetData.pageItems || [], total_count: widgetData.totalItems || 0, page: params.page || 1, page_size: params.page_size || 15, total_pages: Math.ceil((widgetData.totalItems || 0) / (params.page_size || 15)) }; } return { items: [], total_count: 0, page: 1, page_size: 15, total_pages: 0 }; }
• src/index.ts:56-82 (schema)

  Input schema defining the parameters for the search_opportunities tool: keyword, marketplace, page_size, and page.
  inputSchema: { type: 'object', properties: { keyword: { type: 'string', description: 'Search term to filter opportunities' }, marketplace: { type: 'string', description: 'Filter by marketplace code (e.g., PCS, SMP, CMP, LH, TMP, DC, HMP)', enum: config.marketplaces.map(m => m.code) }, page_size: { type: 'number', description: 'Number of results per page (default: 15)', minimum: 1, maximum: 100, default: 15 }, page: { type: 'number', description: 'Page number (default: 1)', minimum: 1, default: 1 } } }
• src/index.ts:53-83 (registration)

  Tool object registration in the TOOLS array used for listing available tools via ListToolsRequest.
  { name: 'search_opportunities', description: 'Search for procurement opportunities on BuyICT with optional filters', inputSchema: { type: 'object', properties: { keyword: { type: 'string', description: 'Search term to filter opportunities' }, marketplace: { type: 'string', description: 'Filter by marketplace code (e.g., PCS, SMP, CMP, LH, TMP, DC, HMP)', enum: config.marketplaces.map(m => m.code) }, page_size: { type: 'number', description: 'Number of results per page (default: 15)', minimum: 1, maximum: 100, default: 15 }, page: { type: 'number', description: 'Page number (default: 1)', minimum: 1, default: 1 } } } },
• src/index.ts:138-150 (registration)

  Dispatch logic in the CallToolRequest handler that routes search_opportunities calls to the ServiceNowClient handler.
  case 'search_opportunities': { const params = args as OpportunitySearchParams; const result = await snClient.searchOpportunities(params); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; }
• src/servicenow-client.ts:186-199 (helper)

  Helper utility function used within searchOpportunities to locate the 'Opportunities V2' widget in the ServiceNow page response.
  private findWidget(pageData: ServiceNowPageResponse, widgetName: string) { for (const container of pageData.result.containers || []) { for (const row of container.rows || []) { for (const column of row.columns || []) { for (const widgetInstance of column.widgets || []) { if (widgetInstance.widget.name === widgetName) { return widgetInstance.widget; } } } } } return null; }