apick-mcp 3.5.0 → 3.6.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 변경 기록
 
+## 3.6.0 — 2026-09-30
+
+- 간편인증 데이터 조회 2종(현금영수증 소득공제 내역, 국세 신고내역 조회)의 접수·결과 Tool 4개와 유튜브 영상 정보·썸네일·자막 목록·자막 다운로드 Tool 4개를 추가했습니다. 전체 114개, Business 29개, Web 17개, 상태 변경 Tool 28개입니다. 원격 서버에는 이미 배포돼 있습니다.
+- Add four request/result tools for two simple-auth data products (cash receipt deductions, tax return history) and four YouTube tools (metadata, thumbnail, subtitle list, subtitle download). 114 total, 29 Business, 17 Web, 28 non-read-only. Already live on the remote server.
+- 새 간편인증 상품은 인증 발송 성공 시 20P, 최초 결과 60P × (1 + 0.5 × (연수 - 1))로 과금되며 대기·유효기간 내 재조회는 무료입니다.
+- The new simple-auth products charge 20P on successful authentication dispatch and 60P × (1 + 0.5 × (years - 1)) for the first result; waiting polls and repeat reads are free.
+
 ## 3.5.0 — 2026-09-28
 
 - 간편인증 데이터 조회 5종의 접수·결과 Tool 10개 계약을 추가했습니다. 전체 106개, Business 25개, 상태 변경 Tool 24개입니다. 원격 서버의 대응 패치 배포가 필요합니다.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 APICK
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 APICK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,10 +2,10 @@
 
 <img src="https://raw.githubusercontent.com/lead788/apick-mcp/main/assets/logo-400.png" alt="APICK" width="88" height="88">
 
-# APICK MCP — 106 Korean Data, AI, Image & Video Tools
+# APICK MCP — 114 Korean Data, AI, Image & Video Tools
 
-> 3.5.0 카탈로그: 106개 Tool(Business 25개). 신규 10개 Tool을 사용하려면 대응하는 원격 서버 버전이 필요합니다. 브릿지 설치만으로 활성화되지 않으며 실제 사용 가능 목록은 연결한 서버의 `tools/list`로 확인하세요.
-> Catalog for 3.5.0: 106 tools (25 Business). The 10 new tools require the matching remote-server deployment; installing this bridge alone does not enable them. Check the connected server’s `tools/list` for availability.
+> 3.6.0 카탈로그: 114개 Tool(Business 29개, Web 17개). 새 Tool은 원격 서버에 이미 배포돼 있으며, 실제 사용 가능 목록은 연결한 서버의 `tools/list`로 확인하세요.
+> Catalog for 3.6.0: 114 tools (29 Business, 17 Web). The new tools are already live on the remote server; check the connected server’s `tools/list` for availability.
 
 **Korean business registry, ID verification, OCR, parcel tracking, file conversion, web intelligence and LLM — as MCP tools for any AI agent.**
 
@@ -25,9 +25,9 @@
 
 ## What is this? / 이게 뭔가요?
 
-**EN** — APICK is a Korean data and AI API platform. This MCP server exposes **106 tools** for Korean business data, identity verification, OCR, parcel tracking, image and video generation, file conversion, web intelligence, and LLM calls.
+**EN** — APICK is a Korean data and AI API platform. This MCP server exposes **114 tools** for Korean business data, identity verification, OCR, parcel tracking, image and video generation, file conversion, web intelligence, and LLM calls.
 
-**KO** — 에이픽(APICK)은 대한민국 데이터·AI API 플랫폼입니다. 이 MCP 서버는 **Tool 106개**로 사업자 조회, 신분증 진위확인, 택배 배송조회, OCR, 이미지·영상 생성, 파일 변환, 웹 검색과 LLM 호출을 **인증키 하나로** 제공합니다.
+**KO** — 에이픽(APICK)은 대한민국 데이터·AI API 플랫폼입니다. 이 MCP 서버는 **Tool 114개**로 사업자 조회, 신분증 진위확인, 택배 배송조회, OCR, 이미지·영상 생성, 파일 변환, 웹 검색과 LLM 호출을 **인증키 하나로** 제공합니다.
 
 **The server is hosted by APICK. Nothing to install, build, or keep running.**
 **서버는 에이픽이 운영합니다. 설치할 것도, 띄워둘 것도 없습니다.**
