Filesystem MCP Server

Filesystem MCP サーバー

STDIO と Streamable HTTP のトランスポートオプションに対応した、堅牢でプラットフォームに依存しないファイルシステム機能を AI エージェントに提供します。

この Model Context Protocol (MCP) サーバーは、AI エージェントがローカルファイルシステムを操作するための、安全で信頼性の高いインターフェースを提供します。ファイルやディレクトリの読み取り、書き込み、更新、管理を可能にします。包括的なログ記録、エラー処理、セキュリティ対策を備えた、本番環境対応の TypeScript 基盤を採用しており、STDIO と HTTP の両方のトランスポートをサポートしています。

目次

• 概要
• 機能
• インストール
• 設定
• MCP クライアントでの使用
• 利用可能なツール
• プロジェクト構成
• 開発
• ライセンス

概要

Model Context Protocol (MCP) は、AI モデルが外部ツールやデータソース（リソース）と安全にやり取りできるようにする標準フレームワークです。このサーバーは MCP 標準を実装し、基本的なファイルシステム操作をツールとして公開することで、AI エージェントに次の機能を提供します。

• ファイルの内容を読み取り、分析します。
• ファイルを作成、変更、または上書きします。
• ディレクトリとファイルパスを管理します。
• ファイル内の指定箇所を更新します。

TypeScript で構築されたこのサーバーは、型安全性、モジュール性、堅牢なエラー処理を重視しており、AI ワークフローへの信頼性の高い統合に適しています。プロセス間の直接通信に使う STDIO と、ネットワークベースの通信に使う HTTP の両方をサポートするようになりました。

アーキテクチャ

このサーバーでは、明確さと保守性を高めるために、階層化アーキテクチャを採用しています。

flowchart TB
    subgraph TransportLayer["Transport Layer"]
        direction LR
        STDIO["STDIO Transport"]
        HTTP["HTTP Transport (Express, JWT Auth)"]
    end

    subgraph APILayer["API Layer"]
        direction LR
        MCP["MCP Protocol Interface"]
        Val["Input Validation (Zod)"]
        PathSan["Path Sanitization"]

        MCP --> Val --> PathSan
    end

    subgraph CoreServices["Core Services"]
        direction LR
        Config["Configuration (Zod-validated Env Vars)"]
        Logger["Logging (Winston, Context-aware)"]
        ErrorH["Error Handling (McpError, ErrorHandler)"]
        ServerLogic["MCP Server Logic"]
        State["Session State (Default Path)"]

        Config --> ServerLogic
        Logger --> ServerLogic & ErrorH
        ErrorH --> ServerLogic
        State --> ServerLogic
    end

    subgraph ToolImpl["Tool Implementation"]
        direction LR
        FSTools["Filesystem Tools"]
        Utils["Core Utilities (Internal, Security, Metrics, Parsing)"]

        FSTools --> ServerLogic
        Utils -- Used by --> FSTools
        Utils -- Used by --> CoreServices
        Utils -- Used by --> APILayer
    end

    TransportLayer --> MCP
    PathSan --> FSTools

    classDef layer fill:#2d3748,stroke:#4299e1,stroke-width:3px,rx:5,color:#fff
    classDef component fill:#1a202c,stroke:#a0aec0,stroke-width:2px,rx:3,color:#fff
    class TransportLayer,APILayer,CoreServices,ToolImpl layer
    class STDIO,HTTP,MCP,Val,PathSan,Config,Logger,ErrorH,ServerLogic,State,FSTools,Utils component

• トランスポート層：STDIO または HTTP（Express.js と JWT 認証を使用）による通信を処理します。
• API 層：MCP 通信を管理し、Zod を使って入力を検証し、パスをサニタイズします。
• コアサービス：設定（Zod で検証される環境変数）、コンテキストを考慮したログ記録、標準化されたエラー報告、セッション状態（デフォルトの作業ディレクトリなど）、および MCP サーバーのメインインスタンスを管理します。
• ツールの実装：各ファイルシステムツール固有のロジックを含み、内部処理、セキュリティ、メトリクス、解析の各モジュールに分類された、リファクタリング済みの共有ユーティリティ群を活用します。

