@yigstudio/skill-filesystem

Secure filesystem operations skill for Yigstudio (MCP Server).

Features

Provides 4 filesystem tools with security controls:

• fs.readFile - Read file contents
• fs.writeFile - Write file contents
• fs.listDir - List directory contents
• fs.deleteFile - Delete files/directories

Security

• Workspace Boundary: Only allows operations within workspace root
• Path Validation: Prevents directory traversal attacks
• Blocked Paths: Denies access to system directories (/etc, /sys, C:\Windows, etc.)
• Delete Protection: Requires explicit recursive: true for directory deletion

Installation

npm install @yigstudio/skill-filesystem

Usage

As MCP Server

Run as a standalone MCP server:

export FILESYSTEM_WORKSPACE="/path/to/workspace"
npx @yigstudio/skill-filesystem

Environment Variables

• FILESYSTEM_WORKSPACE (optional): Workspace root path (default: current directory)
• FILESYSTEM_ALLOWED_PATHS (optional): Comma-separated additional allowed paths
• FILESYSTEM_BLOCKED_PATHS (optional): Comma-separated additional blocked paths

With Yigstudio

Register in your Yigstudio application:

import { MCPClientManager } from '@yigstudio/mcp-runtime';
import { SkillRegistry } from '@yigstudio/skills';

const mcpClient = new MCPClientManager();
const skillRegistry = new SkillRegistry();

// Register Filesystem skill
await mcpClient.registerServer({
  id: 'skill-filesystem',
  name: 'Filesystem Skill',
  transport: {
    type: 'stdio',
    command: 'npx',
    args: ['@yigstudio/skill-filesystem'],
    env: {
      FILESYSTEM_WORKSPACE: process.cwd(),
    },
  },
});

// Register skill metadata
skillRegistry.register({
  id: 'fs-read-file',
  name: 'Read File',
  description: 'Read files from the workspace',
  version: '1.0.0',
  permissions: ['fs:read'],
  mcpServer: {
    serverId: 'skill-filesystem',
    command: 'npx',
    args: ['@yigstudio/skill-filesystem'],
    env: {
      FILESYSTEM_WORKSPACE: process.cwd(),
    },
  },
});

skillRegistry.register({
  id: 'fs-delete-file',
  name: 'Delete File',
  description: 'Delete files or directories from the workspace',
  version: '1.0.0',
  permissions: ['fs:delete'], // Requires elevated permission
  mcpServer: {
    serverId: 'skill-filesystem',
    command: 'npx',
    args: ['@yigstudio/skill-filesystem'],
    env: {
      FILESYSTEM_WORKSPACE: process.cwd(),
    },
  },
});

Tools

fs.readFile

Read the contents of a file.

Parameters:

• path (string, required): File path relative to workspace root
• encoding (string, optional): File encoding (default: utf-8)

Example:

{
  "path": "README.md",
  "encoding": "utf-8"
}

fs.writeFile

Write content to a file (creates parent directories if needed).

Parameters:

• path (string, required): File path relative to workspace root
• content (string, required): File content
• encoding (string, optional): File encoding (default: utf-8)
• mode (string|number, optional): File permissions

Example:

{
  "path": "output/result.txt",
  "content": "Hello, Yigstudio!",
  "encoding": "utf-8"
}

fs.listDir

List contents of a directory.

Parameters:

• path (string, required): Directory path relative to workspace root
• recursive (boolean, optional): Recursively list subdirectories (default: false)

Example:

{
  "path": "src",
  "recursive": true
}

fs.deleteFile

Delete a file or directory.

Parameters:

• path (string, required): File or directory path relative to workspace root
• recursive (boolean, optional): Delete directory recursively (default: false)

Example:

{
  "path": "temp/cache.json"
}

⚠️ Warning: This operation cannot be undone. Requires fs:delete permission in Sentinel.

Security Best Practices

1. Set Explicit Workspace: Always set FILESYSTEM_WORKSPACE to limit access
2. Use Minimal Permissions: Only grant fs:delete to trusted agents
3. Review Blocked Paths: Add sensitive directories to FILESYSTEM_BLOCKED_PATHS
4. Enable Sentinel: Use Sentinel for fine-grained access control

Default Blocked Paths

• /etc, /sys, /proc, /dev, /boot, /root (Linux)
• C:\Windows, C:\Program Files, C:\Program Files (x86) (Windows)
• /System, /Library (macOS)

Permissions

• fs:read: Read file, list directory
• fs:write: Write file
• fs:delete: Delete file/directory (elevated)

License

MIT