@techsologic/unolock-agent-mcp 0.1.13 → 0.1.15

package/README.md

@@ -2,8 +2,30 @@
 
 This repository is the dedicated home for UnoLock's Python agent/MCP client.
 
+UnoLock was built to protect you. Now it can protect both you and your agent.
+
 UnoLock Agent MCP is currently in alpha. It is available for evaluation and early testing, but it is not ready for broad production rollout yet.
 
+## Why Use UnoLock For An Agent
+
+UnoLock Agent MCP is not only about protecting secrets.
+
+It gives an agent a safer place to keep and use:
+
+* secrets
+* durable memory
+* structured notes
+* checklists
+* space-scoped working data
+
+Compared to local memory files or plaintext secret storage, UnoLock gives the agent:
+
+* encrypted storage
+* controlled access to only the Spaces it should use
+* persistence beyond a single local machine or process
+* safer recovery from host loss, reset, or replacement
+* a stronger access model than reusable API keys or plaintext config secrets
+
 ## Security Requirement
 
 UnoLock Agent MCP is built for customers who want the strongest practical protection for AI-accessed secrets.
@@ -44,10 +66,18 @@ Official GitHub repository:
 * `https://github.com/TechSologic/unolock-agent-mcp`
 * Releases: `https://github.com/TechSologic/unolock-agent-mcp/releases`
 
+Agent-first onboarding site:
+
+* `https://unolock.ai/index.html`
+* `https://unolock.ai/install-mcp.html`
+* `https://unolock.ai/connect-agent.html`
+* `https://unolock.ai/agent-explanation-kit.html`
+
 Recommended customer install source:
 
+* `mcporter` keep-alive plus `npx @techsologic/unolock-agent-mcp@latest` when available
 * GitHub Releases binaries
-* `npx @techsologic/unolock-agent-mcp` as the Node/npm wrapper path
+* `npx @techsologic/unolock-agent-mcp@latest` as the Node/npm wrapper path
 * `pipx install` as the fallback source install path when no release binary is available yet
 
 If you are new to UnoLock itself, start with these docs first:
@@ -58,6 +88,11 @@ If you are new to UnoLock itself, start with these docs first:
 * Spaces: `https://docs.unolock.com/features/spaces.html`
 * Connect an AI Agent to a Safe: `https://docs.unolock.com/howto/connecting-an-ai-agent.html`
 
+Prerequisite:
+
+* Free and Inheritance can share their single included Safe space with one extra Agent Key.
+* Sovereign and HighRisk are still the right tiers for broader multi-Space and collaboration-heavy agent workflows.
+
 The current MCP proves the hardest integration seam first:
 
 * live local `/start` flow compatibility
@@ -72,7 +107,7 @@ Safe creation remains a human/browser responsibility, matching the product model
 * human admin creates a Safe
 * human admin creates an agent access key for that Safe
 * MCP registers to the existing Safe
-* MCP later authenticates and uses the shared Safe API surface
+* MCP later authenticates and uses the shared Safe API surface for agent memory, notes, checklists, and secrets
 
 ## Quick start
 
@@ -91,12 +126,16 @@ For real MCP hosts, see:
 * [macOS Quick Start](docs/macos.md)
 * [Supported Environments](docs/supported-environments.md)
 * [MCP Host Config](docs/host-config.md)
+* [mcporter keep-alive setup](docs/mcporter.md)
 * [Support Matrix](docs/support-matrix.md)
 * [Tool Catalog](docs/tool-catalog.md)
 * [Claude Desktop example](examples/claude-desktop-config.json)
 * [Cursor example](examples/cursor-mcp.json)
+* [mcporter example](examples/mcporter.json)
 * [Config file example](examples/unolock-agent-config.json)
 
+`mcporter` is the preferred path when it is available. The user PIN is kept only in MCP process memory, so keeping the MCP alive means lower latency, fewer repeat PIN prompts, and less pressure for the agent to store the PIN persistently.
+
 If you prefer manual install from source:
 
 ```bash
@@ -122,6 +161,12 @@ For the best customer experience, prefer GitHub Release binaries over source ins
 
 ## Preferred Customer Install
 
+When available, prefer `mcporter` keep-alive plus the npm wrapper or release binary instead of a cold-start bare MCP process.
+
+For an agent-first public onboarding flow, send users or agents to:
+
+* `https://unolock.ai/index.html`
+
 When available, prefer the standalone GitHub Release binaries instead of installing from Git.
 
 That avoids most of the Python packaging and source-build overhead for customers.
@@ -129,11 +174,13 @@ That avoids most of the Python packaging and source-build overhead for customers
 If your host environment is already Node/npm-oriented, you can also use the npm wrapper:
 
 ```bash
-npx @techsologic/unolock-agent-mcp --version
+npx @techsologic/unolock-agent-mcp@latest --version
 ```
 
 The wrapper downloads the correct GitHub Release binary for the current platform on first use and then reuses the cached copy.
 
