xserver-files-operator

name	xserver-files-operator
description	Operate the xserver-files-mcp repository safely. Use when working on this repo's local stdio MCP server, CLI, XServer SFTP configuration, remote file reads/writes, .htaccess backups, or domain redirect workflows such as old-site.example.com to new-site.example.com.

XServer Files Operator

Overview

Use this skill to work with the local MCP/CLI in this repository without bypassing its safety model. The MCP connects to XServer over SFTP on port 10022, restricts paths to configured domain roots, and backs up existing files before writes by default.

Safety Contract

• Treat ~/.config/xserver-files-mcp/config.json as the operator-owned config; keep only config/example.config.json in the repo.
• Keep private keys under ~/.ssh/, not in this repository.
• Use server_id for multi-server work; omit it only when the default server is intended.
• Use configured domains such as old-site.example.com; do not pass absolute remote paths to tools or CLI commands.
• Run dry-run first for redirect and write workflows unless the user explicitly asks for an immediate write.
• Keep backups enabled unless the user explicitly accepts the risk.
• Keep local site workspaces outside this repository, normally under ~/Dev/xserver-sites.
• Use workspace pull/push for edited site files; do not clone WordPress/site trees into this tool repository.
• Treat wp-config.php, uploads, logs, backups, SQL/database dumps, and archives as default-excluded workspace paths unless the user explicitly accepts the risk.
• Understand that replaceInFile and set_domain_redirect are not atomic: they read, transform, and write in separate SFTP calls. If another operator edits the same file concurrently, their changes may be lost. Coordinate access or use pull/push workflow for critical edits.

Local Checks

Install and test:

npm install
npm test

Check config parsing without connecting to XServer:

XSERVER_FILES_CONFIG=config/example.config.json node src/cli.js servers

Create a domain workspace outside the repository:

node src/cli.js workspace old-site.example.com

Pull one file for local editing:

node src/cli.js pull old-site.example.com .htaccess

Push the matching workspace file back with a dry-run first:

node src/cli.js push old-site.example.com .htaccess --dry-run
node src/cli.js push old-site.example.com .htaccess

Setup Workflow

1. Copy config/example.config.json to ~/.config/xserver-files-mcp/config.json.
2. Create/register the SSH key outside the repo, for example ~/.ssh/xserver_sv12345.
3. Verify XServer SSH/SFTP access on port 10022 before using remote file tools:

ssh -p 10022 -i ~/.ssh/xserver_sv12345 [e-mail] 'pwd'

4. Confirm the configured document roots before writes:

node src/cli.js roots
node src/cli.js ls old-site.example.com .
node src/cli.js workspace old-site.example.com

Redirect Workflow

For old-site.example.com to https://new-site.example.com, dry-run first:

node src/cli.js redirect old-site.example.com https://new-site.example.com --dry-run

Then apply:

node src/cli.js redirect old-site.example.com https://new-site.example.com

After applying, verify both HTTP hosts:

curl -I http://old-site.example.com/
curl -I http://www.old-site.example.com/

HTTPS verification depends on certificate state:

curl -I https://old-site.example.com/
curl -I https://www.old-site.example.com/

MCP Registration

Register src/server.js as a local stdio MCP command. Use an absolute path and pass the real config path through XSERVER_FILES_CONFIG:

{
  "mcpServers": {
    "xserver-files": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/xserver-files-mcp/src/server.js"],
      "env": {
        "XSERVER_FILES_CONFIG": "/Users/YOU/.config/xserver-files-mcp/config.json"
      }
    }
  }
}

Implementation Rules

• Put SFTP and path-safety logic in src/operations.js, src/sftp.js, or src/path-utils.js.
• Keep MCP tool schemas in src/server.js; keep CLI commands in src/cli.js.
• Add tests for safety-sensitive behavior before changing write, replace, backup, redirect, or path resolution code.
• Run npm test before finishing.