@bimatrix-aud-platform/aud_mcp_server

i-AUD 플랫폼용 MCP(Model Context Protocol) Server입니다.

MTSD/design.json 검증·생성·보정, DB 쿼리 실행, 보고서 저장/동기화, MX-GRID 검증, BoxStyle 관리, WorkFlow 모듈 조회 등 Claude AI가 i-AUD 보고서를 정확하게 개발할 수 있도록 26개의 도구를 제공합니다.

설치 및 등록

방법 1: npx로 바로 사용 (권장)

별도 설치 없이 MCP 설정에 다음을 추가합니다.

Claude Code 프로젝트 설정 (.mcp.json):

{
  "mcpServers": {
    "aud_mcp_server": {
      "command": "npx",
      "args": ["-y", "@bimatrix-aud-platform/aud_mcp_server"]
    }
  }
}

Claude Desktop 전역 설정 (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "aud_mcp_server": {
      "command": "npx",
      "args": ["-y", "@bimatrix-aud-platform/aud_mcp_server"]
    }
  }
}

방법 2: 글로벌 설치 후 사용

npm install -g @bimatrix-aud-platform/aud_mcp_server

MCP 설정:

{
  "mcpServers": {
    "aud_mcp_server": {
      "command": "aud_mcp_server"
    }
  }
}

방법 3: 로컬 경로 직접 지정

{
  "mcpServers": {
    "aud_mcp_server": {
      "command": "node",
      "args": ["C:/source/aud_report_develop/aud_mcp_server/dist/index.js"]
    }
  }
}

제공 도구 (26개)

MTSD 검증 도구

validate_mtsd

MTSD 또는 .design.json 문서 전체를 스키마 검증합니다. format='design'이면 간소화된 스키마(기본값 생략 허용)로 검증합니다.

입력: { document: <JSON 문자열 또는 객체>, format?: "mtsd" | "design" }
출력: { valid: boolean, errors?: [...] }

validate_part

MTSD 또는 .design.json 문서의 특정 부분만 검증합니다. 점진적 문서 생성 시 유용합니다.

입력: { partName: "Form", data: <JSON>, format?: "mtsd" | "design" }
출력: { valid: boolean, errors?: [...] }

partName 목록 (Display):
  LabelElement, ButtonElement, ImageElement
partName 목록 (Input):
  TextBoxElement, MaskTextBoxElement, NumberBoxElement, RichTextBoxElement,
  ComboBoxElement, MultiComboBoxElement, PickListElement,
  CheckBoxElement, RadioButtonElement, ColorSelectorElement, SliderElement,
  CalendarElement, FileUploadButtonElement
partName 목록 (Grid):
  DataGridElement, TreeGridElement, OlapGridElement, iGridElement
partName 목록 (Chart/Container):
  ChartElement, GroupElement, TabElement, TableLayoutElement,
  UserComponentElement, WebContainerElement
partName 목록 (공통):
  ReportInfo, DataSource, DataSources, Form, Element,
  Variable, Module, ExecutionPlan, ServerScript, MetaDataSources

MTSD 스키마 조회 도구

get_schema_info

특정 타입의 스키마 정보(필수/선택 속성, 속성별 설명)를 반환합니다.

입력: { typeName: "Form" }
출력: { required: [...], optional: [...], properties: {...} }

typeName 목록 (공통):
  ReportInfo, DataSource, DataSources, Form, Element,
  Position, Style, Font, Border, Background
typeName 목록 (Element 타입):
  LabelElement, ButtonElement, ImageElement, TextBoxElement, MaskTextBoxElement,
  NumberBoxElement, RichTextBoxElement, ComboBoxElement, MultiComboBoxElement,
  PickListElement, CheckBoxElement, RadioButtonElement, ColorSelectorElement,
  SliderElement, CalendarElement, FileUploadButtonElement,
  DataGridElement, TreeGridElement, OlapGridElement, iGridElement, GridColumn,
  ChartElement, GroupElement, TabElement, TableLayoutElement,
  UserComponentElement, WebContainerElement
typeName 목록 (비 Element):
  Variable, Module, ExecutionPlan, ServerScript,
  MetaDataSources, MetaField, ConditionSet

get_element_types

사용 가능한 모든 Element 타입의 목록과 설명을 반환합니다.

