@sparrowai/sparrow-mcp 1.0.11 → 1.1.0

package/.agent/skills/README.md

@@ -0,0 +1,67 @@
+# Sparrow Security Skills 설치 가이드
+
+Sparrow Security Skills를 프로젝트에 설치하는 방법입니다.
+
+## 전제 조건
+
+1. **Sparrow MCP 서버** 설치 및 설정 완료
+2. **AI IDE** (Gemini Code Assist, Cursor 등)에서 MCP 연결 설정
+
+## 설치 방법
+
+### 방법 1: Git Clone (권장)
+
+```bash
+# 프로젝트 루트에서 실행
+git clone https://github.com/example/sparrow-skills.git .agent/skills
+```
+
+### 방법 2: 수동 복사
+
+1. Skills 폴더를 다운로드합니다
+2. 프로젝트 루트에 `.agent/skills/` 폴더를 생성합니다
+3. 다운로드한 파일을 복사합니다
+
+```
+프로젝트루트/
+└── .agent/
+    └── skills/
+        ├── sparrow-quick-scan/
+        │   └── SKILL.md
+        ├── sparrow-full-audit/
+        │   └── SKILL.md
+        ├── sparrow-fix-vulnerabilities/
+        │   └── SKILL.md
+        ├── sparrow-sca-check/
+        │   └── SKILL.md
+        └── sparrow-comprehensive-security/
+            └── SKILL.md
+```
+
+### 방법 3: npm 패키지 (Coming Soon)
+
+```bash
+npm install @example/sparrow-skills --save-dev
+npx sparrow-skills init
+```
+
+## 사용 방법
+
+설치 후 AI에게 다음과 같이 요청하면 해당 skill이 자동으로 적용됩니다:
+
+| 요청 예시 | 적용되는 Skill |
+|----------|---------------|
+| "이 파일 보안 검사해줘" | sparrow-quick-scan |
+| "프로젝트 전체 보안 감사해줘" | sparrow-full-audit |
+| "취약점 수정해줘" | sparrow-fix-vulnerabilities |
+| "라이브러리 취약점 검사해줘" | sparrow-sca-check |
+| "전반적인 보안 다 검토해줘" | sparrow-comprehensive-security |
+
+## 확인 방법
+
+AI에게 다음과 같이 물어보세요:
+```
+"sparrow skills 설치되어 있어?"
+```
+
+AI가 `.agent/skills/` 폴더를 확인하고 설치 상태를 알려줄 것입니다.

