FS-MCP: Universal File Reader & Intelligent Search MCP Server

FS-MCP：ユニバーサルファイルリーダー＆インテリジェント検索 MCP サーバー

---

English

🚀 特徴

• 🧠 インテリジェントなテキスト検出：ファイル拡張子に依存せず、テキストファイルを自動的に識別します
• 📄 マルチフォーマット対応：テキストファイルやドキュメント形式（Word、Excel、PDF など）を処理します
• 🔒 セキュリティ優先：設定された安全なディレクトリのみへのアクセスを許可します
• 📏 範囲指定読み取り：大容量ファイルの特定の行範囲を読み取れます
• 🔄 ドキュメント変換：ドキュメントを Markdown に自動変換し、キャッシュします
• 🔍 ベクトル検索：AI 埋め込みによるセマンティック検索を提供します
• ⚡ 高パフォーマンス：バッチ処理とインテリジェントなキャッシュに対応します
• 🌐 多言語対応：英語と中国語のコンテンツに対応します

📋 目次

• クイックスタート
• インストール
• 設定
• MCP ツール
• ベクトル検索
• 対応フォーマット
• セキュリティ機能
• 連携
• 開発
• コントリビューション
• ライセンス

🚀 クイックスタート

1. クローンとインストール

git clone https://github.com/yourusername/fs-mcp.git
cd fs-mcp

uv を使用する場合（推奨）：

uv sync

pip を使用する場合：

pip install -r requirements.txt  # If you have a requirements.txt
# OR install directly
pip install fastmcp>=2.0.0 langchain>=0.3.0 python-dotenv>=1.1.0

2. 環境設定

プロジェクトのルートに .env ファイルを作成します。

# Security Settings
SAFE_DIRECTORY=.                    # Directory restriction (required)
MAX_FILE_SIZE_MB=100                # File size limit in MB

# Encoding Settings
DEFAULT_ENCODING=utf-8

# AI Embeddings Configuration (for vector search)
OPENAI_EMBEDDINGS_API_KEY=your-api-key
OPENAI_EMBEDDINGS_BASE_URL=http://your-embedding-service/v1
EMBEDDING_MODEL_NAME=BAAI/bge-m3    # Or your preferred model
EMBEDDING_CHUNK_SIZE=1000

3. サーバーを起動する

python main.py

サーバーは http://localhost:3002 で起動し、ベクトルインデックスを自動的に構築します。

🛠️ インストール

システム要件

• Python：3.12 以降
• OS：Windows、macOS、Linux
• メモリ：ベクトル検索には 4GB 以上を推奨
• ストレージ：キャッシュとインデックス用に 1GB 以上

依存関係

コア依存関係は pyproject.toml で管理されています。

• fastmcp>=2.0.0 - MCP サーバーフレームワーク
• langchain>=0.3.0 - AI とベクトル検索
• python-dotenv>=1.1.0 - 環境管理
• ドキュメント処理ライブラリ（pandas、openpyxl、python-docx など）

⚙️ 設定

環境変数

変数	デフォルト	説明
SAFE_DIRECTORY	.	ファイルアクセスのルートディレクトリ
MAX_FILE_SIZE_MB	100	ファイルサイズの上限
DEFAULT_ENCODING	utf-8	ファイルのデフォルトエンコーディング
OPENAI_EMBEDDINGS_API_KEY	-	埋め込みサービスの API キー
OPENAI_EMBEDDINGS_BASE_URL	-	埋め込みサービスの URL
EMBEDDING_MODEL_NAME	BAAI/bge-m3	埋め込みに使用する AI モデル
EMBEDDING_CHUNK_SIZE	1000	処理時のテキストチャンクサイズ

高度な設定

本番環境にデプロイする場合は、以下を検討してください。

• レート制限の設定
• ログローテーションの設定
• 外部ベクトルデータベースの利用
• モニタリングの設定

