# Oh My KEGG MCP

KEGG (Kyoto Encyclopedia of Genes and Genomes) 데이터베이스에 접근하기 위한 Model Context Protocol (MCP) 서버입니다.(unofficial)

## 주요 기능

- **30개의 KEGG 도구**: 경로, 유전자, 화합물, 반응, 효소, 질병, 약물 등 다양한 생물학적 데이터 검색 및 분석
- **Streamable HTTP Transport**: 웹 환경에서 사용 가능한 HTTP 기반 통신
- **LangChain 통합**: LangChain Agent와 완벽하게 통합되어 LLM이 KEGG 데이터를 활용할 수 있음
- **Ollama 지원**: 로컬 LLM 모델과 함께 사용 가능

## 설치

### 1. 필수 패키지 설치

```bash
pip install -r requirements.txt
```

### 2. 환경 변수 설정

`.env.example` 파일을 참고하여 `.env` 파일을 생성합니다:

```bash
cp .env.example .env
```

`.env` 파일을 편집하여 필요한 값을 설정합니다:

```bash
# OpenAI API 키 (OpenAI 모델 사용 시 필요)
# Ollama 사용 시에는 설정하지 않아도 됩니다
OPENAI_API_KEY=your_openai_api_key

# MCP 서버 URL (클라이언트에서 사용)
# 서버가 다른 호스트/포트에서 실행되는 경우 변경
KEGG_MCP_SERVER_URL=http://localhost:3000/mcp

# MCP 서버 설정 (서버 실행 시 사용, 선택사항)
# 기본값이 설정되어 있어 변경하지 않아도 됩니다
MCP_HOST=localhost
MCP_PORT=3000
MCP_PATH=/mcp

# Ollama 설정 (선택사항)
# Ollama가 다른 호스트/포트에서 실행되는 경우 변경
# OLLAMA_HOST=http://localhost:11434
```

**참고**: 
- **Ollama 사용 시**: `OPENAI_API_KEY`는 설정하지 않아도 됩니다. 현재 코드는 Ollama를 기본 모델로 사용합니다.
- **OpenAI 사용 시**: `OPENAI_API_KEY`에 실제 API 키를 설정하고, `langchain_integration.py`에서 `ChatOpenAI`를 사용하도록 변경해야 합니다.
- **서버 설정**: `MCP_HOST`, `MCP_PORT`, `MCP_PATH`는 서버 실행 시 사용되며, 기본값이 설정되어 있어 변경하지 않아도 됩니다.
- **Ollama 호스트**: Ollama가 기본 포트(11434)가 아닌 다른 포트에서 실행되는 경우 `OLLAMA_HOST`를 설정할 수 있습니다.

## 사용 방법

### 1. 서버 실행

```bash
# 기본 설정으로 실행 (localhost:3000/mcp)
python kegg_mcp_server.py

# 또는 환경 변수로 설정
MCP_HOST=localhost MCP_PORT=3000 MCP_PATH=/mcp python kegg_mcp_server.py
```

서버가 실행되면 다음과 같은 메시지가 표시됩니다:
```
Starting KEGG MCP Server on http://localhost:3000/mcp
Transport: Streamable HTTP
```

### 2. 클라이언트 실행

```bash
# 기본 실행 (Streamable HTTP 사용)
python langchain_integration.py

# Ollama 연결 테스트만 실행
python langchain_integration.py --test

# stdio 사용 (선택사항, 별도 TypeScript 서버 필요)
# langchain_integration.py에서 use_http=False로 변경
# 참고: 현재는 Streamable HTTP 방식만 제공됩니다
```

## 사용 가능한 도구

### Database Information & Statistics (2개)
- `get_database_info` - 데이터베이스 정보 및 통계 조회
- `list_organisms` - 모든 KEGG 생물체 목록 조회

### Pathway Analysis (3개)
- `search_pathways` - 경로 검색
- `get_pathway_info` - 경로 상세 정보
- `get_pathway_genes` - 경로의 유전자 목록

### Gene Analysis (2개)
- `search_genes` - 유전자 검색
- `get_gene_info` - 유전자 상세 정보 (서열 포함 옵션)

### Compound Analysis (2개)
- `search_compounds` - 화합물 검색
- `get_compound_info` - 화합물 상세 정보

### Reaction & Enzyme Analysis (4개)
- `search_reactions` - 반응 검색
- `get_reaction_info` - 반응 상세 정보
- `search_enzymes` - 효소 검색
- `get_enzyme_info` - 효소 상세 정보

