SAP Documentation MCP Server

Instructions

Implementation Reference

• src/lib/sapHelp.ts:44-145 (handler)

  Core handler function for sap_help_search tool. Queries SAP Help Portal's elasticsearch endpoint, processes JSON results into standardized SearchResponse format, implements caching via global.sapHelpSearchCache, and returns formatted results with instructions for sap_help_get.

  export async function searchSapHelp(query: string): Promise<SearchResponse> {
    try {
      const searchParams = {
        transtype: "standard,html,pdf,others",
        state: "PRODUCTION,TEST,DRAFT",
        product: "",
        version: "",
        q: query,
        to: "19", // Limit to 20 results (0-19)
        area: "content",
        advancedSearch: "0",
        excludeNotSearchable: "1",
        language: "en-US",
      };
  
      const searchUrl = `${BASE}/http.svc/elasticsearch?${toQuery(searchParams)}`;
      
      const response = await fetch(searchUrl, {
        headers: {
          Accept: "application/json",
          "User-Agent": "mcp-sap-docs/help-search",
          Referer: BASE,
        },
      });
  
      if (!response.ok) {
        throw new Error(`SAP Help search failed: ${response.status} ${response.statusText}`);
      }
  
      const data: SapHelpSearchResponse = await response.json();
      const results = data?.data?.results || [];
  
      if (!results.length) {
        return {
          results: [],
          error: `No SAP Help results found for "${query}"`
        };
      }
  
      // Store the search results for later retrieval
      const searchResults: SearchResult[] = results.map((hit, index) => ({
        library_id: `sap-help-${hit.loio}`,
        topic: '',
        id: `sap-help-${hit.loio}`,
        title: hit.title,
        url: ensureAbsoluteUrl(hit.url),
        snippet: `${hit.snippet || hit.title} — Product: ${hit.product || hit.productId || "Unknown"} (${hit.version || hit.versionId || "Latest"})`,
        score: 0,
        metadata: {
          source: "help",
          loio: hit.loio,
          product: hit.product || hit.productId,
          version: hit.version || hit.versionId,
          rank: index + 1
        },
        // Legacy fields for backward compatibility
        description: `${hit.snippet || hit.title} — Product: ${hit.product || hit.productId || "Unknown"} (${hit.version || hit.versionId || "Latest"})`,
        totalSnippets: 1,
        source: "help"
      }));
  
      // Store the full search results in a simple cache for retrieval
      // In a real implementation, you might want a more sophisticated cache
      if (!global.sapHelpSearchCache) {
        global.sapHelpSearchCache = new Map();
      }
      results.forEach(hit => {
        global.sapHelpSearchCache!.set(hit.loio, hit);
      });
  
      // Format response similar to other search functions
      const formattedResults = searchResults.slice(0, 20).map((result, i) => 
        `[${i}] **${result.title}**\n   ID: \`${result.id}\`\n   URL: ${result.url}\n   ${result.description}\n`
      ).join('\n');
  
      return {
        results: searchResults.length > 0 ? searchResults : [{
          library_id: "sap-help",
          topic: '',
          id: "search-results",
          title: `SAP Help Search Results for "${query}"`,
          url: '',
          snippet: `Found ${searchResults.length} results from SAP Help:\n\n${formattedResults}\n\nUse sap_help_get with the ID of any result to retrieve the full content.`,
          score: 0,
          metadata: {
            source: "help",
            totalSnippets: searchResults.length
          },
          // Legacy fields for backward compatibility
          description: `Found ${searchResults.length} results from SAP Help:\n\n${formattedResults}\n\nUse sap_help_get with the ID of any result to retrieve the full content.`,
          totalSnippets: searchResults.length,
          source: "help"
        }]
      };
  
    } catch (error: any) {
      return {
        results: [],
        error: `SAP Help search error: ${error.message}`
      };
    }
  }