🔧 MCP ツール

1. view_directory_tree

目的：ディレクトリ構造をツリー形式で表示します

view_directory_tree(
    directory_path=".",     # Target directory
    max_depth=3,           # Maximum depth
    max_entries=300        # Maximum entries to show
)

2. read_file_content

目的：行範囲を指定してファイルの内容を読み取ります

read_file_content(
    file_path="example.py",  # File path
    start_line=1,           # Start line (optional)
    end_line=50             # End line (optional)
)

3. search_documents

目的：ドキュメント全体を対象にインテリジェントなセマンティック検索を行います

search_documents(
    query="authentication logic",     # Search query
    search_type="semantic",          # semantic/filename/hybrid/extension
    file_extensions=".py,.js",       # File type filter (optional)
    max_results=10                   # Maximum results
)

4. rebuild_document_index

目的：検索用のベクトルインデックスを再構築します

rebuild_document_index()  # No parameters needed

5. get_document_stats

目的：インデックスの統計情報とシステムの状態を取得します

get_document_stats()  # Returns comprehensive stats

6. list_files

目的：パターンマッチングを使用してディレクトリ内のファイルを一覧表示します

list_files(
    directory_path="./src",  # Directory to list
    pattern="*.py",         # File pattern
    include_size=True       # Include file sizes
)

7. preview_file

目的：ファイルの内容をすばやくプレビューします

preview_file(
    file_path="example.py",  # File to preview
    lines=20                # Number of lines
)

🔍 ベクトル検索

機能

• セマンティック理解：「ユーザー認証」を検索すると、「ログイン検証」のコードが見つかります
• 同義語の認識：「database」を検索すると、「数据库」（中国語）のコンテンツが見つかります
• 多言語対応：英語、中国語、および混在したコンテンツを処理します
• コンテキスト認識：コードの意味や関連性を理解します

検索タイプ

1. セマンティック検索（semantic）：AI を活用した理解
2. ファイル名検索（filename）：高速なファイル名マッチング
3. 拡張子検索（extension）：ファイルタイプで絞り込み
4. ハイブリッド検索（hybrid）：セマンティック検索とファイル名検索を組み合わせます

技術スタック

• 埋め込みモデル：BAAI/bge-m3（1024 次元ベクトル）
• ベクトルデータベース：ChromaDB
• テキスト分割：インテリジェントなセマンティックチャンク分割
• 差分更新：ハッシュベースの変更検出

📁 対応形式

自動検出されるテキストファイル

• プログラミング言語：.py、.js、.ts、.java、.cpp、.c、.go、.rsなど
• 設定ファイル：.json、.yaml、.toml、.ini、.xml、.env
• ドキュメント：.md、.txt、.rst
• Web ファイル：.html、.css、.scss
• データファイル：.csv、.tsv
• 拡張子のないファイル（自動検出）

ドキュメント形式（Markdown に自動変換）

• Microsoft Office：.docx、.xlsx、.pptx
• OpenDocument：.odt、.ods、.odp
• PDF：.pdf（テキスト抽出）
• 旧形式：.doc、.xls（サポートは限定的）

🔒 セキュリティ機能

アクセス制御

• ディレクトリ制限：アクセスは SAFE_DIRECTORY およびそのサブディレクトリに制限されます
• パストラバーサル対策：../ 攻撃を自動的に防止します
• シンボリックリンク制御：シンボリックリンクへのアクセスを設定できます
• ファイルサイズ制限：サイズが大きすぎるファイルの読み込みを防止します

検証

• パスのサニタイズ：パスを自動的にクリーンアップして検証します
• 権限チェック：アクセス前に読み取り権限を確認します
• エラー処理：わかりやすいメッセージを表示し、適切に処理を終了します

🔗 統合

Claude Desktop

Claude Desktop の MCP 設定に追加します。

