# git-remote-mcp

Node MCP server that exposes local git commands and uses an HTTP API only for custom push workflows.

## Install

```sh
npm install
```

## Run

```sh
npm start
```

HTTP API requests for `git_push` and `git_push_new_branch`:

```sh
remote_url="https://example.com/git/execute" git_jwt_auth="JWT_TOKEN" npm start
```

Read the remote URL from a local file instead of `remote_url`:

```sh
use_remote_url_file=true remote_url_file="/path/to/remote-url.txt" npm start
```

The file should contain the URL as plain text. `remote_url` is only required when using HTTP-backed push tools.

MCP client command:

```json
{
  "command": "node",
  "args": ["/absolute/path/to/git-remote-mcp/src/index.js"],
  "env": {
    "remote_url": "https://example.com/git/execute"
  }
}
```

Supported environment variables:

- `remote_url` or `REMOTE_URL`: HTTP API endpoint for push workflows.
- `use_remote_url_file` or `USE_REMOTE_URL_FILE`: set to `true`, `1`, `yes`, or `on` to read the URL from a file.
- `remote_url_file` or `REMOTE_URL_FILE`: local file containing the HTTP API endpoint.
- `git_jwt_auth` or `GIT_JWT_AUTH`: JWT token sent as `Authorization: Bearer <token>`.
- `REQUEST_TIMEOUT_MS`: request timeout, default `30000`.

## Tools

- `git`: generic allowed git command runner. `git push` is handled as the custom diff upload flow below.
- Read/inspect: `git_status`, `git_log`, `git_diff`, `git_show`, `git_branch`, `git_blame`, `git_grep`, `git_ls_files`.
- Working tree/index: `git_add`, `git_restore`, `git_reset`, `git_rm`, `git_mv`, `git_clean`.
- History: `git_commit`, `git_merge`, `git_rebase`, `git_cherry_pick`, `git_revert`.
- Refs/config: `git_checkout`, `git_switch`, `git_tag`, `git_stash`, `git_config`.
- Upload: `git_push`, `git_push_new_branch`.

Remote/network git actions are disabled before the HTTP request is sent. Blocked commands include:

- `git clone`
- `git fetch`
- `git pull`
- `git remote`
- `git request-pull`
- `git send-pack`
- `git receive-pack`
- `git upload-pack`
- `git upload-archive`
- `git ls-remote`
- `git submodule`

Remote-related options such as `--upload-pack`, `--receive-pack`, `--exec`, `--remote`, and `--recurse-submodules` are also blocked in the generic `git` tool.

## Push upload flow

`git_push` and generic `git` with `command: "push"` do not run `git push`.

Instead, the MCP server:

1. Runs local `git diff <base> --binary`.
2. Writes the returned diff to a local temporary `.patch` file.
3. Calls `remote_url` again with a JSON payload containing the patch path.

The upload request looks like:

```json
{
  "action": "push",
  "command": "push",
  "diffPath": "/tmp/git-remote-mcp-xYz/123.patch",
  "cwd": "/repo/path",
  "base": "HEAD",
  "args": [],
  "message": "optional message"
}
```

The API should read `diffPath` and handle the upload/apply operation. Any `args` are forwarded as metadata only; they are not executed as `git push` by this MCP server.

## New branch push flow

`git_push_new_branch` asks the API to publish a branch to a remote. If `createLocal` is true, the MCP server first runs local `git switch -c <branch> [startPoint]`, then sends:

```json
{
  "action": "push_new_branch",
  "command": "push",
  "cwd": "/repo/path",
  "branch": "feature/example",
  "remote": "origin",
  "startPoint": "main",
  "setUpstream": true,
  "args": ["origin", "feature/example"]
}
```

The API should perform the actual remote branch publish, for example equivalent to `git push -u origin feature/example` when `setUpstream` is true.

## Local git contract

All non-push tools run local git with:

```sh
git <command> ...args
```

The optional `cwd` parameter controls the local repository path.

## HTTP contract

The server sends `POST` requests to `remote_url` only for push workflows. Diff upload requests look like:

```json
{
  "action": "push",
  "command": "push",
  "diffPath": "/tmp/git-remote-mcp-xYz/123.patch",
  "cwd": "/repo/path",
  "base": "HEAD",
  "args": [],
  "message": "optional message"
}
```

and return JSON:

```json
{
  "stdout": "main\n",
  "stderr": "",
  "exitCode": 0
}
```

Any non-2xx HTTP response is treated as an MCP tool error. A JSON response with `ok: false` or non-zero `exitCode` is returned to the MCP client as an error result.

`REQUEST_TIMEOUT_MS` can be set to change the default 30 second remote call timeout.