@klappay/mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Klappay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+<img src="./docs/public/logo.png" alt="Klap" width="80" />
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @klappay/mcp
+
+A local [Model Context Protocol](https://modelcontextprotocol.io) server for
+the Klap Core API. Your AI assistant (Claude Code, Claude Desktop, Cursor,
+or any MCP client) runs it on your own machine over stdio with `npx`.
+Nothing is hosted by Klappay: the server talks straight to the Klap API with
+the key [`klap login`](https://github.com/klappay/klap-cli) already stored in
+`~/.klap/config.json`.
+
+What the assistant can do with it:
+
+- **Read**: look up a charge and its timeline, list webhooks and their
+  deliveries, list accepted `(token, network)` pairs, run metrics queries.
+- **Test mode**: create charges, re-check them on-chain, retry webhook
+  deliveries and push a sandbox charge through its payment states.
+- **Live mode**: read-only by default. Writes are only registered when
+  you opt in explicitly.
+
+Moving money (escrow release/refund) and managing webhook endpoints or
+payout recipients are never exposed. See [Security](./docs/security.md).
+
+## Install
+
+Requires Node.js 24+. Log in once with the CLI so the key lives in
+`~/.klap/config.json` instead of your MCP client's config file:
+
+```sh
+npx @klappay/cli login --api-key - --base-url https://api.klap.example
+```
+
+Paste the key on stdin and press Ctrl-D. `--api-key -` keeps the key out of
+your shell history; `KLAP_API_KEY=... npx @klappay/cli login --base-url ...`
+works too.
+
+Then add one server per environment. Keeping test and live as separate
+servers means the assistant always knows which one it is talking to, and
+you can turn live off without touching test.
+
+### Claude Code
+
+```sh
+claude mcp add klap-test -- npx -y @klappay/mcp@0.1.0
+claude mcp add klap-live -e KLAP_ENV=live -- npx -y @klappay/mcp@0.1.0
+```
+
+### Claude Desktop (`claude_desktop_config.json`) and Cursor (`~/.cursor/mcp.json`)
+
+Both use the same shape:
+
+```json
+{
+  "mcpServers": {
+    "klap-test": {
+      "command": "npx",
+      "args": ["-y", "@klappay/mcp@0.1.0"]
+    },
+    "klap-live": {
+      "command": "npx",
+      "args": ["-y", "@klappay/mcp@0.1.0"],
+      "env": { "KLAP_ENV": "live" }
+    }
+  }
+}
+```
+
+Pin the exact version as above rather than `@latest`: an MCP server runs
+with your API key, so upgrade it on purpose. On startup it prints one line
+to stderr, e.g. `klap-mcp: test → api.example.com`, and never the key.
+
+## Environment variables
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `KLAP_ENV` | `test` | `test` or `live`, exactly. Anything else refuses to start. |
+| `KLAP_API_KEY` | unset | Use this key instead of `~/.klap/config.json`. Requires `KLAP_BASE_URL`. Its prefix must match `KLAP_ENV`. |
+| `KLAP_BASE_URL` | stored `baseUrl` | Required with `KLAP_API_KEY`. With a stored key it must equal the stored `baseUrl`. |
+| `KLAP_MCP_ALLOW_LIVE_WRITES` | unset | Set to exactly `1` to register `charges_create`, `charges_check` and `webhooks_retry_delivery` in live. |
+
+An empty value counts as unset. Full rules: [Configuration](./docs/configuration.md).
+
+## Tools
+
+| Tool | Test | Live | Live + writes |
+|---|---|---|---|
+| `klap_status` | yes | yes | yes |
+| `charges_get` | yes | yes | yes |
+| `charges_timeline` | yes | yes | yes |
+| `webhooks_list` | yes | yes | yes |
+| `webhooks_list_deliveries` | yes | yes | yes |
+| `networks_get` | yes | yes | yes |
+| `metrics_query` | yes | yes | yes |
+| `charges_create` | yes | no | yes |
+| `charges_check` | yes | no | yes |
+| `webhooks_retry_delivery` | yes | no | yes |
+| `sandbox_trigger` | yes | no | no |
+
+Every result is JSON and carries `environment`. Inputs and outputs are
+described in [Tools](./docs/tools.md).
+
+## Security notes
+
+- Live is read-only unless `KLAP_MCP_ALLOW_LIVE_WRITES=1`.
+- A key stored by `klap login` is only ever sent to the base URL it was
+  stored with. Pointing `KLAP_BASE_URL` somewhere else refuses to start.
+- Plain `http://` is only accepted for `localhost`, `127.0.0.1` and `[::1]`.
+- API responses are filtered through the published `@klappay/types`
+  schemas before the assistant sees them; unknown fields are dropped and a
+  charge's `metadata` is left out unless asked for.
+- Not available at all: escrow `release`/`refund`, webhook
+  create/delete/rotate-secret, recipient changes, live event streams, QR
+  codes and swap quotes.
+
+More in [Security](./docs/security.md).
+
+## Documentation
+
+Full docs live in [`docs/`](./docs) and as a browsable site at
+[mcp.klappay.com](https://mcp.klappay.com), which also publishes
+[`llms.txt`](https://mcp.klappay.com/llms.txt) and
+[`llms-full.txt`](https://mcp.klappay.com/llms-full.txt).
+
+| Topic | |
+|---|---|
+| [Getting started](./docs/getting-started.md) | Log in, add the server, first prompts |
+| [Configuration](./docs/configuration.md) | How the environment and key are chosen, every refusal |
+| [Tools](./docs/tools.md) | Every tool's input, output and availability |
+| [Security](./docs/security.md) | Threat model, what's excluded and why |
+
+## License
+
+[MIT](./LICENSE)

package/dist/chunk-FCIY5UOM.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+// src/server-name.ts
+var SERVER_NAME = "klap-mcp";
+
+export {
+  SERVER_NAME
+};
+//# sourceMappingURL=chunk-FCIY5UOM.js.map

package/dist/chunk-FCIY5UOM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server-name.ts"],"sourcesContent":["export const SERVER_NAME = 'klap-mcp'\n"],"mappings":";;;AAAO,IAAM,cAAc;","names":[]}

package/dist/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import {
+  SERVER_NAME
+} from "./chunk-FCIY5UOM.js";
+
+// src/index.ts
+console.log = console.error;
+console.info = console.error;
+console.debug = console.error;
+try {
+  const { start } = await import("./start-4SOOSFNC.js");
+  await start();
+} catch (err) {
+  const name = err instanceof Error ? err.name : typeof err;
+  console.error(`${SERVER_NAME}: failed to start (${name}).`);
+  process.exit(1);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { SERVER_NAME } from './server-name'\n\nconsole.log = console.error\nconsole.info = console.error\nconsole.debug = console.error\n\ntry {\n  const { start } = await import('./start')\n  await start()\n} catch (err) {\n  const name = err instanceof Error ? err.name : typeof err\n  console.error(`${SERVER_NAME}: failed to start (${name}).`)\n  process.exit(1)\n}\n"],"mappings":";;;;;;AAEA,QAAQ,MAAM,QAAQ;AACtB,QAAQ,OAAO,QAAQ;AACvB,QAAQ,QAAQ,QAAQ;AAExB,IAAI;AACF,QAAM,EAAE,MAAM,IAAI,MAAM,OAAO,qBAAS;AACxC,QAAM,MAAM;AACd,SAAS,KAAK;AACZ,QAAM,OAAO,eAAe,QAAQ,IAAI,OAAO,OAAO;AACtD,UAAQ,MAAM,GAAG,WAAW,sBAAsB,IAAI,IAAI;AAC1D,UAAQ,KAAK,CAAC;AAChB;","names":[]}