{
  "mcpServers": {
    "fs-mcp": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "/path/to/fs-mcp",
      "env": {
        "SAFE_DIRECTORY": "/your/project/directory"
      }
    }
  }
}

その他の MCP クライアント

Server-Sent Events（SSE）プロトコルを使用して、http://localhost:3002 に接続します。

API 統合

このサーバーは標準の MCP エンドポイントを公開しており、MCP 互換の任意のクライアントと統合できます。

🏗️ プロジェクト構成

fs-mcp/
├── main.py                    # Main MCP server
├── src/                       # Core modules
│   ├── __init__.py           # Package initialization
│   ├── file_reader.py        # Core file reading logic
│   ├── security_validator.py # Security and validation
│   ├── text_detector.py      # Intelligent file detection
│   ├── config_manager.py     # Configuration management
│   ├── document_cache.py     # Document caching system
│   ├── file_converters.py    # Document format converters
│   ├── dir_tree.py          # Directory tree generation
│   ├── embedding_config.py   # AI embedding configuration
│   ├── codebase_indexer.py   # Vector indexing system
│   ├── codebase_search.py    # Search engine
│   ├── index_scheduler.py    # Index scheduling
│   └── progress_bar.py       # Progress display utilities
├── tests/                    # Test suite
├── cache/                    # Document cache (auto-created)
├── logs/                     # Log files (auto-created)
├── pyproject.toml           # Project configuration
├── .env.example             # Environment template
├── .gitignore              # Git ignore rules
└── README.md               # This file

💻 開発

開発環境のセットアップ

# Clone repository
git clone https://github.com/yourusername/fs-mcp.git
cd fs-mcp

# Install with development dependencies
uv sync --group dev

# OR with pip
pip install -e ".[dev]"

テストの実行

# Run all tests
pytest

# Run with coverage
pytest --cov=src

# Run specific test
pytest tests/test_file_reader.py

コード品質

# Format code
black src/ tests/

# Lint code
flake8 src/ tests/

# Type checking
mypy src/

デバッグ

ログをリアルタイムで監視します。

tail -f logs/mcp_server_$(date +%Y%m%d).log

🤝 コントリビューション

コントリビューションを歓迎します。始めるには、次の手順に従ってください。

1. フォークとクローン

git clone https://github.com/yourusername/fs-mcp.git
cd fs-mcp

2. フィーチャーブランチの作成

git checkout -b feature/your-feature-name

3. 変更の実施

• 既存のコードスタイルに従ってください
• 新しい機能にはテストを追加してください
• 必要に応じてドキュメントを更新してください

4. 変更のテスト

pytest
black src/ tests/
flake8 src/ tests/

5. プルリクエストの送信

• 変更内容を明確に説明してください
• 関連する課題があれば参照してください
• すべてのテストが成功することを確認してください

開発ガイドライン

• コードスタイル：PEP 8 に従い、フォーマットには Black を使用してください
• テスト：テストカバレッジを 80% 以上に保ってください
• ドキュメント：README と docstring を更新してください
• コミット：Conventional Commits のメッセージ形式を使用してください
• セキュリティ：セキュリティのベストプラクティスに従ってください

📋 ロードマップ

• PDF 処理の強化：表や画像の抽出を改善
• 埋め込みモデルの追加：ローカルモデルに対応
• リアルタイムインデックス作成：ファイルシステムウォッチャー
• 高度な検索：正規表現、近接検索、ファセット検索
• パフォーマンスの最適化：非同期処理、キャッシュの改善
• Web インターフェース：管理用のオプションの Web UI
• プラグインシステム：カスタムファイルタイプハンドラー
• エンタープライズ機能：認証、レート制限、監視

📄 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。

🙏 謝辞

• FastMCP - MCP サーバーのフレームワーク
• LangChain - AI 統合
• ChromaDB - ベクトルデータベース
• BGE-M3 - 埋め込みモデル

📞 サポート

