auigrid-mcp-server 0.1.1 → 0.3.0

package/README.md

@@ -1,66 +1,180 @@
-# auigrid-mcp-server
+# AUIGrid MCP Server
 
-An [MCP](https://modelcontextprotocol.io) server that gives AI coding assistants (Claude Code, Claude Desktop, Cursor, etc.) direct, searchable access to the [AUIGrid](https://www.auisoft.net/) API reference — grid options, columns, cell/edit/header renderers, events, instance methods, static utilities, and real sample code — so they can write correct AUIGrid code without guessing at prop names or hallucinating methods.
+AI 개발 도구가 AUIGrid 공식 문서와 실제 예제를 조회하도록 연결하는 MCP(Model Context Protocol) 서버입니다. API의 설정값과 TypeScript 타입을 확인하고, React와 Vue 예제를 참고해 코드를 작성할 때 사용합니다.
 
-Data is built from AUIGrid's official documentation (`auisoft.net`) and its React/TSX type declarations, indexed ahead of time into a local JSON knowledge base the server searches at runtime.
+AUIGrid 3.0.18부터 제공하며 npm 패키지 이름은 **`auigrid-mcp-server`**입니다. TypeScript 타입을 제공하는 [`aui-grid`](https://www.npmjs.com/package/aui-grid)와 별도로 사용합니다.
 
-## Quick install
+[공식 MCP 사용 안내](https://www.auisoft.net/documentation/auigrid/Desc/mcp-server.html) | [npm 패키지](https://www.npmjs.com/package/auigrid-mcp-server)
 
-```bash
-# Claude Code
-claude mcp add auigrid -- npx -y auigrid-mcp-server
+## 연결 방식
 
-# Codex
-codex mcp add auigrid -- npx -y auigrid-mcp-server
+기존 npm 로컬 연결(stdio)을 유지하면서 원격 Streamable HTTP 연결을 추가합니다. 두 방식은 같은 다섯 조회 도구를 사용합니다.
+
+| 방식 | 실행 위치 | 고객 준비 사항 |
+| --- | --- | --- |
+| 로컬 npm | 고객 PC에서 AI 도구가 실행 | Node.js 22.12 이상 |
+| 원격 URL | AUIGrid 운영 서버 | Streamable HTTP 지원 AI 도구와 인터넷 연결 |
+
+### 원격 URL 연결 (서비스 준비 중)
+
+공개 예정 주소는 **`https://auigrid.com/mcp`**입니다. 현재는 운영 서버 연결을 준비 중이며, 아래 설정은 공개 완료 후 사용합니다. 고객 PC에 Node.js나 MCP 패키지를 설치할 필요가 없습니다. 기존 stdio 설정과 원격 설정 중 한 가지를 선택합니다.
+
+Cursor의 `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "auigrid": {
+      "url": "https://auigrid.com/mcp"
+    }
+  }
+}
 ```
 
-After registering, run `/mcp` in the session to confirm the server connected and its tools are visible.
+VS Code의 `.vscode/mcp.json`:
 
-## Tools
+```json
+{
+  "servers": {
+    "auigrid": {
+      "type": "http",
+      "url": "https://auigrid.com/mcp"
+    }
+  }
+}
+```
+
+다른 AI 도구도 원격 MCP URL 입력란에 같은 주소를 지정합니다. 원격 서비스의 자료 버전은 `list_versions`로 확인합니다. 운영자가 배포한 자료를 조회하며 고객이 npm 패키지를 갱신할 필요는 없습니다.
 
-| Tool | Source | Purpose |
-|---|---|---|
-| `search_api` / `get_api_entry` | `.d.ts` + Properties/Events docs | Grid options, `Column` fields, renderers, events (name, type, default, description, examples) |
-| `search_methods` / `get_method` | Methods doc | Instance methods called via `ref`, e.g. `setGridData`, `insertRow`, `exportToCsv` |
-| `search_static_utils` / `get_static_util` | StaticUtils doc | Namespace-level helpers, e.g. `AUIGrid.formatDate()`, `AUIGrid.create()` |
-| `search_samples` / `get_sample` / `list_samples` | Bundled sample code | Real working React/TSX examples (tree grid, custom editors, drag & drop, export, ...) |
-| `ping` | — | Health check |
+설정 형식: [Cursor 공식 안내](https://cursor.com/docs/mcp), [VS Code 공식 안내](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
 
-## Manual config
+## 로컬 npm으로 시작하기
 
-If you'd rather edit the client config directly instead of using the CLI above:
+Node.js **22.12 이상**과 로컬 MCP(stdio)를 지원하는 AI 개발 도구가 필요합니다. 아래 설정을 추가하면 AI 도구가 `npx`로 패키지를 받아 실행합니다. 별도의 웹서버 운영이나 소스 빌드는 필요하지 않습니다.
+
+처음 실행하거나 패키지를 갱신할 때는 npm에 접속할 수 있어야 합니다. `-y`는 설치 확인을 자동 승인하고, `@latest`는 최신 게시 버전을 선택합니다.
+
+### Codex CLI
+
+```sh
+codex mcp add auigrid -- npx -y auigrid-mcp-server@latest
+```
 
-**Claude Code / Claude Desktop** (`.mcp.json`, JSON):
+### Claude Code
+
+사용할 프로젝트의 터미널에서 실행합니다.
+
+```sh
+claude mcp add --transport stdio auigrid -- npx -y auigrid-mcp-server@latest
+```
+
+등록 후 AI 도구를 다시 시작하고 `/mcp`에서 연결 상태를 확인합니다.
+
+### Cursor
+
+프로젝트의 `.cursor/mcp.json`에 추가합니다. 기존 설정이 있다면 다른 서버 항목을 유지합니다.
 
 ```json
 {
   "mcpServers": {
     "auigrid": {
+      "type": "stdio",
       "command": "npx",
-      "args": ["-y", "auigrid-mcp-server"]
+      "args": ["-y", "auigrid-mcp-server@latest"]
     }
   }
 }
 ```
 
-**Codex** (`~/.codex/config.toml`, TOML):
+### VS Code
+
+프로젝트의 `.vscode/mcp.json`에 추가합니다.
 
-```toml
-[mcp_servers.auigrid]
-command = "npx"
-args = ["-y", "auigrid-mcp-server"]
+```json
+{
+  "servers": {
+    "auigrid": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "auigrid-mcp-server@latest"]
+    }
+  }
+}
 ```
 
-## Building from source
+Cursor의 MCP 설정 또는 VS Code의 `MCP: List Servers`에서 서버를 활성화하고 AI 대화에서 사용합니다.
+
+## 사용 예
+
+연결 후 먼저 “AUIGrid MCP의 `list_versions`로 사용할 수 있는 문서 버전을 확인해 줘”라고 요청합니다. 이어서 원하는 기능과 프레임워크를 알려 주십시오.
+
+> AUIGrid MCP에서 bodyLayoutMode의 설정값과 기본값을 확인하고, 밴드형 칼럼 레이아웃을 작성해 줘.
+
+> React TypeScript의 밴드형 기본 예제를 찾아 우리 컴포넌트에 적용해 줘. 실제 타입 선언도 확인해 줘.
+
+> exportToXlsx와 useExportStyle 문서를 찾아 화면과 내보내기 스타일을 분리하는 예제를 작성해 줘.
+
+## 제공 도구
+
+| 도구 | 기능 |
+| --- | --- |
+| `list_versions` | 포함된 문서, 제품과 npm 타입 패키지의 버전 확인 |
+| `search_docs` | 한글 키워드 또는 API 이름으로 공식 문서 검색 |
+| `get_api` | 설명, 기본값, 도입 버전과 대응 TypeScript 선언 조회 |
+| `list_examples` | 기능, 프레임워크와 언어에 맞는 예제 검색 |
+| `get_example` | 실제 예제 코드와 관련 파일, 의존성 및 실행 조건 조회 |
+
+기본 그리드, 밴드형 레이아웃, 반응형 화면, 편집과 내보내기 예제를 제공합니다. JavaScript 기본 예제와 React, Vue의 JavaScript 및 TypeScript 예제 중 실제로 포함된 조합을 조회할 수 있습니다.
 
-```bash
-npm install
-npm run build   # compiles TypeScript, then re-runs all indexers against vendor/
-npm start        # runs the server on stdio
+## 자료와 업데이트
+
+MCP는 패키지에 포함된 공식 문서와 예제를 읽습니다. 그리드 실행 엔진이나 고객 데이터에 접근하지 않으며, 코드 작성과 수정은 연결한 AI 도구가 수행합니다. 예제를 실행할 때는 AUIGrid 엔진과 해당 라이선스를 별도로 준비해야 합니다.
+
+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 이상으로 실행 조건이 변경**되었습니다.
+
+| 기존 도구 | 새 도구 및 지정 방법 |
+| --- | --- |
+| `search_api` | `search_docs`: `query`로 검색하고 필요하면 문서 경로인 `category` 지정 |
+| `get_api_entry` | `get_api`: 검색 결과의 `id`로 조회. 기존 `parent` 대신 `category`로 구분 |
+| `search_methods`, `get_method` | `search_docs`, `get_api`: `category: "DataGrid/Methods"` 지정 |
+| `search_static_utils`, `get_static_util` | `search_docs`, `get_api`: `category: "DataGrid/StaticUtils"` 지정 |
+| `search_samples`, `list_samples` | `list_examples`: `query`, `framework`, `language`로 목록 조회 |
+| `get_sample` | `get_example`: 목록에서 얻은 `id` 사용. 기존 파일명인 `name`을 그대로 넘기지 않음 |
+| `ping` | 연결 확인에는 `list_versions` 호출. 반환값은 `pong`이 아닌 자료 버전 정보 |
+
+기존 도구 이름의 별칭은 제공하지 않습니다. AI 도구를 재시작해 도구 목록을 갱신하고, 저장한 프롬프트나 자동화의 호출 이름과 인자도 변경하십시오. `kind`와 `parent`는 자동 변환되지 않으므로 검색 결과의 `id`를 사용하는 편이 정확합니다.
+
+결과는 Markdown 본문 대신 **`structuredContent` 객체와 같은 내용을 담은 JSON 텍스트**로 반환합니다. 검색과 목록의 최대 `limit`은 20이며, 긴 API는 `nextOffset`, 긴 예제는 `nextStartLine`으로 이어 읽습니다. 조회 실패는 `isError: true`로 반환하고, 검색 결과가 없으면 빈 `results`를 반환합니다.
+
+예제 ID와 제공 범위도 새로 구성했습니다. 기존 패키지의 모든 예제가 포함된 것은 아니며, `list_examples`로 사용 가능한 예제를 먼저 확인하십시오. `query`는 예제 제목과 기능, 태그를 검색하며 소스 전체를 검색하지 않습니다.
+
+자세한 호출 예는 [0.1.1 전환 안내](https://www.auisoft.net/documentation/auigrid/Desc/mcp-server.html#migration)를 참고하십시오.
+
+## HTTP 서버 직접 실행
+
+HTTP 실행 기능은 현재 저장소에 추가되었으며 기존 npm 게시본 `0.2.0`에는 포함되어 있지 않습니다. 이 기능을 포함한 새 버전을 게시한 뒤 아래 명령을 사용할 수 있습니다. VPS에서 운영할 때는 검증한 버전을 고정 설치합니다.
+
+```sh
+# HTTP 기능이 포함된 버전으로 실행할 때 사용합니다.
+auigrid-mcp-server --http --host 127.0.0.1 --port 3000 --public-url https://auigrid.com/mcp
 ```
 
-`npm run build` regenerates `data/*.json` from the vendored sources in `vendor/` (AUIGrid's type declarations and the scraped `auisoft.net` doc pages). Re-run it after updating anything under `vendor/`.
+`--http`를 생략하면 기존 stdio 방식입니다. HTTP는 `/mcp`, 상태 확인은 `/healthz`를 사용합니다. 외부 HTTPS는 웹서버에서 처리하고 Node.js로 전달합니다. `--public-url`은 허용할 주소를 설정하며 DNS, 인증서 및 프록시를 자동 구성하지 않습니다.
+
+`--help`에서 옵션 및 환경변수를 확인합니다. 공개 문서 조회 서비스이며 로그인이나 고객 데이터 조작 도구는 제공하지 않습니다. 요청 본문은 64KiB, 동시 처리는 32개, 프로세스 전체 MCP 요청은 기본 분당 600회로 제한합니다. 원격 운영에는 웹서버의 IP별 요청 제한도 함께 적용합니다.
+
+## 연결 문제 해결
+
+- **원격 주소 연결 실패:** 서비스 공개 여부, 주소의 `/mcp` 경로와 사내 HTTPS 접속 정책을 확인합니다. 주소창의 GET 405 응답만으로 MCP 장애를 판단하지 않습니다.
+- **HTTP 429:** 요청 한도를 초과했습니다. `Retry-After`에 표시된 시간 이후 다시 요청합니다.
 
-## License
+- **npx를 찾을 수 없음:** Node.js 설치 후 AI 도구를 다시 시작합니다. 필요하면 설정의 `command`에 npx의 절대 경로를 지정합니다.
+- **설치 또는 시작 시간 초과:** npm 접속과 사내 프록시 설정을 확인합니다. 최초 설치가 오래 걸리면 AI 도구의 MCP 시작 제한 시간을 늘립니다.
+- **도구가 보이지 않음:** MCP 활성화 상태와 도구 사용 권한을 확인한 뒤 연결을 다시 시작합니다.
+- **Node.js 버전 오류:** AI 도구가 사용하는 Node.js를 22.12 이상으로 갱신합니다. 터미널과 AI 도구의 실행 경로가 다른지도 확인합니다.
 
-MIT for the server code. AUIGrid itself is a commercial product of AUISoft Co., Ltd. — this project only republishes its publicly available documentation for the purpose of API lookup; it has no affiliation beyond that.
+자세한 연결 방법은 [공식 MCP 사용 안내](https://www.auisoft.net/documentation/auigrid/Desc/mcp-server.html)를 참고하십시오.