SourceSage MCP

local-only server

The server can only run on the client’s local machine because it depends on local resources.

Integrations

  • Provides project directory structure visualization, excluding Git-related files and directories through built-in .SourceSageignore patterns to prevent unnecessary Git metadata from appearing in the structure output.

  • Enables visualization of GitHub repositories with automatic handling of GitHub-specific files through customizable ignore patterns, while providing badges that link back to the GitHub repository's license, issues, and pull requests.

  • Offers Node.js project visualization with special handling for Node.js module structures and automatic documentation of Node.js-specific configuration files.

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

  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 ファイルを参照してください。

🔗 関連リンク

👥 メンテナー

  • Sunwood AI Labs Team