# localmcp

A local MCP server for AI coding workflows. It gives ChatGPT a constrained view of one project directory plus the tools needed to inspect, edit, test, commit, and push code.

## What it can do

localmcp exposes 11 tools:

- `workspace_info` — server, workspace, mode, and tool diagnostics
- `list_files` — list a directory
- `tree` — recursively inspect the workspace with depth and entry limits
- `search_files` — substring or regex search with globs and context lines
- `read_file` — read a whole file or a numbered line range
- `write_file` — create or replace a file
- `edit_file` — guarded exact-text replacement
- `apply_patch` — atomically apply multiple guarded edits to one file
- `delete_file` — delete a file
- `move_file` — move or rename a file
- `run_command` — execute a program directly without a shell

Together these are enough for a coding-agent loop such as:

```text
inspect → search → read → edit → test → diff → commit → push
```

Workspace traversal respects the root `.gitignore` by default, and `.git` is always excluded.

## Security model

All localmcp file tools are confined to `LOCALMCP_ROOT`. Absolute paths, `..` traversal, and symbolic-link escapes are rejected.

Command execution has two modes.

### Strict mode

`strict` is the default. `run_command` only accepts executables listed in `LOCALMCP_ALLOWED_COMMANDS`.

```bash
LOCALMCP_ROOT="$HOME/src/my-project" \
LOCALMCP_MODE=strict \
LOCALMCP_ALLOWED_COMMANDS="git,node,npm" \
npm start
```

With an empty allowlist, command execution is effectively disabled.

### YOLO mode

For a trusted coding workspace, `yolo` removes the executable allowlist:

```bash
LOCALMCP_ROOT="$HOME/src/my-project" \
LOCALMCP_MODE=yolo \
npm start
```

localmcp still requires the command `cwd` to resolve inside `LOCALMCP_ROOT`.

**YOLO mode is not an OS sandbox.** An executed program can still read or modify files outside the workspace, access the network, spawn other processes, or execute code with the permissions of the localmcp process. Use an OS/container sandbox if you need process-level isolation.

Commands use Node.js `spawn(..., { shell: false })`, so localmcp does not wrap command input in a shell.

## Requirements

- Node.js 18+
- Any command-line tools you want to execute must be installed and available on `PATH`

## Install

```bash
npm install
```

## Run

macOS/Linux:

```bash
LOCALMCP_ROOT="$HOME/src/my-project" npm start
```

PowerShell:

```powershell
$env:LOCALMCP_ROOT = "C:\src\my-project"
npm start
```

The default mode is `strict`.

Open `http://127.0.0.1:8787/` for the read-only status dashboard. It shows the current execution mode, workspace, MCP endpoint, command access, and runtime limits.

The MCP endpoint is:

```text
http://127.0.0.1:8787/mcp
```

## Server-side tool logs

Every MCP tool call is logged to stderr with its tool name, status, duration, and summarized input:

```text
[localmcp] 2026-10-01T05:50:55.635Z tool=tree status=ok duration_ms=7.5 input={"path":".","max_depth":1,"max_entries":20,"respect_gitignore":true}
```

Large edit/file contents are summarized instead of being printed verbatim. These logs make it possible to follow the sequence of actions an AI client performs against the workspace.

## Configuration

- `PORT` — HTTP port (default `8787`)
- `LOCALMCP_ROOT` — exposed workspace root (default: current directory)
- `LOCALMCP_MODE` — execution mode: `strict` (default) or `yolo`
- `LOCALMCP_ALLOWED_COMMANDS` — comma-separated executable allowlist used by strict mode (default: empty)
- `LOCALMCP_TIMEOUT_MS` — command timeout (default `120000`)
- `LOCALMCP_MAX_OUTPUT` — maximum chars captured per stdout/stderr stream (default `200000`)
- `LOCALMCP_MAX_FILE` — maximum file size in bytes (default `1000000`)

## Test

```bash
npm test
```

The test suite covers workspace path confinement, symlink escape rejection, command allowlisting, dashboard rendering, gitignore-aware traversal, search, line slicing, guarded edits, and multi-edit patching.

## Test with MCP Inspector

```bash
npx @modelcontextprotocol/inspector@latest
```

Choose **Streamable HTTP** and connect to `http://127.0.0.1:8787/mcp`.

## Connect to ChatGPT

ChatGPT needs a reachable HTTPS `/mcp` URL. For development, expose port 8787 with a tunnel and use the resulting HTTPS URL ending in `/mcp`.

A public tunnel creates an entry point to your machine. Keep `LOCALMCP_ROOT` narrow and use `strict` mode unless you intentionally want unrestricted executable selection.