🌟 SourceSage MCP

📖 Overview

SourceSage is an MCP server that visualizes your project's directory structure in a beautiful Markdown format. It is implemented in TypeScript, offers high customizability and flexible exclude patterns, and automatically documents the contents of each file, making it easy to get an overview of your project.

Related MCP server: MCP-Typescribe

🎯 Main features

• 📁 Directory structure output in Markdown format

• 🎨 Beautiful tree structure display (ASCII art)

• 📝 Automatic documentation of file contents (with language-specific syntax highlighting)

• 🔍 Flexible exclude patterns (.SourceSageignore)

• 🚀 A modern implementation using ES2022 and the Node.js module system.

• 💫 High reliability due to strict type checking

🛠️ Technology stack

• 🔷 TypeScript (ES2022 target)

• 📦 Model Context Protocol SDK (v0.6.0)

• 🌐 Node.js (Node 16 module system)

• 📚 glob (v11.0.0) - File pattern matching

• 🎭 ignore (v6.0.2) - Flexible file exclusion functionality

📂 Project Structure

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

⚙️ TypeScript settings

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

⚙️ Installation

Install from npm

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

Build from source

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

🔧 How to use

Setting up as an MCP server

1. Add the following to your MCP config file:

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

🎮 Available Tools

generate_structure

It generates a directory structure for your project and provides detailed documentation including file contents.

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

Usage Example

// 絶対パスでの使用（推奨）
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'
});

Output sample

Example output of actual project structure:

# 📁 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のコンパイル設定

The output includes the following information:

• 📁 Project name and OS information

• 🌳 Directory tree structure

• 📝 Role and description of each file

• 🔍 Exclude unnecessary files with .SourceSageignore

📝 .SourceSageignore settings

Create a .SourceSageignore file in the root of your project and put the patterns you want to exclude into it. By default, it contains the following exclude patterns:

# バージョン管理システム関連
.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

🔄 Example output

  # 📁 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

👨‍💻 Developer Information

Key implementation details

• Server Class : SourceSageServer class provides the core functionality of the MCP server.

• Tree Building :

  • buildTree method recursively analyzes the directory structure.

  • Properly sort and display directories and files

• File Filtering :

  • Use the ignore package for flexible file exclusion

  • Supports a wide range of default exclusion patterns and custom configurations

• Content Generation :

  • Proper syntax highlighting for your file type

  • Providing additional information based on file type

• Async Processing :

  • Efficient file scanning using glob package

  • Supporting large projects with asynchronous processing

Setting up your development environment

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

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

# 開発用ビルド
npm run build

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

Available npm scripts

• npm run build : Compile TypeScript and set execution permissions

• npm run prepare : Automatic build during installation

• npm run watch : Automatic compilation during development

• npm run inspector : Start the MCP inspector

🤝 Contributions

1. Fork this repository

2. Create a new branch ( git checkout -b feature/amazing-feature )

3. Commit your changes ( git commit -m '✨ feat: 素晴らしい機能を追加' )

4. Push to the branch ( git push origin feature/amazing-feature )

5. Create a pull request

📄 License

MIT License - see the LICENSE file for details.

🔗 Related Links

• npm package

• GitHub repository

• Reporting a Bug

👥 Maintainers

• Sunwood AI Labs Team