@seekrit/mcp 0.3.0 → 0.5.0

package/README.md

@@ -18,15 +18,38 @@ it just publishes it as its own binary so no CLI install is required first.
 ## Setup
 
 Add it to any MCP client with a stdio server whose command runs this package via
-`npx`, passing a credential in its environment. For Claude Code:
+`npx`, passing a credential in its environment.
+
+**Fully autonomous agent (recommended).** An agent with no account can
+[sign up](https://seekrit.dev/docs/guides/ai-agents) for **machine credentials**
+(`POST https://mcp.seekrit.dev/signup`) and use the *same* client id + secret for
+everything — the hosted metadata plane and this local crypto plane. Point this
+server at them and it mints its own admin token automatically on first use
+(keyless — the keypair is generated locally), so there is no token to copy:
+
+```json
+{
+  "mcpServers": {
+    "seekrit": {
+      "command": "npx",
+      "args": ["-y", "@seekrit/mcp"],
+      "env": {
+        "SEEKRIT_CLIENT_ID": "<your client id>",
+        "SEEKRIT_CLIENT_SECRET": "<your client secret>"
+      }
+    }
+  }
+}
+```
+
+**With an existing token.** If you already hold a service token, pass it directly.
+For Claude Code:
 
 ```sh
 # An admin token lets the agent provision structure (apps/envs/tokens) too:
 claude mcp add seekrit --env SEEKRIT_TOKEN=skt_… -- npx -y @seekrit/mcp
 ```
 
-Or drop a `.mcp.json` in your project — the whole setup is this snippet:
-
 ```json
 {
   "mcpServers": {
@@ -73,12 +96,14 @@ The container still decrypts locally — nothing plaintext leaves it.
 
 ## Choosing the credential
 
-The server authenticates exactly like the CLI — `SEEKRIT_TOKEN`, or saved
-config at `~/.config/seekrit/config.json`.
+The server authenticates exactly like the CLI — `SEEKRIT_CLIENT_ID` +
+`SEEKRIT_CLIENT_SECRET`, `SEEKRIT_TOKEN`, or saved config at
+`~/.config/seekrit/config.json`.
 
 | Credential | Good for | Notes |
 | --- | --- | --- |
-| **Admin token** (`seekrit token create --admin`) | Provisioning: create apps/groups/envs, compose, grant, mint tokens | Org-scoped; the only headless way to create structure. |
+| **Machine credentials** (`SEEKRIT_CLIENT_ID` + `SEEKRIT_CLIENT_SECRET`) | Fully autonomous agents: one credential for both planes | Auto-mints + caches an admin token on first use. Get them from `POST /signup`. |
+| **Admin token** (`seekrit token create --admin`) | Provisioning: create apps/groups/envs, compose, grant, mint tokens | Org-scoped; a fixed headless credential for structure. |
 | **Runtime token** (bound to an env) | Reading/writing/injecting one environment's secrets | Self-decrypts — no passphrase. Cannot provision. |
 
 Under user auth (no token), tools that decrypt need `SEEKRIT_PASSPHRASE` in the

package/dist/index.js

@@ -3,7 +3,7 @@ import { spawn } from "node:child_process";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, parse } from "node:path";
 import { createInterface } from "node:readline";
@@ -664,7 +664,7 @@ function isServiceToken(value) {
 }
 //#endregion
 //#region ../cli/package.json
-var version$1 = "0.19.0";
+var version$1 = "0.23.0";
 const PROJECT_FILE = "seekrit.json";
 function globalConfigPath() {
 	return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "seekrit", "config.json");
@@ -674,6 +674,26 @@ function readGlobalConfig() {
 	if (!existsSync(path)) return {};
 	return JSON.parse(readFileSync(path, "utf8"));
 }
+function writeGlobalConfig(update) {
+	const path = globalConfigPath();
+	const merged = {
+		...readGlobalConfig(),
+		...update
+	};
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(merged, null, 2)}\n`, { mode: 384 });
+}
+/** The admin token previously auto-minted from these M2M credentials, if any. */
+function readCachedM2mToken(clientId) {
+	return readGlobalConfig().m2mTokens?.[clientId];
+}
+/** Remember an auto-minted admin token so the next run reuses it. */
+function cacheM2mToken(clientId, token) {
+	writeGlobalConfig({ m2mTokens: {
+		...readGlobalConfig().m2mTokens,
+		[clientId]: token
+	} });
+}
 /** Walk up from cwd looking for seekrit.json. */
 function findProjectConfig(startDir = process.cwd()) {
 	let dir = startDir;
@@ -706,19 +726,23 @@ var SeekritClient = class {
 	baseUrl;
 	auth;
 	fetchImpl;
+	client;
 	constructor(options) {
 		this.baseUrl = options.baseUrl.replace(/\/$/, "");
 		this.auth = options.auth;
 		this.fetchImpl = options.fetch ?? ((...args) => fetch(...args));
+		this.client = options.client;
 	}
 	async request(method, path, body) {
 		const headers = { accept: "application/json" };
+		if (this.client) headers["x-seekrit-client"] = this.client;
 		if (this.auth.type === "bearer") headers.authorization = `Bearer ${this.auth.token}`;
 		else if (this.auth.type === "dynamic") {
 			const token = await this.auth.getToken();
 			if (!token) throw new SeekritApiError(401, "unauthorized", "session expired");
 			headers.authorization = `Bearer ${token}`;
-		} else headers["x-seekrit-dev-user"] = this.auth.email;
+		} else if (this.auth.type === "m2m") headers.authorization = `Basic ${btoa(`${this.auth.clientId}:${this.auth.clientSecret}`)}`;
+		else headers["x-seekrit-dev-user"] = this.auth.email;
 		if (body !== void 0) headers["content-type"] = "application/json";
 		const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
 			method,
@@ -971,6 +995,10 @@ var SeekritClient = class {
 	disableKmsKey(orgId, keyId) {
 		return this.request("POST", `/v1/orgs/${orgId}/kms/keys/${keyId}/disable`);
 	}
+	/** Soft-delete a key: it drops out of every listing and read path. */
+	deleteKmsKey(orgId, keyId) {
+		return this.request("DELETE", `/v1/orgs/${orgId}/kms/keys/${keyId}`);
+	}
 	/** The broker's public key — wrap the admin credential to it before registering a target. */
 	getLeaseBrokerKey(orgId) {
 		return this.request("GET", `/v1/orgs/${orgId}/leases/broker-key`);
@@ -1087,6 +1115,8 @@ function promptHidden(question) {
 }
 //#endregion
 //#region ../cli/src/context.ts
+/** Sent as `x-seekrit-client` so the API attributes usage to the CLI (analytics). */
+const CLI_CLIENT = `cli/${version$1}`;
 /**
 * Build the client context from configured credentials, or return null when
 * none are set. `seekrit run` uses this to degrade to a plain launcher instead
@@ -1117,7 +1147,8 @@ function tryBuildContext(dotenvVars = {}) {
 	return {
 		client: new SeekritClient({
 			baseUrl: apiUrl,
-			auth
+			auth,
+			client: CLI_CLIENT
 		}),
 		auth
 	};
@@ -1296,6 +1327,78 @@ async function kmsRecoverMaterial(ctx, orgId, keyId, version) {
 	};
 }
 //#endregion
+//#region ../cli/src/m2m.ts
+/**
+* Resolve M2M client credentials from (in order) the process environment, a
+* `.env` overlay (for `seekrit run`), then saved config. Both halves must come
+* through for the credential to be usable.
+*/
+function readM2mCreds(dotenvVars = {}) {
+	const config = readGlobalConfig();
+	const fromEnv = (key) => process.env[key] ?? dotenvVars[key];
+	const clientId = fromEnv("SEEKRIT_CLIENT_ID") ?? config.clientId;
+	const clientSecret = fromEnv("SEEKRIT_CLIENT_SECRET") ?? config.clientSecret;
+	if (!clientId || !clientSecret) return null;
+	return {
+		clientId,
+		clientSecret
+	};
+}
+/** True when a service/dev credential is already configured explicitly. */
+function hasExplicitCredential(dotenvVars) {
+	const fromEnv = (key) => process.env[key] ?? dotenvVars[key];
+	if (fromEnv("SEEKRIT_TOKEN") || fromEnv("SEEKRIT_DEV_USER")) return true;
+	const config = readGlobalConfig();
+	return Boolean(config.token || config.devUser);
+}
+/** Mint a fresh org-scoped admin token using M2M credentials (keyless). */
+async function mintAdminToken(apiUrl, creds) {
+	const client = new SeekritClient({
+		baseUrl: apiUrl,
+		auth: {
+			type: "m2m",
+			clientId: creds.clientId,
+			clientSecret: creds.clientSecret
+		},
+		client: `cli/${version$1}`
+	});
+	const { orgs } = await client.listOrgs();
+	const org = orgs[0];
+	if (!org) throw new Error("machine client has no organization — sign up first (POST /signup)");
+	const created = await createServiceToken();
+	await client.createToken(org.id, {
+		name: "agent-admin (auto)",
+		tokenId: created.tokenId,
+		tokenHash: created.tokenHash,
+		publicKeyJwk: created.publicKeyJwk,
+		role: "admin",
+		environmentId: null
+	});
+	return created.token;
+}
+/**
+* If M2M credentials are configured (and no explicit token/dev-user is), ensure
+* an admin token exists for them — minting and caching one on first use — and
+* expose it as `SEEKRIT_TOKEN` so the normal credential resolution
+* ({@link tryBuildContext}) picks it up. A no-op (returns null) when there is
+* nothing to bootstrap. Throws only when credentials ARE present but minting
+* fails, so the reason surfaces instead of a later opaque "no credentials".
+*/
+async function ensureM2mAdminToken(dotenvVars = {}) {
+	if (hasExplicitCredential(dotenvVars)) return null;
+	const creds = readM2mCreds(dotenvVars);
+	if (!creds) return null;
+	const cached = readCachedM2mToken(creds.clientId);
+	if (cached) {
+		process.env.SEEKRIT_TOKEN = cached;
+		return cached;
+	}
+	const token = await mintAdminToken(process.env.SEEKRIT_API_URL ?? dotenvVars.SEEKRIT_API_URL ?? readGlobalConfig().apiUrl ?? "https://api.seekrit.dev", creds);
+	cacheM2mToken(creds.clientId, token);
+	process.env.SEEKRIT_TOKEN = token;
+	return token;
+}
+//#endregion
 //#region ../cli/src/dotenv.ts
 /**
 * Minimal `.env` parser: `KEY=VALUE`, `#` comments, an optional `export`
@@ -1413,10 +1516,78 @@ function errText(err) {
 		isError: true
 	};
 }
+/**
+* Short primer surfaced as the MCP server `instructions`. Most clients show
+* this to the model on connect, so it has to orient an agent that lands here
+* with zero context in a few lines.
+*/
+function serverInstructions() {
+	return [
+		"seekrit is a zero-knowledge secrets manager. This is the LOCAL CRYPTO plane —",
+		"it runs on this machine, next to your key, so it's the one server that can",
+		"actually read or write a secret VALUE (everything else can only see structure).",
+		"",
+		"Auth comes from SEEKRIT_TOKEN (a skt_… token), SEEKRIT_CLIENT_ID +",
+		"SEEKRIT_CLIENT_SECRET (machine credentials — an admin token is minted and",
+		"cached automatically on first use), or the config saved by `seekrit login`.",
+		"Decrypting under a user session (not a token) additionally needs",
+		"SEEKRIT_PASSPHRASE set in this server's env — there's no TTY to prompt on.",
+		"",
+		"Model: org → apps/groups → environments → secrets. Call `whoami` first, then",
+		"`get_started` for the recommended end-to-end recipe. Prefer `run_command` over",
+		"`get_secret reveal:true` — it injects secrets into a subprocess so plaintext",
+		"never enters your context or the transcript."
+	].join("\n");
+}
+/** The `get_started` tool body: the recommended first-project flow end to end. */
+function getStartedText() {
+	return [
+		"# Standing up a project with seekrit (agent, end to end)",
+		"",
+		"This server is the crypto plane — every step below runs locally, next to your",
+		"key, so secret values never leave this machine.",
+		"",
+		"## 1. Confirm identity",
+		"`whoami` — see who you're authenticated as and which orgs you can reach. If it",
+		"fails, check SEEKRIT_TOKEN / SEEKRIT_CLIENT_ID+SEEKRIT_CLIENT_SECRET / saved",
+		"login in this server's env.",
+		"",
+		"## 2. Provision structure",
+		"- `create_org` (user session only — a service token can't own one) if you",
+		"  don't have one yet, otherwise skip to the next step.",
+		"- `create_app` — an application to hold environments.",
+		"- `create_env` — generates the data key on this machine and grants it to you.",
+		"- `create_group` + `compose_group` (optional) — a reusable secret bag layered",
+		"  under one or more app environments.",
+		"",
+		"## 3. Store secrets",
+		"- `set_secret` — encrypts a value locally and stores the ciphertext.",
+		"- `list_secrets` — confirm names + versions (never returns values).",
+		"",
+		"## 4. Use secrets without exposing them",
+		"- `run_command -- <cmd>` — inject secrets into a subprocess; prefer this.",
+		"- `export_env` — materialize a `.env` file when a tool needs one on disk.",
+		"- `get_secret reveal:true` — only when the value itself is what's needed.",
+		"",
+		"## 5. Propagate access",
+		"- `create_token` bound to an app+env — a runtime credential for CI/another",
+		"  agent to decrypt with (pass `admin:true` instead for a provisioning token).",
+		"- `grant_env` — give another member or token access to an env's data key.",
+		"- `configure_project` — link a directory to an org/app (writes seekrit.json)",
+		"  so a bound token can infer its target without flags.",
+		"",
+		"## 6. Verify",
+		"`audit` — every write, grant, and revocation is recorded; read it back.",
+		"",
+		"Also available: `kms_*` (client-side managed encrypt/sign keys) and",
+		"`create_pg_lease`/`create_mysql_lease` (short-lived database credentials whose",
+		"password is generated here and never stored anywhere in plaintext)."
+	].join("\n");
+}
 /** Build the client context or throw a friendly, agent-readable error. */
 function getCtx() {
 	const ctx = tryBuildContext();
-	if (!ctx) throw new Error("no credentials — set SEEKRIT_TOKEN (a skt_… token) or SEEKRIT_DEV_USER in the MCP server env, or run `seekrit login` first");
+	if (!ctx) throw new Error("no credentials — set SEEKRIT_CLIENT_ID + SEEKRIT_CLIENT_SECRET (machine credentials from POST /signup) or SEEKRIT_TOKEN (a skt_… token) in the MCP server env, or run `seekrit login` first");
 	return ctx;
 }
 /**
@@ -1504,10 +1675,11 @@ async function resolveTargetEnv(ctx, o) {
 }
 async function runMcpServer(options = {}) {
 	setFailThrows(true);
+	await ensureM2mAdminToken();
 	const server = new McpServer({
 		name: "seekrit",
 		version: options.version ?? version$1
-	});
+	}, { instructions: serverInstructions() });
 	/** Register a tool whose handler returns data (serialized) or throws (→ isError). */
 	const tool = (name, description, shape, handler) => {
 		server.registerTool(name, {
@@ -1521,6 +1693,15 @@ async function runMcpServer(options = {}) {
 			}
 		}));
 	};
+	server.registerTool("get_started", {
+		description: "The recommended first-project recipe: provision structure, store secrets, and use them without exposing values. Call this before doing anything else.",
+		inputSchema: {},
+		annotations: {
+			title: "get_started",
+			readOnlyHint: true,
+			openWorldHint: false
+		}
+	}, async () => jsonText(getStartedText()));
 	tool("whoami", "Show the authenticated identity, its role, and accessible orgs.", {}, async () => {
 		const ctx = getCtx();
 		if (isTokenAuth(ctx) && ctx.auth.type === "bearer") {
@@ -2221,7 +2402,7 @@ async function runMcpServer(options = {}) {
 * `seekrit mcp`. tsdown bundles the shared server source in at build time, so the
 * published package is self-contained and needs no `@seekrit/cli` install.
 */
-runMcpServer({ version: "0.3.0" }).catch((err) => {
+runMcpServer({ version: "0.5.0" }).catch((err) => {
 	const message = err instanceof Error ? err.message : String(err);
 	process.stderr.write(`seekrit-mcp: fatal: ${message}\n`);
 	process.exit(1);

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@seekrit/mcp",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "npx-able MCP server for seekrit — let Claude Code and other MCP clients provision, manage, and inject end-to-end encrypted secrets.",
+  "mcpName": "dev.seekrit/mcp",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -22,7 +23,7 @@
   "devDependencies": {
     "@types/node": "^26.1.0",
     "tsdown": "^0.22.3",
-    "@seekrit/cli": "0.19.0"
+    "@seekrit/cli": "0.23.0"
   },
   "scripts": {
     "build": "tsdown",