MCP Local Agent

A local-first Model Context Protocol (MCP) server for inspecting, modifying, and validating explicitly approved repositories on your computer.

Current status

Version 0.3.0 — Phase 3: Execution Engine. The server supports repository discovery, safe file reads/search, previewable multi-file changes, recovery snapshots, and opt-in execution of allowlisted npm scripts with timeouts and bounded logs over MCP STDIO.

Related MCP server: Gumi-MCP

Requirements

• Node.js 20+

• npm 10+

Setup (Windows PowerShell)

git clone https://github.com/thanhtran2005isme-art/MCP_LOCAL_AGENT.git
cd MCP_LOCAL_AGENT
npm install
npm run typecheck
npm test
npm run build
npm run init:config

If you already cloned an earlier phase, update it first:

git pull origin main
npm install
npm run typecheck
npm test
npm run build

Edit the generated config at %APPDATA%\mcp-local-agent\config.json and add your repository roots. The server uses STDIO; configure your MCP client to run node <absolute-path>\dist\index.js.

Enable execution for a repository

Execution is disabled by default. Explicitly enable only repositories whose code you trust:

{
  "repositories": [
    {
      "id": "my-project",
      "name": "My Project",
      "root": "D:/Projects/MyProject",
      "enabled": true,
      "execution": {
        "enabled": true,
        "allowedScripts": ["test", "build", "lint", "typecheck"],
        "timeoutMs": 120000,
        "maxOutputBytes": 32768,
        "envAllowlist": []
      }
    }
  ]
}

The script names must also exist in the repository's package.json. Only these fixed invocations are supported: npm run <allowlisted-script>. The server does not accept arbitrary commands, arguments, executable paths, npm install, or npm exec.

If a test needs a local environment variable, add its name to envAllowlist; the value is read from the MCP server process environment and is redacted from captured logs when it appears verbatim. Do not add system variables such as PATH, NODE_OPTIONS, or npm configuration variables.

Available MCP tools

Repository and code intelligence

• list_repositories

• get_repo_tree

• get_project_metadata

• read_file — returns file content and SHA-256

• search_code

Code modification

• prepare_changes — prepare up to 20 file operations and return unified diffs

• get_change_diff — retrieve a pending preview

• apply_changes — apply a prepared change set after explicit user approval

• list_snapshots — list recovery snapshots

• restore_snapshot — restore the pre-change state after explicit user approval

Execution engine

• list_execution_tasks — list configured npm scripts without running them

• run_project_check — run one allowlisted npm script after explicit user request

• get_execution_run — retrieve the output of a recent run

• list_execution_runs — list recent runs

Execution controls:

• Per-repository opt-in; disabled by default.

• Exact script-name allowlist (up to 20 scripts).

• Timeout configurable from 1 second to 5 minutes; default 2 minutes.

• Output bounded to 1–64 KiB per stream; default 32 KiB.

• At most one active run per repository and two active runs globally.

• Only a small base environment is inherited; additional variables must be explicitly allowlisted.

• npm pre/post lifecycle scripts are disabled using ignore-scripts.

• Recent run history is held in memory (up to 30 runs) and is cleared when the server restarts.

The execution engine runs with the current operating-system user's permissions. An allowlisted npm script is still executable project code: it can read or modify files and may access the network. This is not an OS sandbox. Enable execution only for repositories you trust.

Recommended workflow

1. Inspect the repository and its package scripts.

2. Configure the repository execution allowlist.

3. Use list_execution_tasks to verify available checks.

4. Use run_project_check only after the user requests execution.

5. Inspect exit status and bounded stdout/stderr.

6. Diagnose failures, prepare a code diff, and request approval before applying changes.

7. Re-run the relevant checks to verify the fix.

Security boundaries

• Only configured repository roots are accessible.

• Absolute paths, traversal, symlinks, sensitive files, generated folders, and unrecognized/binary file types are denied for file operations.

• A change set is limited to 20 files, 512 KiB per file, and 2 MiB of total before/after content.

• Applying changes creates a recovery snapshot and rechecks for concurrent edits.

• Execution is opt-in, allowlisted, time-limited, output-limited, and uses a restricted environment.

• No arbitrary user-supplied shell command or remote network listener is exposed.

See SECURITY.md.

Roadmap

• Phase 1: repository discovery, metadata, safe reads, and code search

• Phase 2: patch-based editing, previews, snapshots, rollback, and conflict detection

• Phase 3: allowlisted test/build/lint execution with timeouts and bounded logs

• Phase 4: secured remote transport and ChatGPT Web compatibility evaluation

• Phase 5: richer code intelligence and multi-step coding workflows

License

MIT