# Authority Webhook MCP

A small, public-ready Node.js MCP server with one consequential boundary: publishing a normalized release notice to a configured webhook.

The server deliberately separates four concerns:

1. MCP input validation.
2. Exact action and target normalization.
3. The host-owned `ReleaseProvider` boundary.
4. Provider result evidence.

With no configuration it uses a deterministic dry-run provider. Set `RELEASE_WEBHOOK_URL` to use the HTTP provider; HTTPS is required except for localhost test endpoints. No production credential is needed to run or test the project.

## Why this repository exists

Agent tools often place review or approval logic too early, before the final target and payload are known. Here the exact seam is explicit in `ReleasePublisher.publish()`:

```text
MCP request
  -> validate
  -> normalize action class + webhook target + exact input
  -> ReleaseProvider.send(action)   <-- consequential provider call
  -> correlate provider result
```

That seam makes the project suitable for evaluating a single-use authority gate without using a live external service.

## Requirements

- Node.js 20 or newer
- npm

## Run the checks

```bash
npm install
npm run ci
```

## Run as an MCP server

Dry-run mode:

```bash
npm run build
npm start
```

Local webhook sandbox:

```bash
RELEASE_WEBHOOK_URL=http://127.0.0.1:8787/releases npm start
```

The exposed tool is `publish_release_notice`:

```json
{
  "repository": "example/agent-tools",
  "tag": "v1.2.0",
  "summary": "Add a sandboxed release-notification tool."
}
```

## Run a deterministic evidence demo

The demo exercises the real normalization and provider boundary with the
in-memory dry-run provider. It performs no network request and prints the exact
action, its SHA-256 fingerprint, and the correlated provider result:

```bash
npm run demo
```

The dry-run provider request ID is derived from the action fingerprint, making
the output reproducible and easy to compare without exposing credentials.

## Current safety properties

- Repository identifiers are normalized to `owner/name`.
- Release tags and summaries have bounded formats.
- Webhook URLs reject embedded credentials and non-HTTPS remote targets.
- The action fingerprint covers the action class, exact target, and exact normalized input.
- Invalid input fails before the provider runs.
- Tests use an injected recording provider and make no external calls.

This baseline does not yet implement human approval, single-use consumption, tamper rejection, or replay protection. Those controls belong immediately before `ReleaseProvider.send()` and should be added only as a deliberate authority-gate integration, with tests that prove the provider remains untouched on every rejected path.

## License

MIT