LocalForge MCP

Local execution and repository runtime for MCP coding agents on Windows.

LocalForge MCP gives an MCP client structured access to a real workspace, files, code search, Git, foreground commands, and long-running development processes. It runs on the host machine under the current Windows user account. It does not create a fake filesystem or hide projects inside a virtual sandbox.

Beta software with powerful host access. Read Security model before use.

Disclaimer: This is a small, quick project that was partially vibe-coded. While I used AI agents to assist with development, I personally reviewed, tested, and validated the code rather than relying on generated output without verification. This project is primarily for personal use, especially to make Amazon Quick more useful in my company and bring it closer to the experience of a real coding agent.

Features

• Workspace root, current directory, and Git-root discovery.

• Real filesystem list, stat, bounded read, atomic write, guarded text replacement, move, mkdir, and delete operations.

• Ripgrep-backed code and filename search with Python fallback.

• Batched multi_search: up to 16 parallel searches in one round-trip.

• Batched batch: run any mix of tool calls in parallel in one round-trip.

• multi_edit: several exact replacements per file in one call, validated end-to-end and written atomically.

• Tolerant argument aliases (old→old_text, replacement→new_text, text→content, file→path, pattern→query, cmd→command, and more), so mis-remembered parameter names do not cost a failed round-trip.

• Persistent todo tool: TodoWrite-style task list backed by the state file; survives restarts.

• MCP 2025-06-18 protocol with structuredContent tool results and the logging capability.

• Long-session guards: Git-root caching, whole-file-edit size limits, and a fixed-size striped path-lock table.

• Structured Git operations plus generic Git argument arrays.

• Foreground execution with separate stdout/stderr, timeout, truncation, duration, and exit metadata.

• Long-running process IDs, incremental split-stream logs, stdin, status, restart, stop, and process-tree cleanup.

• Canonical path checks with separate read/write roots and denied paths.

• Explicit environment inheritance, secret-name filtering, and basic output redaction.

• Concurrent tool execution: pipelined tool calls run in parallel instead of queueing behind the slowest call; edits to the same file serialize while distinct files edit in parallel.

• Nine stable MCP tools rather than many command wrappers.

• No runtime approval tool; approval remains the responsibility of the MCP host such as Amazon Quick.

Related MCP server: GPT Plus Plus

Requirements

• Windows 10 or Windows 11.

• Python 3.11 or newer.

• Git for Git tools.

• Ripgrep is optional but recommended for fast search.

• Developer tools required by your projects, such as Node.js, .NET SDK, Python, Java, or Docker.

Repository layout

localforge-mcp/
├── agent_runtime/
│   ├── capabilities.py
│   ├── config.py
│   ├── errors.py
│   ├── patch.py
│   ├── processes.py
│   ├── security.py
│   ├── server.py
│   ├── state.py
│   └── todos.py
├── tests/
├── localforge.example.json
├── QUICK.md
├── pyproject.toml
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
└── LICENSE

Install on Windows

cd D:\Repositories\localforge-mcp

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e .

Copy-Item localforge.example.json localforge.json
notepad localforge.json

Set workspace_root, allowed_read_roots, and allowed_write_roots before starting.

For one repository:

{
  "workspace_root": "D:\\Repositories\\MyApp",
  "allowed_read_roots": ["D:\\Repositories\\MyApp"],
  "allowed_write_roots": ["D:\\Repositories\\MyApp"]
}

For multiple repositories under one parent:

{
  "workspace_root": "D:\\Repositories",
  "allowed_read_roots": ["D:\\Repositories"],
  "allowed_write_roots": ["D:\\Repositories"]
}

Keep the other properties from localforge.example.json.

Amazon Quick setup

Create a Local MCP connection with these values.

ID

localforge-mcp

Name

LocalForge MCP

Command

D:\Repositories\localforge-mcp\.venv\Scripts\python.exe

Arguments

-m agent_runtime.server

Description

Local Windows coding runtime with workspace files, code search, Git, command execution, and long-running development processes.

Add environment variable:

LOCALFORGE_CONFIG=D:\Repositories\localforge-mcp\localforge.json

Set startup timeout to 60 seconds, save, then toggle the MCP connection off and on after configuration changes.

