auigrid-mcp-server 0.2.0 → 0.3.0

package/README.md

@@ -6,7 +6,49 @@ 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)
 
-## 시작하기
+## 연결 방식
+
+기존 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"
+    }
+  }
+}
+```
+
+VS Code의 `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "auigrid": {
+      "type": "http",
+      "url": "https://auigrid.com/mcp"
+    }
+  }
+}
+```
+
+다른 AI 도구도 원격 MCP URL 입력란에 같은 주소를 지정합니다. 원격 서비스의 자료 버전은 `list_versions`로 확인합니다. 운영자가 배포한 자료를 조회하며 고객이 npm 패키지를 갱신할 필요는 없습니다.
+
+설정 형식: [Cursor 공식 안내](https://cursor.com/docs/mcp), [VS Code 공식 안내](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
+
+## 로컬 npm으로 시작하기
 
 Node.js **22.12 이상**과 로컬 MCP(stdio)를 지원하는 AI 개발 도구가 필요합니다. 아래 설정을 추가하면 AI 도구가 `npx`로 패키지를 받아 실행합니다. 별도의 웹서버 운영이나 소스 빌드는 필요하지 않습니다.
 
@@ -88,7 +130,7 @@ Cursor의 MCP 설정 또는 VS Code의 `MCP: List Servers`에서 서버를 활
 
 MCP는 패키지에 포함된 공식 문서와 예제를 읽습니다. 그리드 실행 엔진이나 고객 데이터에 접근하지 않으며, 코드 작성과 수정은 연결한 AI 도구가 수행합니다. 예제를 실행할 때는 AUIGrid 엔진과 해당 라이선스를 별도로 준비해야 합니다.
 
-AUIGrid 제품, MCP 패키지와 `aui-grid` 타입 패키지의 버전은 각각 관리합니다. 지원하는 문서 버전은 `list_versions`로 확인하십시오. 새 자료가 게시되면 MCP를 다시 시작해 갱신합니다. 특정 MCP 패키지 버전을 유지하려면 설정의 `@latest`를 해당 버전으로 바꿉니다.
+AUIGrid 제품, MCP 패키지와 `aui-grid` 타입 패키지의 버전은 각각 관리합니다. 지원하는 문서 버전은 `list_versions`로 확인하십시오. 로컬 방식은 새 자료가 게시되면 MCP를 다시 시작해 갱신합니다. 원격 방식은 운영 서버에서 자료를 갱신합니다. 특정 MCP 패키지 버전을 유지하려면 설정의 `@latest`를 해당 버전으로 바꿉니다.
 
 ## 기존 0.1.1에서 전환하기
 
@@ -112,8 +154,24 @@ AUIGrid 제품, MCP 패키지와 `aui-grid` 타입 패키지의 버전은 각각
 
 자세한 호출 예는 [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
+```
+
+`--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`에 표시된 시간 이후 다시 요청합니다.
+
 - **npx를 찾을 수 없음:** Node.js 설치 후 AI 도구를 다시 시작합니다. 필요하면 설정의 `command`에 npx의 절대 경로를 지정합니다.
 - **설치 또는 시작 시간 초과:** npm 접속과 사내 프록시 설정을 확인합니다. 최초 설치가 오래 걸리면 AI 도구의 MCP 시작 제한 시간을 늘립니다.
 - **도구가 보이지 않음:** MCP 활성화 상태와 도구 사용 권한을 확인한 뒤 연결을 다시 시작합니다.