xakto-mcp 1.1.0 → 1.2.0

package/README.md

@@ -20,32 +20,34 @@ to it (a service worker cannot listen for anything).
 
 ## Setting it up
 
-1. Open Xakto's menu (its mark at the top of the layers) > **Agent** >
-   **Connect your agent**, or **Settings** > **MCP server**,
-   and turn it on. Settings is a modal over the page, but the page cannot read it:
-   it is drawn in a frame of Xakto's own, since it holds the pairing
-   token.
-2. Run the line Settings shows, in a terminal:
+Xakto calls this **Coding agent**: its menu row, its panel and its section in
+Settings. This package is the MCP server behind it.
+
+1. Open Xakto's menu (its mark at the top of the layers) > **Coding agent** and
+   press **Connect a coding agent**, or turn on **Coding agent** in **Settings**.
+   The panel sits over the page, but the page cannot read it: it is drawn in a
+   frame of Xakto's own, since it holds the pairing key.
+2. **Run this in a terminal**, as the panel's first step says:
 
    ```bash
    npx -y xakto-mcp setup
    ```
 
-   It asks which agent, and for the token (**Copy token** in Settings), then
+   It asks which agent, and for the pairing key (the panel's **Copy key**), then
    adds Xakto to that agent's own settings, keeping everything else there. A
    file it changes keeps a copy beside it, ending `.xakto-backup`; a settings
    file with comments is left alone, and the block to paste is printed
-   instead. Name the agent to skip the first question, and pass the token to
-   skip the second:
+   instead. Name the agent to skip the first question, and pass the key to
+   skip the second (`--token` works as well as `--key`):
 
    ```bash
-   npx -y xakto-mcp setup cursor --token <token from Settings>
+   npx -y xakto-mcp setup cursor --key <pairing key>
    ```
 
    The agents it knows are `claude`, `codex`, `cursor`, `vscode`, `windsurf`
    and `gemini`. `--port` is needed only when Settings names a port.
 
-   **By hand** (Settings › **Set it up by hand**): the relay is the same for
+   **By hand** (the panel's **Other agents, or set up by hand**): the relay is the same for
    every agent; only where the setup goes differs:
 
    | Agent | Where the setup goes |
@@ -61,7 +63,7 @@ to it (a service worker cannot listen for anything).
    For Claude Code it is:
 
    ```bash
-   claude mcp add xakto --scope user --env XAKTO_TOKEN=<token from Settings> -- npx -y xakto-mcp
+   claude mcp add xakto --scope user --env XAKTO_TOKEN=<pairing key> -- npx -y xakto-mcp
    ```
 
    For Codex:
@@ -70,7 +72,7 @@ to it (a service worker cannot listen for anything).
    [mcp_servers.xakto]
    command = "npx"
    args = ["-y", "xakto-mcp"]
-   env = { XAKTO_TOKEN = "<token from Settings>" }
+   env = { XAKTO_TOKEN = "<pairing key>" }
    ```
 
    And the `mcpServers` block, which VS Code reads under `servers` instead:
@@ -81,13 +83,15 @@ to it (a service worker cannot listen for anything).
        "xakto": {
          "command": "npx",
          "args": ["-y", "xakto-mcp"],
-         "env": { "XAKTO_TOKEN": "<token from Settings>" }
+         "env": { "XAKTO_TOKEN": "<pairing key>" }
        }
      }
    }
    ```
-3. Start a new agent session. The pill beside **MCP server** says
-   **Connected** once the relay is running and the two have paired.
+3. Start a new agent session. The pill beside **Coding agent** says
+   **Connected** once the relay is running and the two have paired, and the
+   panel and the menu row name the agent: since 1.2.0 the relay passes on the
+   name the agent gives itself when it connects (MCP's `clientInfo`).
 
 Xakto answers about one page: the tab you switched it on in. Switch it on in
 another tab and that is the page the agent sees.
@@ -151,23 +155,23 @@ for a relay that says so.
 - It accepts a connection only from a `chrome-extension://` origin. Set
   `XAKTO_EXTENSION_ID` to accept only Xakto.
 - Before anything else is said, the relay and the extension each prove that
-  they hold the same pairing token, by answering the other's fresh challenge
-  with an HMAC-SHA256 of it. The token itself never goes over the socket, so
-  whatever answers on the port first learns nothing from it.
-- The token is kept in the extension's own storage, which is closed to content
-  scripts, and is shown only in Xakto's Settings, a frame of the extension's
-  own that the page it sits over cannot read. The page can load a copy of that
-  frame, but the token goes only to the frame Xakto opened and vouched for
-  with a one-time code. **New token** makes the old one useless; run the
-  setup again after it.
+  they hold the same pairing key (`XAKTO_TOKEN`), by answering the other's
+  fresh challenge with an HMAC-SHA256 of it. The key itself never goes over the
+  socket, so whatever answers on the port first learns nothing from it.
+- The key is kept in the extension's own storage, which is closed to content
+  scripts, and is shown only in Xakto's Coding agent panel, a frame of the
+  extension's own that the page it sits over cannot read. The page can load a
+  copy of that frame, but the key goes only to the frame Xakto opened and
+  vouched for with a one-time code. **New pairing key** makes the old one
+  useless; run the setup again after it.
 - No dependencies: the parts of WebSocket and MCP it needs are in its own files.
 
 ## Settings
 
 | Variable | Default | |
 | --- | --- | --- |
-| `XAKTO_TOKEN` | none | The pairing token from Xakto's Settings. Without it the relay pairs with nothing. |
-| `XAKTO_PORT` | `47821` | The port to listen on. It has to be the one Xakto connects to, which the setup in Settings names when it is not the default. |
+| `XAKTO_TOKEN` | none | The pairing key, from Xakto's Coding agent panel (**Copy key**). Without it the relay pairs with nothing. |
+| `XAKTO_PORT` | `47821` | The port to listen on. It has to be the one Xakto connects to, which the setup line names when it is not the default. |
 | `XAKTO_EXTENSION_ID` | none | Accept only this extension. |
 | `XAKTO_CLAUDE_BIN` | found on `PATH` | Where Claude Code is, for the chat, when it is not on the `PATH` or in `~/.local/bin`. |
 
@@ -178,7 +182,7 @@ file itself: `node /path/to/Xakto/bridge/xakto-mcp.mjs` in place of
 `npx -y xakto-mcp`. In Claude Code:
 
 ```bash
-claude mcp add xakto --scope user --env XAKTO_TOKEN=<token from Settings> -- node /path/to/Xakto/bridge/xakto-mcp.mjs
+claude mcp add xakto --scope user --env XAKTO_TOKEN=<pairing key> -- node /path/to/Xakto/bridge/xakto-mcp.mjs
 ```
 
 In an `mcpServers` block, `"command": "node"` and
@@ -189,11 +193,11 @@ stdout is the protocol.
 
 ## When it does not connect
 
-- **The agent hears "Xakto is not connected".** The MCP server switch is off,
-  Chrome is not running, or the relay was started with another token.
-- **Settings says "Token refused".** The relay holds a different token from
-  this browser's. Run `npx -y xakto-mcp setup` again with the token Settings
-  shows, and restart the agent session.
+- **The agent hears "Xakto is not connected".** Coding agent is switched off,
+  Chrome is not running, or the relay was started with another pairing key.
+- **Coding agent says "Old key".** The relay holds a different pairing key from
+  this browser's. Run `npx -y xakto-mcp setup` again with the key the panel
+  gives (**Copy key**), and restart the agent session.
 - **The port is taken.** Only one relay can listen on it, and Xakto pairs
   with one relay at a time. A second agent session's relay tells its agent the
   port is held, and takes it over as soon as it is free: close the other

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xakto-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "The relay between a coding agent and the Xakto Chrome extension: an MCP server on stdio, a paired WebSocket on 127.0.0.1.",
   "homepage": "https://xakto.app",
   "type": "module",

package/xakto-mcp.mjs

@@ -28,7 +28,7 @@ import { createInterface } from "node:readline"
 import { fileURLToPath } from "node:url"
 import { createChat } from "./xakto-chat.mjs"
 
-const VERSION = "1.1.0"
+const VERSION = "1.2.0"
 export const DEFAULT_PORT = 47821
 const PORT = Number(process.env.XAKTO_PORT || DEFAULT_PORT)
 const TOKEN = (process.env.XAKTO_TOKEN ?? "").trim()
@@ -162,6 +162,8 @@ export class FrameReader {
 /* ---------- the extension's end ---------- */
 
 let extension = null
+/** The agent that started this relay, as it named itself in MCP's initialize (clientInfo), for Xakto to show (1.2.0). */
+let agentClient = ""
 let nextRequestId = 1
 const pending = new Map()
 
@@ -192,6 +194,7 @@ function onExtensionMessage(peer, message) {
     if (extension && extension !== peer) closePeer(extension, 4000, "replaced by a newer connection")
     extension = peer
     log("Xakto connected")
+    if (agentClient) sendTo(peer, { type: "client", name: agentClient })
     // Whether Claude Code is there and signed in is said only when Xakto asks (5 Nov), which it does only in a build
     // with the chat: a build without it never has the relay run Claude Code at all.
     return
@@ -351,8 +354,8 @@ function listen() {
 /* ---------- the agent's end: MCP over stdio ---------- */
 
 const NOT_CONNECTED = TOKEN
-  ? "Xakto is not connected. In Chrome, open Xakto's menu > Agent > Connect your agent, or Settings, turn on MCP server, and make sure the token there is the one this server was started with."
-  : "This server was started without XAKTO_TOKEN. Copy the setup for your agent from Xakto's menu > Settings, under MCP server; it carries the token."
+  ? "Xakto is not connected. In Chrome, open Xakto's menu > Coding agent and turn it on. If it says Old key, run npx -y xakto-mcp setup again with the pairing key there."
+  : "This server was started without a pairing key. Run npx -y xakto-mcp setup in a terminal, with the key from Xakto's menu > Coding agent > Copy key."
 
 const PORT_TAKEN = `Xakto is not connected: 127.0.0.1:${PORT} is held by something else - most likely another agent session's Xakto server, which Xakto talks to instead. This server takes the port over as soon as it is free; close that session, or ask there.`
 
@@ -615,6 +618,9 @@ async function answerAgent(message) {
 
   if (method === "initialize") {
     const asked = params?.protocolVersion
+    // Who started this relay - "claude-code", "cursor-vscode" and so on - passed on so Xakto can say what it is connected to.
+    agentClient = String(params?.clientInfo?.name ?? "").replace(/[^\p{L}\p{N} ._-]/gu, "").slice(0, 64)
+    if (agentClient && extension) sendTo(extension, { type: "client", name: agentClient })
     return {
       jsonrpc: "2.0",
       id,
@@ -734,7 +740,7 @@ if (isTheScript() && process.argv[2] === "setup") {
   const { runSetup } = await import("./xakto-setup.mjs")
   process.exitCode = await runSetup(process.argv.slice(3))
 } else if (isTheScript()) {
-  if (!TOKEN) log("XAKTO_TOKEN is not set; Xakto will refuse to pair. Run `npx -y xakto-mcp setup`, or copy the setup from Xakto's Settings.")
+  if (!TOKEN) log("XAKTO_TOKEN (the pairing key) is not set; Xakto will refuse to pair. Run `npx -y xakto-mcp setup`, with the key from Xakto's menu > Coding agent.")
   process.on("exit", () => chat.stopAll())
   listen()
   serveAgent()

package/xakto-setup.mjs

@@ -1,13 +1,13 @@
 /**
  * `npx -y xakto-mcp setup` (8 Nov 2026): adds Xakto to a coding agent, so nobody has to find that agent's settings
- * file and paste a block into it. One command for every agent; it asks which, and for the token from Xakto's
- * Settings, and writes what Settings' "Set it up by hand" shows - `npx -y xakto-mcp` with the token - into that
+ * file and paste a block into it. One command for every agent; it asks which, and for the pairing key from Xakto's
+ * menu › Coding agent (Copy key), and writes what "Other agents, or set up by hand" shows - `npx -y xakto-mcp` with the token - into that
  * agent's own settings, keeping everything else there.
  *
- *   npx -y xakto-mcp setup                      asks which agent, then the token
- *   npx -y xakto-mcp setup cursor               that agent; asks the token
- *   npx -y xakto-mcp setup cursor --token T     nothing to answer
- *   ... --port 47900                            only when Xakto's Settings names a port
+ *   npx -y xakto-mcp setup                      asks which agent, then the pairing key
+ *   npx -y xakto-mcp setup cursor               that agent; asks the pairing key
+ *   npx -y xakto-mcp setup cursor --key K       nothing to answer (--token is the same)
+ *   ... --port 47900                            only when Xakto names a port
  *
  * It only writes files on this computer (and, for Claude Code, runs `claude mcp add`). A settings file it cannot read
  * as plain JSON - VS Code allows comments in its own - is left as it is, and the block is printed to paste by hand.
@@ -192,14 +192,15 @@ export function addToAgent(agent, token, port, { home = homedir(), env = process
   return { file, replaced: merged.replaced, next: NEXT_STEP[agent.id] }
 }
 
-/** --token and --port, wherever they are; the first other word is the agent. */
+/** --key (or --token) and --port, wherever they are; the first other word is the agent. */
 export function parseArgs(argv) {
   const out = { agent: null, token: null, port: null, help: false }
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i]
     if (arg === "--help" || arg === "-h") out.help = true
-    else if (arg === "--token") out.token = argv[(i += 1)] ?? ""
+    else if (arg === "--token" || arg === "--key") out.token = argv[(i += 1)] ?? ""
     else if (arg.startsWith("--token=")) out.token = arg.slice(8)
+    else if (arg.startsWith("--key=")) out.token = arg.slice(6)
     else if (arg === "--port") out.port = argv[(i += 1)] ?? ""
     else if (arg.startsWith("--port=")) out.port = arg.slice(7)
     else if (!out.agent) out.agent = arg
@@ -209,10 +210,10 @@ export function parseArgs(argv) {
 
 const HELP = `Adds Xakto to your coding agent.
 
-  npx -y xakto-mcp setup                    asks which agent, then your token
+  npx -y xakto-mcp setup                    asks which agent, then your pairing key
   npx -y xakto-mcp setup <agent>            ${AGENTS.map((agent) => agent.aliases[0]).join(", ")}
-  npx -y xakto-mcp setup <agent> --token <token from Xakto's Settings>
-  --port <port>                             only if Xakto's Settings names one
+  npx -y xakto-mcp setup <agent> --key <pairing key from Xakto's menu › Coding agent › Copy key>
+  --port <port>                             only if Xakto names one
 `
 
 /** A question; with `hidden`, what is typed shows as dots. */
@@ -253,7 +254,7 @@ export async function runSetup(argv, { input = process.stdin, output = process.s
   let token = (args.token ?? env.XAKTO_TOKEN ?? "").trim().toLowerCase()
   const interactive = Boolean(input.isTTY)
   if ((!agent || !token) && !interactive) {
-    error.write(`Run it in a terminal to be asked, or name the agent and the token:\n\n${HELP}`)
+    error.write(`Run it in a terminal to be asked, or name the agent and the pairing key:\n\n${HELP}`)
     return 2
   }
 
@@ -277,9 +278,9 @@ export async function runSetup(argv, { input = process.stdin, output = process.s
     }
 
     while (!TOKEN_PATTERN.test(token)) {
-      if (token) say("That is not a Xakto token: it is 36 letters and digits, from Xakto › Settings › MCP server › Copy token.")
+      if (token) say("That is not a Xakto pairing key: it is 36 letters and digits, from Xakto's menu › Coding agent › Copy key.")
       if (!interactive) return 2
-      token = (await ask(rl, output, "\nPaste your token from Xakto › Settings › MCP server: ", true)).trim().toLowerCase()
+      token = (await ask(rl, output, "\nPaste your pairing key (Xakto's menu › Coding agent › Copy key): ", true)).trim().toLowerCase()
     }
 
     let result
@@ -291,7 +292,7 @@ export async function runSetup(argv, { input = process.stdin, output = process.s
     }
     say(`\n✔ ${result.replaced ? "Replaced the older Xakto setup in" : "Added Xakto to"} ${agent.name}${agent.kind === "claude" ? ", for all your projects" : ""}.`)
     if (result.file) say(`  ${result.file}`)
-    say(`  ${result.next} Xakto's Settings turns green when it connects.`)
+    say(`  ${result.next} Xakto's menu › Coding agent says Connected when it does.`)
     return 0
   } finally {
     rl?.close()