MapSpring MCP 서버

MapSpring은 엔터프라이즈 데이터베이스 스키마 탐색 및 Spring Boot 에코시스템(MyBatis, JPA) 연동에 특화된 Model Context Protocol (MCP) 서버입니다.

표준 입출력(stdio)을 통해 동작하므로, Claude Desktop이나 Cursor 등의 MCP 호스트 환경에서 손쉽게 연동하여 사용할 수 있습니다.

---

주요 기능

• 이중 실행 모드 (Dual Execution Modes):
  • Online 연결 모드 (--url): PostgreSQL, MySQL, MariaDB, Oracle, Tibero, Microsoft SQL Server (MSSQL)에 직접 연결하여 실시간 스키마 카탈로그 정보를 쿼리합니다.
  • Offline DDL 모드 (--ddl-path): 외부 DB 접근이 차단된 망분리 환경 등에서 로컬 .sql 또는 .ddl 테이블 정의서를 직접 파싱해 메타데이터를 추출합니다.
• 코드 생성 엔진 (Code Generation Engine):
  • 네이밍 변환: 데이터베이스 물리 칼럼명(Snake_Case, 예: USER_ID)을 Java 표준 카멜케이스(CamelCase, 예: userId)로 자동 변환합니다. TB_ 또는 V_와 같은 접두사는 자동으로 제거되어 클래스 이름이 생성됩니다.
  • MyBatis 지원: XML <resultMap> 맵핑 블록과 전용 DTO 클래스 코드를 한 번에 생성합니다.
  • JPA 지원: 표준 JPA 어노테이션 및 유효성 검증 어노테이션(@NotNull, @Size)이 적용된 @Entity 클래스 코드를 빌드합니다.
• Zero Assumption 제약 (Anti-Hallucination): 데이터 구조를 임의로 추측(Hallucination)하지 않으며, 스키마 정의가 발견되지 않을 경우 엄격하게 에러 메세지를 반환합니다.

---

설치 및 빌드 방법

Node.js (>= v18) 환경이 필요합니다.

1. 저장소를 복사하고 의존성을 설치합니다:

   git clone https://github.com/ghdquddnr/map-spring-MCP.git
   cd map-spring-MCP
   npm install
   

2. 프로젝트를 빌드합니다:

   npm run build
   

---

MCP 호스트 환경 설정

Claude Desktop 또는 Cursor 등의 MCP 설정 파일(mcp_config.json)에 아래와 같이 MapSpring을 등록하여 사용합니다:

1. Offline 모드 (망분리 환경)

{
  "mcpServers": {
    "mapspring": {
      "command": "node",
      "args": [
        "/absolute/path/to/map-spring-MCP/dist/index.js",
        "--ddl-path",
        "/absolute/path/to/your/ddl/folder"
      ]
    }
  }
}

2. Online 연결 모드

{
  "mcpServers": {
    "mapspring": {
      "command": "node",
      "args": [
        "/absolute/path/to/map-spring-MCP/dist/index.js",
        "--url",
        "postgresql://username:password@localhost:5432/db"
      ]
    }
  }
}

---

제공되는 MCP 도구 (Tools)

연결이 완료되면 MapSpring은 다음과 같은 도구들을 제공합니다:

list_tables

활성화된 데이터베이스 또는 지정된 DDL 디렉토리에 존재하는 테이블 목록을 조회합니다.

get_table_schema

테이블의 구조와 코멘트 정보를 정교한 Markdown 테이블 형식으로 반환합니다.

• 파라미터:
  • table_name (string, 필수): 조회할 테이블의 물리 명칭 (예: TB_SETTLE_MASTER).

generate_mybatis_mapper

테이블에 대응하는 MyBatis XML <resultMap> 매핑 블록과 DTO 클래스 소스코드를 생성합니다.

• 파라미터:
  • table_name (string, 필수)
  • dto_package (string, 선택): 생성될 DTO의 패키지명 (기본값: com.company.project.domain.dto).

generate_jpa_entity

JPA 매핑 선언 및 유효성 어노테이션이 완벽하게 구성된 Spring Boot JPA Entity 클래스 소스코드를 생성합니다.

• 파라미터:
  • table_name (string, 필수)
  • entity_package (string, 선택): 생성될 Entity의 패키지명 (기본값: com.company.project.domain.entity).

---

라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다.