PatSnap MCP Server

Instructions

Implementation Reference

• src/index.ts:267-271 (handler)

  The handler function implementing the core logic for the 'get_simple_legal_status' tool. It constructs URL parameters from input args and delegates to the callPatsnapApi helper to fetch data from PatSnap's 'simple-legal-status' endpoint.
  async function getSimpleLegalStatus(args: BasePatentArgs): Promise<ServerResult> { const params = buildCommonSearchParams(args); // No 'lang' parameter for this endpoint return callPatsnapApi('simple-legal-status', params, 'get simple legal status'); }
• src/index.ts:303-316 (schema)

  Type and input schema definition (BasePatentArgs type at line 213 and basePatentInputSchema) used for validating inputs to the 'get_simple_legal_status' tool.
  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:372-375 (registration)

  Registration of the tool in the ListTools response, including name, description, and reference to input schema.
  name: 'get_simple_legal_status', description: 'Provides a breakdown of the simple legal status (e.g., Active, Inactive, Pending) for patents in the technology field. Understand the proportion of patents currently in effect. Note: Search must contain either keywords or IPC. If both are provided, IPC is prioritized.', inputSchema: basePatentInputSchema },
• src/index.ts:401-401 (registration)

  Mapping of tool name to handler function in the toolImplementations object used by the CallToolRequest handler.
  'get_simple_legal_status': getSimpleLegalStatus,
• src/index.ts:146-210 (helper)

  Core helper function that performs the actual API call to PatSnap, handles authentication, errors, and formats the response. Used by all tools including get_simple_legal_status.
  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) } ] }; }