+On restart, the npm wrapper now checks GitHub Releases for a newer stable binary and will update its cached binary between tasks when a newer release is available.
+
 The npm package is an OpenClaw-friendly install and launch path for the external UnoLock MCP binary.
 
 It is **not** an OpenClaw plugin package for `openclaw plugins install ...`.
@@ -145,15 +192,62 @@ Project home:
 Use it as a command that OpenClaw can launch, for example:
 
 ```bash
-npx @techsologic/unolock-agent-mcp mcp
+npx @techsologic/unolock-agent-mcp@latest mcp
 ```
 
 With no arguments, the npm wrapper starts the MCP server by default:
 
 ```bash
-npx @techsologic/unolock-agent-mcp
+npx @techsologic/unolock-agent-mcp@latest
+```
+
+Preferred keep-alive example with `mcporter`:
+
+```json
+{
+  "servers": {
+    "unolock-agent": {
+      "command": "npx",
+      "args": ["@techsologic/unolock-agent-mcp@latest"],
+      "lifecycle": "keep-alive"
+    }
+  }
+}
+```
+
+## Update Policy
+
+UnoLock Agent MCP should not replace itself in the middle of an active session or write flow.
+
+The intended update model is:
+
+* the MCP reports update status
+* the wrapper or runner applies updates
+* the runner restarts between tasks so in-memory PINs and sessions can be re-established cleanly
+
+Check update status with:
+
+```bash
+unolock-agent-mcp check-update --json
 ```
 
+Or, through the MCP itself, call:
+
+* `unolock_get_update_status`
+
+Preferred channel behavior:
+
+* `mcporter` + `npx @techsologic/unolock-agent-mcp@latest`
+  * preferred low-friction path
+  * on restart, the npm wrapper checks GitHub Releases and can fetch the latest stable binary
+  * npm publishing is only needed when the wrapper itself changes
+* direct GitHub Release binary
+  * replace the binary manually, then restart the MCP runner
+* Python package install
+  * upgrade the package in that environment, then restart the runner
+
+For the best user experience, do updates between tasks, not while an enrollment flow, authentication flow, or sensitive write flow is active.
+
 ## Standalone config
 
 When the MCP runs outside the main UnoLock monorepo, it can usually derive its UnoLock runtime config from the UnoLock agent key connection URL. Environment variables and config files are primarily for overrides and custom deployments.
@@ -170,12 +264,11 @@ Override example:
 {
   "base_url": "https://api.unolock.example",
   "transparency_origin": "https://safe.unolock.example",
-  "app_version": "1.2.3",
   "signing_public_key_b64": "BASE64_SERVER_PQ_SIGNING_PUBLIC_KEY"
 }
 ```
 
-For the standard hosted UnoLock deployment, the MCP can derive the API origin, UnoLock app version, and PQ validation key from the user-provided agent key connection URL automatically. If you want to force the same hosted deployment without waiting for a connection URL, this also works:
+For the standard hosted UnoLock deployment, the MCP can derive the API origin and PQ validation key from the user-provided agent key connection URL automatically. If you want to force the same hosted deployment without waiting for a connection URL, this also works:
 
 ```json
 {
@@ -183,7 +276,7 @@ For the standard hosted UnoLock deployment, the MCP can derive the API origin, U
 }
 ```
 
-the MCP will derive `https://safe.unolock.com`, fetch `/unolock-client.json`, and read the published app version and `serverPQValidationKey`. If that hosted file is unavailable, it falls back to the transparency bundle.
+the MCP will derive `https://safe.unolock.com`, fetch `/unolock-client.json`, and read the published `serverPQValidationKey`. If that hosted file is unavailable, it falls back to the transparency bundle.
 
 Use this command to verify what the MCP resolved:
 
@@ -191,13 +284,6 @@ Use this command to verify what the MCP resolved:
 python3 -m unolock_mcp config-check
 ```
 
-Versioning is intentionally split:
-
-* MCP package version: the version of `unolock-agent-mcp` itself
-* UnoLock app version: the Safe client/server compatibility version sent as `x-app-version`
-
-For the standard hosted UnoLock deployment, the MCP resolves the UnoLock app version from the hosted client metadata rather than reusing the MCP package version.
-
 TPM provider selection:
 
 * default: `UNOLOCK_TPM_PROVIDER=auto`

package/bin/unolock-agent-mcp.js

@@ -7,8 +7,8 @@ const path = require("path");
 const https = require("https");
 const { spawn } = require("child_process");
 
-const PACKAGE_VERSION = "0.1.13";
-const BINARY_VERSION = "0.1.11";
+const PACKAGE_VERSION = "0.1.15";
+const FALLBACK_BINARY_VERSION = "0.1.15";
 const REPO = "TechSologic/unolock-agent-mcp";
 
 function platformAssetInfo() {
@@ -36,17 +36,21 @@ function cacheRoot() {
   return process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
 }
 
-function binaryPath() {
+function metadataPath() {
+  return path.join(cacheRoot(), "unolock-agent-mcp", "release.json");
+}
+
+function binaryPath(releaseVersion) {
   const { executable } = platformAssetInfo();
-  return path.join(cacheRoot(), "unolock-agent-mcp", BINARY_VERSION, executable);
+  return path.join(cacheRoot(), "unolock-agent-mcp", releaseVersion, executable);
 }
 
-function binaryUrl() {
+function binaryUrl(releaseVersion) {
   if (process.env.UNOLOCK_AGENT_MCP_BINARY_URL) {
     return process.env.UNOLOCK_AGENT_MCP_BINARY_URL;
   }
   const { asset } = platformAssetInfo();
-  return `https://github.com/${REPO}/releases/download/v${BINARY_VERSION}/${asset}`;
+  return `https://github.com/${REPO}/releases/download/v${releaseVersion}/${asset}`;
 }
 
 function ensureDir(dir) {
@@ -95,23 +99,126 @@ function fetchToFile(url, dest) {
   });
 }
 
