name: local version: 1.2.12 description: Windows-native MCP server — shell, files, sessions, transforms, and breadcrumb operation tracking triggers:

• shell
• powershell
• run command
• file operations
• persistent session
• breadcrumb
• track operation
• archive
• transform
• bulk rename
• csv
• registry
• http fetch
• smart read
• process management server: local platform: windows audience: MCP builders shipping on Windows

local MCP Server — Skill Reference (v1.2.12)

Overview

local is a Windows-native MCP server that gives Claude shell access, file operations, persistent sessions, bulk transforms, and a breadcrumb operation tracking system for multi-step work.

What makes local different from Desktop Commander or Anthropic's filesystem MCP:

Minimum viable shell + operation tracking for non-developer users. If you need to run commands, move files, and not lose your place when something crashes — local is the server.

The Breadcrumb System

Breadcrumbs let you track multi-step operations with atomic persistence, crash recovery, and bulk cleanup.

Why Breadcrumbs Exist

Without tracking, a multi-step operation (deploy a server, migrate files, run a build pipeline) is invisible. If Claude's context resets mid-operation, the next session has no idea what happened. Breadcrumbs solve this:

1. Crash recovery — every step is atomically written to disk. A crash between step 3 and step 4 loses zero work. Call breadcrumb_status after restart and you see the exact resume point.
2. Auditability — the breadcrumb log is a durable record of what local did, when, and what the result was.
3. Dashboard visibility — the dashboard.html that ships with local renders breadcrumb history so you can see completed operations at a glance.
4. Bulk cleanup — breadcrumb_clear with older_than_days lets you prune old records without hunting through files.

The Discipline

Rule: 3+ planned steps → start a breadcrumb FIRST.

If your operation has 3 or more steps:
  1. breadcrumb_start  — before you do anything
  2. breadcrumb_step   — after EACH step, with the result
  3. breadcrumb_complete OR breadcrumb_abort — when done or abandoned

Never leave orphan breadcrumbs. If you started one, you must complete or abort it. An orphan breadcrumb signals a crash to the next session.

The Six Core Tools

Plus the cleanup tool:

breadcrumb_status vs breadcrumb_backup

These serve different purposes:

• breadcrumb_status — "Where am I?" Read-only check. Use mid-operation to verify progress, or after a restart to find the resume point. Cheap, no side effects.
• breadcrumb_backup — "Save my place before I do something dangerous." Creates a named snapshot. Use before irreversible steps like deleting files, pushing to production, or overwriting configs. If the next step fails, the backup tells the recovery session exactly what state to restore.

When to use which:

Routine step (install a package, copy a file)  → just breadcrumb_step
Irreversible step (delete old deploy, push)    → breadcrumb_backup, THEN do it, THEN breadcrumb_step
Context lost / restart                         → breadcrumb_status to find resume point

Auto-Start Triggers

As a safety net, local auto-creates breadcrumbs when certain tools are called without an active breadcrumb:

• powershell — shell commands often start multi-step work
• chain — chained operations are inherently multi-step
• psession_run — persistent session commands imply ongoing work

Auto-created breadcrumbs are marked auto_started: true in their metadata.

Important: Auto-triggers are a safety net, not a substitute for discipline. If a breadcrumb is already active, the auto-trigger is suppressed — you're already tracking. But if you know you're about to do a 5-step operation, start your own breadcrumb with a proper title and step plan. The auto-trigger gives you a generic title; your manual breadcrumb gives you a meaningful one.

Auto-Cleanup

Completed breadcrumbs older than 30 days are automatically pruned on local startup. Configure retention with the LOCAL_BREADCRUMB_RETENTION_DAYS environment variable:

{
  "mcpServers": {
    "local": {
      "env": {
        "LOCAL_BREADCRUMB_RETENTION_DAYS": "60"
      }
    }
  }
}

Worked Example: Deploy a Server Binary

Here's a realistic multi-step operation tracked from start to finish.

Scenario: Build and deploy myserver.exe to your servers directory.

Step 1: breadcrumb_start
  title: "Deploy myserver.exe v2.3 | targets: myserver.exe"
  steps: ["archive current binary", "build release", "copy binary", "verify size", "smoke test"]

Step 2: breadcrumb_backup
  label: "pre-deploy backup"
  note: "Current myserver.exe is 12,308 KB, built 2026-04-10 01:06"
  → Recovery point saved. If deploy fails, restore from archive.

Step 3: archive_create
  source: "C:\CPC\servers\myserver.exe"
  dest: "C:\CPC\servers\archive\myserver_20260411.zip"

Step 4: breadcrumb_step
  step: "archive current binary"
  result: "archived to myserver_20260411.zip (12,308 KB)"
  status: "success"

Step 5: run (cargo build --release)
  → Build succeeds, new binary at target\release\myserver.exe (12,450 KB)

Step 6: breadcrumb_step
  step: "build release"
  result: "cargo build --release succeeded, 12,450 KB"
  status: "success"

Step 7: (copy binary to servers/)

Step 8: breadcrumb_step
  step: "copy binary"
  result: "copied to C:\CPC\servers\myserver.exe"
  status: "success"

Step 9: (verify file size)

Step 10: breadcrumb_step
  step: "verify size"
  result: "12,450 KB confirmed at destination"
  status: "success"

Step 11: (run smoke test)

Step 12: breadcrumb_step
  step: "smoke test"
  result: "health endpoint returned OK in 1.2s"
  status: "success"

Step 13: breadcrumb_complete
  summary: "myserver.exe v2.3 deployed. 12,308→12,450 KB. All 5 steps passed."

If Claude's context had reset between step 8 and step 9:

