koreandict-mcp-server/README.md

국립국어원 표준국어대사전 MCP 서버

# 국립국어원 표준국어대사전 MCP 서버

국립국어원 표준국어대사전 API를 MCP(Model Context Protocol) 서버로 제공하는 TypeScript 패키지입니다.

## 소개

이 프로젝트는 [국립국어원 표준국어대사전 오픈 API](https://stdict.korean.go.kr/openapi/openApiInfo.do)를 [MCP(Model Context Protocol)](https://modelcontextprotocol.io) 서버로 변환하여 제공합니다. Claude, ChatGPT 등 대규모 언어 모델(LLM)이 한국어 사전 정보에 접근하고 활용할 수 있도록 도와줍니다.

## 설치

NPM을 통해 설치할 수 있습니다:

```bash
# 전역 설치
npm install -g koreandict-mcp-server

# 로컬 프로젝트에 설치
npm install koreandict-mcp-server
```

## 설정

서버를 실행하기 전에 국립국어원에서 발급받은 API 키를 설정해야 합니다. 다음 두 가지 방법 중 하나를 선택할 수 있습니다:

### 1. 환경 변수 사용

`.env` 파일을 생성하고 API 키를 설정합니다:

```
KOREANDICT_API_KEY=your-api-key-here
```

### 2. MCP 설정 파일 사용

`mcp.json` 파일을 생성하고 다음과 같이 설정합니다:

```json
{
  "koreandict-server": {
    "command": "node",
    "args": [
      "./dist/index.js"
    ],
    "env": {
      "KOREANDICT_API_KEY": "your-api-key-here"
    }
  }
}
```

이 설정 파일은 현재 디렉토리나 홈 디렉토리의 `.cursor/mcp.json`에 위치할 수 있습니다.

## 사용 방법

### 직접 실행

패키지를 전역으로 설치한 경우 명령줄에서 다음과 같이 실행할 수 있습니다:

```bash
koreandict-mcp-server
```

### 프로그래밍 방식으로 사용

프로젝트에 패키지를 설치한 경우 다음과 같이 코드에서 사용할 수 있습니다:

```javascript
import { KoreanDictionaryMcpServer } from 'koreandict-mcp-server';

// 서버 인스턴스 생성
const server = new KoreanDictionaryMcpServer();

// 서버 시작
server.getServer().listen();
```

### MCP 클라이언트에서 사용

MCP 클라이언트(예: Cursor)에서 사용하려면, 클라이언트의 MCP 설정에 서버 정보를 추가합니다. 대부분의 경우 `~/.cursor/mcp.json` 파일을 수정해야 합니다:

```json
{
  "koreandict-server": {
    "command": "koreandict-mcp-server",
    "env": {
      "KOREANDICT_API_KEY": "your-api-key-here"
    }
  }
}
```

## 기능

### MCP 리소스

- `koreandict://word/{word}` - 단어 검색 결과를 제공합니다.
- `koreandict://pos/{pos}/word/{word}` - 품사별 단어 검색 결과를 제공합니다.

### MCP 도구

- `search-word` - 단어를 검색합니다. 검색 방식과 결과 개수를 지정할 수 있습니다.
- `search-by-pos` - 품사별로 단어를 검색합니다.

## 개발

### 저장소 클론

```bash
# 저장소 클론
git clone https://github.com/tenacl/koreandict-mcp-server.git
cd koreandict-mcp-server

# 의존성 설치
npm install

# 개발 서버 실행
npm run dev

# 빌드
npm run build
```

### 테스트

```bash
npm test
```

## 문제 해결

### MCP 연결 오류

MCP 연결 오류가 발생할 경우 다음을 확인하세요:

1. API 키가 올바르게 설정되어 있는지 확인
2. mcp.json 파일의 경로 설정이 올바른지 확인
3. 로그에 나타나는 오류 메시지 확인

## 기여하기

이슈와 풀 리퀘스트는 [GitHub 저장소](https://github.com/tenacl/koreandict-mcp-server)를 통해 제출해주세요.

## 라이선스

MIT

## 참고 자료

- [국립국어원 표준국어대사전](https://stdict.korean.go.kr)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)