# Green Shield MCP — Opnli Green Shield Files

**A reference MCP tool that asks a human before every action.**

Green Shield Files gives an AI host (such as Claude Desktop) three file tools: list, read and move. Before any of them runs, a **Green Shield card** appears on [opn.li](https://opn.li) for the human who owns the tool. They choose Allow or No. The decision is written to their tamper-evident chain on the **Openly Trusted Network (OTN)** first. The tool acts only when it holds that record. No answer within the time limit means No.

It is part of the [Open Consent Project](https://github.com/mikeoz/open-consent) and follows the Human Consent Layer (HCL) standard.

> **Status (October 2026):** proven in Claude Desktop (1 October 2026) and, in private testing through OpenAI's Secure MCP Tunnel, in ChatGPT (22 October 2026). Tested on macOS only.

---

## Ten-minute quickstart (macOS)

**You need:** macOS, [Node.js](https://nodejs.org) (tested with version 24), Claude Desktop, and an opn.li membership. Opnli membership is free. If you do not have one yet, the opn.li page that opens in step 3 lets you create it, and the tool then finishes linking on its own.

### 1. Get the code (1 minute)

```bash
git clone https://github.com/mikeoz/green-shield-mcp.git
cd green-shield-mcp
npm install
```

### 2. Make the Green Shield folder (1 minute)

The tool can reach **only** one folder. By default that is `GreenShieldTest` in your home folder. A path outside it is refused at once, with no card.

```bash
mkdir -p ~/GreenShieldTest
echo "hello from the Green Shield" > ~/GreenShieldTest/hello.txt
```

To use another folder, set `GS_FILES_ROOT` in step 4.

### 3. Link the tool to your membership (2 minutes)

```bash
node link.js
```

Your browser opens opn.li. Sign in, or create your free account. Terminal then shows `LINKED: Green Shield Files`.

What just happened: opn.li handed your sign-in to this computer only. `link.js` used it once to register the tool on the network, with you as its owner, and saved **only the tool's own badge** to `~/.green-shield-files/badge.json` (readable only by you). Your sign-in is never stored. The badge is how the network knows which tool is asking, and that the cards go to you.

### 4. Add the tool to Claude Desktop (3 minutes)

Open Claude Desktop → Settings → Developer → Edit Config, and add (with your own path to `server.js`):

```json
{
  "mcpServers": {
    "opnli-green-shield-files": {
      "command": "node",
      "args": ["/full/path/to/green-shield-mcp/server.js"]
    }
  }
}
```

Optional settings, under `"env"`: `GS_FILES_ROOT` (the folder) and `GS_CONSENT_URL` (the network address; default `https://consent.opn.li`).

Restart Claude Desktop.

### 5. See the Green Shield (3 minutes)

1. Open **opn.li/consent** in your browser and stay signed in.
2. In Claude Desktop, ask: *"List the files in my Green Shield folder."*
3. A card appears on opn.li naming the tool and the action, with a four-letter **match code**. The same code appears in the tool's answer, so you know the card and the request belong together.
4. Choose **Allow once**. Claude shows the file list.
5. Ask again and choose **No**. Nothing is read, and Claude is told it was refused.

---

## How it works

| Step | What happens |
|---|---|
| 1 | Claude calls a tool, for example `list_files`. |
| 2 | The tool sends the request to the network with its badge. The network, not the request, decides who is asking. |
| 3 | A card appears on opn.li for the tool's owner. Standing rules the owner created may answer instead. |
| 4 | The decision is written to the owner's chain **before** anything happens. If the record cannot be written, the answer is No. |
| 5 | On Allow, the tool acts and returns the result with the match code and the chain receipt. |

The tool waits up to 95 seconds for a decision. The card itself expires sooner, and an expired card is a No.

## Make your own Green Shield tool

`server.js` is a small, readable example. To protect your own tool:

- Change the tool name in `link.js` (`entity_name`) and the server name in `server.js`.
- Keep the pattern: **ask the network first, act only with a receipt, treat every error as No.**

A step-by-step guide for adding the Green Shield to an existing MCP server is in preparation.

## Known limits

- `link.js` opens the browser with the macOS `open` command; Windows and Linux are not yet supported.
- Waiting cards are held in memory on the network; a network restart turns a waiting card into a No.

---

## License

Apache 2.0 — see [LICENSE](LICENSE). Copyright 2026 Opnli Corporation.
The Opnli Green Shield logo in `assets/` is a mark of Opnli Corporation; the license covers the code, not the brand.

*Only a human can give consent. Consent requires context. CARDs provide context. The Human Consent Layer enforces the decision.*