Agent prompt: paste the rules in QUICK.md into the connection's agent/system prompt. They steer the model to batch-first dispatch, filesystem-first edits, and process for long waits — the behaviors that make Quick feel like a CLI coding agent.

The older environment variable WIN_AGENT_RUNTIME_CONFIG remains accepted for compatibility.

Manual smoke test

Start server:

$env:LOCALFORGE_CONFIG = "D:\Repositories\localforge-mcp\localforge.json"
.\.venv\Scripts\python.exe -m agent_runtime.server

A blank terminal means the server is waiting for newline-delimited JSON-RPC input. Press Ctrl+C to stop it.

MCP tools

workspace

• get: return workspace root, current directory, and detected Git root.

• set_cwd: change current directory inside read policy.

filesystem

• list, stat, read

• write, replace_text, apply_patch, mkdir, move, delete, copy

read supports byte offset and bounded output. replace_text defaults to exactly one expected occurrence, preventing accidental broad replacements. multi_edit applies several exact replacements to one file in order — the whole set is validated before anything is written, so a failing edit leaves the file untouched; prefer it for multi-part changes to a single file. apply_patch takes a unified diff for multi-hunk or multi-file edits: exact context, validated end-to-end before anything is written, all-or-nothing. Prefer it over writing plus executing a script to edit code. copy duplicates a file (or a directory with recursive) under policy checks — prefer it over shell copy commands, which mis-handle bracketed filenames like [KB1] - doc.pdf without -LiteralPath.

Argument names are tolerant: the server accepts common model guesses as aliases — old/find for old_text, new/replacement for new_text, text for content, file/target for path, start/end for line_start/line_end, dest for destination, pattern for query (search), cmd for command (execute/process), id for process_id, and dir for path (workspace). A canonical name always wins when both are sent.

search

Search text or filenames recursively with include/exclude globs, case control, fixed-string or regex matching, and result limits.

multi_search

Run up to 16 independent searches in one call. Each entry takes the same arguments as search (plus an optional label echoed back with its results), and all entries execute in parallel. Use it to fan out several queries in a single round-trip instead of one search per call — especially useful with clients that issue one tool call per turn. A failing entry is reported per-entry (error) without failing the whole batch.

{"searches": [
  {"query": "UserService", "glob": ["*.py"], "label": "users"},
  {"query": "TODO", "files_only": true, "label": "todos"}
]}

Responses are matched to requests by id, so when a client sends several tool calls in one turn they run concurrently and may complete in any order. Tune the worker count with max_concurrency (default 8).

batch

Run up to 16 tool calls of any type in one call, in parallel — the closest match to how a CLI agent dispatches several tools in a single turn. Each entry names a tool and its arguments exactly as a tools/call request, with an optional label echoed back. Distinct paths run concurrently; edits to the same file serialize on that path (a second edit sees a stale base and fails with content_mismatch rather than overwriting). A failing call is reported per-call (error) without failing the batch. Nested batch calls are rejected.

{"calls": [
  {"tool": "filesystem", "arguments": {"action": "read", "path": "src/app.py"}, "label": "app"},
  {"tool": "search", "arguments": {"query": "UserService", "glob": ["*.py"]}, "label": "users"},
  {"tool": "git", "arguments": {"action": "status"}, "label": "git"}
]}

Prefer filesystem write, replace_text, multi_edit, and apply_patch for file edits over shelling out to python or shell commands: they are atomic, policy-checked, and give structured errors. execute and process are for running programs, builds, and tests — those legitimately write files as the current user.

todo

Persistent task list (TodoWrite-style) with get, add, update, delete, and clear.

{"action":"add","title":"Fix login bug"}
{"action":"update","id":1,"status":"in_progress"}
{"action":"get"}

Keep it current across turns: add before starting work, mark in_progress while working and completed when done, delete stale entries. State is stored next to the config (.localforge-state.json) and survives server restarts; without a state file it is in-memory only.

git

Presets: status, diff, log, show, branch, and root. Broad git add -A / --all / . is blocked (stage explicit files instead), as is staging private keys (*.pfx, *.p12, *.pem, *.key).

Use run with an argument array for other operations:

{"action":"run","args":["add","src/app.py"]}

GitHub via gh CLI

There is no GitHub API tool; use gh through execute (one-time gh auth login on the box — tokens cannot ride env overrides by design, and stored credentials work since processes run as your user):

