kipris_search_patents
Search Korean patents by applicant name using the KIPRIS API. Filter results by status and retrieve detailed patent information in markdown or JSON format.
Instructions
출원인명으로 한국 특허를 검색합니다.
Args:
applicant_name: 출원인명 (필수, 예: '삼성전자', '카카오뱅크')
page: 페이지 번호 (기본값: 1)
page_size: 페이지당 결과 수 (기본값: 20, 최대: 100)
status: 상태 필터 ('A': 공개, 'R': 등록, 'J': 거절, None: 전체)
response_format: 응답 형식 ('markdown' 또는 'json')Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| applicant_name | Yes | ||
| page | No | ||
| page_size | No | ||
| status | No | ||
| response_format | No | markdown |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/korean_patent_mcp/server.py:165-205 (handler)MCP tool handler implementation including registration via @mcp.tool decorator, input schema definition through type hints and docstring, client initialization, API call, error handling, and response formatting.
@mcp.tool(name="kipris_search_patents") async def kipris_search_patents( applicant_name: str, page: int = 1, page_size: int = 20, status: Optional[str] = None, response_format: str = "markdown" ) -> str: """출원인명으로 한국 특허를 검색합니다. Args: applicant_name: 출원인명 (필수, 예: '삼성전자', '카카오뱅크') page: 페이지 번호 (기본값: 1) page_size: 페이지당 결과 수 (기본값: 20, 최대: 100) status: 상태 필터 ('A': 공개, 'R': 등록, 'J': 거절, None: 전체) response_format: 응답 형식 ('markdown' 또는 'json') """ # Get API key from session config or environment api_key = get_config_value("kiprisApiKey") or os.getenv("KIPRIS_API_KEY", "") if api_key: init_client_with_key(api_key) client = get_kipris_client() if client is None: error = get_init_error() or "API 클라이언트 초기화 실패. KIPRIS_API_KEY를 설정해주세요." return f"❌ 오류: {error}" try: result = await client.search_patents_by_applicant( applicant_name=applicant_name, page=page, page_size=min(page_size, 100), status=status or "" ) if response_format == "json": return json.dumps(result, ensure_ascii=False, indent=2) return format_search_result_markdown(result) except Exception as e: return f"❌ 검색 오류: {str(e)}" - Core helper method in KiprisAPIClient that performs the actual KIPRIS API search request, XML parsing, data extraction, and structuring of patent search results.
async def search_patents_by_applicant( self, applicant_name: str, page: int = 1, page_size: int = 20, status: str = "" ) -> Dict[str, Any]: """ 출원인명으로 특허 검색 Args: applicant_name: 출원인명 (예: "삼성전자", "충북대학교 산학협력단") page: 페이지 번호 (1부터 시작) page_size: 페이지당 결과 수 (최대 500) status: 상태 필터 (A: 공개, R: 등록, J: 거절, 빈값: 전체) Returns: 검색 결과 딕셔너리 """ params = { "applicant": applicant_name, "docsStart": str(page), "docsCount": str(min(page_size, 500)), "patent": "true", "utility": "false", "lastvalue": status } root = await self._make_request( self.ENDPOINTS["applicant_search"], params ) if root is None: return {"patents": [], "total_count": 0, "page": page} # 전체 건수 total_elem = root.find(".//TotalSearchCount") total_count = int(total_elem.text) if (total_elem is not None and total_elem.text) else 0 # 특허 정보 추출 patents = [] for item in root.findall(".//PatentUtilityInfo"): patent = self._parse_patent_info(item) patents.append(patent) return { "patents": patents, "total_count": total_count, "page": page, "page_size": len(patents), "has_more": (page * page_size) < total_count, "next_page": page + 1 if (page * page_size) < total_count else None } - Helper function to format the raw search results into a readable Markdown response.
def format_search_result_markdown(result: dict) -> str: lines = [] lines.append("## 검색 결과") lines.append("") lines.append(f"총 **{result['total_count']:,}**건 중 {len(result['patents'])}건 표시 (페이지 {result['page']})") lines.append("") if not result['patents']: lines.append("검색 결과가 없습니다.") return "\n".join(lines) for i, patent in enumerate(result['patents'], 1): lines.append("---") lines.append(f"**[{i}]** {patent.get('title', '제목 없음')}") lines.append(f"- 출원번호: `{patent.get('application_number', '-')}`") lines.append(f"- 출원인: {patent.get('applicant', '-')}") lines.append(f"- 상태: {patent.get('registration_status', '-')}") lines.append("") if result.get('has_more'): lines.append("---") lines.append(f"📄 다음 페이지: `page={result['next_page']}`") return "\n".join(lines) - Global singleton helper to lazily initialize and retrieve the KiprisAPIClient instance.
def get_kipris_client() -> Optional[KiprisAPIClient]: """KIPRIS API 클라이언트 가져오기""" global _kipris_client, _init_error if _kipris_client is None and _init_error is None: try: config = KiprisConfig.from_env() _kipris_client = KiprisAPIClient(config) except ValueError as e: _init_error = str(e) return _kipris_client