強力でプラットフォームに依存しないファイル システム機能を使用して AI エージェントを強化します。
このモデルコンテキストプロトコル（MCP）サーバーは、AIエージェントがローカルファイルシステムとやり取りするための安全で信頼性の高いインターフェースを提供します。包括的なログ記録、エラー処理、セキュリティ対策を備えた本番環境対応のTypeScript基盤を備え、ファイルとディレクトリの読み取り、書き込み、更新、管理を可能にします。
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 componentAPI レイヤー: 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 クライアント (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
}
}設定して実行すると、クライアントはサーバーと利用可能なツールを検出します。
サーバーは、ファイルシステムの対話用に次のツールを公開します。
道具 | 説明 |
| 現在のセッションのデフォルトの絶対パスを設定します。以降のツール呼び出しで使用される相対パスは、このデフォルトに基づいて解決されます。サーバーの再起動時にリセットされます。 |
| 指定されたファイルの内容全体をUTF-8テキストとして読み取ります。相対パス（デフォルトに対して解決）または絶対パスを受け入れます。 |
| 指定されたファイルにコンテンツを書き込みます。ファイル（および必要な親ディレクトリ）が存在しない場合は作成し、存在する場合は上書きします。相対パスまたは絶対パスを指定できます。 |
|
|
| 指定されたパス内のファイルとディレクトリを一覧表示します。再帰的な一覧表示（ |
| 特定のファイルを完全に削除します。相対パスまたは絶対パスを指定できます。 |
| ディレクトリを完全に削除します。空でないディレクトリとその内容を削除するには、 |
| 指定されたパスに新しいディレクトリを作成します。デフォルト（ |
| ファイルまたはディレクトリをソースパスからターゲットパスに移動または名前変更します。相対パスと絶対パスのどちらでも指定できます。 |
| ファイルまたはディレクトリをコピー元パスからコピー先パスにコピーします。ディレクトリの場合、デフォルトで再帰的にコピーします（ |
詳細な入力/出力スキーマ (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ファイルをご覧ください。
Copies a file or directory to a new location. Accepts relative or absolute paths. Defaults to recursive copy for directories.
| Name | Required | Description | Default |
|---|---|---|---|
| destination_path | Yes | The path where the copy should be created. Can be relative or absolute. | |
| recursive | No | If copying a directory, whether to copy its contents recursively. Defaults to true. | |
| source_path | Yes | The path of the file or directory to copy. Can be relative or absolute. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the default recursive behavior for directories, which is useful, but lacks critical details such as permission requirements, error handling (e.g., what happens if source doesn't exist or destination already exists), side effects, or whether it overwrites files. For a mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with two sentences that efficiently convey the core action and a key behavioral trait. There's no wasted text, though it could be slightly more structured (e.g., separating purpose from guidelines).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a file system mutation tool with no annotations and no output schema, the description is incomplete. It lacks information on permissions, error conditions, return values, and how it interacts with sibling tools. The description alone doesn't provide enough context for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by reiterating that paths can be relative or absolute and noting the default recursive behavior, but doesn't provide additional syntax, format, or semantic details. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Copies a file or directory to a new location.' It specifies the verb ('Copies') and resource ('file or directory'), but doesn't explicitly differentiate from sibling tools like 'move_path' or 'write_file' beyond the inherent meaning of 'copy' versus 'move' or 'write'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some implied usage context by mentioning 'Defaults to recursive copy for directories,' which suggests when to use default behavior. However, it doesn't explicitly state when to choose this tool over alternatives like 'move_path' or 'write_file,' nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a directory. Optionally creates parent directories. Accepts relative or absolute paths.
| Name | Required | Description | Default |
|---|---|---|---|
| create_parents | No | If true, create any necessary parent directories that don't exist. If false, fail if a parent directory is missing. | |
| path | Yes | The path to the directory to create. Can be relative or absolute. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the tool can fail if parent directories are missing (when create_parents is false) and supports relative/absolute paths, but doesn't cover critical aspects like permissions needed, error handling, or whether it overwrites existing directories. For a mutation tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with three short sentences that each add value: the core action, the parent directory feature, and path flexibility. There is no wasted text, and it's front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens on success (e.g., returns the created path), error conditions beyond missing parents, or permissions required. Given the complexity of filesystem operations and lack of structured safety hints, more behavioral context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters. The description adds minimal value by restating that paths can be relative or absolute (already in schema) and hinting at parent directory creation (implied by create_parents). It doesn't provide additional syntax, format, or usage details beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Creates a directory') and distinguishes it from siblings like 'delete_directory' or 'list_files' by focusing on creation. It also adds nuance about parent directory creation, which further differentiates it from simple file operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'write_file' for creating files or 'set_filesystem_default' for configuration. It mentions optional parent directory creation but doesn't explain when to enable or disable this feature in practice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Removes a directory. Optionally removes recursively. Accepts relative or absolute paths.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The path to the directory to delete. Can be relative or absolute. | |
| recursive | No | If true, delete the directory and all its contents. If false, only delete if the directory is empty. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the recursive option and path types, but lacks critical details such as permission requirements, whether deletion is irreversible, error handling (e.g., for non-existent paths), or side effects. For a destructive tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two sentences that are front-loaded and efficient. The first sentence states the core action, and the second adds necessary context about recursion and path types, with zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, lack of annotations, and no output schema, the description is incomplete. It should address risks (e.g., irreversible deletion), permissions, or error responses to help an agent use it safely. The current description leaves too many behavioral aspects unspecified for a tool that modifies the filesystem.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters (path and recursive) with clear descriptions. The description adds minimal value by repeating that paths can be relative or absolute and hinting at recursive behavior, but doesn't provide additional syntax or format details beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Removes') and resource ('a directory'), distinguishing it from sibling tools like delete_file (which removes files) and create_directory (which creates directories). The description provides unambiguous action and target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the mention of 'Optionally removes recursively,' suggesting when to use the recursive parameter, but it doesn't explicitly state when to choose this tool over alternatives like delete_file or provide exclusions (e.g., when not to delete system directories). No named alternatives or clear context for tool selection are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Removes a specific file. Accepts relative or absolute paths.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The path to the file to delete. Can be relative or absolute (resolved like readFile). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action is destructive ('Removes') but fails to mention critical behaviors: whether deletion is permanent or reversible, any permission requirements, error handling (e.g., for non-existent files), or side effects. This leaves significant gaps for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences that directly state the tool's purpose and parameter acceptance. Every word serves a purpose, with no redundancy or unnecessary elaboration, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature and lack of annotations or output schema, the description is incomplete. It doesn't address key contextual aspects: the permanence of deletion, permission requirements, error responses, or what happens upon success. For a mutation tool with significant behavioral implications, this leaves too much unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents the single parameter 'path' with details on format and resolution. The description adds minimal value by restating that it 'Accepts relative or absolute paths,' which is already covered in the schema. With only one parameter, the baseline is high, but the description doesn't enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Removes') and target resource ('a specific file'), distinguishing it from siblings like delete_directory (which removes directories) or move_path (which relocates files). It precisely communicates the tool's function without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for file deletion but provides no explicit guidance on when to use this tool versus alternatives like move_path (for relocation) or delete_directory (for directory removal). It lacks context about prerequisites (e.g., file existence, permissions) or exclusions, leaving usage decisions to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists files and directories within the specified directory. Optionally lists recursively and returns a tree-like structure. Includes an optional maxEntries parameter (default 50) to limit the number of items returned.
| Name | Required | Description | Default |
|---|---|---|---|
| includeNested | No | If true, list files and directories recursively. Defaults to false (top-level only). | |
| maxEntries | No | Maximum number of directory entries (files + folders) to return. Defaults to 50. Helps prevent excessive output for large directories. | |
| path | Yes | The path to the directory to list. Can be relative or absolute (resolved like readFile). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about recursive listing and output limiting, but doesn't cover important aspects like error handling, permission requirements, performance implications for large directories, or what the return structure looks like. It's adequate but has clear gaps for a read operation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in three sentences that each add value: stating the core purpose, explaining optional recursive behavior, and detailing the maxEntries parameter. There's no wasted language or redundancy, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with no output schema and no annotations, the description provides basic operational information but lacks details about return format, error conditions, or performance characteristics. It's minimally viable but doesn't fully compensate for the missing structured metadata that would help an agent understand the complete behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description mentions the maxEntries parameter and its default, and implies recursive functionality, but doesn't add significant meaning beyond what the schema provides. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Lists files and directories') and resource ('within the specified directory'), distinguishing it from siblings like copy_path, delete_file, or read_file that perform different operations on files. It precisely communicates the tool's function without being vague or tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing directory contents but doesn't explicitly state when to use this tool versus alternatives like read_file or other file operations. It mentions optional parameters but provides no guidance on scenarios where this tool is preferred over others or any prerequisites for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Moves or renames a file or directory. Accepts relative or absolute paths for source and destination.
| Name | Required | Description | Default |
|---|---|---|---|
| destination_path | Yes | The new path for the file or directory. Can be relative or absolute. | |
| source_path | Yes | The current path of the file or directory to move. Can be relative or absolute. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but doesn't cover critical aspects like whether it overwrites existing files, requires permissions, handles errors, or affects file metadata. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and key parameter feature. Every word contributes meaning without redundancy, making it appropriately sized and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., overwrite behavior, error handling), usage context, and return values, leaving the agent with insufficient information for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters. The description adds minimal value by reiterating that paths can be relative or absolute, but doesn't provide additional syntax, format, or usage details beyond what the schema already specifies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Moves or renames') and resource ('a file or directory'), distinguishing it from siblings like copy_path (copies) or delete_file (deletes). It precisely defines the tool's function without being vague or tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like copy_path or update_file, nor does it mention prerequisites or exclusions. It lacks context for selection among similar file operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads the entire content of a specified file as UTF-8 text. Accepts relative or absolute paths. Relative paths are resolved against the session default set by set_filesystem_default.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The path to the file to read. Can be relative or absolute. If relative, it resolves against the path set by `set_filesystem_default`. If absolute, it is used directly. If relative and no default is set, an error occurs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool reads files as UTF-8 and handles path resolution, but it does not mention error conditions beyond the relative path case, performance implications for large files, or return format details. It adds some behavioral context but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by essential usage details in the second. Both sentences earn their place by providing critical information without waste, making it highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter, no output schema, no annotations), the description is mostly complete. It covers the purpose, usage, and path semantics adequately, but it lacks details on return values (e.g., text content format) and error handling, which would be beneficial for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single parameter. The description adds no additional meaning beyond what the schema provides about the path parameter, such as examples or edge cases. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Reads the entire content') and resource ('of a specified file'), with additional details about encoding ('as UTF-8 text') that distinguish it from siblings like write_file or update_file. It precisely defines what the tool does without being tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool by explaining path resolution rules and referencing set_filesystem_default, but it does not explicitly state when not to use it or name alternatives (e.g., list_files for metadata). The guidance is helpful but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sets a default absolute path for the current session. Relative paths used in other filesystem tools (like readFile) will be resolved against this default. The default is cleared on server restart.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The absolute path to set as the default for resolving relative paths during this session. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it sets a session-scoped default, affects other tools, and clears on server restart. However, it lacks details on permissions, error handling, or validation of the path.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, with two sentences that efficiently convey purpose and behavior without wasted words, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is mostly complete, covering purpose, usage, and key behavior. However, it could benefit from mentioning error cases or interactions with specific sibling tools for full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the 'path' parameter thoroughly. The description adds no additional meaning beyond what the schema provides, such as format examples or constraints, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Sets a default absolute path') and resource ('for the current session'), and distinguishes it from siblings by explaining its unique role in resolving relative paths for other filesystem tools like readFile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool (to set a default path for resolving relative paths in other filesystem tools) and mentions the session scope, but does not explicitly state when not to use it or name specific alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Performs targeted search-and-replace operations within an existing file using an array of {search, replace} blocks. Preferred for smaller, localized changes. For large-scale updates or overwrites, consider using write_file. Accepts relative or absolute paths. File must exist. Supports optional useRegex (boolean, default false) and replaceAll (boolean, default false).
| Name | Required | Description | Default |
|---|---|---|---|
| blocks | Yes | An array of objects, each with a `search` (string) and `replace` (string) property. | |
| path | Yes | The path to the file to update. Can be relative or absolute (resolved like readFile). The file must exist. | |
| replaceAll | No | If true, replace all occurrences matching the SEARCH criteria within the file. If false, only replace the first occurrence. Defaults to false. | |
| useRegex | No | If true, treat the `search` field of each block as a JavaScript regular expression pattern. Defaults to false (exact string matching). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it modifies existing files (implies mutation), requires the file to exist, supports path resolution, and mentions optional parameters with defaults. It doesn't explicitly mention error handling or permissions requirements, but covers most operational aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with zero waste: first sentence states core purpose, second provides usage guidance, third covers path handling and prerequisites, fourth explains optional parameters. Every sentence earns its place and information is front-loaded appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description does well by covering purpose, usage context, prerequisites, and parameter overview. It could be more complete by mentioning what happens on success/failure or typical return values, but given the schema's 100% coverage and clear behavioral disclosure, it's mostly adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents all 4 parameters. The description adds minimal value beyond the schema - it mentions the 'blocks' parameter structure and the optional boolean parameters, but doesn't provide additional semantic context. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'targeted search-and-replace operations within an existing file' using specific data structures. It distinguishes from sibling tools like 'write_file' by specifying it's for 'smaller, localized changes' rather than large-scale overwrites.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Preferred for smaller, localized changes' and 'For large-scale updates or overwrites, consider using `write_file`.' It also states prerequisites: 'File must exist' and 'Accepts relative or absolute paths.' This gives clear when-to-use and when-not-to-use criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes content to a specified file. Creates the file (and necessary directories) if it doesn't exist, or overwrites it if it does. Accepts relative or absolute paths (resolved like readFile).
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The content to write to the file. If the file exists, it will be overwritten. | |
| path | Yes | The path to the file to write. Can be relative or absolute. If relative, it resolves against the path set by `set_filesystem_default`. If absolute, it is used directly. Missing directories will be created. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and discloses key behaviors: it creates files/directories if missing, overwrites existing files, and resolves paths similarly to readFile. It does not mention permissions, error handling, or rate limits, but covers core mutation traits adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by essential behavioral details in two concise sentences. Every sentence adds value without redundancy, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description provides good context on behavior and parameters. It could be more complete by mentioning error cases or return values, but it adequately covers the tool's functionality given the structured data available.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters. The description adds minimal value beyond the schema, only reiterating overwrite behavior for 'content' and path resolution for 'path', aligning with the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'writes' and the resource 'content to a specified file', specifying both creation and overwrite behaviors. It distinguishes from siblings like read_file (read-only), update_file (partial updates), and delete_file (removal).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for writing or creating files, with context on path resolution and directory creation. However, it lacks explicit guidance on when to use this versus alternatives like update_file (for partial updates) or create_directory (for directories only), and no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0copy_pathcreate_directorydelete_directorydelete_filelist_filesmove_pathread_fileset_filesystem_defaultupdate_filewrite_fileScored across 10 tools
Each tool has a clearly distinct purpose with no ambiguity: copy_path, move_path, delete_file, and delete_directory handle different file operations; list_files, read_file, write_file, and update_file serve distinct read/write functions; create_directory and set_filesystem_default are unique utilities. The descriptions reinforce these distinctions, making misselection unlikely.
The tool names follow a consistent snake_case pattern with clear verb_noun structures (e.g., copy_path, delete_file). However, there is a minor deviation with set_filesystem_default, which uses a longer, descriptive name that breaks the simple verb_noun pattern, though it remains readable and consistent in style.
With 10 tools, the count is well-scoped for a filesystem server, covering essential operations like create, read, update, delete, list, copy, move, and session management. Each tool earns its place without redundancy, fitting the typical range of 3-15 tools for such a domain.
The tool set provides complete CRUD/lifecycle coverage for filesystem operations: create_directory, read_file, write_file, update_file, delete_file, and delete_directory handle core file management; list_files, copy_path, and move_path support navigation and organization; set_filesystem_default adds session context. There are no obvious gaps, enabling agents to perform comprehensive filesystem tasks without dead ends.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
A Model Context Protocol server for Wix AI tools