{"command":["gh","pr","create","--title","x","--body","y"]}
{"command":["gh","issue","list","--limit","20"]}

Prefer gh ... --json <fields> for machine-readable output. Note gh counts as network activity when network is disabled.

execute

Prefer argument arrays:

{"command":["npm","test"],"cwd":".","timeout":600}

String commands automatically use the configured shell:

{"command":"npm test | Select-String failed"}

Pass shell explicitly only to force array commands through the shell. Argument arrays bypass shell parsing and stay preferred.

For SSH, prefer key auth with fail-fast flags so prompts never hang the call:

{"command":["ssh","-i","C:\\Keys\\deploy.pem","-o","BatchMode=yes","-o","StrictHostKeyChecking=accept-new","-o","ConnectTimeout=15","ubuntu@host","docker ps"]}

Two Windows gotchas: keys under Downloads usually have permissive ACLs, which ssh rejects (Permissions ... are too open) — fix with icacls key.pem /inheritance:r /grant:r "$env:USERNAME:F". And ssh requires %ProgramData% in the environment (inherited by default since 1.4.0); without it ssh dies instantly with exit 255 and no output.

Complex quoting (multi-line PowerShell with $vars, nested python -c, bracketed paths) breaks when passed as a command string. Write the script with filesystem write to a temp file, then run it by path (powershell -ExecutionPolicy Bypass -File script.ps1, python script.py). Prefer filesystem copy over shell copy commands.

process

Actions: start, read, write, status, list, restart, and stop.

Use after with the previous next_after value for incremental log reads. cursor_lost=true means older output was evicted from the bounded buffer.

Quick examples

{"action":"get"}
{"action":"read","path":"src/app.py","line_start":1,"line_end":80}
{"query":"UserService","glob":["*.py"],"context_lines":2}
{"action":"status"}
{"command":["npm","test"],"cwd":".","timeout":600}
{"action":"start","command":["npm","run","dev"]}

Configuration

Modes

• READ_ONLY: filesystem inspection only.

• WORKSPACE: workspace filesystem changes, but no process execution.

• DEVELOPMENT: workspace access and process execution.

• FULL_ACCESS: dedicated filesystem tools may access paths outside configured roots, while denied paths still apply.

Network

• unrestricted: runtime does not block recognized network commands.

• disabled: blocks recognized package, Git, and URL-oriented commands.

This is command classification, not packet filtering. Use Windows Firewall, a controlled proxy, AppContainer, container, or VM for enforceable network restrictions.

Shells

Supported default_shell values:

• powershell

• pwsh

• cmd

• sh

execute.timeout is seconds. process.wait_ms is milliseconds (max 60000). limit_bytes, max_bytes, and max_file_read_bytes are bytes. filesystem offset is a byte offset in legacy read mode; use line_start/line_end for line mode. max_concurrency bounds how many tool calls run in parallel (default 8). log_to_client (default false) emits an MCP logging notification per tool call (tool, duration, outcome) visible in the client; LOCALFORGE_LOG=1 writes the same line to stderr. replace_text and multi_edit refuse files larger than max_file_read_bytes with file_too_large. kill_children_on_exit (default true) puts every spawned child into a Windows Job Object that the kernel terminates when the server exits, however it exits; set it to false to let children outlive the server.

Security model

LocalForge MCP provides application-level mediation, not an OS security boundary.

Dedicated filesystem tools canonicalize paths and resolve existing links before checking roots. However, once command execution is allowed, the child process has the current Windows user's rights. Build scripts, package lifecycle hooks, Git hooks, interpreters, native binaries, and child processes can access anything that user can access.

For untrusted agents or repositories, run LocalForge MCP under a dedicated low-privilege Windows account and add OS-level isolation. See SECURITY.md for remaining reparse-point race and network limitations.

Development

.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m compileall -q agent_runtime

Status and limitations

• Windows-native process-tree behavior requires Windows testing; cross-platform tests cover portable logic.

• Process state is in-memory and does not survive runtime restart.

• Children die with the server however it exits on Windows (Job Object); on POSIX they die only on explicit stop/restart or clean exit.

• Shell command network detection is intentionally conservative and cannot inspect arbitrary scripts.

• File writes are atomic at replacement time but cannot preserve every filesystem-specific metadata attribute.

• MCP transport is stdio only.

License

MIT. See LICENSE.