get_patent_trends

Instructions

Implementation Reference

• src/index.ts:219-222 (handler)

  The handler function that implements the get_patent_trends tool by constructing query parameters from input args and delegating to the shared PatSnap API caller for the 'patent-trends' endpoint.

  async function getPatentTrends(args: BasePatentArgs): Promise<ServerResult> {
    const params = buildCommonSearchParams(args);
    return callPatsnapApi('patent-trends', params, 'get patent trends');
  }

• src/index.ts:303-316 (schema)

  TypeScript object schema defining the input parameters for the get_patent_trends tool (and others), including optional fields for keywords, IPC, date ranges, and authority.

  const basePatentInputSchema = {
      type: 'object' as const, // Use 'as const' for stricter type checking
      properties: {
          keywords: { type: 'string', description: 'Keywords to search within patent title and abstract/summary. Supports AND, OR, NOT logic. Example: "mobile phone AND (screen OR battery)"' },
          ipc: { type: 'string', description: 'Patent IPC classification code. Used to specify a particular technology field.' },
          apply_start_time: { type: 'string', description: 'Patent application start year (yyyy format). Filters by application filing date.' },
          apply_end_time: { type: 'string', description: 'Patent application end year (yyyy format). Filters by application filing date.' },
          public_start_time: { type: 'string', description: 'Patent publication start year (yyyy format). Filters by publication date.' },
          public_end_time: { type: 'string', description: 'Patent publication end year (yyyy format). Filters by publication date.' },
          authority: { type: 'string', description: 'Patent authority code (e.g., CN, US, EP, JP). Filters by patent office. Use OR for multiple, e.g., "US OR EP".' }
      },
      // Add a note about requiring keywords or IPC for most tools
      description: "Requires either 'keywords' or 'ipc' to be specified for a meaningful search. If both are provided, IPC is prioritized by the API."
  };

• src/index.ts:336-340 (registration)

  Registers the get_patent_trends tool in the ListToolsRequestHandler response, specifying its name, description, and input schema.

  {
    name: 'get_patent_trends',
    description: 'Analyze annual application and issued trends for patents. Understand the trends of patents related to specific technology fields or keywords. Either keywords or IPC classification must be specified.',
    inputSchema: basePatentInputSchema
  },

• src/index.ts:394-394 (registration)

  Registers the tool name to handler mapping in the dispatch object used by CallToolRequestHandler.

  'get_patent_trends': getPatentTrends,

• src/index.ts:146-210 (helper)

  Core helper function that performs authenticated GET requests to PatSnap API endpoints, handles errors, token management, and formats responses as ServerResult. Called by the getPatentTrends handler.

  async function callPatsnapApi(endpoint: string, params: URLSearchParams, errorContext: string): Promise<ServerResult> {
      const token = await getAccessToken(); // Will use cached token if available and valid
      const url = `${PATSNAP_API_BASE_URL}/insights/${endpoint}?${params.toString()}`;
      console.log(`Calling PatSnap API: ${url}`); // Log the request URL (consider using a proper logger)
  
      let response: Response;
      try {
          response = await fetch(url, {
              method: 'GET',
              headers: {
                  // 'Content-Type': 'application/json', // Typically not needed for GET
                  'Authorization': `Bearer ${token}`
              }
              // Consider adding a timeout
              // signal: AbortSignal.timeout(15000) // e.g., 15 seconds timeout
          });
      } catch (error) {
          console.error(`Network error calling PatSnap API endpoint ${endpoint}:`, error);
          throw new McpError(503, `Network error connecting to PatSnap API (${endpoint}): ${error instanceof Error ? error.message : String(error)}`);
      }
  
  
      if (!response.ok) {
          let errorText = `Status code ${response.status}`;
          try {
              errorText = await response.text();
          } catch (e) {
              console.error("Failed to read error response body:", e);
          }
          console.error(`API Error (${response.status}) for ${endpoint}: ${errorText}`); // Log error details
          // Invalidate cache on auth errors (401 Unauthorized, 403 Forbidden)
          if (response.status === 401 || response.status === 403) {
               cachedToken = null;
               console.log('Authentication error detected, clearing token cache.');
          }
          // Map common PatSnap error codes to potentially more user-friendly messages if desired
          // Example: if (errorText.includes("67200002")) { throw new McpError(429, "PatSnap API quota exceeded."); }
          throw new McpError(response.status, `Failed to ${errorContext}: ${errorText}`);
      }
  
      let json: PatsnapApiResponse; // Use interface type
      try {
          json = await response.json() as PatsnapApiResponse; // Type assertion
      } catch (error) {
          console.error(`Error parsing JSON response from ${endpoint}:`, error);
          throw new McpError(500, `Failed to parse JSON response from PatSnap API (${endpoint}): ${error instanceof Error ? error.message : String(error)}`);
      }
  
      // Basic check for PatSnap's own error structure within a 200 OK response
      if (json && typeof json.status === 'boolean' && json.status === false && json.error_code !== 0) {
          console.error(`PatSnap API returned error within successful response for ${endpoint}: Code ${json.error_code}, Msg: ${json.error_msg}`);
          // You might want to map these internal errors to McpError as well
          throw new McpError(400, `PatSnap API Error (${json.error_code || 'N/A'}): ${json.error_msg || 'Unknown error'}`);
      }
  
      return {
          content: [
              {
                  type: 'text',
                  // Return the raw JSON response as text, formatted for readability
                  text: JSON.stringify(json, null, 2)
              }
          ]
      };
  }