通过强大、与平台无关的文件系统功能为您的 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 生成。
输入清理。
可选速率限制（实用程序文件已创建但尚未集成）。
类型安全：在 TypeScript 中完全实现，以提高可靠性和可维护性。
克隆存储库：
git clone https://github.com/cyanheads/filesystem-mcp-server.git
cd filesystem-mcp-server安装依赖项：
npm install构建项目：
npm run build这会将dist/目录中的 TypeScript 代码编译为 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 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 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 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
