KIPRIS Trademark MCP Server (kipris-trademark-mcp)
1. 개요
이 MCP(Model Context Protocol) 서버는 KIPRIS Open API의 상표 관련 기능을 활용하여, AI 에이전트가 상표 정보를 검색하고 상품 분류 코드를 조회하는 등 상표 분석에 필요한 핵심 도구들을 제공합니다.
현재 릴리스 버전: v0.1.0 (PyPI 최초 배포)
주요 특징:
KIPRIS API 연동:
kipris-api-wrapper라이브러리를 사용하여 KIPRIS Open API와 안정적으로 통신합니다.표준화된 도구: AI 에이전트가 쉽게 사용할 수 있도록 표준화된 MCP 도구 인터페이스를 제공합니다.
비동기 처리:
fastmcp프레임워크와asyncio를 기반으로 비동기적으로 작동하여 효율적인 처리가 가능합니다.Stdio 통신: 표준 입출력(Stdio)을 통해 MCP 클라이언트와 통신합니다.
2. 설치
PyPI에서 uv를 사용하여 설치합니다.
uv pip install kipris-trademark-mcp이 패키지는 kipris-api-wrapper (PyPI) 및 fastmcp (PyPI) 등의 의존성을 자동으로 함께 설치합니다.
개발 환경 설치
프로젝트를 클론한 후, mpcs/kipris_trademark_mcp 디렉토리에서 다음 명령을 실행하여 편집 가능한 모드로 설치할 수 있습니다. (개발 및 테스트용)
# 가상 환경 생성 및 활성화 (Python 3.12 이상 권장)
uv venv .venv
source .venv/bin/activate
# 의존성 설치 (개발 의존성 포함)
uv pip install -e ".[dev]" 3. 설정 및 AI 에이전트 연동
3.1. KIPRIS API 키 설정 (필수)
서버를 실행하거나 AI 에이전트에서 사용하기 전에 KIPRIS Open API 키를 KIPRIS_API_KEY 라는 이름의 환경 변수로 설정해야 합니다.
서버 내부의 mcp_server/auth.py에 정의된 api_key_provider 함수가 이 환경 변수를 읽어 kipris-api-wrapper 라이브러리에 전달합니다.
# 예시: KIPRIS_API_KEY 환경 변수 설정
export KIPRIS_API_KEY="YOUR_KIPRIS_API_KEY_HERE"Cloud Run과 같은 배포 환경에서는 서비스 환경 변수로 KIPRIS_API_KEY를 설정하거나, Secret Manager에 저장된 값을 참조하여 주입하는 것을 권장합니다.
3.2. AI 에이전트 연동 (MCP 클라이언트 설정)
AI 에이전트(예: Cursor, Roo)에서 이 MCP 서버를 사용하려면 클라이언트의 MCP 설정 파일에 서버 정보를 등록해야 합니다. PyPI에 배포된 패키지를 uvx로 실행하는 경우, 다음과 같이 설정합니다.
// 예시: AI 에이전트 MCP 설정 파일
{
"mcpServers": {
"kipris_trademark_mcp": { // 또는 원하는 서버 이름
"command": "uvx",
"args": [
"--from", "kipris-trademark-mcp==0.1.0", // PyPI 패키지명 및 버전
"kipris-mcp-server" // pyproject.toml의 [project.scripts]에 정의된 이름
],
"env": {
"KIPRIS_API_KEY": "YOUR_KIPRIS_API_KEY_HERE" // 실제 KIPRIS API 키로 대체
},
"alwaysAllow": [ // 필요에 따라 도구별 alwaysAllow 설정
"search_by_trademark_name",
"search_by_application_number",
"find_codes_by_product_name",
"search_by_registration_number"
]
// "disabled": false // 필요시 활성화/비활성화
}
}
}필수 환경 변수:
KIPRIS_API_KEY: AI 에이전트 MCP 설정의env블록 또는uvx실행 환경에 이 환경 변수가 올바르게 설정되어 있어야 KIPRIS API를 사용하는 도구들이 정상 작동합니다.
3.3. 통합 테스트 설정 (개발자용)
통합 테스트(tests/integration) 실행 시에는 mpcs/kipris_trademark_mcp/tests/integration/.env 파일에 KIPRIS_TEST_API_KEY 라는 이름으로 테스트용 API 키를 설정해야 합니다.
# mpcs/kipris_trademark_mcp/tests/integration/.env (통합 테스트용)
KIPRIS_TEST_API_KEY="YOUR_KIPRIS_API_KEY_FOR_TESTING"tests/integration/conftest.py의 integration_api_key_provider fixture가 이 파일을 로드하여 테스트에 사용합니다. 이 .env 파일은 Git 버전 관리에서 제외해야 합니다.
4. 직접 실행 (uvx 사용)
터미널에서 uvx를 사용하여 MCP 서버를 직접 실행하고 테스트할 수 있습니다.
# KIPRIS_API_KEY 환경 변수 설정
export KIPRIS_API_KEY="YOUR_KIPRIS_API_KEY_HERE"
# uvx로 PyPI에서 패키지를 가져와 실행
uvx --from kipris-trademark-mcp==0.1.0 kipris-mcp-server서버는 Stdio 모드로 실행됩니다.
로컬 개발 환경에서 소스 코드를 직접 실행하려면 다음을 참고하십시오:
# 가상 환경 활성화
source .venv/bin/activate
# KIPRIS_API_KEY 환경 변수 설정 (필요시)
# export KIPRIS_API_KEY="YOUR_KIPRIS_API_KEY_HERE"
# uv를 사용하여 등록된 스크립트 실행 (편집 가능한 모드로 설치된 경우)
uv run kipris-mcp-server5. 제공 도구
이 서버는 다음과 같은 도구를 제공합니다.
5.1. search_by_trademark_name
설명: 상표명 및 선택적 필터(분류 코드, 유사군 코드, 출원인명 등)를 사용하여 KIPRIS에서 상표 정보를 검색합니다.
입력 (
arguments):trademark_name(str, 필수): 검색할 상표명.classification_codes(list[str], 선택): NICE 분류 코드 리스트.similarity_codes(list[str], 선택): 유사군 코드 리스트.applicant_name(str, 선택): 출원인명.rows(int, 선택, 기본값 100): 페이지당 결과 수.page_no(int, 선택, 기본값 1): 페이지 번호.
출력:
total_count(int): 총 검색 결과 수.trademarks(list[dict]): 검색된 상표 목록.
5.2. search_by_application_number
설명: 출원번호를 사용하여 특정 상표의 상세 정보를 검색합니다.
입력 (
arguments):application_number(str, 필수): 검색할 출원번호.
출력:
trademark(dict | None): 검색된 상표 정보 또는None.
5.3. find_codes_by_product_name
설명: 상품 또는 서비스 명칭 키워드를 사용하여 관련된 NICE 분류 코드 및 유사군 코드 정보를 검색합니다.
입력 (
arguments):product_keyword(str, 필수): 검색할 상품/서비스 키워드.rows(int, 선택, 기본값 100): 페이지당 결과 수.page_no(int, 선택, 기본값 1): 페이지 번호.
출력:
total_count(int): 총 검색 결과 수.product_codes(list[dict]): 검색된 상품 코드 정보 목록.
5.4. search_by_registration_number
설명: 등록번호를 사용하여 특정 상표의 상세 정보를 검색합니다.
입력 (
arguments):registration_number(str, 필수): 검색할 등록번호.
출력:
trademark(dict | None): 검색된 상표 정보 또는None.
6. 사용 예시 (Python fastmcp 클라이언트)
다음은 fastmcp 클라이언트를 사용하여 각 도구를 호출하는 예시입니다.
import asyncio
from fastmcp import Client, MCPError
async def run_mcp_client():
# Stdio를 통해 실행 중인 서버에 연결
# 실제 사용 시에는 서버 실행 명령어와 프로세스 관리 필요
# KIPRIS_API_KEY 환경 변수가 설정되어 있어야 함
server_process_cmd = ["uvx", "--from", "kipris-trademark-mcp==0.1.0", "kipris-mcp-server"]
try:
async with Client.stdio(server_process_cmd) as client:
print(f"Connected to server: {client.server_name}")
# 예시 1: 상표명으로 검색
try:
print("\n--- Searching by trademark name 'ExampleBrand' ---")
result_name = await client.use_tool(
"search_by_trademark_name",
{"trademark_name": "ExampleBrand", "rows": 5}
)
print(f"Found {result_name.get('total_count', 0)} trademarks.")
for tm in result_name.get('trademarks', [])[:2]: # 처음 2개만 출력
print(f" - App No: {tm.get('application_number')}, Name: {tm.get('trademark_name')}")
except MCPError as e:
print(f"Error using search_by_trademark_name: {e}")
# (다른 도구 호출 예시 생략 - 필요시 추가)
except Exception as e:
print(f"Failed to connect or communicate with MCP server: {e}")
if __name__ == "__main__":
# 실제 실행 전 KIPRIS_API_KEY 환경 변수 설정 필요
import os
if not os.environ.get("KIPRIS_API_KEY"):
print("Error: KIPRIS_API_KEY environment variable is not set.")
print("Please set it before running the example: export KIPRIS_API_KEY='your_key'")
else:
asyncio.run(run_mcp_client())7. 상세 명세, 개발 계획 및 배포
배포 및 사용 가이드 (PyPI 배포 내용으로 업데이트 예정)
8. 기여
(기여 방법에 대한 안내 추가 예정)
9. 라이선스
MIT License (LICENSE 파일 참조)