입력: {} (파라미터 없음)
출력: { elementTypes: [{ type, description }, ...] }

get_root_structure

MTSD 문서의 루트 구조(최상위 필수/선택 속성)를 반환합니다.

입력: {} (파라미터 없음)
출력: { required: [...], properties: {...} }

MTSD 생성 도구

generate_element

간소화된 입력으로 완전한 Element JSON을 생성합니다. 도킹, 폰트, 배경, 테두리 등의 단축 표기를 지원합니다.

입력: {
  type: "Label",          // 필수. Element 타입
  id: "LBL001",           // 선택. 생략 시 자동 생성
  text: "제목",            // 선택. 표시 텍스트
  position: { left: 10, top: 10, width: 200, height: 30 },
  docking: "top",          // 단축: left, right, top, bottom, fill, left+right 등
  font: { size: 14, bold: true, color: "#333333", align: "center" },
  background: "#FFFFFF",
  border: "solid 1px #DDD",
  compact: false           // true이면 기본값과 동일한 속성 제거 (.design.json용)
}
출력: { success: true, element: <완전한 Element JSON>, warnings?: [...] }

generate_grid_column

간소화된 입력으로 DataGrid의 GridColumn 배열을 생성합니다.

입력: {
  columns: [
    { name: "USER_ID", header: "사용자ID", width: 120 },
    { name: "CHK", type: "checkbox", width: 40, editable: true },
    { name: "STATUS", type: "combo", width: 100 },
    { name: "AMOUNT", align: "right", format: "#,##0" }
  ],
  compact: false
}
출력: { success: true, columns: [...], count: 4 }

generate_datasource

간소화된 입력으로 완전한 DataSource JSON을 생성합니다. SQL에서 파라미터를 자동 추출합니다.

입력: {
  name: "DS_USER",           // 필수
  connection: "CONN_CODE",   // 필수
  sql: "SELECT * FROM USERS WHERE USER_ID = @VS_USER_ID",
  columns: [{ name: "USER_ID" }, { name: "USER_NM" }],
  dsType: 0,                 // 0:DataSource, 1:MetaData, 2:Template, 3:ServerDataSource
  useMeta: false,
  useCache: false,
  compact: false
}
출력: { success: true, dataSource: <완전한 DataSource JSON> }

generate_olap_fields

OlapGrid의 iOLAPView.Fields 배열을 생성합니다. Dimension/Measure 분류, Area 자동 배치, SummaryType 설정이 완료된 OlapField 배열을 반환합니다.

입력: {
  columns: [
    { name: "DEPT_NM", caption: "부서명", type: "string" },
    { name: "SALE_AMT", caption: "매출액", type: "number", summaryType: "sum" }
  ],
  autoPlace: true,       // Area 자동 배치 (기본: true)
  includeOptions: false, // iOLAPView 전체 구조 포함 여부
  compact: false
}
출력: { success: true, fields: [...] }

generate_uuid

i-AUD 보고서용 UUID를 생성합니다. prefix + 32자리 HEX 형식입니다.

입력 (단일):
  { prefix: "Label", count: 3 }
입력 (다중 prefix):
  { items: [{ prefix: "Label", count: 2 }, { prefix: "DS", count: 1 }] }
출력: { ids: [...] }

build_mtsd

MtsdBuilder Fluent API를 사용하는 JavaScript 스크립트를 실행하여 MTSD 문서를 생성합니다.

입력: {
  script: "const doc = new MtsdBuilder('보고서명'); doc.addLabel(...); return doc.build();"
}
출력: <완전한 MTSD JSON>

MTSD 보정 도구

fix_mtsd

MTSD 문서 파일(.design.json, .mtsd, .sc)을 읽어 자동 보정 규칙을 적용하고 파일을 덮어씁니다.

입력: { path: "C:/reports/sample/sample.design.json" }
출력: { success: true, fixCount: 5, fixes: [...] }

