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'
});

输出示例

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

# 📁 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 的编译设置

此输出包含以下信息：

  • 📁 项目名称和操作系统信息
  • 🌳 目录树结构
  • 📝 每个文件的角色和说明
  • 🔍 .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. Fork 这个存储库
  2. 创建一个新分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m '✨ feat: 添加了很棒的功能')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 创建一个 Pull Request

📄 许可证

MIT License - 详细信息请参阅 LICENSE 文件。

🔗 相关链接

👥 维护者

  • Sunwood AI Labs Team

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

推荐服务器

Playwright MCP Server

Playwright MCP Server

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

官方
精选
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

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

官方
精选
本地
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

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

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

graphlit-mcp-server

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

官方
精选
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
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