What is Source Sage Mcp Server

source-sage-mcp-server is a server designed to visualize project directory structures in a beautiful markdown format. Implemented in TypeScript, it offers advanced customization and flexible exclusion patterns, automatically documenting the content of each file for better project overview.

Use cases

Use cases include generating detailed documentation of project structures, visualizing complex directory hierarchies, and excluding unnecessary files from documentation outputs. It is particularly useful for developers looking to maintain clear project organization and documentation.

How to use

To use source-sage-mcp-server, install it via npm with the command npm install -g @sunwood-ai-labs/source-sage-mcp-server. Then, configure it in your MCP settings by adding the server command and arguments pointing to the built index.js file. You can generate the project structure using the generate_structure tool by calling it with the required directory path.

Key features

Key features include markdown output of directory structures, beautiful ASCII art tree displays, automatic documentation of file contents with syntax highlighting, flexible exclusion patterns via .SourceSageignore, and implementation using the latest ES2022 and Node16 module system with strict type checking for high reliability.

Where to use

source-sage-mcp-server can be used in software development projects where visualization of directory structures is needed, particularly in TypeScript-based projects, documentation generation, and project management.

🌟 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設定

⚙️ インストール

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サーバーとしての設定

1. 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メソッドが再帰的にディレクトリ構造を解析
  • ディレクトリとファイルを適切にソートして表示
• File Filtering:
  • 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インスペクターの起動

🤝 コントリビューション

1. このリポジトリをフォーク
2. 新しいブランチを作成 (git checkout -b feature/amazing-feature)
3. 変更をコミット (git commit -m '✨ feat: 素晴らしい機能を追加')
4. ブランチにプッシュ (git push origin feature/amazing-feature)
5. プルリクエストを作成

📄 ライセンス

MIT License - 詳細は LICENSE ファイルを参照してください。

🔗 関連リンク

• npm package
• GitHub repository
• バグ報告

👥 メンテナー

• Sunwood AI Labs Team

Made with ❤️ by Sunwood AI Labs