Example: File Operations

This example demonstrates how to set up file system operations for reading, writing, and listing files.

Overview

This configuration enables an agent to interact with the local file system within specified directories.

What You'll Need

Node.js installed (for the MCP server)
A directory path you want to allow access to

Configuration

providers:
  - cursor
  - claude-code

skills:
  - id: file-manager
    type: inline
    def:
      content: |
        ---
        name: file-manager
        description: Manage local files and directories
        ---
        
        # File Manager
        
        Tools for reading, writing, and managing files.
        
        ## When to Use
        - Reading configuration files
        - Writing output to files
        - Listing directory contents
        - Managing project files
        
        ## Available Tools
        - read_file: Read file contents
        - write_file: Write or update files
        - list_directory: List files in a directory
      requires:
        - read_file
        - write_file
        - list_directory

servers:
  - id: filesystem
    type: mcp
    def:
      cmd: npx
      args:
        - -y
        - "@modelcontextprotocol/server-filesystem"
        - /Users/username/projects  # Change to your path

tools:
  - id: read_file
    type: mcp
    def:
      server: "@filesystem"
      tool: read_file
  
  - id: write_file
    type: mcp
    def:
      server: "@filesystem"
      tool: write_file
  
  - id: list_directory
    type: mcp
    def:
      server: "@filesystem"
      tool: list_directory

{
  "providers": ["cursor", "claude-code"],
  "skills": [
    {
      "id": "file-manager",
      "type": "inline",
      "def": {
        "content": "---\nname: file-manager\ndescription: Manage local files and directories\n---\n\n# File Manager\n\nTools for reading, writing, and managing files.\n\n## When to Use\n- Reading configuration files\n- Writing output to files\n- Listing directory contents\n- Managing project files\n\n## Available Tools\n- read_file: Read file contents\n- write_file: Write or update files\n- list_directory: List files in a directory",
        "requires": ["read_file", "write_file", "list_directory"]
      }
    }
  ],
  "servers": [
    {
      "id": "filesystem",
      "type": "mcp",
      "def": {
        "cmd": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/Users/username/projects"
        ]
      }
    }
  ],
  "tools": [
    {
      "id": "read_file",
      "type": "mcp",
      "def": {
        "server": "@filesystem",
        "tool": "read_file"
      }
    },
    {
      "id": "write_file",
      "type": "mcp",
      "def": {
        "server": "@filesystem",
        "tool": "write_file"
      }
    },
    {
      "id": "list_directory",
      "type": "mcp",
      "def": {
        "server": "@filesystem",
        "tool": "list_directory"
      }
    }
  ]
}

Setup Steps

1. Choose a Directory

Decide which directory the agent should have access to. This could be:

Your projects directory: /Users/username/projects
A specific project: /Users/username/projects/my-project
Your home directory: ~ (use absolute path)

Security Note: Only grant access to directories you trust the agent to modify. The agent will have full read/write access to the specified directory and its subdirectories.

2. Update the Configuration

Replace /Users/username/projects in the configuration with your chosen path.

For Windows:

args:
  - -y
  - "@modelcontextprotocol/server-filesystem"
  - C:\Users\username\projects

3. Initialize and Install

capa init
# Paste the configuration into capabilities.yaml
capa install

Usage Examples

Reading a File

// Activate the file-manager skill
setup_tools({"skills": ["file-manager"]})

// Use call_tool to read a file
call_tool({
  "name": "read_file",
  "data": {
    "path": "/Users/username/projects/config.json"
  }
})

Writing a File

call_tool({
  "name": "write_file",
  "data": {
    "path": "/Users/username/projects/output.txt",
    "content": "Generated content here"
  }
})

Listing Directory Contents

call_tool({
  "name": "list_directory",
  "data": {
    "path": "/Users/username/projects/my-project"
  }
})

Note: These examples assume toolExposure: on-demand. With expose-all, call tools directly.

Multiple Directory Access

To grant access to multiple directories, create multiple servers:

servers:
  - id: projects-fs
    type: mcp
    def:
      cmd: npx -y @modelcontextprotocol/server-filesystem
      args:
        - /Users/username/projects
  
  - id: documents-fs
    type: mcp
    def:
      cmd: npx -y @modelcontextprotocol/server-filesystem
      args:
        - /Users/username/Documents

tools:
  - id: read_project_file
    type: mcp
    def:
      server: "@projects-fs"
      tool: read_file
  
  - id: read_document
    type: mcp
    def:
      server: "@documents-fs"
      tool: read_file

{
  "servers": [
    {
      "id": "projects-fs",
      "type": "mcp",
      "def": {
        "cmd": "npx -y @modelcontextprotocol/server-filesystem",
        "args": ["/Users/username/projects"]
      }
    },
    {
      "id": "documents-fs",
      "type": "mcp",
      "def": {
        "cmd": "npx -y @modelcontextprotocol/server-filesystem",
        "args": ["/Users/username/Documents"]
      }
    }
  ],
  "tools": [
    {
      "id": "read_project_file",
      "type": "mcp",
      "def": {
        "server": "@projects-fs",
        "tool": "read_file"
      }
    },
    {
      "id": "read_document",
      "type": "mcp",
      "def": {
        "server": "@documents-fs",
        "tool": "read_file"
      }
    }
  ]
}

Best Practices

Limit scope: Grant access only to necessary directories
Use project-specific paths: Point to specific projects rather than root directories
Version control: Ensure important files are in version control before allowing agent modifications
Read-only option: Consider exposing only read_file and list_directory for sensitive directories