package/.agent/skills/sparrow-comprehensive-security/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: sparrow-comprehensive-security
+description: SAST와 SCA를 모두 실행하여 소스코드와 오픈소스 라이브러리를 종합적으로 점검합니다
+---
+
+# Sparrow Comprehensive Security
+
+프로젝트의 **소스코드 취약점(SAST)**과 **오픈소스 라이브러리 취약점(SCA)**을 함께 검사하여 종합적인 보안 점검 결과를 제공합니다.
+
+## 사용 시나리오
+
+사용자가 다음과 같이 요청할 때 이 skill을 적용하세요:
+- "이 프로젝트의 전반적인 보안을 다 검토해줘"
+- "코드랑 라이브러리 둘 다 보안 점검해줘"
+- "종합 보안 점검해줘"
+- "완전한 보안 분석 해줘"
+
+## 실행 단계
+
+### 1단계: SAST 분석 시작
+```
+도구: analyze_folder_sast
+입력:
+  - folderPath: 프로젝트 경로
+출력: sast_analysisId
+```
+
+### 2단계: SCA 분석 시작 (병렬 실행)
+```
+도구: analyze_folder_sca
+입력:
+  - folderPath: 프로젝트 경로
+출력: sca_analysisId
+```
+
+### 3단계: 두 분석 진행률 추적
+SAST와 SCA 분석이 모두 완료될 때까지 추적합니다.
+
+```
+도구: track_analysis_progress
+입력: sast_analysisId
+---
+도구: track_analysis_progress
+입력: sca_analysisId
+```
+
+### 4단계: SAST 결과 조회
+```
+도구: get_analysis_results
+입력:
+  - analysisId: sast_analysisId
+출력: 코드 취약점 목록
+```
+
+### 5단계: SCA 결과 조회
+```
+도구: get_sca_analysis_results
+입력:
+  - analysisId: sca_analysisId
+출력: 라이브러리 취약점, 라이선스 정보
+```
+
+### 6단계: 통합 보고서 작성
+두 결과를 종합하여 하나의 보고서로 작성합니다.
+
+## 결과 보고 형식
+
+```markdown
+# 🛡️ 종합 보안 점검 보고서
+
+**프로젝트**: [폴더명]
+**분석일시**: [날짜]
+
+---
+
+## 📊 Executive Summary
+
+| 구분 | 항목 | Critical | High | Medium | Low |
+|------|------|----------|------|--------|-----|
+| SAST | 코드 취약점 | N | N | N | N |
+| SCA | 라이브러리 취약점 | N | N | N | N |
+| **합계** | | **N** | **N** | **N** | **N** |
+
+---
+
+## 🔍 Part 1: 소스코드 취약점 (SAST)
+
+### 발견된 취약점
+1. [파일:라인] **취약점명** - 설명
+   - 심각도: Critical
+   - 권장 조치: [조치 내용]
+
+### 컴플라이언스 현황
+[OWASP, CWE 매핑 정보]
+
+---
+
+## 📦 Part 2: 오픈소스 라이브러리 (SCA)
+
+### 취약한 라이브러리
+| 라이브러리 | 버전 | CVE | CVSS | 권장 버전 |
+|-----------|------|-----|------|----------|
+| lodash | 4.17.15 | CVE-2021-23337 | 7.2 | 4.17.21 |
+
+### 라이선스 현황
+| 라이브러리 | 라이선스 |
+|-----------|---------|
+| react | MIT |
+
+---
+
+## ✅ 종합 권장 조치사항
+
+### 즉시 조치 필요 (Critical/High)
+1. [SAST] SQL Injection 수정
+2. [SCA] lodash 업데이트
+
+### 중기 조치 (Medium)
+1. ...
+
+### 참고사항 (Low)
+1. ...
+```
+
+## 🌐 언어 정책 (Language Policy)
+
+- 결과 언어는 사용자가 입력한 프롬프트의 언어를 따릅니다.
+- 모든 출력 및 보고서는 사용자의 언어로 표시하여 가독성을 높입니다.
+
+## 추가 작업
+
+- SAST 취약점은 `generate_secure_code`로 수정 코드 제공
+- SCA 취약점은 업데이트 명령어 제공 (npm update 등)
+- 우선순위별로 조치 가이드 정리
+
+## 장점
+
+이 통합 skill을 사용하면:
+- ✅ 코드 취약점과 라이브러리 취약점을 한번에 파악
+- ✅ 전체 보안 상태를 한눈에 볼 수 있는 통합 보고서
+- ✅ 우선순위에 따른 조치 가이드 제공

package/.agent/skills/sparrow-fix-vulnerabilities/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: sparrow-fix-vulnerabilities
+description: 발견된 보안 취약점에 대한 수정 코드를 자동 생성하고 적용합니다
+---
+
+# Sparrow Fix Vulnerabilities
+
+보안 분석 결과를 바탕으로 취약점을 자동으로 수정합니다.
+
+## 사용 시나리오
+
+사용자가 다음과 같이 요청할 때 이 skill을 적용하세요:
+- "취약점 발견했으면 수정해줘"
+- "보안 패치 자동 적용해줘"
+- "이 취약점 고쳐줘"
+- "수정 코드 만들어줘"
+
+## 전제 조건
+
+이 skill은 **이전에 보안 분석이 완료된 상태**에서 사용합니다.
+- `analysisId`가 필요합니다
+- 분석 상태가 'COMPLETE'이어야 합니다
+
+## 실행 단계
+
+### 1단계: 분석 결과 확인
+`get_analysis_results`로 취약점 목록을 확인합니다.
+
+```
+도구: get_analysis_results
+입력:
+  - analysisId: 이전 분석 ID
+출력: 취약점 목록 (파일, 라인, 유형)
+```
+
+### 2단계: 수정 코드 생성
+각 취약 파일에 대해 `generate_secure_code`를 호출합니다.
+
+```
+도구: generate_secure_code
+입력:
+  - analysisId: 분석 ID
+  - fileContent: 원본 파일 내용 (view_file로 읽기)
+출력:
+  - secureCode: 수정된 전체 코드
+  - secureCodeBrief: 수정 내용 설명
+  - diff: 변경사항 Diff
+```
+
+### 3단계: 변경사항 적용
+사용자 승인 후 코드를 적용합니다.
+
+```
+1. diff를 사용자에게 보여주고 확인 요청
+2. 승인 시 replace_file_content 또는 write_to_file로 적용
+3. 변경 내용 요약 제공
+```
+
+## 결과 보고 형식
+
+```markdown
+## 🔧 취약점 수정 결과
+
+### 수정된 파일: [파일명]
+
+**변경 내용:**
+[secureCodeBrief 내용]
+
+**Diff:**
+```diff
+[diff 내용]
+```
+
+✅ 수정이 완료되었습니다. 다음 취약점이 해결되었습니다:
+- [취약점 1]: SQL Injection → Prepared Statement 적용
+- [취약점 2]: XSS → 입력값 검증 추가
+```
+
+## 워크플로우 옵션
+
+### 옵션 A: 대화형 (기본)
+1. 각 파일별로 diff 보여주기
+2. 사용자 확인 후 적용
+3. 다음 파일로 진행
+
+### 옵션 B: 일괄 적용
+사용자가 "전부 적용해줘"라고 하면:
+1. 모든 수정 코드를 한번에 생성
+2. 전체 변경 요약 보여주기
+3. 일괄 적용 후 결과 보고
+
+## 🌐 언어 정책 (Language Policy)
+
+- 결과 언어는 사용자가 입력한 프롬프트의 언어를 따릅니다.
+- 모든 출력 및 보고서는 사용자의 언어로 표시하여 가독성을 높입니다.
+
+## 주의사항
+
+- 수정 코드 적용 전 **반드시 사용자 확인**을 받으세요
+- 원본 코드 백업 권장을 안내하세요
+- 자동 생성된 코드는 테스트가 필요함을 알려주세요