特徴

• 包括的なファイル操作：ファイルやディレクトリの読み取り、書き込み、一覧表示、削除、移動、コピーを行うツールを提供します。
• 対象を絞った更新：update_file ツールを使うと、ファイル内で正確な検索と置換を実行できます。プレーンテキストと正規表現に対応しています。
• セッション対応のパス管理：set_filesystem_default ツールを使うと、セッション中に相対パスを解決するためのデフォルトの作業ディレクトリを設定できます。
• 2 種類のトランスポートに対応：
  • STDIO：子プロセスとして実行する場合に、直接かつ効率的に通信します。
  • HTTP：ネットワーク経由の通信に対応します。RESTful エンドポイント、ストリーミング用の Server-Sent Events（SSE）、JWT ベースの認証を備えています。
• セキュリティを最優先：
  • 組み込みのパスサニタイズにより、ディレクトリトラバーサル攻撃を防ぎます。
  • HTTP トランスポートでは JWT 認証を使用します。
  • Zod による入力検証に対応しています。
• 堅牢な基盤：本番環境にも対応するユーティリティを備え、モジュール性を高めるために再編成しました。
  • 内部ユーティリティ：コンテキストを考慮したロギング（Winston）、標準化されたエラー処理（McpError、ErrorHandler）、リクエストコンテキスト管理。
  • セキュリティユーティリティ：入力のサニタイズ、レート制限、UUID と接頭辞付き ID の生成。
  • メトリクスユーティリティ：トークン数のカウント。
  • 解析ユーティリティ：自然言語による日付の解析、部分的な JSON の解析。
• 設定の強化：Zod で検証される環境変数により、型安全で信頼性の高いセットアップを実現します。
• 型安全性：信頼性と保守性を高めるため、TypeScript で完全に実装されています。

インストール

手順

1. リポジトリをクローンします：

   git clone https://github.com/cyanheads/filesystem-mcp-server.git
   cd filesystem-mcp-server
   

2. 依存関係をインストールします：

   npm install
   

3. プロジェクトをビルドします：

   npm run build
   

   TypeScript コードを dist/ ディレクトリ内の JavaScript にコンパイルし、メインスクリプトを実行可能にします。実行可能ファイルは dist/index.js に配置されます。

設定

環境変数を使用してサーバーを設定します（.env ファイルもサポートされています）。

コアサーバー設定：

• MCP_LOG_LEVEL（任意）：ログの最小レベル（例：debug、info、warn、error）。デフォルトはdebugです。
• LOGS_DIR（任意）：ログファイルのディレクトリ。デフォルトはプロジェクトのルートにある./logsです。
• NODE_ENV（任意）：実行環境（例：development、production）。デフォルトはdevelopmentです。

トランスポート設定：

• MCP_TRANSPORT_TYPE（任意）：通信トランスポート（stdioまたはhttp）。デフォルトはstdioです。
  • httpを選択した場合：
    • MCP_HTTP_PORT（任意）：HTTP サーバーのポート。デフォルトは3010です。
    • MCP_HTTP_HOST（任意）：HTTP サーバーのホスト。デフォルトは127.0.0.1です。
    • MCP_ALLOWED_ORIGINS（任意）：許可する CORS オリジンのカンマ区切りリスト（例：http://localhost:3000,https://example.com）。
    • MCP_AUTH_SECRET_KEY（HTTP 認証で必須）：JWT 認証用の安全な秘密鍵（32 文字以上）。本番環境では極めて重要です。

ファイルシステムのセキュリティ：

• FS_BASE_DIRECTORY（任意）：すべてのファイルシステム操作のルートディレクトリを定義します。絶対パスまたはプロジェクトルートからの相対パス（例：./data_sandbox）を指定できます。設定すると、サーバーのツールは、この指定された（解決後の絶対）パスとそのサブディレクトリ内のファイルおよびディレクトリのみにアクセスできます。これは、ファイルシステムの他の領域への意図しないアクセスを防ぐための重要なセキュリティ機能です。設定されていない場合（本番環境では推奨されません）、警告がログに記録され、操作は制限されません。

