Skip to content

MCP Server Guide

Andrew Paolucci edited this page Nov 19, 2026 · 1 revision

Model Context Protocol (MCP) Server Guide

robocopy2rust embeds a pure-Rust JSON-RPC 2.0 over stdio Model Context Protocol server implementing protocol version 2024-11-05, exposed both via robocopy2rust mcp and as a dedicated standalone binary robocopy2rust-mcp (crates/robocopy2rust-mcp/src/).


Client Configuration

Standard MCP Client (mcp.json)

{
  "mcpServers": {
    "robocopy2rust": {
      "command": "robocopy2rust",
      "args": [
        "mcp"
      ],
      "env": {
        "RUST_LOG": "warn"
      }
    }
  }
}

Standalone Binary / Smithery (smithery.yaml)

Using robocopy2rust-mcp directly avoids even the subcommand argument ("command": "robocopy2rust-mcp"). Notice that robocopy2rust-mcp starts reading JSON-RPC requests immediately from stdin (it does not accept --help), while all diagnostic tracing logs go strictly to stderr so JSON-RPC stdout framing stays pristine.

Supported JSON-RPC methods: initialize, ping, tools/list, tools/call, plus notifications notifications/initialized and notifications/cancelled. Invalid JSON returns -32700; unknown methods return -32601.


Exposed Tools (9 Structured Tools)

1. robocopy2rust_environment

Probes the host OS, robocopy.exe availability (C:\Windows\System32\robocopy.exe first, then PATH), resolved executable path, and ProfileStore config directory.

  • Arguments: {}

2. robocopy2rust_presets

Returns all 8 built-in JobPreset definitions with categories, destructive flags, summaries, and complete RobocopyJob configurations.

  • Arguments: {}

3. robocopy2rust_build_command

Constructs and validates a Robocopy command plus optional .rcj, .bat, .ps1, and Windows Task Scheduler schtasks outputs.

  • Arguments:
    • job (object, optional) — Full RobocopyJob JSON
    • preset (string, optional) — Preset ID or name
    • source / destination (string, optional)
    • file_specs (string[], optional)
    • dry_run (bool, optional)
    • include_scripts (bool, optional) — Includes rcj, batch_script, and powershell_script
    • task_name (string, optional) — Triggers schtasks generation
    • cadence (string, optional) — daily, weekly, hourly, onstart, onlogon (default daily)
    • start_time (string, optional) — HH:MM (default "02:00")

4. robocopy2rust_parse_command

Parses a raw command-line string or on-disk .rcj file (UTF-8 or UTF-16LE/BE) into normalized command_line, parser warnings, validation findings, and structured job JSON.

  • Arguments: Either command (string) or rcj_path (string).

5. robocopy2rust_decode_exit_code

Decodes a Robocopy exit code (0..=16, or < 0 cancelled) into severity, short_label, is_success (0..=7 = true), summary, and bit_descriptions.

  • Arguments: code (integer, required).

6. robocopy2rust_profiles

Full persistent profile CRUD against profiles.json (or an isolated store_dir for testing/workspaces).

  • Arguments:
    • action (enum, required): "list" | "get" | "save" | "delete"
    • name (string) — Required for get, save, delete
    • description (string, optional) — Used on save
    • job (object, optional) — Used on save
    • store_dir (string, optional) — Custom directory override

7. robocopy2rust_dry_run

Executes a non-destructive /L simulation (with_list_only()), enforcing all Error-level validation rules first. Returns full RunResult JSON (summary, file_actions, errors, exit_code, log_sha256). Verified in unit tests against real Windows robocopy.exe.

  • Arguments: Any combination of job, command, preset, source, destination.

8. robocopy2rust_run (Strict Safety Refusal)

Executes a live Robocopy transfer after running validate_job.

  • Arguments: job, command, preset, source, destination, confirm_destructive (bool, optional).
  • Safety Gate: If job.has_destructive_flags() is true (/MIR, /PURGE, /MOVE, or /MOV without /L) and confirm_destructive is not true, robocopy2rust_run refuses immediately with isError: true:

    SAFETY REFUSAL: Job includes destructive flag(s) (/MIR, /PURGE). Re-run with robocopy2rust_dry_run first or set confirm_destructive=true.

9. robocopy2rust_report

Generates offline HTML, JSON, Markdown, or all three (all) from either an existing log_path or a live /L dry-run job.

  • Arguments: output (string, required), format (html | json | markdown | all, default html), plus either log_path or job parameters (job/source/destination).
  • Returns: { "status": "success", "files_written": [...], "exit_code": ..., "log_sha256": "..." }.

Recommended Safe AI Agent Workflow

  1. Call robocopy2rust_environment to verify robocopy_available: true on the host.
  2. Call robocopy2rust_presets or robocopy2rust_build_command to assemble and validate flags (check findings for Error or Warning diagnostics).
  3. Call robocopy2rust_dry_run to inspect exact summary counts and planned file_actions without touching destination files.
  4. Present any destructive deletions (*EXTRA File / /MIR / /PURGE / /MOVE) to the human user for explicit approval.
  5. Only after approval, call robocopy2rust_run (setting confirm_destructive: true if destructive) and verify exit code via robocopy2rust_decode_exit_code.
  6. Persist an audit trail via robocopy2rust_report (format: "all").

Clone this wiki locally