Filesystem Usage Guide¶

Overview¶

This guide shows how to use the Filesystem with different MCP clients and integration methods.

Tool Discovery¶

Interactive CLIRegular CLIPython Client

# Start interactive mode
mcp_platform interactive

# List available tools
mcpp> tools filesystem

# Discover tools using CLI
mcp_platform tools filesystem

from mcp_platform.client import MCPClient

async def discover_tools():
    client = MCPClient()
    tools = client.list_tools("filesystem")
    for tool in tools:
        print(f"Tool: {tool['name']} - {tool['description']}")

Available Tools¶

copy_file¶

Description: Copy files and directories.

Parameters: - destination (string) (required): Destination path - source (string) (required): Source path of the file or directory

create_directory¶

Description: Create a new directory or ensure a directory exists.

Parameters: - path (string) (required): Path of the directory to create

delete_file¶

Description: Delete a file or directory from the file system.

Parameters: - path (string) (required): Path to the file or directory to delete - recursive (boolean) (optional): Whether to recursively delete directories (default: false)

get_file_info¶

Description: Retrieve detailed metadata about a file or directory.

Parameters: - path (string) (required): Path to the file or directory

list_allowed_directories¶

Description: Returns the list of directories that this server is allowed to access.

Parameters: - No parameters required

list_directory¶

Description: Get a detailed listing of all files and directories in a specified path.

Parameters: - path (string) (required): Path of the directory to list

modify_file¶

Description: Update file by finding and replacing text. Provides a simple pattern matching interface without needing exact character positions.

Parameters: - all_occurrences (boolean) (optional): Replace all occurrences of the matching text (default: true) - find (string) (required): Text to search for (exact match or regex pattern) - path (string) (required): Path to the file to modify - regex (boolean) (optional): Treat the find pattern as a regular expression (default: false) - replace (string) (required): Text to replace with

move_file¶

Description: Move or rename files and directories.

Parameters: - destination (string) (required): Destination path - source (string) (required): Source path of the file or directory

read_file¶

Description: Read the complete contents of a file from the file system.

Parameters: - path (string) (required): Path to the file to read

read_multiple_files¶

Description: Read the contents of multiple files in a single operation.

Parameters: - paths (array) (required): List of file paths to read

search_files¶

Description: Recursively search for files and directories matching a pattern.

Parameters: - path (string) (required): Starting path for the search - pattern (string) (required): Search pattern to match against file names

search_within_files¶

Description: Search for text within file contents. Unlike search_files which only searches file names, this tool scans the actual contents of text files for matching substrings. Binary files are automatically excluded from the search. Reports file paths and line numbers where matches are found.

Parameters: - depth (number) (optional): Maximum directory depth to search (default: unlimited) - max_results (number) (optional): Maximum number of results to return (default: 1000) - path (string) (required): Starting path for the search (must be a directory) - substring (string) (required): Text to search for within file contents

tree¶

Description: Returns a hierarchical JSON representation of a directory structure.

Parameters: - depth (number) (optional): Maximum depth to traverse (default: 3) - follow_symlinks (boolean) (optional): Whether to follow symbolic links (default: false) - path (string) (required): Path of the directory to traverse

write_file¶

Description: Create a new file or overwrite an existing file with new content.

Parameters: - content (string) (required): Content to write to the file - path (string) (required): Path where to write the file

Usage Examples¶

Interactive CLIRegular CLIPython Client

# Start interactive mode
mcp_platform interactive

# Deploy the template (if not already deployed)
mcpp> deploy filesystem

# List available tools after deployment
mcpp> tools filesystem

Then call tools:

mcpp> call filesystem copy_file '{"destination": "example_value", "source": "example_value"}'

mcpp> call filesystem create_directory '{"path": "example_value"}'

mcpp> call filesystem delete_file '{"path": "example_value", "recursive": true}'

# Deploy the template
mcp_platform deploy filesystem

# Check deployment status
mcp_platform status

# View logs
mcp_platform logs filesystem

# Stop the template
mcp_platform stop filesystem

import asyncio
from mcp_platform.client import MCPClient

async def use_filesystem():
    client = MCPClient()

    # Start the server
    deployment = client.start_server("filesystem", {})

    if deployment["success"]:
        deployment_id = deployment["deployment_id"]

        try:
            # Discover available tools
            tools = client.list_tools("filesystem")
            print(f"Available tools: {[t['name'] for t in tools]}")

            # Call copy_file
            result = client.call_tool("filesystem", "copy_file", {'destination': 'example_value', 'source': 'example_value'})
            print(f"copy_file result: {result}")

            # Call create_directory
            result = client.call_tool("filesystem", "create_directory", {'path': 'example_value'})
            print(f"create_directory result: {result}")

        finally:
            # Clean up
            client.stop_server(deployment_id)
    else:
        print("Failed to start server")

# Run the example
asyncio.run(use_filesystem())

Integration Examples¶

Claude DesktopVS CodeManual Connection

Add this configuration to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "python",
      "args": ["-m", "mcp_platform", "connect", "filesystem", "--stdio"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Install the MCP extension and add this to your VS Code settings (.vscode/settings.json):

{
  "mcp.servers": {
    "filesystem": {
      "command": "python",
      "args": ["-m", "mcp_platform", "connect", "filesystem", "--stdio"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

# Get connection details for other integrations
mcp_platform connect filesystem --llm claude
mcp_platform connect filesystem --llm vscode

Configuration¶

For template-specific configuration options, see the main template documentation. Common configuration methods:

Environment VariablesCLI ConfigurationConfig File

# Deploy with environment variables
mcp_platform deploy filesystem --env KEY=VALUE

# Deploy with configuration
mcp_platform deploy filesystem --config key=value

# Deploy with nested configuration
mcp_platform deploy filesystem --config category__property=value

# Deploy with config file
mcp_platform deploy filesystem --config-file config.json

Troubleshooting¶

Common Issues¶

Template not found: Ensure the template name is correct
```
mcp_platform list  # List available templates
```
Connection issues: Check if the server is running
```
mcp_platform status
```
Tool discovery fails: Try refreshing the tool cache
```
mcpp> tools filesystem --refresh
```

Debug Mode¶

Enable debug logging for troubleshooting:

Interactive CLIDeploy with Debug

# Interactive CLI with debug
LOG_LEVEL=debug mcp_platform interactive

# Deploy with debug logging
mcp_platform deploy filesystem --config log_level=debug

For more help, see the main documentation or open an issue in the repository.