LLM と API の統合（任意）：

• OPENROUTER_APP_URL：OpenRouter 用のアプリケーション URL。
• OPENROUTER_APP_NAME：OpenRouter 用のアプリケーション名。デフォルトはMCP_SERVER_NAMEです。
• OPENROUTER_API_KEY：OpenRouter サービス用の API キー。
• LLM_DEFAULT_MODEL：使用するデフォルトの LLM モデル（例：google/gemini-2.5-flash-preview-05-20）。
• LLM_DEFAULT_TEMPERATURE、LLM_DEFAULT_TOP_P、LLM_DEFAULT_MAX_TOKENS、LLM_DEFAULT_TOP_K、LLM_DEFAULT_MIN_P：LLM 呼び出しのデフォルトパラメーター。
• GEMINI_API_KEY：Google Gemini サービス用の API キー。

OAuth プロキシとの統合（任意、高度なシナリオ向け）：

• OAUTH_PROXY_AUTHORIZATION_URL、OAUTH_PROXY_TOKEN_URL、OAUTH_PROXY_REVOCATION_URL、OAUTH_PROXY_ISSUER_URL、OAUTH_PROXY_SERVICE_DOCUMENTATION_URL、OAUTH_PROXY_DEFAULT_CLIENT_REDIRECT_URIS：OAuth プロキシの設定。

完全な一覧と Zod スキーマの定義については、src/config/index.ts と .clinerules ファイルを参照してください。

MCP クライアントでの使用方法

MCP クライアント（AI アシスタントなど）がこのサーバーを使用できるようにするには、次の手順を実行します。

1. サーバーを起動する： ターミナルからサーバーを起動します。

   node dist/index.js
   # Or if you are in the project root:
   # npm start
   

