mcp-integration-server-solin/README.md

MCP Server for Cody, YouTrack, and Forgejo integration

# MCP 통합 서버

Cody, YouTrack, Forgejo를 연동하는 Model Context Protocol (MCP) 서버입니다.

## 🚀 주요 기능

### 통합 서비스
- **YouTrack**: 이슈 관리 및 추적
- **Forgejo**: Git 저장소 관리 및 버전 관리
- **Cody**: 코드 분석 및 생성 (로컬 분석 포함)

### 핵심 기능
- 이슈와 커밋 자동 연결
- 코드 분석 결과 기반 이슈 자동 생성
- 통합된 프로젝트 관리 워크플로우
- 외부 API 의존성 최소화

## 📋 사전 요구사항

- Node.js 18+ 
- npm 또는 yarn
- YouTrack 인스턴스 및 API 토큰
- Forgejo 서버 및 액세스 토큰

## 🛠️ 설치 및 설정

### 1. 프로젝트 클론 및 의존성 설치

```bash
git clone <repository-url>
cd mcp-integration-server
npm install
```

### 2. 환경 변수 설정

`env.example` 파일을 `.env`로 복사하고 설정값을 입력하세요:

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

`.env` 파일 예시:
```env
# YouTrack 설정
YOUTRACK_BASE_URL=https://your-company.youtrack.cloud
YOUTRACK_TOKEN=your_youtrack_permanent_token

# Forgejo Git 서버 설정
FORGEJO_BASE_URL=https://your-git-server.com
FORGEJO_TOKEN=your_forgejo_access_token
FORGEJO_USERNAME=your_username

# MCP 서버 설정
MCP_SERVER_NAME=integration-server
MCP_SERVER_VERSION=1.0.0
```

### 3. 빌드 및 실행

```bash
# 개발 모드
npm run dev

# 프로덕션 빌드
npm run build
npm start
```

## 🔧 사용 방법

### MCP 클라이언트에서 서버 연결

MCP 클라이언트 설정에 다음을 추가하세요:

```json
{
  "mcpServers": {
    "integration-server": {
      "command": "node",
      "args": ["path/to/mcp-integration-server/dist/index.js"]
    }
  }
}
```

### 사용 가능한 도구들

#### YouTrack 도구
- `youtrack_get_issues`: 이슈 목록 조회
- `youtrack_create_issue`: 새 이슈 생성
- `youtrack_update_issue`: 이슈 업데이트
- `youtrack_get_issue`: 특정 이슈 조회

#### Forgejo 도구
- `forgejo_get_repositories`: 저장소 목록 조회
- `forgejo_get_commits`: 커밋 목록 조회
- `forgejo_create_pull_request`: Pull Request 생성
- `forgejo_get_pull_requests`: Pull Request 목록 조회

#### Cody 도구
- `cody_analyze_code`: 코드 분석 (로컬)
- `cody_generate_code`: 코드 생성 템플릿

#### 통합 도구
- `link_issue_to_commit`: 이슈와 커밋 연결
- `create_issue_from_code_analysis`: 코드 분석 기반 이슈 생성

## 💡 사용 예시

### 1. YouTrack 이슈 조회
```json
{
  "tool": "youtrack_get_issues",
  "arguments": {
    "project": "PROJ",
    "query": "state: Open",
    "limit": 5
  }
}
```

### 2. 코드 분석 후 이슈 생성
```json
{
  "tool": "create_issue_from_code_analysis",
  "arguments": {
    "project": "PROJ",
    "code": "function badCode() { var x = 1; }",
    "filePath": "src/example.js",
    "analysisType": "quality"
  }
}
```

### 3. 이슈와 커밋 연결
```json
{
  "tool": "link_issue_to_commit",
  "arguments": {
    "issueId": "PROJ-123",
    "owner": "myorg",
    "repo": "myrepo",
    "commitSha": "abc123def456"
  }
}
```

## 🏗️ 아키텍처

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │    │   MCP Server    │    │   External APIs │
│   (Cody, etc)   │◄──►│  Integration    │◄──►│  YouTrack, Git  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │ Local Services  │
                       │ (Code Analysis) │
                       └─────────────────┘
```

## 🔒 보안 고려사항

- API 토큰은 환경 변수로 관리
- HTTPS 연결 사용 권장
- 토큰 권한 최소화 원칙 적용
- 정기적인 토큰 갱신

## 🚀 확장 가능성

### 추가 가능한 통합
- GitLab/GitHub 지원
- Jira 연동
- Slack/Teams 알림
- CI/CD 파이프라인 연동

### 커스터마이징
- 코드 분석 규칙 추가
- 워크플로우 자동화 규칙
- 커스텀 이슈 템플릿

## 🐛 문제 해결

### 일반적인 문제들

1. **연결 오류**
   - API URL과 토큰 확인
   - 네트워크 연결 상태 확인
   - 방화벽 설정 확인

2. **권한 오류**
   - API 토큰 권한 확인
   - 프로젝트 접근 권한 확인

3. **빌드 오류**
   - Node.js 버전 확인 (18+ 필요)
   - 의존성 재설치: `rm -rf node_modules && npm install`

## 📝 라이선스

MIT License

## 🤝 기여하기

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## 📞 지원

문제가 발생하면 이슈를 생성하거나 문서를 참조하세요.

---

**비용 최적화 포인트:**
- 외부 API 호출 최소화
- 로컬 코드 분석 우선 사용
- 캐싱 메커니즘 활용
- 배치 처리로 API 호출 효율화