SourceSage MCP

SourceSage MCP

一个基于 TypeScript 的服务器，可以将项目目录结构可视化为 Markdown 格式，自动记录文件内容并进行语法高亮显示，同时支持自定义排除模式。

开发者工具
文件系统
本地
TypeScript
访问服务器

Tools

generate_structure

プロジェクトのディレクトリ構造を生成し、ファイル内容も含めた詳細なドキュメントを作成します。プロジェクトやリポジトリ、フォルダの内容を理解するときに使用します。

README

<div align="center">
<img src="https://raw.githubusercontent.com/Sunwood-ai-labs/source-sage-mcp-server/refs/heads/master/assets/sourcesage-magical.svg" width="100%">

# 🌟 SourceSage MCP

<p align="center">
<img alt="GitHub" src="https://img.shields.io/github/license/sunwood-ai-labs/source-sage-mcp-server">
<img alt="GitHub package.json version" src="https://img.shields.io/github/package-json/v/sunwood-ai-labs/source-sage-mcp-server">
<img alt="GitHub issues" src="https://img.shields.io/github/issues/sunwood-ai-labs/source-sage-mcp-server">
<img alt="GitHub pull requests" src="https://img.shields.io/github/issues-pr/sunwood-ai-labs/source-sage-mcp-server">
<img alt="npm" src="https://img.shields.io/npm/v/@sunwood-ai-labs/source-sage-mcp-server">
<img alt="npm" src="https://img.shields.io/npm/dt/@sunwood-ai-labs/source-sage-mcp-server">
</p>

## 📖 概要

SourceSageは、プロジェクトのディレクトリ構造を美しいマークダウン形式で可視化するMCPサーバーです。TypeScriptで実装され、高度なカスタマイズ性と柔軟な除外パターン機能を提供します。また、各ファイルの内容を自動的にドキュメント化し、プロジェクトの全体像を把握しやすくします。

</div>


## 🎯 主な特徴

- 📁 ディレクトリ構造のマークダウン形式での出力
- 🎨 美しい木構造表示（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) - 柔軟なファイル除外機能

## 📂 プロジェクト構造

```plaintext
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

<p align="center">Made with ❤️ by Sunwood AI Labs</p>

<div align="center"> <img src="https://raw.githubusercontent.com/Sunwood-ai-labs/source-sage-mcp-server/refs/heads/master/assets/sourcesage-magical.svg" width="100%">

🌟 SourceSage MCP

<p align="center"> <img alt="GitHub" src="https://img.shields.io/github/license/sunwood-ai-labs/source-sage-mcp-server"> <img alt="GitHub package.json version" src="https://img.shields.io/github/package-json/v/sunwood-ai-labs/source-sage-mcp-server"> <img alt="GitHub issues" src="https://img.shields.io/github/issues/sunwood-ai-labs/source-sage-mcp-server"> <img alt="GitHub pull requests" src="https://img.shields.io/github/issues-pr/sunwood-ai-labs/source-sage-mcp-server"> <img alt="npm" src="https://img.shields.io/npm/v/@sunwood-ai-labs/source-sage-mcp-server"> <img alt="npm" src="https://img.shields.io/npm/dt/@sunwood-ai-labs/source-sage-mcp-server"> </p>

📖 概要

SourceSage 是一个 MCP 服务器，可以将项目的目录结构以美观的 Markdown 格式可视化。它使用 TypeScript 实现，提供高度的定制性和灵活的排除模式功能。此外，它还可以自动记录每个文件的内容，从而更容易掌握项目的整体情况。

</div>

🎯 主要特点

  • 📁 以 Markdown 格式输出目录结构
  • 🎨 美观的树状结构显示（ASCII 艺术）
  • 📝 自动文件内容文档化（带有语言特定的语法高亮）
  • 🔍 灵活的排除模式（.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'
});

输出示例

实际项目结构的输出示例：

# 📁 项目: source-sage

## 🌳 目录结构

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

└─ source-sage/
   ├─ src/
   │  └─ index.ts          # MCP 服务器的主要实现
   ├─ package.json         # 项目的依赖项和设置
   ├─ README.md           # 项目的详细说明
   └─ tsconfig.json       # TypeScript 的编译设置

此输出包含以下信息：

  • 📁 项目名称和操作系统信息
  • 🌳 目录树结构
  • 📝 每个文件的角色和说明
  • 🔍 .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

🔄 输出示例

  # 📁 项目: 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. Fork 这个存储库
  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

<p align="center">Made with ❤️ by Sunwood AI Labs</p>

推荐服务器

Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Excel MCP Server

Excel MCP Server

一个模型上下文协议服务器，使 AI 助手能够读取和写入 Microsoft Excel 文件，支持诸如 xlsx、xlsm、xltx 和 xltm 等格式。

精选
本地
Go
Playwright MCP Server

Playwright MCP Server

提供一个利用模型上下文协议的服务器，以实现类人浏览器的自动化，该服务器使用 Playwright，允许控制浏览器行为，例如导航、元素交互和滚动。

精选
本地
TypeScript
MCP Package Docs Server

MCP Package Docs Server

促进大型语言模型高效访问和获取 Go、Python 和 NPM 包的结构化文档，通过多语言支持和性能优化来增强软件开发。

精选
本地
TypeScript
Claude Code MCP

Claude Code MCP

一个实现了 Claude Code 作为模型上下文协议（Model Context Protocol, MCP）服务器的方案，它可以通过标准化的 MCP 接口来使用 Claude 的软件工程能力（代码生成、编辑、审查和文件操作）。

精选
本地
JavaScript
@kazuph/mcp-taskmanager

@kazuph/mcp-taskmanager

用于任务管理的模型上下文协议服务器。它允许 Claude Desktop（或任何 MCP 客户端）在基于队列的系统中管理和执行任务。

精选
本地
JavaScript
Apple MCP Server

Apple MCP Server

通过 MCP 协议与 Apple 应用（如“信息”、“备忘录”和“通讯录”）进行交互，从而使用自然语言发送消息、搜索和打开应用内容。

精选
本地
TypeScript