@portone/mcp-server 0.14.0 → 0.15.0-alpha.0

package/README.md

@@ -21,7 +21,8 @@
 
 3. 설치 후 도구를 재시작하여 MCP 서버가 정상적으로 등록되었는지 확인합니다.
 
-> [!WARNING] > **Claude Desktop에서 DXT 파일 사용 시 주의사항**
+> [!WARNING]
+> **Claude Desktop에서 DXT 파일 사용 시 주의사항**
 >
 > 현재 [알려진 이슈](https://github.com/anthropics/dxt/issues/45)로 인해 Claude Desktop에서 DXT 설치 후 MCP 서버가 정상적으로 작동하지 않을 수 있습니다.
 >
@@ -50,7 +51,8 @@
 
 1. 도구를 재시작해 portone-mcp-server 및 해당 서버가 제공하는 도구들이 잘 등록되었는지 확인합니다.
 
-> [!CAUTION] > **제3자 AI 서비스를 사용할 경우, API 응답(조회된 데이터 등)이 AI 서비스 측으로 전달되어 저장되거나 해당 서비스의 정책에 따라 모델 학습에 사용될 수 있습니다.**
+> [!CAUTION]
+> **제3자 AI 서비스를 사용할 경우, API 응답(조회된 데이터 등)이 AI 서비스 측으로 전달되어 저장되거나 해당 서비스의 정책에 따라 모델 학습에 사용될 수 있습니다.**
 >
 > MCP 서버는 API 응답에 포함된 개인정보가 외부로 전달되지 않도록, 우선적으로 해당 정보를 식별 및 제거하는 보호 조치를 마련하고 있습니다.
 > 다만, 그 외의 정보는 AI 서비스의 운영 정책에 따라 일시적으로 저장되거나 처리될 수 있는 점을 유의해야 합니다.

package/assets/docs/_components/ko/docs-for-llms.md

@@ -0,0 +1,21 @@
+---
+title: LLM을 위한 개발자센터 문서 디렉터리 지원
+description: LLM을 위한 개발자센터 문서 디렉터리와 사용 방법을 설명합니다.
+targetVersions:
+  - v1
+  - v2
+---
+
+Cursor, Windsurf, Claude Code와 같이 코드베이스 맥락을 자동으로 분석하는 AI 도구를 사용하는 경우,
+LLM을 위한 포트원 문서 디렉터리를 다운받아 작업 중인 코드베이스 내에 위치시키는 방식으로도 활용할 수 있습니다.
+
+이 경우, 위 AI 도구들이 제공하는 임베딩 기반 색인과 RAG (Retrieval Augmented Generation) 검색이 자동적으로 적용되어
+보다 원활히 원하는 결과를 얻으실 수 있습니다.
+
+(파일: LLM 전용 포트원 문서 디렉터리 다운로드)
+
+### 사용 방법
+
+1. 위 링크를 눌러 LLM 전용 포트원 문서 압축 파일을 다운로드합니다.
+2. 압축을 해제하고, 해당 디렉터리를 작업 중인 코드베이스 내에 위치시킵니다.
+3. 포트원 관련 질의 시 AI에게 해당 디렉터리를 태그하여 질의합니다.

package/assets/docs/_components/ko/llms-txt-support.md

@@ -0,0 +1,15 @@
+---
+title: llms.txt 표준 지원
+description: 포트원이 지원하는 llms.txt 표준에 대한 내용입니다.
+targetVersions:
+  - v1
+  - v2
+---
+
+포트원 개발자센터 웹사이트는 [llms.txt 표준](https://llmstxt.org)을 준수하며, LLM이 문서 정보를 쉽게 조회할 수 있도록 지원하고 있습니다.
+
+- [llms.txt](https://developers.portone.io/llms.txt): LLM을 위한 가이드 및 문서 목차를 포함합니다.
+- [llms-full.txt](https://developers.portone.io/llms-full.txt): llms.txt에 더해 모든 문서 내용을 추가로 포함합니다.
+- [llms-small.txt](https://developers.portone.io/llms-small.txt): llms.txt에 더해 모든 문서의 메타 정보만 추가로 포함합니다.
+
+llms.txt, llms-small.txt를 사용하는 AI 어시스턴트의 프롬프트에 포함하거나, llms-full.txt를 파일로 업로드해 질의하는 방식으로도 활용이 가능합니다.

package/assets/docs/_components/ko/using-mcp-server.md

@@ -0,0 +1,60 @@
+---
+title: 포트원 MCP (Model Context Protocol) 서버 사용하기
+description: 포트원이 제공하는 MCP (Model Context Protocol) 서버 사용 방법을 안내합니다.
+targetVersions:
+  - v1
+  - v2
+---
+
+포트원은 쉬운 연동과 빠른 개발을 위해 MCP 서버를 제공합니다. [(GitHub 저장소 바로가기)](https://github.com/portone-io/mcp-server)
+
+포트원 MCP 서버는 개발자센터 문서 내용을 AI에게 제공하여,
+AI가 보다 정확하고 구체적인 정보를 바탕으로 사용자의 연동 및 질의를 돕도록 합니다.
+
+### 1. MCP 서버 등록하기
+
+포트원 MCP 서버를 사용하기 위해서는 먼저 사용하는 AI 도구에 서버를 등록해야 합니다.
+
+Cursor, Windsurf, Claude Code, Claude for Desktop 등 다양한 AI 도구의 설정 파일에서 아래 내용을 추가하여 MCP 서버를 등록할 수 있습니다.
+
+```json
+{
+  // ...
+
+  "mcpServers": {
+    // ...
+
+    "portone-mcp-server": {
+      "command": "uvx",
+      "args": ["portone-mcp-server"]
+    }
+  }
+}
+```
+
+<div class="hint" data-style="info">
+
+사용 환경에 [uv](https://docs.astral.sh/uv/getting-started/installation/)가 설치되어 있어야 합니다.
+
+</div>
+
+설정 파일 수정이 완료된 후 AI 도구를 재시작하면 MCP 서버가 적용됩니다.
+
+### 2. MCP 서버 활용하기
+
+사용 중인 AI 도구에 포트원 MCP 서버가 적용되었다면, 아래 예시들과 같이 질의하여 사용할 수 있습니다.
+
+#### 개발 관련 프롬프트 예시
+
+- _"포트원 V2 Python 서버 SDK를 사용해서 서버 연동 코드를 작성해줘"_
+- _"포트원 V2 Kotlin 서버 SDK를 사용해 웹훅 검증을 구현해줘"_
+- _"포트원 V1 브라우저 SDK를 사용한 페이팔 결제창 호출을 구현해줘"_
+- _"파트너정산 자동화 서비스에 파트너 등록하는 코드를 타입스크립트로 구현해줘"_
+- _"포트원 V2 본인인증 기능 연동해줘"_
+
+#### 전반적인 질의 예시
+
+- _"포트원 V2와 V1의 차이점을 설명해줘"_
+- _"포트원 V2가 지원하는 PG사 목록 보여줘"_
+- _"포트원 API의 하위호환성 정책 설명해줘"_
+- _"포트원 파트너정산 자동화 서비스가 제공하는 기능들을 요약해줘"_

package/assets/docs/api/rest-v1/_components/v1auth.md

@@ -0,0 +1,103 @@
+---
+title: V1 API 인증 방법
+description: 포트원 V1 API 사용 시 인증 방법에 관한 내용입니다.
+targetVersions:
+  - v1
+---
+
+포트원 API를 호출할 때는 **액세스 토큰**을 `Authorization` 헤더에 넣어주어야 합니다.\
+액세스 토큰은 [access\_token 발급 API - POST /users/getToken](https://developers.portone.io/schema/v1.openapi.yml)를 호출해서 발급받을 수 있습니다.
+
+액세스 토큰 발급 API를 호출하려면 **API 키**와 **API 시크릿**을 인자로 넣어주어야 합니다.
+
+<details>
+
+<summary>API 키와 API 시크릿 확인하기</summary>
+
+1. [관리자 콘솔 `상점・계정 관리` 화면](https://admin.portone.io/merchant) 접속
+2. `내 식별코드・API Keys` 버튼 클릭
+
+(이미지 첨부: API 키와 API 시크릿은 관리자 콘솔 → 상점・계정 관리 메뉴 → 내 식별코드・API Keys 모달을 열어서 확인하실 수 있습니다)
+
+<div class="hint" data-style="danger">
+
+**API 시크릿은 절대로 외부에 노출되어서는 안 되는 값**입니다.\
+실제 구현에서 액세스 토큰 발급은 꼭 서버 사이드에서 해주세요.
+
+</div>
+
+</details>
+
+<details>
+
+<summary>액세스 토큰 발급 받기</summary>
+
+[access\_token 발급 API - POST /users/getToken](https://developers.portone.io/schema/v1.openapi.yml) 호출
+
+(이미지 첨부: /users/getToken API를 호출해서 액세스 토큰을 발급받습니다)
+
+<div class="hint" data-style="info">
+
+포트원 REST API 서버는 **Google Public NTP**의 시간과 동기화되고 있습니다.
+
+</div>
+
+<div class="hint" data-style="warning">
+
+하위 상점 연동을 할 경우 액세스 토큰을 발급받을 때 **Agent 계정**의 **API 키** 와 **API 시크릿**을 사용해야 합니다.
+
+[Agency & Tier 란?](https://developers.portone.io/opi/ko/support/agency-and-tier)
+
+</div>
+
+</details>
+
+<details>
+
+<summary>액세스 토큰 사용하기</summary>
+
+발급받은 액세스 토큰은 다른 API를 호출할 때\
+`Authorization` 헤더에 `Bearer <액세스 토큰>` 형식의 값을 넣어주면 됩니다.
+
+자세한 내용은 [MDN - HTTP 인증 문서](https://developer.mozilla.org/ko/docs/Web/HTTP/Authentication)를 참고해주세요.
+
+(관련 이미지 첨부)
+
+<div class="hint" data-style="warning">
+
+하위 상점 연동을 할 경우 포트원 API 호출시 `Tier` 헤더에 하위 상점 티어 코드를 입력해야 합니다.
+
+[Agency & Tier 란?](https://developers.portone.io/opi/ko/support/agency-and-tier)
+
+(관련 이미지 첨부)
+
+</div>
+
+</details>
+
+<details>
+
+<summary>액세스 토큰 만료기한 연장</summary>
+
+만료된 액세스 토큰으로 API를 호출하면 `401 Unauthorized` 응답을 받습니다.\
+액세스 토큰의 만료 기한은 발행시간부터 **30분**입니다.
+
+- 기존 액세스 토큰이 만료되기 전 [access\_token 발급 API - POST /users/getToken](https://developers.portone.io/schema/v1.openapi.yml)를 다시 호출했을 경우
+  - 기존 액세스 토큰이 반환됩니다.\
+    **만료 기한이 1분 안쪽으로 남았을 때** 요청했다면 기존 액세스 토큰의 만료 기한이 **5분 연장**됩니다.
+
+- 기존 액세스 토큰이 만료된 다음 [access\_token 발급 API - POST /users/getToken](https://developers.portone.io/schema/v1.openapi.yml)를 다시 호출했을 경우
+  - 새로운 액세스 토큰이 반환됩니다.
+
+(관련 이미지 첨부)
+
+<div class="hint" data-style="info">
+
+액세스 토큰의 재사용과 만료기한 5분 연장 동작방식은 다음과 같은 상황을 고려해서 설계되었습니다.
+
+- 한 고객사에서 여러 대의 웹서버가 동시에 경쟁적으로 REST API(`/users/getToken`)를 호출하는 상황
+- 한 고객사에서 여러 대의 웹서버가 시간 동기화 되어있지 않은 상황
+
+</div>
+
+</details>

package/assets/docs/help/admin-console/analytics/content32.md

@@ -144,11 +144,11 @@ searchTags:
 - **데이터 표기 기준**
   - 카드결제 : 결제 요청시 지정된 결제수단 (pay\_method) 값이 card로 지정된 거래입니다.
   - 간편결제 : 결제요청시 지정된 결제수단 (pay\_method)이나 결제대행사(pg\_provider)가 간편결제(예: naverpay , kakaopay) 로 지정된 거래입니다.
-    - 결제 데이터 분석의 간편결제는 허브형 혹은 직계약에 상관없이 최종 상세 결제 수단으로 표기됩니다. (예: 카카오페이, 네이버페이)
+    - 결제 데이터 분석의 간편결제는 PG 제휴 혹은 직계약에 상관없이 최종 상세 결제 수단으로 표기됩니다. (예: 카카오페이, 네이버페이)
     - 참고
-      - 간편결제를 허브형으로 이용한 경우, 포트원 관리자 콘솔은 아래와 같이 별도 표기합니다.
-        - 결제대행사는 `허브형 계약된 결제대행사`로 노출 (ex: 결제대행사: KCP)
-        - 결제내역 상세 모달 내 결제대행사는 결제대행사 허브형ㅣ간편결제로 노출 (ex: 결제대행사: KCP 허브형 ㅣ 네이버페이 결제형)
+      - 간편결제를 PG를 통해 이용한 경우, 포트원 관리자 콘솔은 아래와 같이 별도 표기합니다.
+        - 결제대행사는 `일반 결제대행사`로 노출 (ex: 결제대행사: KCP)
+        - 결제내역 상세 모달 내 결제대행사는 결제대행사ㅣ간편결제로 노출 (ex: 결제대행사: KCP ㅣ 네이버페이 결제형)
 
 * **\[전체 결제수단] 페이지**
   - **국내결제**