breadcrumb_status →
  title: "Deploy myserver.exe v2.3"
  completed: ["archive current binary", "build release", "copy binary"]
  next: "verify size"
  backup: "pre-deploy backup" (pre-deploy state saved)

The new session picks up at "verify size" with full context of what happened.

Core Concepts

Smart Read

smart_read is the file reading tool that won't blow your context window.

Patterns:

# Find a function definition in a large file
smart_read(path="src/main.rs", grep="fn handle_request")

# Read just the first 100 lines of a config
smart_read(path="config.toml", lines="1-100")

# Read a huge log without blowing context
smart_read(path="app.log", grep="ERROR", max_kb=50)

Always prefer smart_read over read_file for files you haven't seen before. If the file is over 100KB and you read it raw, you just burned half your context.

Persistent Sessions

One-shot commands (run, powershell) spin up a shell, run, and tear down. Persistent sessions keep state:

session_create(name="deploy", shell="powershell")
session_run(name="deploy", command="cd C:\CPC\servers")
session_run(name="deploy", command="$env:RUST_LOG='debug'")
session_run(name="deploy", command=".\myserver.exe --health")
# CWD and env vars persist across all three commands
session_destroy(name="deploy")

When to use persistent sessions:

• You need CWD to persist (navigating directories)
• You need environment variables to persist
• You're running a sequence of related commands
• You need to check session_history later

When one-shot is fine:

• Single independent command
• Command that doesn't depend on prior state
• Quick check (file exists, process running)

Important: Always session_destroy when done. Sessions hold resources. If you forget, they'll accumulate until local restarts.

Archive-First Discipline

Before replacing or deleting any file that matters:

archive_create(source="path/to/file", dest="path/to/archive/file_YYYYMMDD.zip")

This is not optional for deployments. If a new binary is broken and you already overwrote the old one without archiving, your only recovery is rebuilding from source — which might not even be at the same commit.

Common Patterns

Build and Deploy

1. breadcrumb_start (title includes binary name + target path)
2. breadcrumb_backup (snapshot current state)
3. archive_create (archive current binary)
4. run/powershell (build)                    → breadcrumb_step
5. copy new binary                           → breadcrumb_step
6. verify (size, health check)               → breadcrumb_step
7. breadcrumb_complete

Bulk File Transform

1. breadcrumb_start (title: "bulk rename *.log → *.log.bak in /logs")
2. transform_bulk_rename (pattern, replacement, dry_run=true) → breadcrumb_step (preview)
3. Review preview
4. transform_bulk_rename (dry_run=false) → breadcrumb_step (executed)
5. breadcrumb_complete

Investigate and Fix

1. smart_read (grep for error pattern)
2. If fix is 1-2 steps: just do it, no breadcrumb needed
3. If fix is 3+ steps: breadcrumb_start, then tracked steps

Data Pipeline

1. http_fetch or http_download (get data)
2. transform_csv_to_json or transform_json_format (reshape)
3. write_file (output)
# If all three are needed → breadcrumb it

Tool Reference

Shell

Files

Sessions

Transforms

Breadcrumbs

Archive

HTTP

Registry

System

Infrastructure

The Activity Log

Local writes an activity log to C:\CPC\logs\local_activity.jsonl. Every tool call is recorded with timestamp, tool name, parameters, result status, and duration.

View it via:

• dashboard.html — ships with local, renders the log as a timeline
• smart_read — smart_read(path="C:\\CPC\\logs\\local_activity.jsonl", grep="ERROR", max_kb=20)
• tail_file — tail_file(path="C:\\CPC\\logs\\local_activity.jsonl", lines=50)

The log is append-only. It grows over time. Use smart_read with grep to search it rather than reading the whole thing.

Anti-Patterns

Troubleshooting

"breadcrumb_status shows an operation I didn't start"

That's an auto-started breadcrumb from a previous powershell, chain, or psession_run call. Check its steps to understand the context. If it's stale, breadcrumb_abort it with a reason like "stale auto-started breadcrumb from prior session" and start fresh.

"Session command returns empty output"

The command may have written to stderr only. Check session_read_output which captures both streams. Also verify the session still exists with session_list — sessions can be destroyed by local restarts.

"PowerShell command fails but works in a terminal"

Common causes:

• Execution policy — local's PowerShell may have a restricted policy. Try powershell(command="Set-ExecutionPolicy -Scope Process Bypass; your-command").
• Cargo/Rust output — PowerShell doesn't handle cargo's stderr well. Use run(command="cmd /c cargo build --release 2>&1") instead.
• Path encoding — PowerShell uses backtick escaping. If your path has spaces, wrap in double quotes inside the command string.

"smart_read returns truncated output"

That's working as intended — max_kb caps the response. If you need more, increase max_kb or use lines to target the specific range. Don't remove the cap entirely on files you haven't measured.

"breadcrumb_clear deleted things I wanted to keep"

Always run with dry_run=true first. The default older_than_days=30 only touches completed breadcrumbs. Active and aborted breadcrumbs are never auto-cleared — only force=true removes those.

"archive_create fails on locked files"

Windows locks open files. If archiving a running server binary, stop it first, archive, then restart. For log files that are being written to, use copy_file to a temp location first, then archive the copy.

"Local server won't start / transport errors"

1. Check if the port is in use: port_check
2. Check if another local instance is running: list_process grep for local
3. Verify the binary exists and is the right version
4. Check server_health — if it responds, the server is up but the MCP transport layer may need reconnection in your client

"Persistent session lost state after local restart"

Sessions are in-memory. A local restart destroys all sessions. Use session_checkpoint before risky operations to save state, and session_recover after restart. For critical state, write it to a file instead of relying on session persistence.