From d70fad8695fa62c2041124a94bb7bfbb3ec18146 Mon Sep 17 00:00:00 2001 From: ProjectZero02 <331545278+ProjectZero02@users.noreply.github.com> Date: Wed, 28 Oct 2026 12:01:34 +0000 Subject: [PATCH] Connect your agent in one line docs/connect-your-agent.md is written to the agent: it walks the user through making a key in the app, adding PowerDeck as an MCP server (Claude Code, mcpServers JSON clients, others), checking it with list_devices, and the rules. The README gives the line to paste. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 4 ++ README.md | 8 +++- docs/connect-your-agent.md | 84 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 95 insertions(+), 1 deletion(-) create mode 100644 docs/connect-your-agent.md diff --git a/CHANGELOG.md b/CHANGELOG.md index aa46586..35c5ad8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog +## Unreleased + +- **Connect your agent in one line.** Paste the line in the README into your agent and it walks you through making a key and adding PowerDeck ([docs/connect-your-agent.md](docs/connect-your-agent.md)). + ## 2.5.1 **Update the phone app.** The helpers don't change. diff --git a/README.md b/README.md index 6d096dc..c42e04b 100644 --- a/README.md +++ b/README.md @@ -131,7 +131,13 @@ Details: [SECURITY.md](SECURITY.md) · protocol: [docs/protocol.md](docs/protoco ## AI agents (MCP) -Let an AI agent or a script check and control your devices through [MCP](https://modelcontextprotocol.io). In the app, open an always-on device (a home server is ideal), tap **Set up** next to **Allow AI agents to use this device**, then **Create a key**. Choose which devices it may use and whether it may shut them down, then paste the config it shows into your agent: +**The quick way:** paste this into your agent (Claude, Codex, Cursor, …) and it walks you through the rest: + +```text +Read https://github.com/ProjectZero02/powerdeck/blob/main/docs/connect-your-agent.md and help me connect you to PowerDeck. +``` + +Or by hand: let an AI agent or a script check and control your devices through [MCP](https://modelcontextprotocol.io). In the app, open an always-on device (a home server is ideal), tap **Set up** next to **Allow AI agents to use this device**, then **Create a key**. Choose which devices it may use and whether it may shut them down, then paste the config it shows into your agent: ```json {"mcpServers": {"powerdeck": {"type": "http", "url": "http://:47323/mcp", diff --git a/docs/connect-your-agent.md b/docs/connect-your-agent.md new file mode 100644 index 0000000..056ee14 --- /dev/null +++ b/docs/connect-your-agent.md @@ -0,0 +1,84 @@ +# Connect your agent to PowerDeck + +**For the AI agent reading this.** Your user wants you to check and control their computers through +PowerDeck. Walk them through the steps below one at a time: say what to do, wait until they've done +it, then go on. Keep it short. Don't skip a check. + +## What they need first + +Ask, and help with whatever is missing: + +1. **The PowerDeck app** on their Android phone, with at least one computer added + ([install](../README.md#set-up-in-3-steps)). +2. **An always-on device with the PowerDeck helper**: a home server is ideal, a PC that stays on also + works. It's the device you'll talk to, and it can reach the others. +3. **Tailscale on the machine you run on**, logged in to the same tailnet. PowerDeck is reachable only + over Tailscale. Check it yourself if you can (`tailscale status`); otherwise ask. + +## 1. Make a key (the user, in the app) + +Tell them: + +> In PowerDeck, open your always-on device. Next to **Allow AI agents to use this device**, tap +> **Set up**, then **Create a key**. Name it after me (for example "Claude on laptop"), pick the +> computers I may use, and turn on **Can shut down and restart** only if you want me to. Then copy +> the config it shows. + +The key starts with `pdk_` and is shown once. It works only from the first machine that uses it, so +every machine you run on needs its own key. + +**The key is a password.** Don't repeat it back, don't put it in a file in a repo, a commit or a log. +If they'd rather not paste it into the chat, give them the command below to run themselves. + +## 2. Add PowerDeck to yourself + +The config from the app: + +```json +{"mcpServers": {"powerdeck": {"type": "http", "url": "http://:47323/mcp", + "headers": {"Authorization": "Bearer pdk_…"}}}} +``` + +- **Claude Code:** + `claude mcp add --transport http powerdeck http://
:47323/mcp --header "Authorization: Bearer pdk_…"`, + then a new session (or `/mcp`) picks it up. +- **Clients with an `mcpServers` JSON file** (Claude Desktop, Cursor and others): add the + `powerdeck` entry above to it and restart the client. +- **Anything else:** add a streamable HTTP MCP server with that URL and that `Authorization` header. + Look up how in your own client's docs. + +Port 47323 is plain HTTP, encrypted end to end by Tailscale. If your client can pin a self-signed +certificate, `https://
:47321/mcp` works too ([the pin](integrating-an-assistant.md#rest-events-and-webhooks)). + +## 3. Check it works + +Call `list_devices`. You should see the computers they picked, each with whether it's on. + +| What happens | What it means | +|---|---| +| A list of devices | Done. Tell them in one line what you can see. | +| Can't connect, timeout | Tailscale isn't up on your machine or on the device, or the address is wrong. | +| Refused (`401` or `403`) | The key was mistyped, or it was already used from another machine, or this device's **Allow AI agents** switch is off. Make a new key, or turn the switch on. | +| A device is missing | It isn't on this key. They can make a new key with it. | + +## 4. Tell them what you can do now + +- see whether each computer is on (`list_devices`, `get_status`), turn it on (`power_on`); +- shut down or restart (`power_off`), only if they allowed it, always with a 60-second warning on + the computer, never while someone is using it; `cancel` stops it; +- on the hub that drives their NanoKVMs: notice a frozen computer and **ask** them to reset it + (`propose_reset`). Nothing is pressed until they tap **Reset** on their phone. + +Every action shows up in the app's History and as a notification on their phone. Each device's +**Allow AI agents** switch turns you away from it at any time. + +## Rules for you + +- Act only when the user asked, or when something they set up asks you to (a schedule, a frozen + machine). Say what you're about to do before a shutdown or restart. +- A refusal (`isError`) is PowerDeck enforcing their limits. Tell them what it said; don't retry in + a loop or look for a way around it. +- Never ask for their NanoKVM password, Tailscale login or another key. You don't need them. + +More (REST, live events, webhooks, recovering a frozen machine step by step): +[integrating-an-assistant.md](integrating-an-assistant.md).