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

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

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

概要

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

ファイルの内容を読み取り、分析します。
ファイルを作成、変更、または上書きします。
ディレクトリとファイルパスを管理します。
ファイル内で対象を絞った更新を実行します。

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

建築

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

API レイヤー: MCP 通信を処理し、Zod を使用して入力を検証し、パスをサニタイズします。
コアサービス: 構成、ログ記録、エラーレポート、セッション状態 (既定の作業ディレクトリなど)、およびメインの MCP サーバーインスタンスを管理します。
ツール実装: 共有ユーティリティを活用して、各ファイルシステムツールの特定のロジックが含まれています。

特徴

包括的なファイル操作: ファイルとディレクトリの読み取り、書き込み、一覧表示、削除、移動、コピーを行うツール。
ターゲット更新: update_fileツールを使用すると、プレーンテキストと正規表現をサポートし、ファイル内で正確な検索と置換操作を実行できます。
セッション対応パス管理: set_filesystem_defaultツールは、セッション中に相対パスを解決するためのデフォルトの作業ディレクトリを確立します。
セキュリティ第一：組み込みのパスサニタイズ機能により、ディレクトリトラバーサル攻撃を防止します。オプションのベースディレクトリ制限により、セキュリティが強化されます。
堅牢な基盤: 以下の製品レベルのユーティリティが含まれています:
- 構造化されたコンテキスト認識型のログ記録。
- 特定のエラーコードを使用した標準化されたエラー処理。
- リクエストトレース用の一意の ID 生成。
- 入力のサニタイズ。
- オプションのレート制限 (util ファイルは作成されましたが、まだ統合されていません)。
型安全性: 信頼性と保守性を向上させるために TypeScript で完全に実装されています。

インストール

手順

リポジトリをクローンします。
git clone https://github.com/cyanheads/filesystem-mcp-server.git cd filesystem-mcp-server
依存関係をインストールします:
npm install
プロジェクトをビルドします。
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 アシスタントなど) がこのサーバーを使用できるようにするには:

**サーバーの実行:**ターミナルからサーバーを起動します。
node dist/index.js # Or if you are in the project root: # npm start
クライアントの設定： 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 } }

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

利用可能なツール

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

道具	説明
`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 スキーマ) については、ツール登録ファイル ( 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ファイルをご覧ください。

Filesystem MCP Server

Integrations