auigrid-mcp-server 0.1.0 → 0.2.0

package/README.md

@@ -1,44 +1,122 @@
-# 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)와 별도로 사용합니다.
 
-## Tools
+[공식 MCP 사용 안내](https://www.auisoft.net/documentation/auigrid/Desc/mcp-server.html) | [npm 패키지](https://www.npmjs.com/package/auigrid-mcp-server)
 
-| 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 |
+## 시작하기
 
-## Usage
+Node.js **22.12 이상**과 로컬 MCP(stdio)를 지원하는 AI 개발 도구가 필요합니다. 아래 설정을 추가하면 AI 도구가 `npx`로 패키지를 받아 실행합니다. 별도의 웹서버 운영이나 소스 빌드는 필요하지 않습니다.
 
-Add it to your MCP client config (e.g. `.mcp.json` for Claude Code, or Claude Desktop's config):
+처음 실행하거나 패키지를 갱신할 때는 npm에 접속할 수 있어야 합니다. `-y`는 설치 확인을 자동 승인하고, `@latest`는 최신 게시 버전을 선택합니다.
+
+### Codex CLI
+
+```sh
+codex mcp add auigrid -- npx -y auigrid-mcp-server@latest
+```
+
+### 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"]
     }
   }
 }
 ```
 
-## Building from source
+### VS Code
 
-```bash
-npm install
-npm run build   # compiles TypeScript, then re-runs all indexers against vendor/
-npm start        # runs the server on stdio
+프로젝트의 `.vscode/mcp.json`에 추가합니다.
+
+```json
+{
+  "servers": {
+    "auigrid": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "auigrid-mcp-server@latest"]
+    }
+  }
+}
 ```
 
-`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/`.
+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 예제 중 실제로 포함된 조합을 조회할 수 있습니다.
+
+## 자료와 업데이트
+
+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)를 참고하십시오.
+
+## 연결 문제 해결
 
-## 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)를 참고하십시오.