MCP Filesystem Server

move_file

Move or rename files and directories within allowed paths. This tool transfers files between directories or renames them in place, failing if the destination already exists.

Instructions

Move or rename files and directories. Can move files between directories and rename them in a single operation. If the destination exists, the operation will fail. Works across different directories and can be used for simple renaming within the same directory. Both source and destination must be within allowed directories.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`source`	Yes	Source path of the file or directory to move
`destination`	Yes	Destination path where to move the file or directory

Implementation Reference

src/index.ts:577-604 (handler)

The main execution logic for the 'move_file' tool. Parses input arguments using the schema, validates both source and destination paths against allowed directories, creates the destination parent directory if necessary, performs the file/directory move using fs.rename, logs the operation, and returns a success message.

case 'move_file': {
  const parsed = MoveFileArgsSchema.safeParse(a)
  if (!parsed.success) {
    throw new FileSystemError(`Invalid arguments for ${name}`, 'INVALID_ARGS', undefined, {
      errors: parsed.error.format(),
    })
  }

  const validSourcePath = await validatePath(parsed.data.source, config)
  const validDestPath = await validatePath(parsed.data.destination, config)

  // Ensure the destination parent directory exists
  const destDir = path.dirname(validDestPath)
  await fs.mkdir(destDir, { recursive: true })

  await fs.rename(validSourcePath, validDestPath)
  await logger.debug(`Moved file from ${validSourcePath} to ${validDestPath}`)

  endMetric()
  return {
    content: [
      {
        type: 'text',
        text: `Successfully moved ${parsed.data.source} to ${parsed.data.destination}`,
      },
    ],
  }
}

src/index.ts:128-131 (schema)

Zod schema defining the expected input structure for the move_file tool: source (string) and destination (string) paths.

const MoveFileArgsSchema = z.object({
  source: z.string().describe('Source path of the file or directory to move'),
  destination: z.string().describe('Destination path where to move the file or directory'),
})

src/index.ts:297-305 (registration)

Tool registration in the ListTools handler response. Specifies the tool name, detailed description of functionality and limitations, and converts the Zod schema to JSON schema for the MCP protocol.

{
  name: 'move_file',
  description:
    'Move or rename files and directories. Can move files between directories ' +
    'and rename them in a single operation. If the destination exists, the ' +
    'operation will fail. Works across different directories and can be used ' +
    'for simple renaming within the same directory. Both source and destination must be within allowed directories.',
  inputSchema: zodToJsonSchema(MoveFileArgsSchema) as ToolInput,
},

Schema Changelog

Changes observed during successful MCP inspections.

First observedAug 22, 2025

TDQS

A3.9/5.0

Behavior3/5

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 helpfully states that the operation fails if the destination exists and that both paths must be within allowed directories. However, it doesn't mention permissions needed, whether the operation is atomic, what happens on partial failures, or if there are rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with three sentences that each earn their place: first states the core functionality, second adds important behavioral constraints, third provides scope limitations. No wasted words or redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

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 adequate but incomplete context. It covers the basic operation and some constraints, but doesn't describe the return value, error conditions beyond destination existence, or what 'allowed directories' means in practice.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 adequately. The description adds minimal value beyond the schema by implying the relationship between source and destination parameters, but doesn't provide additional syntax, format details, or constraints beyond what's in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

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 ('move or rename') and resources ('files and directories'), distinguishing it from siblings like 'create_directory', 'edit_file', or 'write_file'. It explicitly mentions the dual functionality of moving between directories and renaming within the same directory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool ('move files between directories and rename them'), but doesn't explicitly state when not to use it or name alternatives. For example, it doesn't clarify if 'rename_file' is a separate tool or if this should be used over 'edit_file' for renaming.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server