### Disease & Drug Analysis (5개)
- `search_diseases` - 질병 검색
- `get_disease_info` - 질병 상세 정보
- `search_drugs` - 약물 검색
- `get_drug_info` - 약물 상세 정보
- `get_drug_interactions` - 약물 상호작용 조회

### Module & Orthology Analysis (4개)
- `search_modules` - 모듈 검색
- `get_module_info` - 모듈 상세 정보
- `search_ko_entries` - KO 엔트리 검색
- `get_ko_info` - KO 상세 정보

### Glycan Analysis (2개)
- `search_glycans` - 글리칸 검색
- `get_glycan_info` - 글리칸 상세 정보

### BRITE Hierarchy Analysis (2개)
- `search_brite` - BRITE 계층 검색
- `get_brite_info` - BRITE 상세 정보

### Advanced Analysis Tools (5개)
- `get_pathway_compounds` - 경로의 화합물 목록
- `get_pathway_reactions` - 경로의 반응 목록
- `get_compound_reactions` - 화합물의 반응 목록
- `get_gene_orthologs` - 유전자 직계동족 찾기
- `batch_entry_lookup` - 배치 엔트리 조회

### Cross-References & Integration (2개)
- `convert_identifiers` - 데이터베이스 간 식별자 변환
- `find_related_entries` - 관련 엔트리 찾기

## 예제

### 기본 사용 예제

```python
import asyncio
from langchain_integration import create_kegg_client, load_and_display_tools, create_default_model, run_agent_query
from langchain.agents import create_agent

async def main():
    # 클라이언트 생성 (Streamable HTTP)
    client = create_kegg_client()
    
    try:
        # 도구 로드
        tools = await load_and_display_tools(client)
        
        # 모델 및 Agent 생성
        model = create_default_model()
        agent = create_agent(model=model, tools=tools)
        
        # 쿼리 실행
        await run_agent_query(
            agent,
            "인간의 당분해(glycolysis) 경로를 찾아주세요.",
            "당분해 경로 검색"
        )
    finally:
        if hasattr(client, 'close'):
            try:
                await client.close()
            except:
                pass

if __name__ == "__main__":
    asyncio.run(main())
```

## 프로젝트 구조

```
kegg-mcp-test/
├── kegg_mcp_server.py          # Python MCP 서버 (Streamable HTTP)
├── langchain_integration.py    # LangChain 통합 클라이언트
├── requirements.txt             # Python 패키지 의존성
├── .env.example                # 환경 변수 예제 파일
├── .gitignore                  # Git 무시 파일 목록
├── LICENSE                     # MIT 라이선스
└── README.md                    # 프로젝트 문서 (이 파일)
```

## 통신 방식

### Streamable HTTP (권장)
- **장점**: 웹 환경 지원, 확장성 좋음, 표준 HTTP 프로토콜
- **사용**: Python 서버 (`kegg_mcp_server.py`)
- **포트**: 기본 3000 (환경 변수로 변경 가능)

### stdio (로컬 전용, 선택사항)
- **장점**: 최고의 보안, 낮은 오버헤드, 간단한 설정
- **사용**: `langchain_integration.py`에서 `use_http=False`로 설정 시 사용 가능
- **제한**: 로컬 실행만 가능, 별도 TypeScript 서버 필요

## 문제 해결

### 서버가 시작되지 않는 경우
1. 포트가 이미 사용 중인지 확인: `lsof -i :3000`
2. 필요한 패키지가 설치되었는지 확인: `pip install -r requirements.txt`
3. Python 버전 확인: Python 3.11 이상 필요

### 클라이언트 연결 실패
1. 서버가 실행 중인지 확인
2. 서버 URL이 올바른지 확인: `KEGG_MCP_SERVER_URL` 환경 변수
3. 방화벽 설정 확인

### Ollama 연결 실패
1. Ollama가 실행 중인지 확인: `ollama serve`
2. 모델이 설치되었는지 확인: `ollama list`
3. 모델 다운로드: `ollama pull gemma3:4b` (또는 사용할 모델)

## 라이선스

MIT License

## 참고 자료

- [KEGG REST API 문서](https://www.kegg.jp/kegg/rest/keggapi.html)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [LangChain 문서](https://python.langchain.com)
- [FastMCP 문서](https://github.com/jlowin/fastmcp)