@seekrit/mcp 0.4.0 → 0.5.0

package/dist/index.js

@@ -664,7 +664,7 @@ function isServiceToken(value) {
 }
 //#endregion
 //#region ../cli/package.json
-var version$1 = "0.20.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");
@@ -726,13 +726,16 @@ 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();
@@ -992,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`);
@@ -1108,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
@@ -1138,7 +1147,8 @@ function tryBuildContext(dotenvVars = {}) {
 	return {
 		client: new SeekritClient({
 			baseUrl: apiUrl,
-			auth
+			auth,
+			client: CLI_CLIENT
 		}),
 		auth
 	};
@@ -1349,7 +1359,8 @@ async function mintAdminToken(apiUrl, creds) {
 			type: "m2m",
 			clientId: creds.clientId,
 			clientSecret: creds.clientSecret
-		}
+		},
+		client: `cli/${version$1}`
 	});
 	const { orgs } = await client.listOrgs();
 	const org = orgs[0];
@@ -1505,6 +1516,74 @@ 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();
@@ -1600,7 +1679,7 @@ async function runMcpServer(options = {}) {
 	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, {
@@ -1614,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") {
@@ -2314,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.4.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.4.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.20.0"
+    "@seekrit/cli": "0.23.0"
   },
   "scripts": {
     "build": "tsdown",