2. クライアントを設定する： MCP クライアントの設定にサーバーを追加します。具体的な方法はクライアントによって異なります。

   STDIO トランスポートの場合（デフォルト）： 通常は、次の項目を指定します。

   • コマンド： node
   • 引数： ビルド済みサーバー実行ファイルの絶対パス（例：/path/to/filesystem-mcp-server/dist/index.js）。
   • 環境変数（任意）： Configuration セクションにある必要な環境変数を設定します。

   STDIO 用 MCP 設定の例（概念）：

   {
     "mcpServers": {
       "filesystem_stdio": {
         "command": "node",
         "args": ["/path/to/filesystem-mcp-server/dist/index.js"],
         "env": {
           "MCP_LOG_LEVEL": "debug"
           // Other relevant env vars
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

   HTTP トランスポートの場合： クライアントには、サーバーの URL（例：http://localhost:3010）と認証方法（MCP_AUTH_SECRET_KEY が設定されている場合は JWT ベアラートークンを指定するなど）を知らせる必要があります。HTTP サーバーの設定については、使用する MCP クライアントのドキュメントを参照してください。

設定してサーバーを起動すると、クライアントがサーバーと利用可能なツールを検出します。

利用可能なツール

このサーバーは、ファイルシステムを操作するための次のツールを公開します。

ツール	説明
set_filesystem_default	現在のセッションのデフォルトの絶対パスを設定します。以降のツール呼び出しで使用する相対パスは、このデフォルトを基準に解決されます。サーバーの再起動時にリセットされます。
read_file	指定したファイルの内容全体を UTF-8 テキストとして読み込みます。相対パス（デフォルトを基準に解決）または絶対パスを指定できます。
write_file	指定したファイルに内容を書き込みます。ファイルが存在しない場合は（必要な親ディレクトリも含めて）作成し、存在する場合は上書きします。相対パスまたは絶対パスを指定できます。
update_file	{search, replace} ブロックの配列を使用して、既存のファイル内で対象を絞った検索と置換を実行します。部分的な変更に適しています。プレーンテキストまたは正規表現による検索（useRegex: true）と、すべての一致箇所の置換（replaceAll: true）に対応しています。相対パスまたは絶対パスを指定できます。ファイルが存在する必要があります。
list_files	指定したパス内のファイルとディレクトリを一覧表示します。オプションで、再帰的な一覧表示（includeNested: true）やエントリー数の上限（maxEntries）を指定できます。整形されたツリー構造で返されます。相対パスまたは絶対パスを指定できます。
delete_file	特定のファイルを完全に削除します。相対パスまたは絶対パスを指定できます。
delete_directory	ディレクトリを完全に削除します。空でないディレクトリとその内容を削除するには、recursive: true を指定してください（慎重に使用してください！）。相対パスまたは絶対パスを指定できます。
create_directory	指定したパスに新しいディレクトリを作成します。デフォルト（create_parents: true）では、必要な親ディレクトリも作成します。相対パスまたは絶対パスを指定できます。
move_path	ファイルまたはディレクトリを、移動元のパスから移動先のパスへ移動または名前変更します。移動元と移動先の両方に、相対パスまたは絶対パスを指定できます。
copy_path	ファイルまたはディレクトリを、コピー元のパスからコピー先のパスへコピーします。ディレクトリはデフォルトで再帰的にコピーされます（recursive: true）。相対パスまたは絶対パスを指定できます。
詳細な入出力スキーマ（Zod／JSON Schema）については、ツール登録ファイル（src/mcp-server/tools/*/registration.ts）を参照してください。

プロジェクト構成

コードベースは、明瞭さと保守性を重視して構成されています。

filesystem-mcp-server/
├── dist/                 # Compiled JavaScript output (after npm run build)
├── logs/                 # Log files (created at runtime)
├── node_modules/         # Project dependencies
├── src/                  # TypeScript source code
│   ├── config/           # Configuration loading (index.ts)
│   ├── mcp-server/       # Core MCP server logic
│   │   ├── server.ts     # Server initialization, tool registration, transport handling
│   │   ├── state.ts      # Session state management (e.g., default path)
│   │   ├── tools/        # Individual tool implementations (one subdir per tool)
│   │   │   ├── readFile/
│   │   │   │   ├── index.ts
│   │   │   │   ├── readFileLogic.ts
│   │   │   │   └── registration.ts
│   │   │   └── ...       # Other tools (writeFile, updateFile, etc.)
│   │   └── transports/   # Communication transport implementations
│   │       ├── authentication/ # Auth middleware for HTTP
│   │       │   └── authMiddleware.ts
│   │       ├── httpTransport.ts
│   │       └── stdioTransport.ts
│   ├── types-global/     # Shared TypeScript types and interfaces
│   │   ├── errors.ts     # Custom error classes and codes (McpError, BaseErrorCode)
│   │   ├── mcp.ts        # MCP related types
│   │   └── tool.ts       # Tool definition types
│   ├── utils/            # Reusable utility modules, categorized
│   │   ├── internal/     # Core internal utilities (errorHandler, logger, requestContext)
│   │   ├── metrics/      # Metrics-related utilities (tokenCounter)
│   │   ├── parsing/      # Parsing utilities (dateParser, jsonParser)
│   │   ├── security/     # Security-related utilities (idGenerator, rateLimiter, sanitization)
│   │   └── index.ts      # Barrel export for all utilities
│   └── index.ts          # Main application entry point
├── .clinerules           # Cheatsheet for LLM assistants
├── .dockerignore
├── Dockerfile
├── LICENSE
├── mcp.json              # MCP server manifest (generated by SDK or manually)
├── package.json
├── package-lock.json
├── README.md             # This file
├── repomix.config.json
├── smithery.yaml         # Smithery configuration (if used)
└── tsconfig.json         # TypeScript compiler options

現在の構成をリアルタイムで詳しく確認するには、npm run tree を実行してください（変更に src/scripts/tree.ts が含まれていた場合は、このスクリプトの更新が必要になることがあります）。

開発者向け注記： このリポジトリには .clinerules ファイルが含まれています。このチートシートは、コードベースのパターン、ファイルの場所、使用例など、LLM コーディングアシスタントに必要なコンテキストを提供します。サーバーの進化に合わせて、常に最新の状態に保ってください。

ライセンス

このプロジェクトは Apache License 2.0 のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。

---