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

package/README.md

@@ -2,6 +2,32 @@
 
 포트원 사용자를 위한 MCP (Model Context Protocol) 서버입니다. 포트원 개발자센터, 헬프센터 등 공식 문서 내용을 LLM(Large Language Model)에 제공해 정확한 정보를 바탕으로 사용자의 연동 및 질의를 돕도록 합니다.
 
+이외에도 포트원 콘솔에서 제공하는 기능 중 일부를 수행할 수 있습니다.
+
+- 채널 목록 조회
+- 테스트 채널 추가
+- 하위 상점 조회
+- 결제 내역 조회
+
+콘솔 기능 사용 시 브라우저를 통해 콘솔 로그인이 필요합니다.
+
+## DXT를 이용한 설치
+
+[DXT (Desktop Extensions)](https://github.com/anthropics/dxt)를 이용해 MCP 서버를 원클릭으로 설치할 수 있습니다.
+
+1. [GitHub Releases](https://github.com/portone-io/mcp-server/releases)에서 최신 `portone-mcp-server.dxt` 파일을 다운로드합니다.
+
+2. 지원하는 AI 도구(Claude Desktop 등)에서 다운로드한 `.dxt` 파일을 드래그 앤 드롭하거나 열기를 통해 설치합니다.
+
+3. 설치 후 도구를 재시작하여 MCP 서버가 정상적으로 등록되었는지 확인합니다.
+
+> [!WARNING]
+> **Claude Desktop에서 DXT 파일 사용 시 주의사항**
+>
+> 현재 [알려진 이슈](https://github.com/anthropics/dxt/issues/45)로 인해 Claude Desktop에서 DXT 설치 후 MCP 서버가 정상적으로 작동하지 않을 수 있습니다.
+>
+> 이 경우 Node.js 22.6.0 이상을 설치하고 Claude Desktop 설정에서 **"MCP용 내장 Node.js 사용"** 옵션을 비활성화한 후 재시작하면 정상적으로 작동합니다.
+
 ## MCP 서버 등록하기
 
 1. Node.js 22.6.0 이상이 설치되어 있어야 합니다.
@@ -25,47 +51,6 @@
 
 1. 도구를 재시작해 portone-mcp-server 및 해당 서버가 제공하는 도구들이 잘 등록되었는지 확인합니다.
 
-## MCP 서버에서 포트원 기능 사용하기
-
-MCP 서버에 포트원 기능을 연동하면, AI가 아래와 같은 작업을 수행할 수 있습니다.
-
-- 결제 내역 단건/다건 조회
-- 본인인증 내역 단건/다건 조회
-
-연동을 활성화하려면, MCP 설정 파일의 env 블록에 포트원 관리자 콘솔에서 발급받은 API 시크릿을 추가합니다.
-
-```json
-{
-  // ...
-
-  "mcpServers": {
-    // ...
-
-    "portone-mcp-server": {
-      "command": "npx",
-      "args": [
-         "-y",
-         "@portone/mcp-server@latest"
-       ],
-      // 아래 env 블록을 추가하여 API 시크릿을 설정합니다.
-      "env": {
-        "API_SECRET": "<YOUR_PORTONE_API_SECRET>"
-      }
-    }
-  }
-}
-```
-
-> [!CAUTION]
-> **API 시크릿은 MCP 서버에서 제공하는 기능 외에도 포트원 REST API의 모든 권한을 가집니다.**
->
-> 내부의 인가된 인원만이 MCP 서버를 사용할 수 있도록 통제해야 합니다.
-
-> [!CAUTION]
-> **MCP 서버는 포트원의 공개된 API 기능만을 사용하며, 인증을 위해 사용자가 제공한 API 시크릿을 활용합니다.**
->
-> 이 인증 과정은 전적으로 MCP 서버 내부에서 일어나므로, 언어 모델의 문제로 인해 비인가 사용자에게 기밀 정보가 유출되지는 않습니다.
-
 > [!CAUTION]
 > **제3자 AI 서비스를 사용할 경우, API 응답(조회된 데이터 등)이 AI 서비스 측으로 전달되어 저장되거나 해당 서비스의 정책에 따라 모델 학습에 사용될 수 있습니다.**
 >
@@ -91,12 +76,6 @@ MCP 서버에 포트원 기능을 연동하면, AI가 아래와 같은 작업을
    pnpm dev
    ```
 
-1. 테스트
-
-   ```bash
-   pnpm test
-   ```
-
 1. 코드 린팅 및 포맷팅
 
    ```bash
@@ -160,6 +139,42 @@ MCP 서버에 포트원 기능을 연동하면, AI가 아래와 같은 작업을
    2. MCP 서버의 docs 디렉토리를 새로 생성된 내용으로 교체
    3. 개발자센터, 헬프센터 외 일부 문서 다운로드 및 교체
 
+## Python 버전에서 마이그레이션
+
+기존에 Python 버전(<0.13.0)의 MCP 서버를 사용하고 계셨다면 TypeScript 버전으로 마이그레이션하는 것을 권장합니다.
+
+### 마이그레이션 방법
+
+1. **MCP 설정 변경**
+
+   기존 파이썬 버전 설정:
+
+   ```json
+   "mcpServers": {
+     "portone-mcp-server": {
+       "command": "uvx",
+       "args": ["portone-mcp-server@latest"]
+     }
+   }
+   ```
+
+   새로운 TypeScript 버전 설정:
+
+   ```json
+   "mcpServers": {
+     "portone-mcp-server": {
+       "command": "npx",
+       "args": ["-y", "@portone/mcp-server@latest"]
+     }
+   }
+   ```
+
+2. **환경 변수 및 API 시크릿 설정은 동일**하게 유지됩니다.
+
+3. **Node.js 설치**: Node.js 22.6.0 이상이 필요합니다.
+
+4. **AI 도구 재시작**: 설정 변경 후 사용 중인 AI 도구를 재시작합니다.
+
 ## 라이선스
 
 [Apache License 2.0](LICENSE-APACHE) OR [MIT License](LICENSE-MIT)

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 ㅣ 네이버페이 결제형)
 
 * **\[전체 결제수단] 페이지**
   - **국내결제**