PatSnap MCP Server

Instructions

Implementation Reference

• src/index.ts:240-246 (handler)

  The handler function that executes the core logic for the 'get_top_authorities_of_origin' tool. It builds search parameters from the input args (with default lang='en'), and calls the shared PatSnap API helper for the 'priority-country' endpoint.

  async function getTopAuthoritiesOfOrigin(args: LangPatentArgs): Promise<ServerResult> {
    const params = buildCommonSearchParams(args);
    if (!args.lang) { // Add default lang if not provided
        params.append('lang', 'en');
    }
    return callPatsnapApi('priority-country', params, 'get top authorities of origin');
  }

• src/index.ts:318-324 (schema)

  The input schema specific to language-enabled tools like get_top_authorities_of_origin, extending the base schema with an optional 'lang' property. Referenced in the tool's ListTools response.

  const langPatentInputSchema = {
      ...basePatentInputSchema,
      properties: {
          ...basePatentInputSchema.properties,
          lang: { type: 'string', description: 'Language setting. Default is "en" (English). Choose "cn" (Chinese) or "en".' }
      }
  };

• src/index.ts:357-360 (registration)

  Registration of the tool in the ListToolsRequestHandler, defining its name, description, and inputSchema for MCP clients to discover and validate inputs.

    name: 'get_top_authorities_of_origin',
    description: 'Returns the top authorities (priority countries) of origin for patents matching the criteria. Analyze main sources of priority filings. Either keywords or IPC classification must be specified.',
    inputSchema: langPatentInputSchema
  },

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

  Maps the tool name to its handler implementation in the toolImplementations dictionary, used by the CallToolRequestHandler for dispatching.

  'get_top_authorities_of_origin': getTopAuthoritiesOfOrigin,

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

  Core helper function that performs the actual API call to PatSnap's insights endpoint (used by all tools, including 'priority-country' for this tool), handles authentication, errors, and formats the response as MCP ServerResult.

  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)
              }
          ]
      };
  }