auigrid-mcp-server 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +74 -18
  2. package/content/catalog.json +1 -1
  3. package/dist/catalog.js +62 -21
  4. package/dist/tools.js +8 -7
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -6,20 +6,32 @@ AUIGrid 3.0.18부터 제공하며 npm 패키지 이름은 **`auigrid-mcp-server`
6
6
 
7
7
  [공식 MCP 사용 안내](https://www.auisoft.net/documentation/auigrid/Desc/mcp-server.html) | [npm 패키지](https://www.npmjs.com/package/auigrid-mcp-server)
8
8
 
9
+ 이 패키지는 **AUIGrid 3.0.19** 문서와 예제를 포함합니다. 백분율 표시 및 편집 렌더러, 셀 범위 이동과 복사, 그룹 칼럼 숨김, 병합 헤더 이동 및 내보내기 레이아웃을 조회할 수 있습니다. 원격 서버의 자료 버전은 `list_versions`로 확인하십시오.
10
+
11
+ **AUIGrid 3.0.18 사용자도 이용할 수 있습니다.** 조회 도구의 `version`에 `3.0.18` 또는 `3.0.18.1` 같은 패치 버전을 지정하면 현재 3.0.19 자료에서 기능별 지원 여부를 판정합니다. 신규 기능은 필요한 버전을 안내하며, 지원하는 기능의 상세 문서와 예제를 조회할 수 있습니다.
12
+
9
13
  ## 연결 방식
10
14
 
11
- 기존 npm 로컬 연결(stdio)을 유지하면서 원격 Streamable HTTP 연결을 추가합니다. 두 방식은 같은 다섯 조회 도구를 사용합니다.
15
+ 원격 Streamable HTTP 연결(권장)과 로컬 npm 연결(stdio)을 제공합니다. 두 방식은 같은 다섯 조회 도구를 사용합니다.
12
16
 
13
17
  | 방식 | 실행 위치 | 고객 준비 사항 |
14
18
  | --- | --- | --- |
19
+ | 원격 URL (권장) | AUIGrid 운영 서버 | Streamable HTTP 지원 AI 도구와 인터넷 연결 |
15
20
  | 로컬 npm | 고객 PC에서 AI 도구가 실행 | Node.js 22.12 이상 |
16
- | 원격 URL | AUIGrid 운영 서버 | Streamable HTTP 지원 AI 도구와 인터넷 연결 |
17
21
 
18
- ### 원격 URL 연결 (서비스 준비 중)
22
+ ### 원격 URL 연결 (권장)
23
+
24
+ 원격 MCP 서버 주소는 **`https://auigrid.com/mcp`**입니다. `https://`를 포함하고 주소 끝에 슬래시(`/`)를 붙이지 않습니다. 전송 방식은 **Streamable HTTP**이며, 인증 없이 공개 문서와 예제를 읽기 전용으로 조회합니다. 로그인이나 API 키 설정, 고객 PC의 Node.js 및 MCP 패키지 설치는 필요하지 않습니다.
25
+
26
+ 로컬 연결과 원격 연결 중 하나를 선택합니다. 기존 설정이 있다면 다른 MCP 서버 항목은 유지하고 `auigrid` 항목을 추가하거나 변경합니다.
19
27
 
20
- 공개 예정 주소는 **`https://auigrid.com/mcp`**입니다. 현재는 운영 서버 연결을 준비 중이며, 아래 설정은 공개 완료 후 사용합니다. 고객 PC에 Node.js나 MCP 패키지를 설치할 필요가 없습니다. 기존 stdio 설정과 원격 설정 중 한 가지를 선택합니다.
28
+ **Claude Code** — 사용할 프로젝트의 터미널에서 실행합니다.
29
+
30
+ ```sh
31
+ claude mcp add --transport http auigrid https://auigrid.com/mcp
32
+ ```
21
33
 
22
- Cursor의 `.cursor/mcp.json`:
34
+ **Cursor** — 프로젝트의 `.cursor/mcp.json`에 추가합니다.
23
35
 
24
36
  ```json
25
37
  {
@@ -31,7 +43,7 @@ Cursor의 `.cursor/mcp.json`:
31
43
  }
32
44
  ```
33
45
 
34
- VS Code의 `.vscode/mcp.json`:
46
+ **VS Code** — 프로젝트의 `.vscode/mcp.json`에 추가합니다. 최상위 키는 **`servers`**이며, Cursor의 `mcpServers`와 다릅니다.
35
47
 
36
48
  ```json
37
49
  {
@@ -44,9 +56,19 @@ VS Code의 `.vscode/mcp.json`:
44
56
  }
45
57
  ```
46
58
 
47
- 다른 AI 도구도 원격 MCP URL 입력란에 같은 주소를 지정합니다. 원격 서비스의 자료 버전은 `list_versions`로 확인합니다. 운영자가 배포한 자료를 조회하며 고객이 npm 패키지를 갱신할 필요는 없습니다.
59
+ **Codex CLI** — 터미널에서 실행합니다.
48
60
 
49
- 설정 형식: [Cursor 공식 안내](https://cursor.com/docs/mcp), [VS Code 공식 안내](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
61
+ ```sh
62
+ codex mcp add auigrid --url https://auigrid.com/mcp
63
+ ```
64
+
65
+ **다른 MCP 지원 도구** — Claude의 사용자 지정 커넥터 등에서 원격 MCP 서버로 `https://auigrid.com/mcp`를 등록하고 전송 방식을 Streamable HTTP로 선택합니다.
66
+
67
+ 연결 후 AI에게 `list_versions`로 사용 가능한 문서 버전을 확인하도록 요청하십시오. 원격 자료는 운영 서버에서 갱신하므로 고객이 npm 패키지를 갱신할 필요는 없습니다.
68
+
69
+ 브라우저 주소창에서 `https://auigrid.com/mcp`를 열면 **HTTP 405**가 표시됩니다. MCP 요청만 처리하는 주소이므로 정상입니다. **HTTP 429**는 요청 한도를 초과했다는 뜻이며 응답의 `Retry-After`에 표시된 시간 이후 다시 요청합니다.
70
+
71
+ 설정 형식: [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/).
50
72
 
51
73
  ## 로컬 npm으로 시작하기
52
74
 
@@ -114,27 +136,60 @@ Cursor의 MCP 설정 또는 VS Code의 `MCP: List Servers`에서 서버를 활
114
136
 
115
137
  > exportToXlsx와 useExportStyle 문서를 찾아 화면과 내보내기 스타일을 분리하는 예제를 작성해 줘.
116
138
 
139
+ ## 비상업용 버전의 CDN으로 빠르게 시작하기
140
+
141
+ AUIGrid는 비상업용 버전의 CDN을 제공합니다. 정품은 CDN으로 제공하지 않습니다. 비상업용 목적의 `localhost` 또는 `127.0.0.1`에서 무료로 시작할 수 있습니다. MCP에 포함된 시작 안내와 HTML 예제를 사용하면 AI가 CDN을 연결하고 데이터를 넣어 실행 가능한 그리드를 작성할 수 있습니다.
142
+
143
+ > AUIGrid MCP에서 비상업용 CDN 시작 예제를 찾아줘. localhost에서 실행할 HTML 하나에 데이터를 넣고 정렬, 필터 및 편집이 가능한 그리드를 만들어줘.
144
+
145
+ 1. `search_docs`에서 `CDN`, `비상업용`, `무료`, `시작하기`로 검색합니다.
146
+ 2. `get_api`에 `id: "Desc/noncommercial.html"`을 전달하여 연결 방법과 사용 조건을 확인합니다.
147
+ 3. `list_examples`에서 `query: "CDN"`으로 예제를 찾고, `get_example`에 `id: "noncommercial-cdn-vanilla-js"`를 전달하여 HTML을 조회합니다.
148
+ 4. 작성한 HTML을 로컬 웹 서버에서 열고 데이터를 바꾸며 사용합니다. 별도 데이터 파일이나 WebDemo의 PHP 공통 파일은 필요하지 않습니다.
149
+
150
+ React/Vue 프로젝트에 적용할 때는 프레임워크와 JavaScript/TypeScript 사용 여부를 함께 알려 해당 샘플과 래퍼를 참고하도록 요청하십시오.
151
+
152
+ [비상업용 CDN 시작 안내](https://www.auisoft.net/documentation/auigrid/Desc/noncommercial.html) | [GitHub 다운로드 및 사용 조건](https://github.com/aui-community/auigrid-noncommercial#readme)
153
+
154
+ localhost 이외의 도메인이나 IP에서 테스트하려면 [평가판 다운로드](https://www.auisoft.net/dcenter.html)를 이용할 수 있습니다. AI에는 `get_api`의 `Desc/noncommercial.html`에서 평가판 안내를 확인하고, 내려받은 평가판 파일로 연결하도록 요청하십시오.
155
+
117
156
  ## 제공 도구
118
157
 
119
158
  | 도구 | 기능 |
120
159
  | --- | --- |
121
- | `list_versions` | 포함된 문서, 제품과 npm 타입 패키지의 버전 확인 |
160
+ | `list_versions` | 포함된 문서/엔진, 조회 가능한 제품과 npm 타입 패키지의 버전 확인 |
122
161
  | `search_docs` | 한글 키워드 또는 API 이름으로 공식 문서 검색 |
123
- | `get_api` | 설명, 기본값, 도입 버전과 대응 TypeScript 선언 조회 |
162
+ | `get_api` | 지원 여부 판정 후 설명, 기본값, 버전과 대응 TypeScript 선언 조회 |
124
163
  | `list_examples` | 기능, 프레임워크와 언어에 맞는 예제 검색 |
125
164
  | `get_example` | 실제 예제 코드와 관련 파일, 의존성 및 실행 조건 조회 |
126
165
 
127
166
  기본 그리드, 밴드형 레이아웃, 반응형 화면, 편집과 내보내기 예제를 제공합니다. JavaScript 기본 예제와 React, Vue의 JavaScript 및 TypeScript 예제 중 실제로 포함된 조합을 조회할 수 있습니다.
128
167
 
168
+ ### 3.0.18 제품에서 이용하기
169
+
170
+ AI 도구에 사용 중인 제품 버전을 함께 알려 주십시오.
171
+
172
+ > AUIGrid 3.0.18을 사용 중이야. MCP 조회에 version을 3.0.18로 지정하고, since가 3.0.19인 API는 제외해서 작성해줘.
173
+
174
+ `search_docs`, `get_api`, `list_examples`, `get_example` 모두 같은 버전 지정 방식을 사용합니다. 현재 허용 제품은 `3.0.18`, `3.0.19`와 각 제품의 패치 버전이며, `list_versions`의 `acceptedProductVersions`와 `acceptsPatchVersions`에서 확인할 수 있습니다.
175
+
176
+ 응답의 `requestedVersion`은 요청한 제품 버전, `version`은 실제 자료 버전입니다. 예를 들어 `3.0.18`을 요청해도 `version`은 `3.0.19`이며 이전 제품에는 `compatibilityNote`를 함께 반환합니다. 과거 문서판을 제공하는 것은 아닙니다.
177
+
178
+ MCP의 **`since`는 최초 제공 버전인 3.0.18부터 시작**합니다. 그 이전부터 있던 기능은 `since: "3.0.18"`, 3.0.19에서 추가한 기능은 `since: "3.0.19"`로 표시합니다. 공식 원본에 기록된 실제 API 도입 이력은 `introducedVersion`에 보존하며, 기록이 없으면 `null`입니다. 공식 HTML과 TypeScript의 기존 도입 버전은 바꾸지 않습니다.
179
+
180
+ 검색 결과와 예제 목록의 `available`은 요청한 제품이 해당 `since` 기준을 충족하는지 나타냅니다. `available: false`인 API 또는 예제를 상세 조회하면 **`isError: true`, `code: "VERSION_NOT_AVAILABLE"`**와 필요한 버전을 반환하며 상세 코드와 예제 파일은 제공하지 않습니다. 예를 들어 3.0.18에서 `PercentageRenderer`를 요청하면 3.0.19 이상이 필요하다는 안내를 받습니다. 렌더러 대표 문서, 대응 TypeScript 타입과 예제에 같은 기준을 적용합니다.
181
+
182
+ `available: true`는 도입 기준 충족을 의미합니다. 기존 API의 기본값, 추가 옵션, 타입과 현재 예제의 동작까지 구버전과 같다고 보장하지 않으므로 사용 중인 제품 문서와 확인하십시오.
183
+
129
184
  ## 자료와 업데이트
130
185
 
131
- MCP는 패키지에 포함된 공식 문서와 예제를 읽습니다. 그리드 실행 엔진이나 고객 데이터에 접근하지 않으며, 코드 작성과 수정은 연결한 AI 도구가 수행합니다. 예제를 실행할 때는 AUIGrid 엔진과 해당 라이선스를 별도로 준비해야 합니다.
186
+ MCP는 패키지에 포함된 공식 문서와 예제를 읽습니다. 그리드 실행 엔진이나 고객 데이터에 접근하지 않으며, 코드 작성과 수정은 연결한 AI 도구가 수행합니다. 예제를 실행할 때는 AUIGrid 엔진, 라이선스 및 CSS가 필요합니다. 비상업용 로컬 예제는 CDN으로 연결하거나 GitHub에서 내려받아 사용하며, 상용 환경에서는 해당 환경에 맞는 제품 배포본과 라이선스를 사용합니다.
132
187
 
133
188
  AUIGrid 제품, MCP 패키지와 `aui-grid` 타입 패키지의 버전은 각각 관리합니다. 지원하는 문서 버전은 `list_versions`로 확인하십시오. 로컬 방식은 새 자료가 게시되면 MCP를 다시 시작해 갱신합니다. 원격 방식은 운영 서버에서 자료를 갱신합니다. 특정 MCP 패키지 버전을 유지하려면 설정의 `@latest`를 해당 버전으로 바꿉니다.
134
189
 
135
190
  ## 기존 0.1.1에서 전환하기
136
191
 
137
- 이 안내는 AUIGrid 3.0.18 문서를 제공하는 새 구현을 기준으로 합니다. 기존 `auigrid-mcp-server@0.1.1`과 도구 호출 형식이 다릅니다. 패키지 이름과 npx 실행 명령은 같지만, **Node.js 18 이상에서 22.12 이상으로 실행 조건이 변경**되었습니다.
192
+ 이 안내는 AUIGrid 3.0.19 문서를 제공하는 구현을 기준으로 합니다. 기존 `auigrid-mcp-server@0.1.1`과 도구 호출 형식이 다릅니다. 패키지 이름과 npx 실행 명령은 같지만, 로컬 연결의 **Node.js 실행 조건은 18 이상에서 22.12 이상으로 변경**되었습니다. 원격 연결에는 고객 PC의 Node.js가 필요하지 않습니다.
138
193
 
139
194
  | 기존 도구 | 새 도구 및 지정 방법 |
140
195
  | --- | --- |
@@ -156,10 +211,10 @@ AUIGrid 제품, MCP 패키지와 `aui-grid` 타입 패키지의 버전은 각각
156
211
 
157
212
  ## HTTP 서버 직접 실행
158
213
 
159
- HTTP 실행 기능은 현재 저장소에 추가되었으며 기존 npm 게시본 `0.2.0`에는 포함되어 있지 않습니다. 이 기능을 포함한 새 버전을 게시한 뒤 아래 명령을 사용할 수 있습니다. VPS에서 운영할 때는 검증한 버전을 고정 설치합니다.
214
+ 자체 서버를 운영할 때는 HTTP 실행 기능을 포함한 패키지를 설치한 뒤 아래 명령을 사용합니다. VPS에서는 검증한 버전을 고정 설치합니다. 공개 원격 URL에 연결하는 고객은 서버를 직접 실행할 필요가 없습니다.
160
215
 
161
216
  ```sh
162
- # HTTP 기능이 포함된 버전으로 실행할 때 사용합니다.
217
+ # HTTP 기능을 포함한 패키지를 설치한 운영 서버에서 실행합니다.
163
218
  auigrid-mcp-server --http --host 127.0.0.1 --port 3000 --public-url https://auigrid.com/mcp
164
219
  ```
165
220
 
@@ -169,12 +224,13 @@ auigrid-mcp-server --http --host 127.0.0.1 --port 3000 --public-url https://auig
169
224
 
170
225
  ## 연결 문제 해결
171
226
 
172
- - **원격 주소 연결 실패:** 서비스 공개 여부, 주소의 `/mcp` 경로와 사내 HTTPS 접속 정책을 확인합니다. 주소창의 GET 405 응답만으로 MCP 장애를 판단하지 않습니다.
227
+ - **원격 주소 연결 실패:** 주소가 `https://auigrid.com/mcp`와 정확히 같은지, 끝에 슬래시가 없는지 확인합니다. 전송 방식은 Streamable HTTP이며 사내 HTTPS 접속 정책도 확인합니다.
228
+ - **브라우저에서 HTTP 405:** 일반 웹페이지가 아닌 MCP 요청 전용 주소이므로 정상입니다. AI 도구에서 연결 상태를 확인합니다.
173
229
  - **HTTP 429:** 요청 한도를 초과했습니다. `Retry-After`에 표시된 시간 이후 다시 요청합니다.
174
230
 
175
- - **npx를 찾을 수 없음:** Node.js 설치 후 AI 도구를 다시 시작합니다. 필요하면 설정의 `command`에 npx의 절대 경로를 지정합니다.
176
- - **설치 또는 시작 시간 초과:** npm 접속과 사내 프록시 설정을 확인합니다. 최초 설치가 오래 걸리면 AI 도구의 MCP 시작 제한 시간을 늘립니다.
231
+ - **로컬 연결에서 npx를 찾을 수 없음:** Node.js 설치 후 AI 도구를 다시 시작합니다. 필요하면 설정의 `command`에 npx의 절대 경로를 지정합니다.
232
+ - **로컬 설치 또는 시작 시간 초과:** npm 접속과 사내 프록시 설정을 확인합니다. 최초 설치가 오래 걸리면 AI 도구의 MCP 시작 제한 시간을 늘립니다.
177
233
  - **도구가 보이지 않음:** MCP 활성화 상태와 도구 사용 권한을 확인한 뒤 연결을 다시 시작합니다.
178
- - **Node.js 버전 오류:** AI 도구가 사용하는 Node.js를 22.12 이상으로 갱신합니다. 터미널과 AI 도구의 실행 경로가 다른지도 확인합니다.
234
+ - **로컬 연결에서 Node.js 버전 오류:** AI 도구가 사용하는 Node.js를 22.12 이상으로 갱신합니다. 터미널과 AI 도구의 실행 경로가 다른지도 확인합니다.
179
235
 
180
236
  자세한 연결 방법은 [공식 MCP 사용 안내](https://www.auisoft.net/documentation/auigrid/Desc/mcp-server.html)를 참고하십시오.