naver-api-hub-mcp

Naver Search Open API를 MCP 서버로 구현한 예제 + Claude Code Skill 기반의 가벼운 코드 컨벤션 체크 / PR 초안 자동화 워크플로우.

왜 만들었나

• 신규 API를 MCP로 감싸는 연습.

• Claude Code의 Skill을 활용해 "diff 안의 변경분만" 대상으로 하는 가벼운 자동화(네이밍 컨벤션 체크, PR 초안 작성)를 레포에 녹여보는 것.

Related MCP server: Naver Search MCP Server

구성

mcp_server/          # MCP 서버 (search_news / search_blog / search_img / search_webkr)
.claude/skills/
  naming-check/       # diff에 추가된 함수/변수명 네이밍 검사
  pr-draft/           # diff + naming-check 결과로 PR 본문 초안 작성
tests/
CLAUDE.md             # 컨벤션 및 워크플로우 규칙

실행

pip install -r requirements.txt
cp .env.example .env   # NAVER_CLIENT_ID / NAVER_CLIENT_SECRET 채우기 (없어도 mock으로 동작)
python3 -m mcp_server.server

Claude Code에서 MCP 서버로 등록하려면 claude mcp add 또는 프로젝트 .mcp.json에 다음과 같이 추가하세요:

{
  "mcpServers": {
    "naver-search": {
      "command": "python3",
      "args": ["-m", "mcp_server.server"],
      "cwd": "."
    }
  }
}

Claude Code Skills

.claude/skills/에 있는 두 skill을 소개합니다.

naming-check

description: 현재 Git diff에서 새로 추가된 함수/변수 이름이 저장소 네이밍 규칙(Python은 snake_case, JS/TS는 camelCase, 의미 없는 한 글자 이름과 비-ASCII 식별자 금지)을 지키는지 검사합니다. PR을 만들기 전이나, 네이밍·코드 컨벤션·변수명 검사를 요청받았을 때 사용합니다.

네이밍 규칙 검사

검사 범위는 일부러 좁게 잡았습니다. Git diff에서 새로 추가된 줄만, 그중에서도 함수·변수 선언만 봅니다. 전체 코드에 린터를 돌리는 게 아니라, 기존 코드는 건드리지 않고 이번에 바뀐 부분만 확인하는 용도입니다.

언제 쓰나

• PR 초안을 쓰거나 PR을 만들기 직전

• 네이밍 규칙·변수명·코드 컨벤션 검사를 요청받았을 때

실행 방법

python3 .claude/skills/naming-check/scripts/check_naming.py [git-diff-args]

• 인자 없이 실행하면 unstaged 변경 사항을 diff합니다.

• --cached를 주면 staged된 변경 사항을 diff합니다.

• <base>...HEAD처럼 기준 브랜치를 지정하면 그 브랜치와 비교합니다. (PR을 만들기 전에는 이 방식을 쓰세요.)

위반 사항이 있으면 0이 아닌 종료 코드와 함께 file:line — issue 형식의 목록을 출력하고, 문제가 없으면 ✅ 한 줄만 출력합니다.

규칙

1. Python 함수/변수명은 snake_case. (ALL_CAPS 상수는 예외.)

2. JS/TS 함수/변수명은 camelCase.

3. 한글 등 비-ASCII 식별자는 금지.

4. 의미 없는 한 글자 이름은 금지. (단, i, j, k, x, y, n, _처럼 흔히 쓰이는 루프/인덱스 표기는 예외.)

결과 보고

PR 워크플로우 안에서 실행했다면, 출력을 요약하거나 풀어 쓰지 말고 PR 설명의 "Naming check" 섹션에 그대로 붙여넣어야 합니다.

pr-draft

description: 현재 브랜치와 기준 브랜치의 diff로 PR 설명을 작성하고 네이밍 규칙 검사 결과를 포함시킨 뒤, 사용자가 확인한 경우에만 gh pr create로 PR을 생성합니다. PR 생성, PR 초안 작성, "PR 만들어줘" 같은 요청에 사용합니다.

PR 초안 작성

현재 브랜치의 diff를 바탕으로 PR 설명을 작성하고, 사용자 확인을 받은 후에만 PR을 생성합니다. 사용자 동의 없이 push하거나 PR을 만들지 않습니다.

절차

1. 기준 브랜치를 확인합니다(기본값 main). 또한 git status로 작업 트리에 커밋되지 않은 변경 사항이 있는지 확인해, 의도치 않게 변경 사항을 잃는 일이 없도록 합니다.

2. PR 컨텍스트 수집 스크립트를 실행합니다.

   python3 .claude/skills/pr-draft/scripts/gather_pr_context.py <base_ref>

   커밋 목록, 변경된 파일 통계, naming-check 리포트를 그대로 반환합니다(가공하거나 설명을 덧붙이지 않은 원본 데이터입니다).

3. 이 데이터와 직접 읽은 diff(git diff <base>...HEAD)를 바탕으로 templates/pr_template.md 형식에 맞춰 PR 본문을 작성합니다.

   • Summary: diff 통계를 다시 나열하는 게 아니라, 왜 이 변경을 했는지 2~4개 불릿포인트로.

   • Naming check: 스크립트 출력을 그대로 붙여넣습니다.

   • Test plan: 리뷰어가 그대로 실행할 수 있는 구체적인 명령이나 절차.

4. 작성한 본문을 사용자에게 보여주고, GitHub에 영향을 주는 작업을 하기 전에 확인을 받습니다.

5. 확인을 받은 뒤에만 아래를 실행합니다.

   gh pr create --title "<title>" --body-file <path-to-drafted-body>

규칙

• 사용자가 본문을 명시적으로 승인하기 전에는 gh pr create나 git push를 절대 실행하지 않습니다.

• naming-check에서 위반 사항이 나오면 조용히 고치거나 빼지 말고, 초안에 그대로 드러내어 사용자가 판단하게 합니다.

네이밍 컨벤션 체크

python3 .claude/skills/naming-check/scripts/check_naming.py

테스트

python3 -m pytest tests/