auigrid-mcp-server 0.2.0 → 0.3.1

package/README.md

@@ -6,7 +6,69 @@ AUIGrid 3.0.18부터 제공하며 npm 패키지 이름은 **`auigrid-mcp-server`
 
 [공식 MCP 사용 안내](https://www.auisoft.net/documentation/auigrid/Desc/mcp-server.html) | [npm 패키지](https://www.npmjs.com/package/auigrid-mcp-server)
 
-## 시작하기
+이 패키지는 **AUIGrid 3.0.19** 문서와 예제를 포함합니다. 백분율 표시 및 편집 렌더러, 셀 범위 이동과 복사, 그룹 칼럼 숨김, 병합 헤더 이동 및 내보내기 레이아웃을 조회할 수 있습니다. 원격 서버의 자료 버전은 `list_versions`로 확인하십시오.
+
+## 연결 방식
+
+원격 Streamable HTTP 연결(권장)과 로컬 npm 연결(stdio)을 제공합니다. 두 방식은 같은 다섯 조회 도구를 사용합니다.
+
+| 방식 | 실행 위치 | 고객 준비 사항 |
+| --- | --- | --- |
+| 원격 URL (권장) | AUIGrid 운영 서버 | Streamable HTTP 지원 AI 도구와 인터넷 연결 |
+| 로컬 npm | 고객 PC에서 AI 도구가 실행 | Node.js 22.12 이상 |
+
+### 원격 URL 연결 (권장)
+
+원격 MCP 서버 주소는 **`https://auigrid.com/mcp`**입니다. `https://`를 포함하고 주소 끝에 슬래시(`/`)를 붙이지 않습니다. 전송 방식은 **Streamable HTTP**이며, 인증 없이 공개 문서와 예제를 읽기 전용으로 조회합니다. 로그인이나 API 키 설정, 고객 PC의 Node.js 및 MCP 패키지 설치는 필요하지 않습니다.
+
+로컬 연결과 원격 연결 중 하나를 선택합니다. 기존 설정이 있다면 다른 MCP 서버 항목은 유지하고 `auigrid` 항목을 추가하거나 변경합니다.
+
+**Claude Code** — 사용할 프로젝트의 터미널에서 실행합니다.
+
+```sh
+claude mcp add --transport http auigrid https://auigrid.com/mcp
+```
+
+**Cursor** — 프로젝트의 `.cursor/mcp.json`에 추가합니다.
+
+```json
+{
+  "mcpServers": {
+    "auigrid": {
+      "url": "https://auigrid.com/mcp"
+    }
+  }
+}
+```
+
+**VS Code** — 프로젝트의 `.vscode/mcp.json`에 추가합니다. 최상위 키는 **`servers`**이며, Cursor의 `mcpServers`와 다릅니다.
+
+```json
+{
+  "servers": {
+    "auigrid": {
+      "type": "http",
+      "url": "https://auigrid.com/mcp"
+    }
+  }
+}
+```
+
+**Codex CLI** — 터미널에서 실행합니다.
+
+```sh
+codex mcp add auigrid --url https://auigrid.com/mcp
+```
+
+**다른 MCP 지원 도구** — Claude의 사용자 지정 커넥터 등에서 원격 MCP 서버로 `https://auigrid.com/mcp`를 등록하고 전송 방식을 Streamable HTTP로 선택합니다.
+
+연결 후 AI에게 `list_versions`로 사용 가능한 문서 버전을 확인하도록 요청하십시오. 원격 자료는 운영 서버에서 갱신하므로 고객이 npm 패키지를 갱신할 필요는 없습니다.
+
+브라우저 주소창에서 `https://auigrid.com/mcp`를 열면 **HTTP 405**가 표시됩니다. MCP 요청만 처리하는 주소이므로 정상입니다. **HTTP 429**는 요청 한도를 초과했다는 뜻이며 응답의 `Retry-After`에 표시된 시간 이후 다시 요청합니다.
+
+설정 형식: [Claude Code](https://code.claude.com/docs/en/mcp), [Cursor](https://cursor.com/docs/mcp), [VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers), [Codex CLI](https://developers.openai.com/codex/mcp/).
+
+## 로컬 npm으로 시작하기
 
 Node.js **22.12 이상**과 로컬 MCP(stdio)를 지원하는 AI 개발 도구가 필요합니다. 아래 설정을 추가하면 AI 도구가 `npx`로 패키지를 받아 실행합니다. 별도의 웹서버 운영이나 소스 빌드는 필요하지 않습니다.
 
@@ -72,6 +134,23 @@ Cursor의 MCP 설정 또는 VS Code의 `MCP: List Servers`에서 서버를 활
 
 > exportToXlsx와 useExportStyle 문서를 찾아 화면과 내보내기 스타일을 분리하는 예제를 작성해 줘.
 
+## 비상업용 버전의 CDN으로 빠르게 시작하기
+
+AUIGrid는 비상업용 버전의 CDN을 제공합니다. 정품은 CDN으로 제공하지 않습니다. 비상업용 목적의 `localhost` 또는 `127.0.0.1`에서 무료로 시작할 수 있습니다. MCP에 포함된 시작 안내와 HTML 예제를 사용하면 AI가 CDN을 연결하고 데이터를 넣어 실행 가능한 그리드를 작성할 수 있습니다.
+
+> AUIGrid MCP에서 비상업용 CDN 시작 예제를 찾아줘. localhost에서 실행할 HTML 하나에 데이터를 넣고 정렬, 필터 및 편집이 가능한 그리드를 만들어줘.
+
+1. `search_docs`에서 `CDN`, `비상업용`, `무료`, `시작하기`로 검색합니다.
+2. `get_api`에 `id: "Desc/noncommercial.html"`을 전달하여 연결 방법과 사용 조건을 확인합니다.
+3. `list_examples`에서 `query: "CDN"`으로 예제를 찾고, `get_example`에 `id: "noncommercial-cdn-vanilla-js"`를 전달하여 HTML을 조회합니다.
+4. 작성한 HTML을 로컬 웹 서버에서 열고 데이터를 바꾸며 사용합니다. 별도 데이터 파일이나 WebDemo의 PHP 공통 파일은 필요하지 않습니다.
+
+React/Vue 프로젝트에 적용할 때는 프레임워크와 JavaScript/TypeScript 사용 여부를 함께 알려 해당 샘플과 래퍼를 참고하도록 요청하십시오.
+
+[비상업용 CDN 시작 안내](https://www.auisoft.net/documentation/auigrid/Desc/noncommercial.html) | [GitHub 다운로드 및 사용 조건](https://github.com/aui-community/auigrid-noncommercial#readme)
+
+localhost 이외의 도메인이나 IP에서 테스트하려면 [평가판 다운로드](https://www.auisoft.net/dcenter.html)를 이용할 수 있습니다. AI에는 `get_api`의 `Desc/noncommercial.html`에서 평가판 안내를 확인하고, 내려받은 평가판 파일로 연결하도록 요청하십시오.
+
 ## 제공 도구
 
 | 도구 | 기능 |
@@ -86,13 +165,13 @@ Cursor의 MCP 설정 또는 VS Code의 `MCP: List Servers`에서 서버를 활
 
 ## 자료와 업데이트
 
-MCP는 패키지에 포함된 공식 문서와 예제를 읽습니다. 그리드 실행 엔진이나 고객 데이터에 접근하지 않으며, 코드 작성과 수정은 연결한 AI 도구가 수행합니다. 예제를 실행할 때는 AUIGrid 엔진과 해당 라이선스를 별도로 준비해야 합니다.
+MCP는 패키지에 포함된 공식 문서와 예제를 읽습니다. 그리드 실행 엔진이나 고객 데이터에 접근하지 않으며, 코드 작성과 수정은 연결한 AI 도구가 수행합니다. 예제를 실행할 때는 AUIGrid 엔진, 라이선스 및 CSS가 필요합니다. 비상업용 로컬 예제는 CDN으로 연결하거나 GitHub에서 내려받아 사용하며, 상용 환경에서는 해당 환경에 맞는 제품 배포본과 라이선스를 사용합니다.
 
-AUIGrid 제품, MCP 패키지와 `aui-grid` 타입 패키지의 버전은 각각 관리합니다. 지원하는 문서 버전은 `list_versions`로 확인하십시오. 새 자료가 게시되면 MCP를 다시 시작해 갱신합니다. 특정 MCP 패키지 버전을 유지하려면 설정의 `@latest`를 해당 버전으로 바꿉니다.
+AUIGrid 제품, MCP 패키지와 `aui-grid` 타입 패키지의 버전은 각각 관리합니다. 지원하는 문서 버전은 `list_versions`로 확인하십시오. 로컬 방식은 새 자료가 게시되면 MCP를 다시 시작해 갱신합니다. 원격 방식은 운영 서버에서 자료를 갱신합니다. 특정 MCP 패키지 버전을 유지하려면 설정의 `@latest`를 해당 버전으로 바꿉니다.
 
 ## 기존 0.1.1에서 전환하기
 
-이 안내는 AUIGrid 3.0.18 문서를 제공하는 새 구현을 기준으로 합니다. 기존 `auigrid-mcp-server@0.1.1`과 도구 호출 형식이 다릅니다. 패키지 이름과 npx 실행 명령은 같지만, **Node.js 18 이상에서 22.12 이상으로 실행 조건이 변경**되었습니다.
+이 안내는 AUIGrid 3.0.19 문서를 제공하는 구현을 기준으로 합니다. 기존 `auigrid-mcp-server@0.1.1`과 도구 호출 형식이 다릅니다. 패키지 이름과 npx 실행 명령은 같지만, 로컬 연결의 **Node.js 실행 조건은 18 이상에서 22.12 이상으로 변경**되었습니다. 원격 연결에는 고객 PC의 Node.js가 필요하지 않습니다.
 
 | 기존 도구 | 새 도구 및 지정 방법 |
 | --- | --- |
@@ -112,11 +191,28 @@ AUIGrid 제품, MCP 패키지와 `aui-grid` 타입 패키지의 버전은 각각
 
 자세한 호출 예는 [0.1.1 전환 안내](https://www.auisoft.net/documentation/auigrid/Desc/mcp-server.html#migration)를 참고하십시오.
 
+## HTTP 서버 직접 실행
+
+자체 서버를 운영할 때는 HTTP 실행 기능을 포함한 패키지를 설치한 뒤 아래 명령을 사용합니다. VPS에서는 검증한 버전을 고정 설치합니다. 공개 원격 URL에 연결하는 고객은 서버를 직접 실행할 필요가 없습니다.
+
+```sh
+# HTTP 기능을 포함한 패키지를 설치한 운영 서버에서 실행합니다.
+auigrid-mcp-server --http --host 127.0.0.1 --port 3000 --public-url https://auigrid.com/mcp
+```
+
+`--http`를 생략하면 기존 stdio 방식입니다. HTTP는 `/mcp`, 상태 확인은 `/healthz`를 사용합니다. 외부 HTTPS는 웹서버에서 처리하고 Node.js로 전달합니다. `--public-url`은 허용할 주소를 설정하며 DNS, 인증서 및 프록시를 자동 구성하지 않습니다.
+
+`--help`에서 옵션 및 환경변수를 확인합니다. 공개 문서 조회 서비스이며 로그인이나 고객 데이터 조작 도구는 제공하지 않습니다. 요청 본문은 64KiB, 동시 처리는 32개, 프로세스 전체 MCP 요청은 기본 분당 600회로 제한합니다. 원격 운영에는 웹서버의 IP별 요청 제한도 함께 적용합니다.
+
 ## 연결 문제 해결
 
-- **npx를 찾을 수 없음:** Node.js 설치 후 AI 도구를 다시 시작합니다. 필요하면 설정의 `command`에 npx의 절대 경로를 지정합니다.
-- **설치 또는 시작 시간 초과:** npm 접속과 사내 프록시 설정을 확인합니다. 최초 설치가 오래 걸리면 AI 도구의 MCP 시작 제한 시간을 늘립니다.
+- **원격 주소 연결 실패:** 주소가 `https://auigrid.com/mcp`와 정확히 같은지, 끝에 슬래시가 없는지 확인합니다. 전송 방식은 Streamable HTTP이며 사내 HTTPS 접속 정책도 확인합니다.
+- **브라우저에서 HTTP 405:** 일반 웹페이지가 아닌 MCP 요청 전용 주소이므로 정상입니다. AI 도구에서 연결 상태를 확인합니다.
+- **HTTP 429:** 요청 한도를 초과했습니다. `Retry-After`에 표시된 시간 이후 다시 요청합니다.
+
+- **로컬 연결에서 npx를 찾을 수 없음:** Node.js 설치 후 AI 도구를 다시 시작합니다. 필요하면 설정의 `command`에 npx의 절대 경로를 지정합니다.
+- **로컬 설치 또는 시작 시간 초과:** npm 접속과 사내 프록시 설정을 확인합니다. 최초 설치가 오래 걸리면 AI 도구의 MCP 시작 제한 시간을 늘립니다.
 - **도구가 보이지 않음:** MCP 활성화 상태와 도구 사용 권한을 확인한 뒤 연결을 다시 시작합니다.
-- **Node.js 버전 오류:** AI 도구가 사용하는 Node.js를 22.12 이상으로 갱신합니다. 터미널과 AI 도구의 실행 경로가 다른지도 확인합니다.
+- **로컬 연결에서 Node.js 버전 오류:** AI 도구가 사용하는 Node.js를 22.12 이상으로 갱신합니다. 터미널과 AI 도구의 실행 경로가 다른지도 확인합니다.
 
 자세한 연결 방법은 [공식 MCP 사용 안내](https://www.auisoft.net/documentation/auigrid/Desc/mcp-server.html)를 참고하십시오.