@@ -45,8 +45,8 @@ https://apick.app/mcp/all
 Sign up at **[apick.app](https://apick.app)** and copy your license key from the dashboard. New accounts get **1,000 free points**.
 **[apick.app](https://apick.app)** 에서 가입하고 대시보드에서 인증키를 복사하세요. 신규 가입 시 **1,000포인트 무료**.
 
-> `tools/list` works **without** a key — a client can connect and discover all 106 tools before you sign up. Only `tools/call` validates the key and allowed IP.
-> `tools/list`는 **인증 없이** 동작합니다. 가입 전에도 클라이언트가 연결해 106개 Tool을 확인할 수 있고, 키와 허용 IP는 `tools/call`부터 검증합니다.
+> `tools/list` works **without** a key — a client can connect and discover all 114 tools before you sign up. Only `tools/call` validates the key and allowed IP.
+> `tools/list`는 **인증 없이** 동작합니다. 가입 전에도 클라이언트가 연결해 114개 Tool을 확인할 수 있고, 키와 허용 IP는 `tools/call`부터 검증합니다.
 
 Leave the allowed-IP list blank for unrestricted access. To restrict access, register the public IPv4 address seen by APICK as an exact address or CIDR such as `/32`. Changes apply immediately with no separate synchronization.
 마이페이지의 허용 IP가 공란이면 제한 없이 사용할 수 있습니다. 제한하려면 APICK에 도착하는 공인 IPv4를 단일 주소 또는 CIDR(`/32` 등)로 등록하세요. 저장 즉시 반영되며 별도 동기화는 필요하지 않습니다.
@@ -152,11 +152,11 @@ Connect to `all` for everything, or to one server to keep the tool list short an
 
 | Server 서버 | Endpoint | Tools | Coverage 범위 |
 | --- | --- | --- | --- |
-| **All 통합** | `https://apick.app/mcp/all` | **106** | 아래 전부 |
-| [Business 사업자·커머스](TOOLS.md#business) | `https://apick.app/mcp/business` | 25 | 사업자·법인 조회, 택배 배송조회, 부동산 실거래가, 차량 이력, 유효성 검사 |
+| **All 통합** | `https://apick.app/mcp/all` | **114** | 아래 전부 |
+| [Business 사업자·커머스](TOOLS.md#business) | `https://apick.app/mcp/business` | 29 | 사업자·법인 조회, 택배 배송조회, 부동산 실거래가, 차량 이력, 유효성 검사 |
 | [Identity 신분증](TOOLS.md#identity) | `https://apick.app/mcp/identity` | 16 | 주민등록증·운전면허증·여권·외국인등록증 진위확인, 실명확인, 개인정보 마스킹 |
 | [Convert 파일변환](TOOLS.md#convert) | `https://apick.app/mcp/convert` | 22 | PDF·DOCX·엑셀 변환, STT, 비동기 TTS, 워터마크 |
-| [Web 웹·검색](TOOLS.md#web) | `https://apick.app/mcp/web` | 13 | 도메인·IP·WHOIS, 웹페이지 수집, 구글 검색, 유튜브 |
+| [Web 웹·검색](TOOLS.md#web) | `https://apick.app/mcp/web` | 17 | 도메인·IP·WHOIS, 웹페이지 수집, 구글 검색, 유튜브 |
 | [Vision 이미지·영상](TOOLS.md#vision) | `https://apick.app/mcp/vision` | 6 | 얼굴 검출, 이미지 유사도, 유해이미지 판별, 영상 추출 |
 | [OCR 문자인식](TOOLS.md#ocr) | `https://apick.app/mcp/ocr` | 6 | 이미지 텍스트 추출, 신분증 항목 추출 |
 | [AI · LLM](TOOLS.md#ai) | `https://apick.app/mcp/ai` | 15 | LLM 챗, 텍스트 요약·교정, 이미지 생성·편집·대량 작업, 비동기 영상 생성 |
@@ -164,13 +164,13 @@ Connect to `all` for everything, or to one server to keep the tool list short an
 
 ### Every tool / 전체 Tool
 
-**[→ TOOLS.md](TOOLS.md)** — all 106 tools with parameters, types, and copy-paste JSON-RPC examples.
-**[→ TOOLS.md](TOOLS.md)** — 106개 전체를 파라미터·타입·호출 예시까지 정리했습니다.
+**[→ TOOLS.md](TOOLS.md)** — all 114 tools with parameters, types, and copy-paste JSON-RPC examples.
+**[→ TOOLS.md](TOOLS.md)** — 114개 전체를 파라미터·타입·호출 예시까지 정리했습니다.
 
 <details>
 <summary><b>Tool names at a glance / Tool 이름 한눈에 보기</b></summary>
 
-**Business** `biz_detail` `venture_biz_info` `land_rt_price` `req_pccc` `get_pccc` `req_employment` `get_employment` `req_personal_income` `get_personal_income` `req_nps_join_history` `get_nps_join_history` `req_driving_license` `get_driving_license` `req_health_checkup` `get_health_checkup` `get_car_flooding` `get_car_scrap` `parcel_tracking` `parcel_tracking_auto` `check_email_valid` `check_phone_valid` `check_spam_number` `holiday_info` `search_juso` `info`
+**Business** `biz_detail` `venture_biz_info` `land_rt_price` `req_pccc` `get_pccc` `req_employment` `get_employment` `req_personal_income` `get_personal_income` `req_nps_join_history` `get_nps_join_history` `req_driving_license` `get_driving_license` `req_health_checkup` `get_health_checkup` `req_cash_receipt_deduction` `get_cash_receipt_deduction` `req_tax_return_history` `get_tax_return_history` `get_car_flooding` `get_car_scrap` `parcel_tracking` `parcel_tracking_auto` `check_email_valid` `check_phone_valid` `check_spam_number` `holiday_info` `search_juso` `info`
 
 **Identity** `identi_card1`–`identi_card5` `identi_card_image1`–`identi_card_image5` `name_rrn_auth` `hide_rrn` `identity_document_id_card` `identity_document_driver_license` `identity_document_passport` `identity_document_residence_card`
 
@@ -178,7 +178,7 @@ Connect to `all` for everything, or to one server to keep the tool list short an
 
 **Finance** `transfer_1won` `account_realname` `bank_code`
 
-**Web** `nslookup` `reverse_ip` `location` `ip_history` `whois` `url_html` `url_screenshot` `url_similarity` `google_search` `google_image_search` `google_lens_search` `crawl_youtube` `download_youtube_video`
+**Web** `nslookup` `reverse_ip` `location` `ip_history` `whois` `url_html` `url_screenshot` `url_similarity` `google_search` `google_image_search` `google_lens_search` `crawl_youtube` `download_youtube_video` `youtube_metadata` `youtube_thumbnail` `youtube_subtitle_list` `youtube_subtitle`
 
 **Convert** `stt` `tts_jobs_create` `tts_jobs_status` `tts_jobs_cancel` `tts_jobs_result` `tts_jobs_subtitles` `tts_jobs_quality` `tts_jobs_retry` `tts_jobs_candidate_audio` `voice_change` `face_blur` `pdf_to_docx` `pdf_to_image` `pdf_merge` `html_to_pdf` `docx_to_pdf` `json_to_excel` `base64_to_image` `set_watermark` `get_watermark` `draw_watermark_pdf` `draw_watermark_image`
 
@@ -283,7 +283,7 @@ Seedance 참조 소재 모드는 지원 버전에서 참조 이미지·영상·
 | **Transport** | Streamable HTTP — one endpoint per server, JSON-RPC 2.0 over HTTPS POST, stateless | 서버당 단일 엔드포인트, HTTPS POST로 JSON-RPC 2.0, 세션 없이 요청 단위 |
 | **Protocol** | MCP `2026-07-28`, auto-compatible with earlier client versions | MCP `2026-07-28` 기본, 이전 규격 클라이언트 자동 호환 |
 | **Discovery** | `tools/list` returns every tool with JSON Schema, description and live price — no key needed | `tools/list`가 스키마·설명·실시간 단가를 반환, 인증 불필요 |
-| **Annotations** | Every tool declares `title`, `readOnlyHint`, `openWorldHint`. 24 of 106 are not read-only | 전 Tool이 `title`·`readOnlyHint`·`openWorldHint` 선언. 106개 중 상태 변경 Tool은 24개 |
+| **Annotations** | Every tool declares `title`, `readOnlyHint`, `openWorldHint`. 28 of 114 are not read-only | 전 Tool이 `title`·`readOnlyHint`·`openWorldHint` 선언. 114개 중 상태 변경 Tool은 28개 |
 | **Results** | Text (JSON) + `structuredContent`. Images as image content; files up to 8MB as base64 | 텍스트(JSON)와 `structuredContent` 동시 반환. 이미지는 이미지 콘텐츠, 8MB 이하 파일은 base64 |
 | **File input** | File-taking tools accept a public `https` URL (`image_url`, `pdf_url`, …) — APICK downloads and processes it | 파일 Tool은 공개 `https` URL을 받습니다. 에이픽 서버가 내려받아 처리합니다 |
 | **Errors** | Delivered via `isError`; identity masking also preserves `structuredContent.error_code` | `isError`로 전달되며 신분증 마스킹은 `structuredContent.error_code`도 보존합니다 |
@@ -302,12 +302,14 @@ Call the request tool on Business or All, ask the user to approve on their phone
 | 국민연금 가입내역 | `requestNpsJoinHistory` / `getNpsJoinHistory` | `req_nps_join_history` / `get_nps_join_history` |
 | 운전면허 조회 | `requestDrivingLicense` / `getDrivingLicense` | `req_driving_license` / `get_driving_license` |
 | 국가 건강검진 결과 | `requestHealthCheckup` / `getHealthCheckup` | `req_health_checkup` / `get_health_checkup` |
+| 현금영수증 소득공제 내역 | `requestCashReceiptDeduction` / `getCashReceiptDeduction` | `req_cash_receipt_deduction` / `get_cash_receipt_deduction` |
+| 국세 신고내역 조회 | `requestTaxReturnHistory` / `getTaxReturnHistory` | `req_tax_return_history` / `get_tax_return_history` |
 
 공통 입력은 SDK와 같은 `name`, `birthDate`(YYYYMMDD), `phone`, `authProvider`입니다. 상품별 기간 옵션과 응답 상태·오류는 [Tool 계약](TOOLS.md#simple-auth-data)을 확인하세요. 최초 결과 반환 시 조회 범위에 따라 과금하며, 대기 중 조회와 유효기간 내 재조회는 무료입니다.
 
 Common inputs match the SDK: `name`, `birthDate`, `phone`, and `authProvider`. The first result delivery is billed by query scope; waiting polls and repeat reads within the result lifetime are free. See the [tool contract](TOOLS.md#simple-auth-data) for options and response fields.
 
-**PCCC 비교:** 승인 흐름은 같지만 `req_pccc`는 `birthday`·`provider`, `get_pccc`는 `tx_id`를 사용하며 결과 재조회도 과금됩니다. 신규 5개 상품의 입력 이름이나 무료 재조회 정책을 PCCC에 적용하지 마세요.
+**PCCC 비교:** 승인 흐름은 같지만 `req_pccc`는 `birthday`·`provider`, `get_pccc`는 `tx_id`를 사용하며 결과 재조회도 과금됩니다. 간편인증 데이터 조회 7개 상품의 입력 이름이나 무료 재조회 정책을 PCCC에 적용하지 마세요.
 
 **PCCC comparison:** The approval flow is the same, but PCCC retains `birthday`/`provider` and `tx_id`, and charges for repeated result reads. Its contract is unchanged.
 
@@ -315,8 +317,8 @@ Common inputs match the SDK: `name`, `birthDate`, `phone`, and `authProvider`. T
 
 ### Tools with side effects / 부작용이 있는 Tool
 
-82 of 106 tools are read-only. The other 24 change state, charge points, cancel work, or consume a result and carry `readOnlyHint: false` so your client can require approval:
-106개 중 82개는 조회입니다. 나머지 24개는 과금·취소·결과 생성 등 상태를 바꾸므로 `readOnlyHint: false`가 붙습니다.
+86 of 114 tools are read-only. The other 28 change state, charge points, cancel work, or consume a result and carry `readOnlyHint: false` so your client can require approval:
+114개 중 86개는 조회입니다. 나머지 28개는 과금·취소·결과 생성 등 상태를 바꾸므로 `readOnlyHint: false`가 붙습니다.
 
 | Tool | What it does / 하는 일 |
 | --- | --- |
@@ -330,6 +332,10 @@ Common inputs match the SDK: `name`, `birthDate`, `phone`, and `authProvider`. T
 | `get_driving_license` | Collects and bills the first result; repeat reads are free · 결과 수집·최초 반환 과금, 재조회 무료 |
 | `req_health_checkup` | Requests phone approval and charges acceptance · 국가 건강검진 결과 인증 요청·접수 과금 |
 | `get_health_checkup` | Collects and bills the first result; repeat reads are free · 결과 수집·최초 반환 과금, 재조회 무료 |
+| `req_cash_receipt_deduction` | Requests phone approval and charges acceptance · 현금영수증 소득공제 내역 인증 요청·접수 과금 |
+| `get_cash_receipt_deduction` | Collects and bills the first result; repeat reads are free · 결과 수집·최초 반환 과금, 재조회 무료 |
+| `req_tax_return_history` | Requests phone approval and charges acceptance · 국세 신고내역 조회 인증 요청·접수 과금 |
+| `get_tax_return_history` | Collects and bills the first result; repeat reads are free · 결과 수집·최초 반환 과금, 재조회 무료 |
 | `image_generate` / `image_edit` / `image_batch_create` | Creates images and charges points · 이미지 생성·편집·작업 접수 과금 |
 | `tts_jobs_retry` | Resumes a TTS job · TTS 작업 상태 변경 |
 | `transfer_1won` | Deposits 1 KRW into a bank account · 실제로 1원을 입금합니다 |

package/TOOLS.md

@@ -1,10 +1,10 @@
 # APICK MCP — Full Tool Catalog / 전체 Tool 목록
 
-**106 tools** across **8 domain servers**, plus the combined `all` server.
-**Tool 106개**, 분야별 서버 8개와 통합 서버 `all`.
+**114 tools** across **8 domain servers**, plus the combined `all` server.
+**Tool 114개**, 분야별 서버 8개와 통합 서버 `all`.
 
-> 3.5.0 카탈로그: 106개 Tool(Business 25개). 신규 10개 Tool을 사용하려면 대응하는 원격 서버 버전이 필요합니다. 브릿지 설치만으로 활성화되지 않으며 실제 사용 가능 목록은 연결한 서버의 `tools/list`로 확인하세요.
-> Catalog for 3.5.0: 106 tools (25 Business). The 10 new tools require the matching remote-server deployment; installing this bridge alone does not enable them. Check the connected server’s `tools/list` for availability.
+> 3.6.0 카탈로그: 114개 Tool(Business 29개, Web 17개). 새 Tool은 원격 서버에 이미 배포돼 있으며, 실제 사용 가능 목록은 연결한 서버의 `tools/list`로 확인하세요.
+> Catalog for 3.6.0: 114 tools (29 Business, 17 Web). The new tools are already live on the remote server; check the connected server’s `tools/list` for availability.
 
 
 Official site 공식 사이트: **<https://apick.app>** · Docs 연동 가이드: **<https://apick.app/dev_guide/mcp>**
@@ -16,19 +16,19 @@ Endpoint pattern: `https://apick.app/mcp/{server}` — connect to `all` for ever
 
 | Server 서버 | Endpoint | Tools | Coverage 범위 |
 | --- | --- | --- | --- |
-| [Business & Commerce · 사업자 · 커머스](#business) | `/mcp/business` | 25 | 사업자·법인 조회, 택배 배송조회, 부동산 실거래가, 차량 이력, 유효성 검사. |
+| [Business & Commerce · 사업자 · 커머스](#business) | `/mcp/business` | 29 | 사업자·법인 조회, 택배 배송조회, 부동산 실거래가, 차량 이력, 유효성 검사. |
 | [Identity Verification · 신분증 진위확인 · 마스킹](#identity) | `/mcp/identity` | 16 | 주민등록증·운전면허증·여권·외국인등록증 진위확인, 실명확인, 개인정보 마스킹. |
 | [OCR · OCR 문자인식](#ocr) | `/mcp/ocr` | 6 | 이미지 텍스트 추출과 신분증 항목 추출. |
 | [Finance · 금융 · 계좌확인](#finance) | `/mcp/finance` | 3 | 계좌 예금주 실명조회와 1원 인증. |
-| [Web & Search · 웹 · 검색](#web) | `/mcp/web` | 13 | 도메인·IP 조회, WHOIS, 웹페이지 수집, 구글 검색, 유튜브. |
+| [Web & Search · 웹 · 검색](#web) | `/mcp/web` | 17 | 도메인·IP 조회, WHOIS, 웹페이지 수집, 구글 검색, 유튜브. |
 | [File Conversion · 파일 변환 · 워터마크](#convert) | `/mcp/convert` | 22 | PDF·DOCX·엑셀 변환, 음성인식(STT), 비동기 TTS, 워터마크. |
 | [Vision · 이미지 · 영상 분석](#vision) | `/mcp/vision` | 6 | 얼굴 검출, 이미지 유사도, 유해이미지 판별, 영상 추출. |
 | [AI & LLM · AI · LLM](#ai) | `/mcp/ai` | 15 | LLM 챗, 텍스트 도구, 이미지 생성·편집·대량 작업, 비동기 영상 생성. |
-| **All 통합** | `/mcp/all` | **106** | 아래 전부 |
+| **All 통합** | `/mcp/all` | **114** | 아래 전부 |
 
-<details><summary><b>All 106 tool names / 전체 Tool 이름</b></summary>
+<details><summary><b>All 114 tool names / 전체 Tool 이름</b></summary>
 
-`biz_detail` · `venture_biz_info` · `land_rt_price` · `req_pccc` · `get_pccc` · `req_employment` · `get_employment` · `req_personal_income` · `get_personal_income` · `req_nps_join_history` · `get_nps_join_history` · `req_driving_license` · `get_driving_license` · `req_health_checkup` · `get_health_checkup` · `get_car_flooding` · `get_car_scrap` · `parcel_tracking` · `parcel_tracking_auto` · `check_email_valid` · `check_phone_valid` · `check_spam_number` · `holiday_info` · `search_juso` · `info`
+`biz_detail` · `venture_biz_info` · `land_rt_price` · `req_pccc` · `get_pccc` · `req_employment` · `get_employment` · `req_personal_income` · `get_personal_income` · `req_nps_join_history` · `get_nps_join_history` · `req_driving_license` · `get_driving_license` · `req_health_checkup` · `get_health_checkup` · `req_cash_receipt_deduction` · `get_cash_receipt_deduction` · `req_tax_return_history` · `get_tax_return_history` · `get_car_flooding` · `get_car_scrap` · `parcel_tracking` · `parcel_tracking_auto` · `check_email_valid` · `check_phone_valid` · `check_spam_number` · `holiday_info` · `search_juso` · `info`
 
 `identi_card1` · `identi_card2` · `identi_card3` · `identi_card4` · `identi_card5` · `identi_card_image1` · `identi_card_image2` · `identi_card_image3` · `identi_card_image4` · `identi_card_image5` · `name_rrn_auth` · `hide_rrn` · `identity_document_residence_card` · `identity_document_passport` · `identity_document_id_card` · `identity_document_driver_license`
 
@@ -36,7 +36,7 @@ Endpoint pattern: `https://apick.app/mcp/{server}` — connect to `all` for ever
 
 `transfer_1won` · `account_realname` · `bank_code`
 
-`nslookup` · `reverse_ip` · `location` · `ip_history` · `whois` · `url_html` · `url_screenshot` · `url_similarity` · `google_search` · `google_image_search` · `google_lens_search` · `crawl_youtube` · `download_youtube_video`
+`nslookup` · `reverse_ip` · `location` · `ip_history` · `whois` · `url_html` · `url_screenshot` · `url_similarity` · `google_search` · `google_image_search` · `google_lens_search` · `crawl_youtube` · `download_youtube_video` · `youtube_metadata` · `youtube_thumbnail` · `youtube_subtitle_list` · `youtube_subtitle`
 
 `stt` · `tts_jobs_create` · `tts_jobs_status` · `tts_jobs_cancel` · `tts_jobs_result` · `tts_jobs_subtitles` · `tts_jobs_quality` · `tts_jobs_retry` · `tts_jobs_candidate_audio` · `voice_change` · `face_blur` · `pdf_to_docx` · `pdf_to_image` · `pdf_merge` · `html_to_pdf` · `docx_to_pdf` · `json_to_excel` · `base64_to_image` · `set_watermark` · `get_watermark` · `draw_watermark_pdf` · `draw_watermark_image`
 
@@ -52,7 +52,7 @@ Endpoint pattern: `https://apick.app/mcp/{server}` — connect to `all` for ever
 
 ## Business & Commerce · 사업자 · 커머스
 
-`https://apick.app/mcp/business` — 25 tools
+`https://apick.app/mcp/business` — 29 tools
 
 Korean business registry, corporate credit, parcel tracking, real-estate prices, vehicle history, and input validation.
 
@@ -75,6 +75,10 @@ Korean business registry, corporate credit, parcel tracking, real-estate prices,
 | [`get_driving_license`](#get-driving-license) | 운전면허 조회 상태·결과 | `transactionId` |
 | [`req_health_checkup`](#req-health-checkup) | 국가 건강검진 결과 인증 요청 | `name`, `birthDate`, `phone`, `authProvider` |
 | [`get_health_checkup`](#get-health-checkup) | 국가 건강검진 결과 상태·결과 | `transactionId` |
+| [`req_cash_receipt_deduction`](#req-cash-receipt-deduction) | 현금영수증 소득공제 내역 인증 요청 | `name`, `birthDate`, `phone`, `authProvider` |
+| [`get_cash_receipt_deduction`](#get-cash-receipt-deduction) | 현금영수증 소득공제 내역 상태·결과 | `transactionId` |
+| [`req_tax_return_history`](#req-tax-return-history) | 국세 신고내역 조회 인증 요청 | `name`, `birthDate`, `phone`, `authProvider` |
+| [`get_tax_return_history`](#get-tax-return-history) | 국세 신고내역 조회 상태·결과 | `transactionId` |
 | [`get_car_flooding`](#get-car-flooding) | 차량 침수차 여부 조회 | `type`, `value` |
 | [`get_car_scrap`](#get-car-scrap) | 차량 폐차사고처리 여부 조회 | `type`, `value` |
 | [`parcel_tracking`](#parcel-tracking) | 택배 배송조회 | `carrier`, `trackingNumber` |
@@ -188,7 +192,7 @@ req_pccc Tool 호출로 받은 tx_id 를 입력해 처리 상태를 확인합니
 
 ### 간편인증 데이터 조회 공통 계약 / Shared data-lookup contract
 
-아래 5개 상품은 **접수 → 휴대폰 승인 → 결과 조회** 순서로 호출합니다. 접수 전에 알림 발송·과금과 조회 항목을 사용자에게 확인하고, 승인은 사용자가 휴대폰에서 직접 수행합니다. 승인 대기 중 접수를 반복하지 않습니다.
+아래 7개 상품은 **접수 → 휴대폰 승인 → 결과 조회** 순서로 호출합니다. 접수 전에 알림 발송·과금과 조회 항목을 사용자에게 확인하고, 승인은 사용자가 휴대폰에서 직접 수행합니다. 승인 대기 중 접수를 반복하지 않습니다.
 
 Use request → user approval on the phone → result lookup. Confirm the requested data and acceptance charge before submitting. Never approve on the user’s behalf or automatically repeat the authentication request.
 
@@ -210,6 +214,8 @@ Result tools require the `transactionId` from the same product. Both stages are
 | 국민연금 가입내역 | from, to: YYYY-MM (각각 선택) | `result.npsJoinHistory` |
 | 운전면허 조회 | 없음 | `result.drivingLicense` |
 | 국가 건강검진 결과 | 없음 | `result.healthCheckup` |
+| 현금영수증 소득공제 내역 | incomeYears: 정수 1~3 (선택, 기본 1) | `result.cashReceiptDeduction` |
+| 국세 신고내역 조회 | years: 정수 1~10 (선택, 기본 1) | `result.taxReturnHistory` |
 
 **응답:** MCP의 `structuredContent`와 JSON 텍스트에는 REST 응답의 `data`가 그대로 담깁니다. `schemaVersion`, `transactionId`, `product`, `status`, `resultAvailable`, `charged`, `sources`, `message`, `success`를 확인합니다. 접수에는 `expiresAt`와 선택적 `approvals`, 수집 중에는 `progress`, 결과에는 `checkedAt`, `resultExpiresAt`, `result`가 포함될 수 있습니다. 실제 차감 포인트는 `_meta["app.apick/cost"]`입니다.
 
@@ -224,7 +230,7 @@ Result tools require the `transactionId` from the same product. Both stages are
 
 `errorCode`는 `RESULT_EXPIRED`, `AUTH_EXPIRED`, `AUTH_REJECTED`, `COLLECT_FAILED`를 포함합니다. 만료된 결과는 다시 조회할 수 없으며 새로운 인증 접수가 필요합니다. 업무 상태 오류는 `isError: false`인 정상 MCP 응답에도 담길 수 있으므로 `status`와 `errorCode`를 함께 검사하세요.
 
-접수 시 정액 과금, 결과 최초 반환 시 조회 범위별 과금입니다. 승인 대기·수집 중 조회 및 `resultExpiresAt` 전 재조회는 무료입니다. **PCCC는 별도 계약**으로 `birthday`·`provider`·`tx_id`를 사용하고 결과 재조회도 과금됩니다.
+접수 시 정액 과금, 결과 최초 반환 시 조회 범위별 과금입니다. 현금영수증 소득공제 내역과 국세 신고내역은 인증 발송 성공 시 20P, 최초 결과 60P × (1 + 0.5 × (연수 - 1))입니다. 승인 대기·수집 중 조회 및 `resultExpiresAt` 전 재조회는 무료입니다. **PCCC는 별도 계약**으로 `birthday`·`provider`·`tx_id`를 사용하고 결과 재조회도 과금됩니다.
 
 Acceptance is billed separately; first result delivery is billed by scope. Waiting/collecting polls and repeat reads before `resultExpiresAt` are free. PCCC keeps its existing `birthday`/`provider`/`tx_id` contract and charges repeated result reads.
 
@@ -382,6 +388,54 @@ REST: `POST /rest/get_health_checkup` · SDK: `getHealthCheckup()`
 
 ---
 
+<a id="req-cash-receipt-deduction"></a>
+
+### `req_cash_receipt_deduction` — 현금영수증 소득공제 내역 인증 요청
+
+REST: `POST /rest/req_cash_receipt_deduction` · SDK: `requestCashReceiptDeduction()`
+
+필수: `name`, `birthDate`, `phone`, `authProvider`. 선택: incomeYears: 정수 1~3 (선택, 기본 1). 인증 발송 성공 시 20P이며 조회 범위와 무관합니다.
+
+[공통 입력·응답·과금 계약](#simple-auth-data)을 따릅니다.
+
+---
+
+<a id="get-cash-receipt-deduction"></a>
+
+### `get_cash_receipt_deduction` — 현금영수증 소득공제 내역 결과 조회
+
+REST: `POST /rest/get_cash_receipt_deduction` · SDK: `getCashReceiptDeduction()`
+
+필수: `transactionId`. 성공 결과: `result.cashReceiptDeduction` (`조회연도`, `전체합계`, `연도별[].사용내역`). 최초 결과 60P × (1 + 0.5 × (incomeYears - 1)), 기본 60P.
+
+[공통 입력·응답·과금 계약](#simple-auth-data)을 따릅니다.
+
+---
+
+<a id="req-tax-return-history"></a>
+
+### `req_tax_return_history` — 국세 신고내역 조회 인증 요청
+
+REST: `POST /rest/req_tax_return_history` · SDK: `requestTaxReturnHistory()`
+
+필수: `name`, `birthDate`, `phone`, `authProvider`. 선택: years: 정수 1~10 (선택, 기본 1). 인증 발송 성공 시 20P이며 조회 범위와 무관합니다.
+
+[공통 입력·응답·과금 계약](#simple-auth-data)을 따릅니다.
+
+---
+
+<a id="get-tax-return-history"></a>
+
+### `get_tax_return_history` — 국세 신고내역 조회 결과 조회
+
+REST: `POST /rest/get_tax_return_history` · SDK: `getTaxReturnHistory()`
+
+필수: `transactionId`. 성공 결과: `result.taxReturnHistory` (`조회기간`, `합계`, `신고내역`). 최초 결과 60P × (1 + 0.5 × (years - 1)), 기본 60P.
+
+[공통 입력·응답·과금 계약](#simple-auth-data)을 따릅니다.
+
+---
+
 <a id="get-car-flooding"></a>
 
 ### `get_car_flooding` — 차량 침수차 여부 조회
@@ -1129,7 +1183,7 @@ _No parameters. 파라미터 없음._
 
 ## Web & Search · 웹 · 검색
 
-`https://apick.app/mcp/web` — 13 tools
+`https://apick.app/mcp/web` — 17 tools
 
 Domain and IP intelligence, WHOIS, page capture, Google search, and YouTube.
 
@@ -1150,6 +1204,10 @@ Domain and IP intelligence, WHOIS, page capture, Google search, and YouTube.
 | [`google_lens_search`](#google-lens-search) | 구글 렌즈 검색(이미지로 검색) | `image_url` |
 | [`crawl_youtube`](#crawl-youtube) | 유튜브 계정 정보 수집 | `user_id` |
 | [`download_youtube_video`](#download-youtube-video) | 유튜브 동영상 다운로드 | `url` |
+| [`youtube_metadata`](#youtube-metadata) | 유튜브 영상 정보 조회 | `url` |
+| [`youtube_thumbnail`](#youtube-thumbnail) | 유튜브 썸네일 다운로드 | `url` |
+| [`youtube_subtitle_list`](#youtube-subtitle-list) | 유튜브 자막 목록 조회 | `url` |
+| [`youtube_subtitle`](#youtube-subtitle) | 유튜브 자막 다운로드 | `url`, `lang` |
 
 <a id="nslookup"></a>
 
@@ -1390,6 +1448,89 @@ Download a publicly available YouTube video and return it as an MP4 file.
 
 ---
 
+<a id="youtube-metadata"></a>
+
+### `youtube_metadata` — 유튜브 영상 정보 조회
+
+Look up metadata of a public YouTube video: title, channel, duration, views, likes, upload date, description, tags, chapters and thumbnails. 20 points per call.
+
+유튜브 공개 영상의 제목·채널·길이·조회수·좋아요·업로드일·설명·태그·챕터·썸네일 목록을 조회합니다. 호출당 20포인트.
+
+> 읽기 전용 / read-only · 외부 데이터 조회 / external lookup · server `web`
+
+| Parameter | Type | Required | Description 설명 |
+| --- | --- | --- | --- |
+| `url` | `string` | **필수 / required** | 유튜브 영상 URL 또는 11자리 영상 ID (watch·youtu.be·shorts 주소 지원) |
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"youtube_metadata","arguments":{"url":"<url>"}}}
+```
+
+---
+
+<a id="youtube-thumbnail"></a>
+
+### `youtube_thumbnail` — 유튜브 썸네일 다운로드
+
+Download the largest thumbnail of a public YouTube video as a JPG image. 20 points per call.
+
+유튜브 공개 영상의 가장 큰 썸네일을 JPG 이미지로 내려받습니다. 호출당 20포인트.
+
+> 읽기 전용 / read-only · 외부 데이터 조회 / external lookup · server `web`
+
+| Parameter | Type | Required | Description 설명 |
+| --- | --- | --- | --- |
+| `url` | `string` | **필수 / required** | 유튜브 영상 URL 또는 11자리 영상 ID (watch·youtu.be·shorts 주소 지원) |
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"youtube_thumbnail","arguments":{"url":"<url>"}}}
+```
+
+---
+
+<a id="youtube-subtitle-list"></a>
+
+### `youtube_subtitle_list` — 유튜브 자막 목록 조회
+
+List the manual and auto-generated subtitle languages available for a public YouTube video. 20 points per call.
+
+유튜브 공개 영상의 수동 자막과 자동 생성 자막 언어 목록을 조회합니다. 자동 번역 자막은 `translated: true`로 표시됩니다. 호출당 20포인트.
+
+> 읽기 전용 / read-only · 외부 데이터 조회 / external lookup · server `web`
+
+| Parameter | Type | Required | Description 설명 |
+| --- | --- | --- | --- |
+| `url` | `string` | **필수 / required** | 유튜브 영상 URL 또는 11자리 영상 ID (watch·youtu.be·shorts 주소 지원) |
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"youtube_subtitle_list","arguments":{"url":"<url>"}}}
+```
+
+---
+
+<a id="youtube-subtitle"></a>
+
+### `youtube_subtitle` — 유튜브 자막 다운로드
+
+Download the subtitles of a public YouTube video in one language as VTT, SRT or plain text. Check available languages with `youtube_subtitle_list` first. 30 points per call.
+
+유튜브 공개 영상의 자막을 언어별로 VTT·SRT·텍스트 파일로 내려받습니다. 제공 언어는 `youtube_subtitle_list`로 먼저 확인하고, 영상 원어 자막 사용을 권장합니다. 호출당 30포인트.
+
+> 읽기 전용 / read-only · 외부 데이터 조회 / external lookup · server `web`
+
+| Parameter | Type | Required | Description 설명 |
+| --- | --- | --- | --- |
+| `url` | `string` | **필수 / required** | 유튜브 영상 URL 또는 11자리 영상 ID (watch·youtu.be·shorts 주소 지원) |
+| `lang` | `string` | **필수 / required** | 자막 언어 코드 (예: ko, en, en-US, en-orig). 자막 목록 조회 결과의 lang 값 |
+| `format` | `string` | 선택 / optional | `vtt`(기본)·`srt`·`txt`. `txt`는 시간 정보를 뺀 본문만 반환 |
+| `type` | `string` | 선택 / optional | `any`(기본: 수동 자막 우선)·`manual`·`auto` |
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"youtube_subtitle","arguments":{"url":"<url>","lang":"en","format":"srt"}}}
+```
+
+---
+
 <a id="convert"></a>
 
 ## File Conversion · 파일 변환 · 워터마크

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "apick-mcp",
-  "version": "3.5.0",
-  "description": "APICK MCP — 106 Korean data, AI, image & video tools for AI agents. 사업자조회·신분증·OCR·배송조회·이미지 생성·편집·영상 생성·파일변환·검색·LLM.",
+  "version": "3.6.0",
+  "description": "APICK MCP — 114 Korean data, AI, image & video tools for AI agents. 사업자조회·신분증·OCR·배송조회·이미지 생성·편집·영상 생성·파일변환·검색·LLM.",
   "type": "module",
   "license": "MIT",
   "author": "APICK",

package/src/bridge.js

@@ -1,175 +1,175 @@
-// stdio <-> Streamable HTTP bridge for the APICK MCP server.
-//
-// APICK serves MCP over Streamable HTTP at https://apick.app/mcp/{server}. Clients that
-// speak remote HTTP should connect there directly. This bridge exists for clients that
-// only launch local stdio processes.
-//
-// It is a pump, not a protocol implementation: every JSON-RPC message read from stdin is
-// forwarded verbatim, and every message the server returns is written verbatim to stdout.
-// Capability and version negotiation, tool schemas and errors are all handled end to end
-// by the client and the server.
-
-export const DEFAULT_ENDPOINT = 'https://apick.app/mcp';
-
-export const SERVERS = [
-	'all',
-	'business',
-	'identity',
-	'ocr',
-	'finance',
-	'web',
-	'convert',
-	'vision',
-	'ai'
-];
-
-// A key must never reach stdout, stderr or an error message.
-export function redact(text, apiKey) {
-	if (!text) return text;
-	let out = String(text);
-	if (apiKey) out = out.split(apiKey).join('***');
-	return out.replace(/(Bearer\s+)[\w.\-]+/gi, '$1***');
-}
-
-// Streamable HTTP replies with either a single JSON body or an SSE stream carrying one or
-// more JSON-RPC messages. Both shapes reduce to "a list of messages".
-function parseEventStream(text) {
-	const messages = [];
-	for (const block of text.split(/\r?\n\r?\n/)) {
-		const data = block
-			.split(/\r?\n/)
-			.filter((line) => line.startsWith('data:'))
-			.map((line) => line.slice(5).trim())
-			.join('\n');
-		if (!data) continue;
-		try {
-			messages.push(JSON.parse(data));
-		} catch {
-			// Keep-alive or comment frame - nothing to forward.
-		}
-	}
-	return messages;
-}
-
-export function createBridge(options = {}) {
-	const server = options.server || 'all';
-	const apiKey = options.apiKey || '';
-	const endpoint = (options.endpoint || DEFAULT_ENDPOINT).replace(/\/+$/, '') + '/' + server;
-	const fetchImpl = options.fetch || globalThis.fetch;
-	const write = options.write || ((line) => process.stdout.write(line + '\n'));
-	const warn = options.warn || ((line) => process.stderr.write(line + '\n'));
-
-	// The gateway is stateless, but honour a session id and the negotiated protocol
-	// version if the server ever starts sending them.
-	let sessionId = null;
-	let protocolVersion = null;
-
-	function headers() {
-		const h = {
-			'content-type': 'application/json',
-			accept: 'application/json, text/event-stream',
-			'user-agent': 'apick-mcp-bridge'
-		};
-		if (apiKey) h.authorization = 'Bearer ' + apiKey;
-		if (sessionId) h['mcp-session-id'] = sessionId;
-		if (protocolVersion) h['mcp-protocol-version'] = protocolVersion;
-		return h;
-	}
-
-	function remember(message) {
-		const negotiated = message && message.result && message.result.protocolVersion;
-		if (negotiated) protocolVersion = negotiated;
-	}
-
-	async function send(message) {
-		let res;
-		try {
-			res = await fetchImpl(endpoint, {
-				method: 'POST',
-				headers: headers(),
-				body: JSON.stringify(message)
-			});
-		} catch (err) {
-			return fail(message, -32001, 'Cannot reach ' + endpoint + ': ' + redact(err.message, apiKey));
-		}
-
-		const incomingSession = res.headers.get && res.headers.get('mcp-session-id');
-		if (incomingSession) sessionId = incomingSession;
-
-		const body = await res.text();
-		if (!body) {
-			// 202 for notifications and responses - nothing to forward.
-			if (res.ok) return;
-			return fail(message, -32002, 'HTTP ' + res.status + ' from ' + endpoint);
-		}
-
-		const contentType = (res.headers.get && res.headers.get('content-type')) || '';
-		let messages;
-		if (contentType.includes('text/event-stream')) {
-			messages = parseEventStream(body);
-		} else {
-			try {
-				const parsed = JSON.parse(body);
-				messages = Array.isArray(parsed) ? parsed : [parsed];
-			} catch {
-				return fail(message, -32002, 'HTTP ' + res.status + ' from ' + endpoint + ': unexpected response body');
-			}
-		}
-
-		for (const out of messages) {
-			remember(out);
-			write(JSON.stringify(out));
-		}
-	}
-
-	// Only a request (one carrying an id) can be answered with an error; a failed
-	// notification is reported on stderr so the client is not left waiting on a reply.
-	function fail(message, code, text) {
-		const detail = redact(text, apiKey);
-		if (message && message.id !== undefined && message.id !== null) {
-			write(JSON.stringify({ jsonrpc: '2.0', id: message.id, error: { code, message: detail } }));
-		} else {
-			warn('apick-mcp: ' + detail);
-		}
-	}
-
-	// Newline-delimited JSON in, newline-delimited JSON out.
-	function handleLine(line) {
-		const trimmed = line.trim();
-		if (!trimmed) return Promise.resolve();
-		let message;
-		try {
-			message = JSON.parse(trimmed);
-		} catch {
-			warn('apick-mcp: ignoring unparseable input line');
-			return Promise.resolve();
-		}
-		return send(message);
-	}
-
-	function attach(input) {
-		let buffer = '';
-		const pending = new Set();
-		input.setEncoding('utf8');
-		input.on('data', (chunk) => {
-			buffer += chunk;
-			let index;
-			while ((index = buffer.indexOf('\n')) !== -1) {
-				const line = buffer.slice(0, index);
-				buffer = buffer.slice(index + 1);
-				const task = handleLine(line).catch((err) => warn('apick-mcp: ' + redact(err.message, apiKey)));
-				pending.add(task);
-				task.finally(() => pending.delete(task));
-			}
-		});
-		return new Promise((resolve) => {
-			input.on('end', async () => {
-				if (buffer.trim()) await handleLine(buffer).catch(() => {});
-				await Promise.allSettled([...pending]);
-				resolve();
-			});
-		});
-	}
-
-	return { endpoint, attach, handleLine };
-}
+// stdio <-> Streamable HTTP bridge for the APICK MCP server.
+//
+// APICK serves MCP over Streamable HTTP at https://apick.app/mcp/{server}. Clients that
+// speak remote HTTP should connect there directly. This bridge exists for clients that
+// only launch local stdio processes.
+//
+// It is a pump, not a protocol implementation: every JSON-RPC message read from stdin is
+// forwarded verbatim, and every message the server returns is written verbatim to stdout.
+// Capability and version negotiation, tool schemas and errors are all handled end to end
+// by the client and the server.
+
+export const DEFAULT_ENDPOINT = 'https://apick.app/mcp';
+
+export const SERVERS = [
+	'all',
+	'business',
+	'identity',
+	'ocr',
+	'finance',
+	'web',
+	'convert',
+	'vision',
+	'ai'
+];
+
+// A key must never reach stdout, stderr or an error message.
+export function redact(text, apiKey) {
+	if (!text) return text;
+	let out = String(text);
+	if (apiKey) out = out.split(apiKey).join('***');
+	return out.replace(/(Bearer\s+)[\w.\-]+/gi, '$1***');
+}
+
+// Streamable HTTP replies with either a single JSON body or an SSE stream carrying one or
+// more JSON-RPC messages. Both shapes reduce to "a list of messages".
+function parseEventStream(text) {
+	const messages = [];
+	for (const block of text.split(/\r?\n\r?\n/)) {
+		const data = block
+			.split(/\r?\n/)
+			.filter((line) => line.startsWith('data:'))
+			.map((line) => line.slice(5).trim())
+			.join('\n');
+		if (!data) continue;
+		try {
+			messages.push(JSON.parse(data));
+		} catch {
+			// Keep-alive or comment frame - nothing to forward.
+		}
+	}
+	return messages;
+}
+
+export function createBridge(options = {}) {
+	const server = options.server || 'all';
+	const apiKey = options.apiKey || '';
+	const endpoint = (options.endpoint || DEFAULT_ENDPOINT).replace(/\/+$/, '') + '/' + server;
+	const fetchImpl = options.fetch || globalThis.fetch;
+	const write = options.write || ((line) => process.stdout.write(line + '\n'));
+	const warn = options.warn || ((line) => process.stderr.write(line + '\n'));
+
+	// The gateway is stateless, but honour a session id and the negotiated protocol
+	// version if the server ever starts sending them.
+	let sessionId = null;
+	let protocolVersion = null;
+
+	function headers() {
+		const h = {
+			'content-type': 'application/json',
+			accept: 'application/json, text/event-stream',
+			'user-agent': 'apick-mcp-bridge'
+		};
+		if (apiKey) h.authorization = 'Bearer ' + apiKey;
+		if (sessionId) h['mcp-session-id'] = sessionId;
+		if (protocolVersion) h['mcp-protocol-version'] = protocolVersion;
+		return h;
+	}
+
+	function remember(message) {
+		const negotiated = message && message.result && message.result.protocolVersion;
+		if (negotiated) protocolVersion = negotiated;
+	}
+
+	async function send(message) {
+		let res;
+		try {
+			res = await fetchImpl(endpoint, {
+				method: 'POST',
+				headers: headers(),
+				body: JSON.stringify(message)
+			});
+		} catch (err) {
+			return fail(message, -32001, 'Cannot reach ' + endpoint + ': ' + redact(err.message, apiKey));
+		}
+
+		const incomingSession = res.headers.get && res.headers.get('mcp-session-id');
+		if (incomingSession) sessionId = incomingSession;
+
+		const body = await res.text();
+		if (!body) {
+			// 202 for notifications and responses - nothing to forward.
+			if (res.ok) return;
+			return fail(message, -32002, 'HTTP ' + res.status + ' from ' + endpoint);
+		}
+
+		const contentType = (res.headers.get && res.headers.get('content-type')) || '';
+		let messages;
+		if (contentType.includes('text/event-stream')) {
+			messages = parseEventStream(body);
+		} else {
+			try {
+				const parsed = JSON.parse(body);
+				messages = Array.isArray(parsed) ? parsed : [parsed];
+			} catch {
+				return fail(message, -32002, 'HTTP ' + res.status + ' from ' + endpoint + ': unexpected response body');
+			}
+		}
+
+		for (const out of messages) {
+			remember(out);
+			write(JSON.stringify(out));
+		}
+	}
+
+	// Only a request (one carrying an id) can be answered with an error; a failed
+	// notification is reported on stderr so the client is not left waiting on a reply.
+	function fail(message, code, text) {
+		const detail = redact(text, apiKey);
+		if (message && message.id !== undefined && message.id !== null) {
+			write(JSON.stringify({ jsonrpc: '2.0', id: message.id, error: { code, message: detail } }));
+		} else {
+			warn('apick-mcp: ' + detail);
+		}
+	}
+
+	// Newline-delimited JSON in, newline-delimited JSON out.
+	function handleLine(line) {
+		const trimmed = line.trim();
+		if (!trimmed) return Promise.resolve();
+		let message;
+		try {
+			message = JSON.parse(trimmed);
+		} catch {
+			warn('apick-mcp: ignoring unparseable input line');
+			return Promise.resolve();
+		}
+		return send(message);
+	}
+
+	function attach(input) {
+		let buffer = '';
+		const pending = new Set();
+		input.setEncoding('utf8');
+		input.on('data', (chunk) => {
+			buffer += chunk;
+			let index;
+			while ((index = buffer.indexOf('\n')) !== -1) {
+				const line = buffer.slice(0, index);
+				buffer = buffer.slice(index + 1);
+				const task = handleLine(line).catch((err) => warn('apick-mcp: ' + redact(err.message, apiKey)));
+				pending.add(task);
+				task.finally(() => pending.delete(task));
+			}
+		});
+		return new Promise((resolve) => {
+			input.on('end', async () => {
+				if (buffer.trim()) await handleLine(buffer).catch(() => {});
+				await Promise.allSettled([...pending]);
+				resolve();
+			});
+		});
+	}
+
+	return { endpoint, attach, handleLine };
+}

package/src/index.js

@@ -1,92 +1,92 @@
-#!/usr/bin/env node
-// apick-mcp - run the APICK MCP server over stdio.
-//
-// Usage:
-//   apick-mcp [--server <name>]
-//
-// Environment:
-//   APICK_API_KEY     APICK license key. Optional: tools/list works without one,
-//                     tools/call needs it.
-//   APICK_MCP_SERVER  Which server to expose (default: all).
-//   APICK_MCP_URL     Base URL override (default: https://apick.app/mcp).
-
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { createBridge, DEFAULT_ENDPOINT, SERVERS } from './bridge.js';
-
-const HELP = `apick-mcp - APICK MCP server over stdio
-
-  apick-mcp [--server <name>]
-
-Options
-  --server, -s <name>  ${SERVERS.join(', ')}  (default: all)
-  --version, -v        print version
-  --help, -h           print this message
-
-Environment
-  APICK_API_KEY        APICK license key (get one at https://apick.app)
-  APICK_MCP_SERVER     same as --server
-  APICK_MCP_URL        base URL override (default: ${DEFAULT_ENDPOINT})
-
-Clients that support remote MCP can skip this bridge and connect straight to
-${DEFAULT_ENDPOINT}/all with an Authorization: Bearer header.
-Docs: https://apick.app/dev_guide/mcp
-`;
-
-function parseArgs(argv) {
-	const args = { server: process.env.APICK_MCP_SERVER || 'all' };
-	for (let i = 0; i < argv.length; i++) {
-		const arg = argv[i];
-		if (arg === '--help' || arg === '-h') args.help = true;
-		else if (arg === '--version' || arg === '-v') args.version = true;
-		else if (arg === '--server' || arg === '-s') args.server = argv[++i];
-		else if (arg.startsWith('--server=')) args.server = arg.slice('--server='.length);
-		else args.unknown = arg;
-	}
-	return args;
-}
-
-async function main() {
-	const args = parseArgs(process.argv.slice(2));
-
-	if (args.help) {
-		process.stdout.write(HELP);
-		return;
-	}
-	if (args.version) {
-		const pkgPath = fileURLToPath(new URL('../package.json', import.meta.url));
-		process.stdout.write(JSON.parse(readFileSync(pkgPath, 'utf8')).version + '\n');
-		return;
-	}
-	if (args.unknown) {
-		process.stderr.write('apick-mcp: unknown argument ' + args.unknown + '\n\n' + HELP);
-		process.exitCode = 2;
-		return;
-	}
-	if (!SERVERS.includes(args.server)) {
-		process.stderr.write(
-			'apick-mcp: unknown server "' + args.server + '". Available: ' + SERVERS.join(', ') + '\n'
-		);
-		process.exitCode = 2;
-		return;
-	}
-
-	const bridge = createBridge({
-		server: args.server,
-		apiKey: process.env.APICK_API_KEY,
-		endpoint: process.env.APICK_MCP_URL
-	});
-
-	if (!process.env.APICK_API_KEY) {
-		process.stderr.write(
-			'apick-mcp: no APICK_API_KEY set - tool discovery works, tool calls will ask you to sign in at https://apick.app\n'
-		);
-	}
-
-	await bridge.attach(process.stdin);
-}
-
-main().catch((err) => {
-	process.stderr.write('apick-mcp: ' + err.message + '\n');
-	process.exitCode = 1;
-});
+#!/usr/bin/env node
+// apick-mcp - run the APICK MCP server over stdio.
+//
+// Usage:
+//   apick-mcp [--server <name>]
+//
+// Environment:
+//   APICK_API_KEY     APICK license key. Optional: tools/list works without one,
+//                     tools/call needs it.
+//   APICK_MCP_SERVER  Which server to expose (default: all).
+//   APICK_MCP_URL     Base URL override (default: https://apick.app/mcp).
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createBridge, DEFAULT_ENDPOINT, SERVERS } from './bridge.js';
+
+const HELP = `apick-mcp - APICK MCP server over stdio
+
+  apick-mcp [--server <name>]
+
+Options
+  --server, -s <name>  ${SERVERS.join(', ')}  (default: all)
+  --version, -v        print version
+  --help, -h           print this message
+
+Environment
+  APICK_API_KEY        APICK license key (get one at https://apick.app)
+  APICK_MCP_SERVER     same as --server
+  APICK_MCP_URL        base URL override (default: ${DEFAULT_ENDPOINT})
+
+Clients that support remote MCP can skip this bridge and connect straight to
+${DEFAULT_ENDPOINT}/all with an Authorization: Bearer header.
+Docs: https://apick.app/dev_guide/mcp
+`;
+
+function parseArgs(argv) {
+	const args = { server: process.env.APICK_MCP_SERVER || 'all' };
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === '--help' || arg === '-h') args.help = true;
+		else if (arg === '--version' || arg === '-v') args.version = true;
+		else if (arg === '--server' || arg === '-s') args.server = argv[++i];
+		else if (arg.startsWith('--server=')) args.server = arg.slice('--server='.length);
+		else args.unknown = arg;
+	}
+	return args;
+}
+
+async function main() {
+	const args = parseArgs(process.argv.slice(2));
+
+	if (args.help) {
+		process.stdout.write(HELP);
+		return;
+	}
+	if (args.version) {
+		const pkgPath = fileURLToPath(new URL('../package.json', import.meta.url));
+		process.stdout.write(JSON.parse(readFileSync(pkgPath, 'utf8')).version + '\n');
+		return;
+	}
+	if (args.unknown) {
+		process.stderr.write('apick-mcp: unknown argument ' + args.unknown + '\n\n' + HELP);
+		process.exitCode = 2;
+		return;
+	}
+	if (!SERVERS.includes(args.server)) {
+		process.stderr.write(
+			'apick-mcp: unknown server "' + args.server + '". Available: ' + SERVERS.join(', ') + '\n'
+		);
+		process.exitCode = 2;
+		return;
+	}
+
+	const bridge = createBridge({
+		server: args.server,
+		apiKey: process.env.APICK_API_KEY,
+		endpoint: process.env.APICK_MCP_URL
+	});
+
+	if (!process.env.APICK_API_KEY) {
+		process.stderr.write(
+			'apick-mcp: no APICK_API_KEY set - tool discovery works, tool calls will ask you to sign in at https://apick.app\n'
+		);
+	}
+
+	await bridge.attach(process.stdin);
+}
+
+main().catch((err) => {
+	process.stderr.write('apick-mcp: ' + err.message + '\n');
+	process.exitCode = 1;
+});