• 課題：GitHub Issues
• ディスカッション：GitHub Discussions
• ドキュメント：docs/ フォルダーを確認してください（利用可能な場合）

---

中国語

🚀 機能

• 🧠 インテリジェントなテキスト検出：拡張子に依存せず、テキストファイルを自動識別します
• 📄 複数形式のサポート：テキストファイルとドキュメント形式（Word、Excel、PDF など）をサポートします
• 🔒 安全な検証：設定された安全なディレクトリ内のファイルのみ読み取れます
• 📏 行単位での読み取り：行範囲を指定して読み取れるため、大きなファイルの処理に便利です
• 🔄 ドキュメント変換：ドキュメント形式を自動的にMarkdownに変換してキャッシュします
• 🔍 ベクトル検索：AI 埋め込みに基づくセマンティック検索
• ⚡ 高パフォーマンス：ファイルの一括処理とインテリジェントなキャッシュに対応します
• 🌐 多言語対応：中国語と英語のコンテンツ処理に対応します

🚀 クイックスタート

1. クローンとインストール

git clone https://github.com/yourusername/fs-mcp.git
cd fs-mcp

# 推荐使用 uv
uv sync

# 或使用 pip
pip install -r requirements.txt

2. 環境設定

.env ファイルを作成します：

# 安全设置
SAFE_DIRECTORY=.                    # 目录访问限制（必需）
MAX_FILE_SIZE_MB=100                # 文件大小限制（MB）

# 编码设置
DEFAULT_ENCODING=utf-8

# AI嵌入配置（用于向量搜索）
OPENAI_EMBEDDINGS_API_KEY=your-api-key
OPENAI_EMBEDDINGS_BASE_URL=http://your-embedding-service/v1
EMBEDDING_MODEL_NAME=BAAI/bge-m3    # 或您偏好的模型
EMBEDDING_CHUNK_SIZE=1000

3. サーバーの起動

python main.py

サーバーは http://localhost:3002 で起動し、ベクトルインデックスを自動的に作成します。

🛠️ MCP ツールの説明

ツールの詳しい使用方法については、英語部分の MCP Tools セクションを参照してください。

🔍 ベクトル検索機能

• 概念のマッチング：「ユーザー認証」を検索すると、「ログイン検証」に関連するコードが見つかります
• 同義語の理解：「database」を検索すると、「データベース」に関連するコンテンツが見つかります
• 多言語対応：中国語と英語のコードおよびコメントを同時に理解します
• コンテキストの理解：コードの意味とコンテキストの関係を理解します

📁 サポート対象のファイル形式

サポート対象の形式について詳しくは、英語部分の Supported Formats セクションを参照してください。

🔒 セキュリティ機能

• パスの検証：設定された安全なディレクトリとそのサブディレクトリのみアクセスできます
• ファイルサイズの制限：大きすぎるファイルの読み取りを防ぎます
• パストラバーサル対策：../ などによるパストラバーサル攻撃を自動的に防ぎます
• シンボリックリンクの制御：シンボリックリンクへのアクセスを許可するかどうか設定できます

🔗 統合方法

Claude Desktop との統合

Claude Desktop の MCP 設定に追加します：

{
  "mcpServers": {
    "fs-mcp": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "/path/to/fs-mcp",
      "env": {
        "SAFE_DIRECTORY": "/your/project/directory"
      }
    }
  }
}

💻 開発

開発環境の設定

# 克隆仓库
git clone https://github.com/yourusername/fs-mcp.git
cd fs-mcp

# 安装开发依赖
uv sync --group dev

テストの実行

# 运行所有测试
pytest

# 运行覆盖率测试
pytest --cov=src

🤝 貢献

コードの貢献を歓迎します！詳しくは、英語部分の Contributing セクションを参照してください。

📄 ライセンス

本プロジェクトは MIT ライセンスを採用しています。詳しくは LICENSE ファイルを参照してください。

---