package/.agent/skills/sparrow-full-audit/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: sparrow-full-audit
+description: 프로젝트 전체에 대한 종합 보안 감사를 수행하고 상세 보고서를 생성합니다
+---
+
+# Sparrow Full Audit
+
+프로젝트 전체 폴더를 대상으로 종합적인 보안 감사를 수행합니다.
+
+## 사용 시나리오
+
+사용자가 다음과 같이 요청할 때 이 skill을 적용하세요:
+- "이 프로젝트 전체 보안 감사해줘"
+- "릴리즈 전 보안 점검 해줘"
+- "전체 코드 보안 분석해줘"
+- "보안 감사 보고서 만들어줘"
+
+## 실행 단계
+
+### 1단계: 폴더 분석 시작
+`analyze_folder_sast` 도구를 호출합니다.
+
+```
+도구: analyze_folder_sast
+입력:
+  - folderPath: 분석할 프로젝트 경로
+  - zipFileName: (선택) 분석용 ZIP 파일명
+출력: analysisId, skippedFolders (제외된 폴더 목록)
+```
+
+> **참고**: node_modules, .git, dist 등은 자동으로 제외됩니다.
+
+### 2단계: 진행률 추적
+`track_analysis_progress` 도구로 분석 완료를 기다립니다.
+
+```
+도구: track_analysis_progress
+입력:
+  - analysisId: 1단계에서 받은 ID
+  - maxWaitMs: 300000 (5분, 프로젝트 크기에 따라 조정)
+출력: 분석 완료 상태
+```
+
+### 3단계: 결과 조회
+`get_analysis_results` 도구로 상세 결과를 확인합니다.
+
+```
+도구: get_analysis_results
+입력:
+  - analysisId: 분석 ID
+출력: 취약점 목록, 파일별 위치, 컴플라이언스 정보
+```
+
+### 4단계: 보고서 작성
+결과를 바탕으로 종합 보고서를 작성합니다.
+
+## 결과 보고 형식
+
+```markdown
+# 🔐 보안 감사 보고서
+
+**프로젝트**: [폴더명]
+**분석일시**: [날짜]
+**분석 ID**: [analysisId]
+
+## 📊 Executive Summary
+
+| 항목 | 수치 |
+|------|------|
+| 분석 파일 수 | N개 |
+| 발견된 취약점 | N개 |
+| Critical/High | N개 |
+| 제외된 폴더 | [목록] |
+
+## 🚨 주요 발견사항
+
+### Critical & High 취약점
+1. [파일:라인] **취약점명** - 설명
+   - 위험도: Critical
+   - 권장 조치: [조치 내용]
+
+### Medium & Low 취약점
+[목록으로 간략히 표시]
+
+## 📋 컴플라이언스 현황
+[OWASP, CWE 등 매핑 정보]
+
+## ✅ 권장 조치사항
+1. [우선순위 높은 조치]
+2. [중간 우선순위 조치]
+3. [참고 사항]
+```
+
+## 🌐 언어 정책 (Language Policy)
+
+- 결과 언어는 사용자가 입력한 프롬프트의 언어를 따릅니다.
+- 모든 출력 및 보고서는 사용자의 언어로 표시하여 가독성을 높입니다.
+
+## 추가 작업
+
+Critical/High 취약점이 발견된 경우:
+- 각 취약 파일에 대해 `generate_secure_code`를 호출하여 수정 코드 제공
+- 수정 우선순위를 제시하여 단계적 개선 가이드 제공

