SourceSage MCP
🌟 SourceSage MCP
📖 概要
SourceSageは、プロジェクトのディレクトリ構造を美しいマークダウン形式で可視化するMCPサーバーです。TypeScriptで実装され、高度なカスタマイズ性と柔軟な除外パターン機能を提供します。また、各ファイルの内容を自動的にドキュメント化し、プロジェクトの全体像を把握しやすくします。
Related MCP server: MCP-Typescribe
🎯 主な特徴
📁 ディレクトリ構造のマークダウン形式での出力
🎨 美しい木構造表示(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メソッドが再帰的にディレクトリ構造を解析ディレクトリとファイルを適切にソートして表示
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インスペクターの起動
🤝 コントリビューション
このリポジトリをフォーク
新しいブランチを作成 (
git checkout -b feature/amazing-feature)変更をコミット (
git commit -m '✨ feat: 素晴らしい機能を追加')ブランチにプッシュ (
git push origin feature/amazing-feature)プルリクエストを作成
📄 ライセンス
MIT License - 詳細は LICENSE ファイルを参照してください。
🔗 関連リンク
👥 メンテナー
Sunwood AI Labs Team
Available Tools
1 toolgenerate_structureA
プロジェクトのディレクトリ構造を生成し、ファイル内容も含めた詳細なドキュメントを作成します。プロジェクトやリポジトリ、フォルダの内容を理解するときに使用します。
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | 構造を生成するディレクトリの絶対パス | |
| ignorePath | No | .SourceSageignoreファイルの絶対パス(オプション) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must cover behavioral aspects. It mentions reading file contents and generating a document, but does not disclose side effects, permissions, or performance considerations. Basic transparency but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded with the core action. It wastes no words but could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should clarify the output format. It only says 'detailed document' without specifying the type or delivery method. Missing details for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions already present. The description adds context about use cases but no additional semantic information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool generates a directory structure and a detailed document including file contents, with a specific use case. The verb 'generate' and resource 'directory structure' are distinct and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for understanding project contents but does not provide when-not-to-use or alternatives. Since there are no sibling tools, it is minimally adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
1 tool update
v1.0.0- First observed
generate_structure
TDQS
Scored across 1 tool
With only one tool, there is no possibility of confusion between tools. The tool's purpose is clearly defined and distinct.
Since there is only one tool, naming consistency is not applicable, but the single name 'generate_structure' follows a clear verb_noun pattern.
A single tool for a server named 'SourceSage MCP' is too few for the apparent scope. While the tool is substantive, the server lacks complementary tools that would support a typical workflow for project understanding.
The tool covers the core purpose of generating structure and documentation, but there are notable gaps: no ability to list files individually, retrieve specific file contents, or search within the project, limiting granular interactions.
Maintenance
Related MCP Connectors
Serves your design system and coding standards to coding agents, so they stop guessing.
A TypeScript MCP server for Home Assistant, enabling programmatic management of entities, automati…
Publish Markdown incident reports, ADRs, RFCs and runbooks as web pages, with team spaces.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceA TypeScript-based server project that can be integrated with Cursor IDE as an MCP (Model Control Protocol) server, enabling enhanced development capabilities.133ISC
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables LLMs to understand and work with TypeScript APIs they haven't been trained on by providing structured access to TypeScript type definitions and documentation.44 npm46MIT
- AlicenseNot gradedqualityDmaintenanceA TypeScript-based document processing server that supports various document formats (.docx, .pdf, .xlsx) and integrates with Model Context Protocol SDK for efficient document context management.1,927 npm1MIT
- FlicenseNot gradedqualityDmaintenanceA TypeScript server that exposes various code automation tools powered by Gemini, including code refactoring, test generation, documentation creation, debugging assistance, and code navigation capabilities.1-