# 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.

## Requirements

- Node.js 20+
- npm 10+

## Setup (Windows PowerShell)

~~~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:

~~~powershell
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:

~~~json
{
  "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](SECURITY.md).

## Roadmap

- [x] Phase 1: repository discovery, metadata, safe reads, and code search
- [x] Phase 2: patch-based editing, previews, snapshots, rollback, and conflict detection
- [x] 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