ファイルシステムMCPサーバー

👁 タイプスクリプト
👁 モデルコンテキストプロトコル
👁 バージョン
👁 ライセンス
👁 状態
👁 GitHub

強力でプラットフォームに依存しないファイル システム機能を使用して AI エージェントを強化します。

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

目次

• 概要

• 特徴

• インストール

• 構成

• MCPクライアントでの使用

• 利用可能なツール

• プロジェクト構造

• 発達

• ライセンス

Related MCP server: MCP Filesystem Server

概要

モデルコンテキストプロトコル（MCP）は、AIモデルが外部ツールやデータソース（リソース）と安全にやり取りできるようにする標準フレームワークです。このサーバーはMCP標準を実装し、重要なファイルシステム操作をツールとして公開することで、AIエージェントが以下のことを実現できるようにします。

• ファイルの内容を読み取り、分析します。

• ファイルを作成、変更、または上書きします。

• ディレクトリとファイル パスを管理します。

• ファイル内で対象を絞った更新を実行します。

TypeScript で構築されたこのサーバーは、型の安全性、モジュール性、堅牢なエラー処理を重視しており、AI ワークフローへの信頼性の高い統合に適しています。

建築

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

flowchart TB
 subgraph API["API Layer"]
 direction LR
 MCP["MCP Protocol Interface"]
 Val["Input Validation (Zod)"]
 San["Path Sanitization"]

 MCP --> Val --> San
 end

 subgraph Core["Core Services"]
 direction LR
 Config["Configuration"]
 Logger["Logging (Winston)"]
 Error["Error Handling"]
 Server["MCP Server Logic"]
 State["Session State"]

 Config --> Server
 Logger --> Server & Error
 Error --> Server
 State --> Server
 end

 subgraph Implementation["Tool Implementation"]
 direction LR
 ToolLogic["Filesystem Tools"]
 Utils["Core Utilities"]

 ToolLogic --> Server
 Utils -- Used by --> ToolLogic
 Utils -- Used by --> Core
 end

 San --> ToolLogic

 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 API,Core,Implementation layer
 class MCP,Val,San,Config,Logger,Error,Server,State,ToolLogic,Utils component

• API レイヤー: MCP 通信を処理し、Zod を使用して入力を検証し、パスをサニタイズします。

• コア サービス: 構成、ログ記録、エラー レポート、セッション状態 (既定の作業ディレクトリなど)、およびメインの MCP サーバー インスタンスを管理します。

• ツール実装: 共有ユーティリティを活用して、各ファイルシステム ツールの特定のロジックが含まれています。

特徴

• 包括的なファイル操作: ファイルとディレクトリの読み取り、書き込み、一覧表示、削除、移動、コピーを行うツール。

• ターゲット更新: update_fileツールを使用すると、プレーン テキストと正規表現をサポートし、ファイル内で正確な検索と置換操作を実行できます。

• セッション対応パス管理: set_filesystem_defaultツールは、セッション中に相対パスを解決するためのデフォルトの作業ディレクトリを確立します。

• セキュリティ第一：組み込みのパスサニタイズ機能により、ディレクトリトラバーサル攻撃を防止します。オプションのベースディレクトリ制限により、セキュリティが強化されます。

• 堅牢な基盤: 以下の製品レベルのユーティリティが含まれています:

  • 構造化されたコンテキスト認識型のログ記録。

  • 特定のエラー コードを使用した標準化されたエラー処理。

  • リクエストトレース用の一意の ID 生成。

  • 入力のサニタイズ。

  • オプションのレート制限 (util ファイルは作成されましたが、まだ統合されていません)。

• 型安全性: 信頼性と保守性を向上させるために 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に保存されます。

構成

環境変数を使用してサーバーを構成します。

• FS_BASE_DIRECTORY (オプション、セキュリティのために推奨):

  • 絶対パスに設定すると、サーバーによるすべてのファイル操作は、このディレクトリとそのサブディレクトリ内に厳密に制限されます。これにより、AIエージェントが意図したスコープ外のファイルにアクセスするのを防ぎます。

  • 例: FS_BASE_DIRECTORY=/Users/casey/safe-agent-files

• LOG_LEVEL (オプション):

  • ログの詳細度を制御します。オプション: error 、 warn 、 info 、 http 、 verbose 、 debug 、 silly 。

  • デフォルトはinfoです。

• LOG_DIR (オプション):

  • ログ ファイル ( combined.log 、 error.log ) が保存されるディレクトリを指定します。

  • デフォルトは、サーバーの実行ディレクトリを基準とした./logsです。

MCPクライアントでの使用

MCP クライアント (AI アシスタントなど) がこのサーバーを使用できるようにするには:

1. **サーバーの実行:**ターミナルからサーバーを起動します。

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

2. クライアントの設定： MCPクライアントの設定にサーバーを追加します。具体的な方法はクライアントによって異なりますが、通常は以下の項目を指定します。

   • コマンド: node

   • **引数:**構築されたサーバー実行可能ファイルへの絶対パス (例: /path/to/filesystem-mcp-server/dist/index.js )。

   • **環境変数 (オプション):**必要に応じてFS_BASE_DIRECTORY 、 LOG_LEVEL 、またはLOG_DIRを設定します。

   MCP 設定の例 (概念):

   {
    "mcpServers": {
    "filesystem": {
    "command": "node",
    "args": ["/path/to/filesystem-mcp-server/dist/index.js"],
    "env": {
    "FS_BASE_DIRECTORY": "/path/to/base/directory",
    "LOG_LEVEL": "debug"
    },
    "disabled": false,
    "autoApprove": []
    }
    // ... other servers
    }
   }

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

利用可能なツール

サーバーは、ファイルシステムの対話用に次のツールを公開します。

詳細な入力/出力スキーマ (Zod/JSON スキーマ) については、ツール登録ファイル ( 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 and tool registration
│ │ ├── 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.)
│ ├── types-global/ # Shared TypeScript types and interfaces
│ │ ├── errors.ts # Custom error classes and codes
│ │ ├── mcp.ts # MCP related types
│ │ └── tool.ts # Tool definition types
│ ├── utils/ # Reusable utility modules
│ │ ├── errorHandler.ts
│ │ ├── idGenerator.ts
│ │ ├── index.ts
│ │ ├── logger.ts
│ │ ├── rateLimiter.ts
│ │ ├── requestContext.ts
│ │ └── sanitization.ts
│ └── index.ts # Main application entry point
├── .clinerules # Cheatsheet for LLM assistants
├── .gitignore
├── LICENSE
├── package.json
├── package-lock.json
├── README.md # This file
└── tsconfig.json # TypeScript compiler options

現在の構造の詳細なライブビューを表示するには、 npm run treeを実行します。

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

ライセンス

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

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers

Tools

• copy_pathB
• create_directoryB
• delete_directoryB
• delete_fileA
• list_filesA
• move_pathB
• read_fileA
• set_filesystem_defaultA