# pushnote

pushnote talks to a Gotify server: it sends push notifications,
reads back messages, server health and version, and manages the
Gotify applications and clients that notifications flow through.
Everything is exposed as one action-router tool, `gotify`, over a
command-line interface and a stdio MCP server, both served by the
same binary.

Three environment variables configure it. `GOTIFY_URL` is the
base URL of your Gotify server and is required — without it, every
action except the local `help` fails before any request is made.
`GOTIFY_CLIENT_TOKEN` is a Gotify client token used for reads and
management (current user, messages, applications, clients).
`GOTIFY_APP_TOKEN` is a Gotify application token used only by the
`send` action. Tokens come from the environment only; they are
never tool arguments.

## Install

```bash
npx @reneturcios/pushnote health
```

Or run the container image:

```bash
docker run -i ghcr.io/cloudcorprecords/pushnote
```

The container defaults to the MCP server (see below). Pass CLI
arguments to use it as a CLI instead.

## CLI

Each command mirrors one router action. Multi-word commands accept
both the hyphenated form shown here and the underscore action name
(for example `create-application` or `create_application`).

```bash
export GOTIFY_URL=https://gotify.example.com
export GOTIFY_CLIENT_TOKEN=<client token>
export GOTIFY_APP_TOKEN=<app token>

pushnote health
pushnote version
pushnote me
pushnote messages --limit 25 --since 40
pushnote messages --app-id 7
pushnote applications
pushnote clients
pushnote status
pushnote send "deploy finished" --title CI --priority 5
pushnote create-application alerts --description "Alert channel" --default-priority 4
pushnote update-application 3 --name renamed
pushnote create-client phone
pushnote delete-message 9 --confirm
pushnote delete-all-messages --confirm
pushnote delete-application 4 --confirm
pushnote delete-client 5 --confirm
pushnote help

pushnote --version
```

Successful commands print the upstream JSON payload (`status` and
`help` print local output instead). Exit codes: `0` on success,
`1` when a call fails (including an upstream API error or a
refused destructive action), `2` for usage errors.

Destructive commands — the four `delete-*` commands — do nothing
unless `--confirm` is passed. Without it they fail before any
request reaches the Gotify server.

## MCP server

The `mcp` subcommand starts a stdio MCP server:

```bash
npx -y @reneturcios/pushnote mcp
```

MCP client configuration:

```json
{
  "mcpServers": {
    "pushnote": {
      "command": "npx",
      "args": ["-y", "@reneturcios/pushnote", "mcp"],
      "env": {
        "GOTIFY_URL": "https://gotify.example.com",
        "GOTIFY_CLIENT_TOKEN": "<client token>",
        "GOTIFY_APP_TOKEN": "<app token>"
      }
    }
  }
}
```

### Tool

One tool, `gotify`, takes a required `action` argument plus the
parameters that action needs as optional top-level arguments:

| Action | Required | Optional | Token |
| --- | --- | --- | --- |
| `health` | — | — | none |
| `version` | — | — | none |
| `me` | — | — | client |
| `messages` | — | `app_id`, `limit`, `since` | client |
| `applications` | — | — | client |
| `clients` | — | — | client |
| `status` | — | — | none (local) |
| `send` | `message` | `title`, `priority`, `extras` | app |
| `create_application` | `name` | `description`, `default_priority` | client |
| `update_application` | `app_id` | `name`, `description`, `default_priority` | client |
| `create_client` | `name` | — | client |
| `delete_message` | `id`, `confirm` | — | client |
| `delete_all_messages` | `confirm` | — | client |
| `delete_application` | `app_id`, `confirm` | — | client |
| `delete_client` | `client_id`, `confirm` | — | client |
| `help` | — | — | none (local) |

All four delete actions refuse to run unless `confirm` is `true`,
and that check happens before any request. `status` returns a
local snapshot (Gotify URL, which tokens are configured, action
count) and never includes a token value. `help` returns the action
documentation locally.

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx
```

## License

MIT — see `LICENSE`.