+function fetchJson(url) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(
+      url,
+      {
+        headers: {
+          "Accept": "application/vnd.github+json",
+          "User-Agent": "unolock-agent-mcp-npm-wrapper"
+        }
+      },
+      (response) => {
+        if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+          response.resume();
+          fetchJson(response.headers.location).then(resolve, reject);
+          return;
+        }
+        if (response.statusCode !== 200) {
+          response.resume();
+          reject(new Error(`Failed to query UnoLock Agent MCP latest release: HTTP ${response.statusCode}`));
+          return;
+        }
+        let body = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          body += chunk;
+        });
+        response.on("end", () => {
+          try {
+            resolve(JSON.parse(body));
+          } catch (error) {
+            reject(error);
+          }
+        });
+      }
+    );
+    request.on("error", reject);
+  });
+}
+
+function normalizeVersion(value) {
+  if (!value || typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+  return trimmed.startsWith("v") ? trimmed.slice(1) : trimmed;
+}
+
+function readReleaseMetadata() {
+  try {
+    return JSON.parse(fs.readFileSync(metadataPath(), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeReleaseMetadata(releaseVersion) {
+  ensureDir(path.dirname(metadataPath()));
+  fs.writeFileSync(
+    metadataPath(),
+    JSON.stringify(
+      {
+        releaseVersion,
+        checkedAt: Date.now()
+      },
+      null,
+      2
+    ),
+    "utf8"
+  );
+}
+
+async function resolveReleaseVersion() {
+  const override = normalizeVersion(process.env.UNOLOCK_AGENT_MCP_BINARY_VERSION);
+  if (override) {
+    return override;
+  }
+  const metadata = readReleaseMetadata();
+  try {
+    const payload = await fetchJson(`https://api.github.com/repos/${REPO}/releases/latest`);
+    const latest = normalizeVersion(payload && payload.tag_name);
+    if (latest) {
+      writeReleaseMetadata(latest);
+      return latest;
+    }
+  } catch (error) {
+    if (metadata && typeof metadata.releaseVersion === "string" && fs.existsSync(binaryPath(metadata.releaseVersion))) {
+      return metadata.releaseVersion;
+    }
+    process.stderr.write(`Warning: ${error.message}. Falling back to bundled release ${FALLBACK_BINARY_VERSION}.\n`);
+  }
+  writeReleaseMetadata(FALLBACK_BINARY_VERSION);
+  return FALLBACK_BINARY_VERSION;
+}
+
 async function ensureBinary() {
-  const dest = binaryPath();
+  const releaseVersion = await resolveReleaseVersion();
+  const dest = binaryPath(releaseVersion);
   if (fs.existsSync(dest)) {
-    return dest;
+    return { dest, releaseVersion };
   }
   ensureDir(path.dirname(dest));
-  process.stderr.write(`Downloading UnoLock Agent MCP ${BINARY_VERSION} for ${process.platform}/${process.arch}...\n`);
-  await fetchToFile(binaryUrl(), dest);
-  return dest;
+  process.stderr.write(`Downloading UnoLock Agent MCP ${releaseVersion} for ${process.platform}/${process.arch}...\n`);
+  await fetchToFile(binaryUrl(releaseVersion), dest);
+  return { dest, releaseVersion };
 }
 
 async function main() {
-  const dest = await ensureBinary();
+  const { dest, releaseVersion } = await ensureBinary();
   const forwardedArgs = process.argv.length > 2 ? process.argv.slice(2) : ["mcp"];
   const child = spawn(dest, forwardedArgs, {
     stdio: "inherit",
-    env: process.env
+    env: {
+      ...process.env,
+      UNOLOCK_AGENT_MCP_INSTALL_CHANNEL: "npm-wrapper",
+      UNOLOCK_AGENT_MCP_WRAPPER_VERSION: PACKAGE_VERSION,
+      UNOLOCK_AGENT_MCP_BINARY_VERSION: releaseVersion
+    }
   });
   child.on("exit", (code, signal) => {
     if (signal) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@techsologic/unolock-agent-mcp",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "npx wrapper for the official UnoLock Agent MCP release binaries",
-  "license": "SEE LICENSE IN README.md",
+  "license": "UNLICENSED",
   "homepage": "https://github.com/TechSologic/unolock-agent-mcp",
   "repository": {
     "type": "git",