🌟 SourceSage MCP

📖 개요

SourceSage는 프로젝트의 디렉토리 구조를 아름다운 마크다운 형식으로 시각화하는 MCP 서버입니다. TypeScript로 구현되어 고급 사용자 정의 및 유연한 제외 패턴 기능을 제공합니다. 또한 각 파일의 내용을 자동으로 문서화하여 프로젝트의 전체적인 모습을 파악하기 쉽게 합니다.

🎯 주요 특징

📁 디렉토리 구조의 마크 다운 형식으로 출력
🎨 아름다운 나무 구조 표시 (ASCII art)
📝 파일 내용 자동 문서화(언어별 구문 강조표시 포함)
🔍 유연한 제외 패턴(.SourceSageignore)
🚀 ES2022 및 Node16 모듈 시스템으로 최신 구현
💫 엄격한 유형 검사로 높은 신뢰성

🛠️ 기술 스택

🔷 TypeScript (ES2022 타겟)
📦 Model Context Protocol SDK (v0.6.0)
🌐 Node.js (Node16 모듈 시스템)
📚 glob (v11.0.0) - 파일 패턴 매칭
🎭 ignore (v6.0.2) - 유연한 파일 제외 기능

📂 프로젝트 구조

source-sage/
├── assets/
│   └── header.svg          # プロジェクトヘッダー画像
├── src/
│   └── index.ts           # メインサーバー実装
├── build/                 # コンパイル済みJavaScriptファイル
├── .gitignore            # Gitの除外設定
├── .SourceSageignore     # SourceSage固有の除外設定
├── package.json          # プロジェクト設定・依存関係
├── README.md            # プロジェクトドキュメント
└── tsconfig.json        # TypeScript設定

⚙️ TypeScript 설정

{
  "compilerOptions": {
    "target": "ES2022",        // 最新のECMAScript機能を活用
    "module": "Node16",        // Node.js 16の最新モジュールシステムを使用
    "moduleResolution": "Node16",
    "outDir": "./build",      // コンパイル済みファイルの出力先
    "rootDir": "./src",       // ソースファイルのルートディレクトリ
    "strict": true,           // 厳格な型チェックを有効化
    "esModuleInterop": true,  // CommonJSモジュールとの相互運用性を確保
    "skipLibCheck": true,     // 型定義ファイルのチェックをスキップ
    "forceConsistentCasingInFileNames": true  // ファイル名の大文字小文字を厳格に管理
  }
}

⚙️ 설치

npm에서 설치

npm install -g @sunwood-ai-labs/source-sage-mcp-server

소스에서 빌드

git clone https://github.com/sunwood-ai-labs/source-sage-mcp-server.git
cd source-sage-mcp-server
npm install
npm run build

🔧 사용법

MCP 서버로 설정

MCP 구성 파일에 다음을 추가합니다.

{
  "mcpServers": {
    "source-sage": {
      "command": "node",
      "args": ["C:/path/to/source-sage/build/index.js"]
    }
  }
}

🎮 사용 가능한 도구

generate_structure

프로젝트의 디렉토리 구조를 생성하고 파일 내용을 포함한 자세한 문서를 만듭니다.

interface GenerateStructureArgs {
  // 構造を生成するディレクトリのパス（必須）
  // 必ず絶対パスで指定してください
  path: string;
  // .SourceSageignoreファイルのパス（オプション）
  // 指定する場合は絶対パスで指定してください
  ignorePath?: string;
}

사용 예

// 絶対パスでの使用（推奨）
const result = await mcpClient.callTool('source-sage', 'generate_structure', {
  path: 'C:/Users/your-name/path/to/your-project',
  ignorePath: 'C:/Users/your-name/path/to/your-project/.SourceSageignore'
});

출력 샘플

실제 프로젝트 구조의 출력 예:

# 📁 Project: source-sage

## 🌳 ディレクトリ構造

OS: win32
Directory: C:\Users\your-name\source-sage

└─ source-sage/
   ├─ src/
   │  └─ index.ts          # MCPサーバーの主要な実装
   ├─ package.json         # プロジェクトの依存関係と設定
   ├─ README.md           # プロジェクトの詳細な説明
   └─ tsconfig.json       # TypeScriptのコンパイル設定

이 출력에는 다음 정보가 포함됩니다.

📁 프로젝트 이름 및 OS 정보
🌳 디렉토리 트리 구조
📝 각 파일의 역할과 설명
🔍 .SourceSageignore로 불필요한 파일 제외

📝 .SourceSageignore 설정

프로젝트의 루트에 .SourceSageignore 파일을 만들고 제외하려는 패턴을 설명합니다. 기본적으로 다음과 같은 제외 패턴이 포함됩니다.

# バージョン管理システム関連
.git
.gitignore

# キャッシュファイル
__pycache__
.pytest_cache
**/__pycache__/**
*.pyc

# ビルド・配布関連
build
dist
*.egg-info

# 一時ファイル・出力
output
output.md
test_output
.SourceSageAssets
.SourceSageAssetsDemo

# アセット
*.png
*.svg
assets

# その他
LICENSE
example
folder
package-lock.json

🔄 출력 예

  # 📁 Project: my-project

  ## 🌳 ディレクトリ構造

  OS: win32
  Directory: C:\path\to\my-project

  └─ my-project/
    ├─ src/
    │  ├─ index.ts
    │  └─ utils/
    │     └─ helper.ts
    └─ package.json

  ## 📄 ファイル内容

  ### 📝 `src/index.ts`
  **Type**: TypeScript Source File

👨‍💻 개발자 정보

주요 구현 세부사항

Server Class : SourceSageServer 클래스가 MCP 서버의 핵심 기능을 제공
Tree Building :
- buildTree 메서드가 재귀적으로 디렉토리 구조를 구문 분석
- 디렉토리와 파일을 적절하게 정렬하고 표시
파일 필터링 :
- ignore 패키지를 사용하여 유연한 파일 제외 실현
- 풍부한 기본 제외 패턴 및 맞춤 설정 지원
Content Generation :
- 파일 형식에 따라 적절한 구문 강조표시
- 파일 형식에 따라 추가 정보 제공
Async Processing :
- glob 패키지를 사용한 효율적인 파일 스캔
- 비동기 처리를 통한 대규모 프로젝트 지원

개발 환경 설정

# リポジトリのクローン
git clone https://github.com/sunwood-ai-labs/source-sage-mcp-server.git

# 依存関係のインストール
npm install

# 開発用ビルド
npm run build

# 開発サーバーの起動
npm run inspector

사용 가능한 npm 스크립트

npm run build : TypeScript 컴파일 및 실행 권한 설정
npm run prepare : 설치시 자동 빌드
npm run watch : 개발 시 자동 컴파일
npm run inspector : MCP Inspector 시작

🤝 기여

이 저장소를 포크
새로운 브랜치 만들기 ( git checkout -b feature/amazing-feature )
변경 커밋 ( git commit -m '✨ feat: 素晴らしい機能を追加' )
브랜치에 푸시 ( git push origin feature/amazing-feature )
끌어오기 요청 만들기

SourceSage MCP

Integrations