Glossary MCP Server

표준단어(Standard Word)와 표준용어(Standard Term)를 관리하는 MCP(Model Context Protocol) 전용 서버입니다. AI 에이전트가 MCP 프로토콜을 통해 용어 검색, 등록, DDL 마이그레이션 등을 자동화합니다.

이 브랜치는 프론트엔드/UI가 제거된 MCP 서버 전용 구성입니다. 풀스택 애플리케이션은 main 브랜치를 참고하세요.

표준단어 및 표준용어 개념

표준단어 (Standard Word)

용어를 구성하는 최소 단위로, 의미적으로 더 이상 쪼개지지 않는 가장 작은 단위의 형태소(단어)입니다.

예시: 권한, 코드, 자동차, 계약, 금액

표준용어 (Standard Term)

'표준단어'의 조합으로 구성된 용어로, 정형화된 데이터 타입과 길이를 갖는 통일된 하나의 속성(컬럼) 명칭입니다.

예시: '권한' + '코드' (단어조합) = '권한코드' (용어)

표준단어 명명 규칙

• 명사형 단어만 사용 - 동사/부사/접속사/복수형/소유격 사용 불가
• 축약단어 사용 불가 - 주민번호(X), 주민등록번호(O)
• 특수문자, 띄어쓰기 사용 불가
• 숫자만 사용 불가 - 1(X), 200(X), 12월(O)
• 접두사/접미사 단독 사용 불가 - 기^납부(X), 기납부(O)
• 고유명사는 단일어 사용 - 금융 결제원(X), 금융결제원(O)
• 영문단어 사용 원칙
  • 한글화 적용 - FUND(X), 펀드(O)
  • 범용적인 경우 예외(약어, 경제/금융용어 등) - IP(O), IMF(O)

기술 스택

| 구분 | 스택 | |------|------| | Backend | Java 17, Spring Boot 3.4.1, Spring Data JPA, Spring Security, Spring AI MCP Server 1.1.4 | | Database | MariaDB 10.11.3 | | AI/NLP | KOMORAN (형태소 분석), DeepL API (번역), Ollama LLM | | Infra | Docker & Docker Compose, Gradle |

시작하기

사전 요구사항

• Java 17 이상
• Docker & Docker Compose

데이터베이스 설정

docker-compose up -d db-glossary

서버 실행

# 빌드
./gradlew build -x test

# 실행 (로컬: 7800)
./gradlew bootRun --args='--spring.profiles.active=local'

프로파일

| 프로파일 | 포트 | 용도 | |----------|------|------| | local | 7800 | 로컬 개발, MCP 인증 비활성화 가능 | | dev | 7900 | 운영/Docker |

MCP 연결

권장: npm 브릿지 패키지 (@coreit/glossary)

stdio 기반 MCP 클라이언트(Claude Desktop, Cursor 등) 대부분에서 동작합니다. 운영 환경은 기본 URL 이 패키지에 박혀있어 사용자는 API Key 만 준비하면 됩니다.

1. 내부 GUI 에 로그인 후 마이페이지에서 API Key 발급
2. 클라이언트 설정에 아래 내용 추가
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "glossary": {
      "command": "npx",
      "args": ["-y", "@coreit/glossary"],
      "env": {
        "GLOSSARY_API_KEY": "mcp_xxxxxxxx.yyyyyyyy"
      }
    }
  }
}

운영 서버 URL 은 패키지에 기본 내장되어 있습니다. 다른 환경(로컬·스테이징)에 붙이려면 GLOSSARY_MCP_URL 환경변수로 override:

"env": {
  "GLOSSARY_MCP_URL": "http://localhost:7800/mcp",
  "GLOSSARY_API_KEY": "mcp_xxxxxxxx.yyyyyyyy"
}

저장 후 클라이언트 재시작 → 도구 목록에 glossary가 노출됩니다.

대안: 직접 HTTP 연결 (Streamable HTTP 지원 클라이언트용)

Claude Desktop 최신 버전 등 HTTP MCP를 네이티브로 지원하는 클라이언트에서 사용 가능 (운영 URL 은 시스템 관리자에게 문의):

{
  "mcpServers": {
    "glossary": {
      "type": "http",
      "url": "<서버 URL>/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_API_KEY>"
      }
    }
  }
}

로컬 개발 서버로 붙일 때는 url을 http://localhost:7800/mcp로 교체하고, 필요 시 mcp.auth.enabled=false로 인증을 비활성화할 수 있습니다.

MCP Tool 목록

| Tool | 설명 | |------|------| | GlossarySearchTool | 단어/용어/도메인 검색 (5개 함수) | | GlossaryRegistrationTool | 단어/용어/도메인 등록 (3개 함수) | | GlossaryValidationTool | 유효성 검증 및 제안 (3개 함수) | | ProjectTool | 프로젝트 관리 (3개 함수) | | TermProcessTool | 자동 용어 처리 (2개 함수) | | TrmWordVerificationTool | 용어-단어 관계 검증 | | SchemaStructureTool | DB 스키마 분석 | | DdlMigrationTool | DDL 변환 (2개 함수) | | MigrationLookupTool | 마이그레이션 조회 | | DbExecutionTool | 타겟 DB에 CREATE TABLE 실행 (pending 조회 + 선택 실행) |

핵심 흐름

processTerm("사용자명")
  -> 형태소 분석 (KOMORAN)
  -> 단어 조회/등록
  -> 도메인 추론
  -> 용어 조회/등록
  -> 프로젝트 연결

상세 설계: doc/mcp-design.md, doc/mcp-tools.md

DDL 마이그레이션

레거시 DDL을 표준 용어사전 기반으로 자동 변환합니다.

• MariaDB/MySQL, Oracle DB종류 지원
• 도메인(데이터타입) 자동 추론
• Preview/Commit 단계별 처리

배포

./gradlew build -x test
# build/libs/glossary-0.0.1-SNAPSHOT.jar -> /data/glossary/app.jar 업로드
docker-compose down was-glossary
docker-compose up -d was-glossary

API 문서

백엔드 실행 후 http://localhost:7800/swagger-ui.html

문제 해결

| 문제 | 해결 | |------|------| | DB 연결 오류 | Docker 컨테이너 실행 여부 확인 | | MCP 연결 오류 | API Key 유효성 및 mcp.auth.enabled 설정 확인 | | JWT 토큰 오류 | 토큰 만료 시간 및 시크릿 키 설정 확인 |