package/.agent/skills/sparrow-mcp-test/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: sparrow-mcp-test
+description: Sparrow MCP 서버를 자동으로 테스트하고 TSV 결과를 생성합니다
+---
+
+# Sparrow MCP Test Skill
+
+이 스킬은 설치된 Sparrow MCP 서버를 자동으로 테스트하고 결과를 TSV 파일로 생성합니다.
+
+## 사용 시기
+
+- MCP 서버가 정상적으로 작동하는지 확인하고 싶을 때
+- 모든 MCP tool이 제대로 동작하는지 검증하고 싶을 때
+- 테스트 결과를 TSV 형식으로 문서화하고 싶을 때
+
+## 사용 방법
+
+### 1. 로컬 개발 서버 테스트
+
+프로젝트 디렉토리에서:
+
+```bash
+node bin/sparrow-mcp-test.cjs
+```
+
+### 2. NPM 패키지로 설치된 서버 테스트
+
+```bash
+npm install -g @sparrowai/sparrow-mcp
+sparrow-mcp-test
+```
+
+## 테스트 내용
+
+이 스킬은 다음 테스트를 수행합니다:
+
+### TC001: 단일 Java 파일 SAST 분석
+- **도구**: `analyze_file_sast`
+- **내용**: SQL Injection 취약점이 있는 Java 코드 분석
+- **검증**: MCP tool 호출 → 분석 완료 대기 → 결과 조회
+
+### TC004: JavaScript 파일 분석
+- **도구**: `analyze_file_sast`
+- **내용**: JavaScript 코드 분석
+- **검증**: 지원 언어 확인
+
+## 출력
+
+### 콘솔 출력
+```
+🧪 Sparrow MCP 자동 테스트 시작
+
+╔═══════════════════════════════════════════════════════════════╗
+║            Sparrow MCP - 자동화 테스트 (MCP Client)          ║
+╚═══════════════════════════════════════════════════════════════╝
+
+내장 테스트 케이스: 2개
+최대 대기 시간: 15분
+
+✅ MCP 서버 연결 성공
+
+[TC001] Running: 단일 Java 파일 SAST 분석 성공...
+[TC001] 통과 (213.7s)
+
+[TC004] Running: 지원 언어 확인 - JavaScript...
+[TC004] 통과 (0.2s)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ 테스트 완료
+   통과: 2/2
+   실패: 0
+
+📄 결과 저장: sparrow-mcp-test-results.tsv
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### TSV 파일
+`sparrow-mcp-test-results.tsv` 파일이 현재 디렉토리에 생성됩니다.
+
+**포함 내용:**
+- 테스트ID, 도구명, 테스트분류, 테스트명
+- 사전조건, 테스트절차, 기대결과
+- 테스트데이터, 우선순위, 상태, 담당자
+- 결과, 판단근거, 분석 링크, 비고
+
+## 환경 변수
+
+### SPARROW_API_KEY (필수)
+Sparrow OnDemand API 키
+
+```bash
+# Windows
+$env:SPARROW_API_KEY = "your-api-key"
+
+# Linux/macOS
+export SPARROW_API_KEY="your-api-key"
+```
+
+### SPARROW_API_URL (선택)
+Sparrow API URL (기본값: https://ondemand.sparrowcloud.ai)
+
+## 기술 세부사항
+
+### MCP 클라이언트 사용
+이 스킬은 `McpClient`를 사용하여 실제 MCP 프로토콜을 통해 tool을 호출합니다.
+
+```typescript
+// MCP tool 호출 예시
+const result = await client.request('tools/call', {
+    name: 'analyze_file_sast',
+    arguments: {
+        fileContent: javaCode,
+        fileName: 'UserController.java'
+    }
+});
+```
+
+### 테스트 흐름
+1. MCP 서버 시작 (`McpClient.start()`)
+2. 각 테스트 케이스 실행:
+   - MCP tool 호출
+   - analysisId 추출
+   - 분석 완료 대기 (polling)
+   - 결과 조회
+3. TSV 파일 생성
+4. MCP 서버 종료
+
+### 내장 테스트 파일
+- Java 코드: SQL Injection 취약점 포함
+- JavaScript 코드: 간단한 Express 서버
+
+## 문제 해결
+
+### MCP 서버 연결 실패
+```
+Error: Server closed unexpectedly
+```
+
+**해결 방법:**
+1. 서버가 빌드되어 있는지 확인: `npm run build`
+2. 서버 경로가 올바른지 확인
+3. 환경 변수가 설정되어 있는지 확인
+
+### API 키 오류
+```
+⚠️ 경고: SPARROW_API_KEY가 설정되지 않았습니다.
+```
+
+**해결 방법:**
+환경 변수를 설정하거나 `.env` 파일에 추가
+
+### 분석 타임아웃
+```
+Polling timeout after 300 attempts
+```
+
+**해결 방법:**
+1. 네트워크 연결 확인
+2. Sparrow API 서버 상태 확인
+3. 필요시 `MAX_POLL_ATTEMPTS` 증가
+
+## 확장 방법
+
+### 더 많은 테스트 추가
+
+`BUILTIN_TESTS` 배열에 새 테스트 케이스 추가:
+
+```typescript
+{
+    id: 'TC_NEW',
+    tool: 'analyze_folder_sast',
+    category: '정상동작',
+    name: '폴더 분석 테스트',
+    procedure: '...',
+    expected: '...',
+    priority: '높음',
+    task: async (client: McpClient) => {
+        const result = await client.request('tools/call', {
+            name: 'analyze_folder_sast',
+            arguments: { folderPath: './test-folder' }
+        });
+        // ...
+    }
+}
+```
+
+### 사용자 정의 테스트 파일
+
+향후 MD 파일에서 테스트 케이스를 읽어올 수 있도록 확장 가능:
+
+```bash
+sparrow-mcp-test --test-cases ./my-tests.md
+```
+
+## 참고 문서
+
+- [test-cases-example.md](../../test-cases-example.md) - 테스트 케이스 예시
+- [MCP Client 구현](../mcp-test/mcp-client.ts) - MCP 클라이언트 코드
+- [README.md](../../README.md) - Sparrow MCP 전체 문서

package/.agent/skills/sparrow-quick-scan/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: sparrow-quick-scan
+description: 단일 파일 또는 특정 코드 조각의 빠른 보안 점검을 수행합니다
+---
+
+# Sparrow Quick Scan
+
+단일 파일의 보안 취약점을 빠르게 진단하고 수정 코드를 제공합니다.
+
+## 사용 시나리오
+
+사용자가 다음과 같이 요청할 때 이 skill을 적용하세요:
+- "이 파일 보안 검사해줘"
+- "UserController.java 취약점 있어?"
+- "이 코드 보안 분석해줘"
+- 특정 파일을 지정하여 보안 점검 요청 시
+
+## 실행 단계
+
+### 1단계: 분석 시작
+`analyze_file_sast` 도구를 호출하여 분석을 시작합니다.
+
+```
+도구: analyze_file_sast
+입력:
+  - fileContent: 분석할 파일 내용
+  - fileName: 파일명 (예: "UserController.java")
+출력: analysisId
+```
+
+### 2단계: 진행률 추적
+`track_analysis_progress` 도구로 분석 완료를 기다립니다.
+
+```
+도구: track_analysis_progress
+입력:
+  - analysisId: 1단계에서 받은 ID
+  - maxWaitMs: 60000 (1분)
+출력: 분석 완료 상태
+```
+
+### 3단계: 결과 조회
+`get_analysis_results` 도구로 취약점 목록을 확인합니다.
+
+```
+도구: get_analysis_results
+입력:
+  - analysisId: 분석 ID
+출력: 취약점 목록, 심각도, 위치
+```
+
+### 4단계: 수정 코드 생성 (취약점 발견 시)
+`generate_secure_code` 도구로 안전한 코드를 생성합니다.
+
+```
+도구: generate_secure_code
+입력:
+  - analysisId: 분석 ID
+  - fileContent: 원본 파일 내용
+출력: 수정된 코드, 변경 설명, Diff
+```
+
+## 결과 보고 형식
+
+분석 완료 후 다음 형식으로 보고하세요:
+
+```markdown
+## 🔒 보안 분석 결과
+
+**분석 파일**: [파일명]
+**발견된 취약점**: [N]개
+
+### 심각도별 요약
+- 🔴 Critical: N개
+- 🟠 High: N개
+- 🟡 Medium: N개
+- 🟢 Low: N개
+
+### 수정 조치
+[generate_secure_code 결과의 Diff 표시]
+```
+
+## 🌐 언어 정책 (Language Policy)
+
+- 결과 언어는 사용자가 입력한 프롬프트의 언어를 따릅니다.
+- 모든 출력 및 보고서는 사용자의 언어로 표시하여 가독성을 높입니다.
+
+## 주의사항
+
+- 취약점이 발견되면 반드시 `generate_secure_code`로 수정 코드를 제시하세요
+- "취약점이 발견되었습니다" 대신 **"보안 이슈를 해결했습니다"**라고 긍정적으로 표현하세요