• src/lib/BaseServerHandler.ts:260-294 (registration)

  MCP tool registration for sap_help_search, including name, detailed description with usage examples, and input schema validation.

            {
              name: "sap_help_search",
              description: `SEARCH SAP HELP PORTAL: sap_help_search(query="product + topic")
  
  FUNCTION NAME: sap_help_search (or mcp_sap-docs-remote_sap_help_search)
  
  SEARCHES: Official SAP Help Portal (help.sap.com)
  COVERS: Product guides, implementation guides, technical documentation
  
  TYPICAL WORKFLOW:
  1. sap_help_search(query="product name + configuration topic")
  2. sap_help_get(result_id="sap-help-12345abc")
  
  BEST PRACTICES:
  • Include product names: "S/4HANA", "BTP", "Fiori"
  • Add specific tasks: "configuration", "setup", "deployment"
  • Use official SAP terminology`,
              inputSchema: {
                type: "object",
                properties: {
                  query: {
                    type: "string",
                    description: "Search terms for SAP Help Portal. Include product names and specific topics.",
                    examples: [
                      "S/4HANA configuration",
                      "Fiori Launchpad setup", 
                      "BTP integration",
                      "ABAP development guide",
                      "SAP Analytics Cloud setup"
                    ]
                  }
                },
                required: ["query"]
              }
            },

• src/lib/BaseServerHandler.ts:605-647 (handler)

  MCP CallToolRequestSchema handler dispatch for sap_help_search: extracts query argument, calls searchSapHelp, transforms response to ChatGPT-compatible JSON format, handles errors and logging.

  if (name === "sap_help_search") {
    const { query } = args as { query: string };
    
    // Enhanced logging with timing
    const timing = logger.logToolStart(name, query, clientMetadata);
    
    try {
      const res: SearchResponse = await searchSapHelp(query);
      
      if (!res.results.length) {
        logger.logToolSuccess(name, timing.requestId, timing.startTime, 0);
        return createErrorResponse(
          res.error || `No SAP Help results found for "${query}". Try different keywords or check your connection.`,
          timing.requestId
        );
      }
      
      // Transform SAP Help search results to ChatGPT-compatible format
      const helpResults: SearchResult[] = res.results.map((r, index) => ({
        // ChatGPT-required format: id, title, url
        id: r.id || `sap-help-${index}`,
        title: r.title || 'SAP Help Document',
        url: r.url || `#${r.id}`,
        // Additional fields for enhanced functionality
        snippet: r.description ? r.description.substring(0, 200) + '...' : '',
        metadata: {
          source: 'sap-help',
          totalSnippets: r.totalSnippets,
          rank: index + 1
        }
      }));
      
      logger.logToolSuccess(name, timing.requestId, timing.startTime, res.results.length);
      
      return createSearchResponse(helpResults);
    } catch (error) {
      logger.logToolError(name, timing.requestId, timing.startTime, error);
      return createErrorResponse(
        `SAP Help search service temporarily unavailable. Please try again later.`,
        timing.requestId
      );
    }
  }

• src/lib/types.ts:25-64 (schema)

  TypeScript interfaces defining input/output structures for SAP Help search: SapHelpSearchResult, SapHelpSearchResponse, and related metadata/page content responses used by the handler.

  // SAP Help specific types
  export interface SapHelpSearchResult {
    loio: string;
    title: string;
    url: string;
    productId?: string;
    product?: string;
    version?: string;
    versionId?: string;
    language?: string;
    snippet?: string;
  }
  
  export interface SapHelpSearchResponse {
    data?: {
      results?: SapHelpSearchResult[];
    };
  }
  
  export interface SapHelpMetadataResponse {
    data?: {
      deliverable?: {
        id: string;
        buildNo: string;
      };
      filePath?: string;
    };
  }
  
  export interface SapHelpPageContentResponse {
    data?: {
      currentPage?: {
        t?: string; // title
      };
      deliverable?: {
        title?: string;
      };
      body?: string;
    };
  } 

• src/lib/sapHelp.ts:13-18 (helper)

  Utility function toQuery converts search parameters to URL query string, used in SAP Help elasticsearch requests.

  function toQuery(params: Record<string, any>): string {
    return Object.entries(params)
      .filter(([, v]) => v !== undefined && v !== null && v !== "")
      .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
      .join("&");
  }