보정 항목:
  [Rule1] DataSource Name→Id 참조 보정
  [Rule2] OlapGrid DataSource 기반 Fields 자동 생성
  [Rule2-2] OlapGrid Fields 내 CreateType=1 중복 보정 (#MEASURES_HEADER#만 허용)
  [Rule3] Enum/Range 값 범위 초과 보정 (Border.LineType, Font 정렬, Color RGBA clamp, GridColumn/OlapField 속성 등)
  Params ParamType 누락 보정

검증 도구

validate_module

모듈 JSON(.module.json) 파일을 검증합니다. 스키마 준수 여부 및 비즈니스 로직 경고를 포함합니다.

입력 (둘 중 하나):
  { path: "C:/reports/sample/모듈제목.module.json" }
  { document: <JSON 문자열 또는 객체> }
출력: { valid: boolean, warnings?: [...], errors?: [...] }

validate_mxgrid

MX-GRID 템플릿(.json2) 및 데이터셋(.ds) 파일을 검증합니다. 스타일/시트 참조 불일치 등 비즈니스 로직 경고도 포함합니다.

입력 (파일 경로):
  { path: "C:/reports/sample/template.json2" }
입력 (JSON 직접):
  { document: <JSON>, type: "json2" | "ds" }
출력: { valid: boolean, warnings?: [...], errors?: [...] }

컨트롤 정보 도구

get_control_info

MTSD 파일에서 컨트롤의 Name과 Type 매핑 정보를 추출합니다. TypeScript 스크립트 작성 시 타입 확인 또는 import 문 생성에 사용합니다.

입력: { path: "C:/reports/sample/sample.mtsd", name: "GRD001" }
  - name 생략 시 전체 컨트롤 목록 반환
출력: { controls: [{ name: "GRD001", type: "DataGrid" }, ...] }

i-AUD 서버 연동 도구

get_dbms_list

현재 사용자에게 권한이 있는 데이터베이스 연결(DBMS) 목록을 조회합니다.

입력: {} (파라미터 없음)
출력: { connections: [{ connectionCode, name, dbType }, ...] }

execute_query

i-AUD 서버를 통해 SQL 쿼리를 실행하고 결과를 반환합니다.

입력: {
  connectionCode: "AUD_SAMPLE_DB",
  sql: "SELECT * FROM USERS WHERE USER_ID = :VS_USER_ID",
  limitRows: 100,           // 기본: 100, 최대: 1000
  params: { "VS_USER_ID": "U001" }
}
출력: { rows: [...], columns: [...] }

get_table_list

i-AUD 메타 데이터에서 테이블/뷰 목록을 조회합니다.

입력: {
  connectionCode: "AUD_SAMPLE_DB",
  filter: "USER",          // 검색어 (선택)
  limitRows: 500
}
출력: { tables: [{ TABLE_ID, SCHEMA_NM, TABLE_NM, TABLE_DESC }, ...] }

get_table_columns

특정 테이블의 컬럼 목록을 조회합니다.

입력: {
  connectionCode: "AUD_SAMPLE_DB",
  tableId: "TABLE_ID값"    // get_table_list 결과의 TABLE_ID
}
출력: { columns: [{ COLUMN_NM, DATA_TYPE, DATA_LEN, IS_PK, NULLABLE, COLUMN_DESC }, ...] }

get_boxstyle_list

i-AUD 서버에서 BoxStyle 목록을 조회합니다.

입력: {} (파라미터 없음)
출력: { boxStyles: [{ Name, StyleName, Background, Border, Font }, ...] }

save_boxstyle

i-AUD 서버에 BoxStyle을 저장(생성/수정)합니다. 단일 객체 또는 배열로 여러 개를 한 번에 저장할 수 있습니다.

입력: {
  boxStyle: {
    Name: "BTN_DEFAULT",
    StyleName: "기본 버튼 스타일",
    Background: { ColorR: 66, ColorG: 133, ColorB: 244, ColorA: 1 },
    Border: { LineType: "solid", Thickness: "1,1,1,1", CornerRadius: "4,4,4,4" },
    Font: { Bold: true, Size: 13, HorizontalAlignment: "center" }
  }
}
출력: { success: true }

save_report

보고서를 i-AUD 서버에 저장(Publish)합니다. MTSD, DataSource, ServerScript, JScript를 수집하여 서버에 전송하고 .mtsd 및 .design.json 파일을 갱신합니다.

입력: {
  reportPath: "C:/reports/sample",  // .design.json 또는 .mtsd가 있는 폴더
  build: false                       // TypeScript 빌드(tsc) 실행 여부
}
출력: { success: true, ... }

pull_report

i-AUD 서버에서 보고서의 최신 내용을 로컬 폴더에 동기화합니다. .mtsd 및 .design.json을 생성/갱신합니다.

입력: {
  reportPath: "C:/reports/sample"
}
출력: { success: true, ... }

run_designer

i-AUD Designer를 브라우저에서 실행합니다.

입력: {
  reportPath: "C:/reports/sample"
}
출력: { success: true, url: "..." }

WorkFlow 모듈 도구

get_module_list

i-AUD 서버에서 WorkFlow 모듈 목록을 조회합니다.

입력: {
  filter: "검색어",   // 선택. 모듈명/설명에서 검색
  limitRows: 500
}
출력: { modules: [{ MODULE_CODE, MODULE_NM, ... }, ...] }

get_module_params

특정 모듈의 파라미터 목록을 조회합니다.

입력: {
  moduleCode: "MODULE_CODE값"   // get_module_list로 조회
}
출력: { params: [{ PARAM_NM, PARAM_TYPE, ... }, ...] }

프로젝트 구조

aud_mcp_server/
├── src/
│   ├── index.ts                  # MCP 서버 메인 (도구 정의 + 핸들러)
│   ├── generators/
│   │   ├── element.ts            # generate_element 구현
│   │   ├── grid-column.ts        # generate_grid_column 구현
│   │   ├── datasource.ts         # generate_datasource 구현
│   │   ├── olap-field.ts         # generate_olap_fields 구현
│   │   ├── compact.ts            # compact 출력 변환
│   │   ├── mtsd-builder.ts       # build_mtsd 구현
│   │   ├── fixer.ts              # fix_mtsd 구현
│   │   ├── control-info.ts       # get_control_info 구현
│   │   └── defaults.ts           # Element 기본값 정의
│   └── utils/
│       ├── aud-api-client.ts     # i-AUD 서버 API 클라이언트
│       ├── report-publisher.ts   # save_report / pull_report 구현
│       ├── mtsd-file-ref.ts      # .design.json 파일 경로 참조 처리
│       ├── color.ts              # 색상 변환 유틸
│       ├── docking.ts            # 도킹 단축 표기 변환
│       └── uuid.ts               # UUID 생성
├── schemas/
│   ├── mtsd.schema.json          # MTSD JSON Schema (AJV 검증용)
│   ├── design.schema.json        # .design.json JSON Schema (간소화 형식)
│   ├── module.schema.json        # 모듈 JSON Schema
│   ├── json2.schema.json         # MX-GRID 템플릿 Schema
│   └── ds.schema.json            # MX-GRID 데이터셋 Schema
├── dist/                         # 빌드 결과물
├── package.json
├── tsconfig.json
└── README.md

사용 예시

MTSD 문서 생성 워크플로우

1. get_root_structure로 전체 구조 파악
2. get_schema_info로 각 섹션의 필수/선택 속성 확인
3. generate_element, generate_grid_column, generate_datasource로 각 파트 생성
4. validate_part로 부분별 즉시 검증
5. 전체 완성 후 validate_mtsd로 최종 검증
6. fix_mtsd로 자동 보정 적용
7. save_report로 서버에 저장

보고서 서버 동기화 워크플로우

1. pull_report로 서버→로컬 최신 내용 동기화
2. 로컬에서 코드 수정
3. save_report(build: true)로 빌드 후 서버에 저장
4. run_designer로 브라우저에서 결과 확인

DB 스키마 탐색 워크플로우

1. get_dbms_list로 연결 코드 확인
2. get_table_list로 테이블 검색
3. get_table_columns로 컬럼 구조 확인
4. execute_query로 샘플 데이터 조회
5. generate_datasource로 DataSource JSON 생성

모듈 생성 워크플로우

1. JavaScript 스크립트 작성
2. .module.json 파일 구성 (TYPE, MTX_MODULE_INFO, MTX_MODULE_PARAMS)
3. validate_module로 스키마 + 비즈니스 로직 검증

TypeScript 전환 워크플로우

1. get_control_info로 MTSD에서 컨트롤 Name→Type 매핑 추출
2. 타입 정보를 기반으로 Matrix.getObject() 호출에 타입 어노테이션 추가

요구사항

• Node.js >= 18.0.0

라이선스

MIT