get_top_authorities_of_origin
Identify leading countries for patent priority filings by analyzing patent data based on keywords or IPC classification, with options to filter by date and authority.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| keywords | No | Keywords to search within patent title and abstract/summary. Supports AND, OR, NOT logic. Example: "mobile phone AND (screen OR battery)" | |
| ipc | No | Patent IPC classification code. Used to specify a particular technology field. | |
| apply_start_time | No | Patent application start year (yyyy format). Filters by application filing date. | |
| apply_end_time | No | Patent application end year (yyyy format). Filters by application filing date. | |
| public_start_time | No | Patent publication start year (yyyy format). Filters by publication date. | |
| public_end_time | No | Patent publication end year (yyyy format). Filters by publication date. | |
| authority | No | Patent authority code (e.g., CN, US, EP, JP). Filters by patent office. Use OR for multiple, e.g., "US OR EP". | |
| lang | No | Language setting. Default is "en" (English). Choose "cn" (Chinese) or "en". |
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) } ] }; }