mrmainspring 0.1.0 → 0.1.2

package/README.md

@@ -8,6 +8,7 @@ boundaries, and x402 settlement-provider wiring.
 
 ```bash
 npm install -g mrmainspring
+mainspring setup cursor
 ```
 
 Run the stdio MCP server:
@@ -25,13 +26,14 @@ npm run mcp:stdio
 
 ## Environment
 
-The server loads `.env` from the current directory, backend directory, or repo
-root. Use `SIGIL_ENV_FILE` to point at a specific env file.
+No environment variables are required for local memory, Grimoire, audit, or
+payment preflight tools. `mainspring setup` creates the local config, data, and
+logs directories under the user's standard app config folder. Use
+`SIGIL_ENV_FILE` to point at a specific env file for advanced setups.
 
 Important package boundaries:
 
-- Keep `.env`, `.sigil/`, local keys, and generated demo data outside the npm
-  package.
+- Keep `.env`, local keys, and generated demo data outside the npm package.
 - Real Casper submission remains gated by `CASPER_ENABLE_REAL_SUBMISSION=true`.
 - Real x402 settlement remains gated by `X402_ENABLE_REAL_SETTLEMENT=true` and
   a configured `X402_SIGNER_URL`.

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+type InitResult = {
+    envFile: string;
+    dataDir: string;
+    logsDir: string;
+};
+export declare function runCliCommand(args: string[]): boolean;
+export declare function initializeLocalSetup(env?: NodeJS.ProcessEnv): InitResult;
+export declare function formatMcpConfig(): string;
+export {};

package/dist/cli.js

@@ -0,0 +1,147 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { loadConfig } from "./config.js";
+import { ensureGrimoireMasterKey, loadLocalEnvFile, resolveEnvPath } from "./env-file.js";
+import { getDefaultMainspringPaths } from "./paths.js";
+const VERSION = "0.1.1";
+const HELP = `Mr Mainspring MCP server
+
+Usage:
+  mainspring                  Start the MCP stdio server
+  mainspring --help           Show this help
+  mainspring --version        Show the installed version
+  mainspring init             Create local config, data, and logs directories
+  mainspring config           Print MCP client config JSON
+  mainspring setup [client]   Initialize local files and print MCP config
+  mainspring doctor           Check the local setup
+
+MCP client config:
+  {
+    "mcpServers": {
+      "mainspring": {
+        "command": "mainspring"
+      }
+    }
+  }
+
+Advanced users can still set SIGIL_ENV_FILE, SIGIL_DATA_DIR, Supabase, Casper,
+and x402 env vars. No env vars are required for local memory, Grimoire, audit,
+or payment preflight tools.
+`;
+export function runCliCommand(args) {
+    const [command, target] = args;
+    if (!command || command === "stdio" || command === "server" || command === "mcp") {
+        return false;
+    }
+    if (command === "--help" || command === "-h" || command === "help") {
+        process.stdout.write(HELP);
+        return true;
+    }
+    if (command === "--version" || command === "-v" || command === "version") {
+        process.stdout.write(`${VERSION}\n`);
+        return true;
+    }
+    if (command === "init") {
+        const result = initializeLocalSetup();
+        process.stdout.write(formatInitResult(result));
+        return true;
+    }
+    if (command === "config") {
+        process.stdout.write(`${formatMcpConfig()}\n`);
+        return true;
+    }
+    if (command === "setup") {
+        const result = initializeLocalSetup();
+        process.stdout.write(formatInitResult(result));
+        process.stdout.write(`\nPaste this into ${formatClientName(target)} MCP config:\n\n`);
+        process.stdout.write(`${formatMcpConfig()}\n`);
+        return true;
+    }
+    if (command === "doctor") {
+        process.stdout.write(formatDoctorReport());
+        return true;
+    }
+    process.stderr.write(`Unknown command: ${command}\n\n${HELP}`);
+    process.exitCode = 1;
+    return true;
+}
+export function initializeLocalSetup(env = process.env) {
+    const paths = getDefaultMainspringPaths(env);
+    const envFile = env.SIGIL_ENV_FILE?.trim() ? resolveEnvPath(env) : paths.envFile;
+    mkdirSync(paths.appDir, { recursive: true });
+    mkdirSync(paths.dataDir, { recursive: true });
+    mkdirSync(paths.logsDir, { recursive: true });
+    mkdirSync(dirname(envFile), { recursive: true });
+    if (!existsSync(envFile)) {
+        writeFileSync(envFile, [
+            "# Mr Mainspring local config",
+            "SIGIL_STORAGE_BACKEND=file",
+            `SIGIL_DATA_DIR=${quoteEnvValue(paths.dataDir)}`,
+            ""
+        ].join("\n"), "utf8");
+    }
+    const setupEnv = { ...env, SIGIL_ENV_FILE: envFile };
+    loadLocalEnvFile(setupEnv);
+    ensureGrimoireMasterKey(setupEnv, { announce: false });
+    return {
+        envFile,
+        dataDir: paths.dataDir,
+        logsDir: paths.logsDir
+    };
+}
+export function formatMcpConfig() {
+    return JSON.stringify({
+        mcpServers: {
+            mainspring: {
+                command: "mainspring"
+            }
+        }
+    }, null, 2);
+}
+function formatInitResult(result) {
+    return [
+        "Mr Mainspring local setup is ready.",
+        `Config: ${result.envFile}`,
+        `Data:   ${result.dataDir}`,
+        `Logs:   ${result.logsDir}`,
+        ""
+    ].join("\n");
+}
+function formatDoctorReport(env = process.env) {
+    const paths = getDefaultMainspringPaths(env);
+    const envFile = resolveEnvPath(env);
+    const envCopy = { ...env };
+    loadLocalEnvFile(envCopy);
+    const lines = ["Mr Mainspring doctor"];
+    const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+    lines.push(formatCheck(nodeMajor >= 20, `Node.js ${process.versions.node}`, "Node.js 20 or newer is required"));
+    lines.push(formatCheck(existsSync(envFile), `Config file: ${envFile}`, "Config file missing; run mainspring init"));
+    lines.push(formatCheck(existsSync(paths.dataDir), `Data dir: ${paths.dataDir}`, "Data dir missing; run mainspring init"));
+    lines.push(formatCheck(existsSync(paths.logsDir), `Logs dir: ${paths.logsDir}`, "Logs dir missing; run mainspring init"));
+    try {
+        const config = loadConfig(envCopy);
+        lines.push(`[ok] Storage backend: ${config.storage.backend}`);
+        lines.push(`[ok] Casper real submission: ${config.casper.submissionEnabled ? "enabled" : "disabled"}`);
+        lines.push(`[ok] x402 real settlement: ${config.x402.settlementEnabled ? "enabled" : "disabled"}`);
+    }
+    catch (error) {
+        lines.push(`[error] ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+    return `${lines.join("\n")}\n`;
+}
+function formatCheck(ok, success, failure) {
+    return ok ? `[ok] ${success}` : `[warn] ${failure}`;
+}
+function formatClientName(target) {
+    if (!target)
+        return "your";
+    if (target.toLowerCase() === "cursor")
+        return "Cursor";
+    if (target.toLowerCase() === "claude")
+        return "Claude Desktop";
+    return target;
+}
+function quoteEnvValue(value) {
+    return `"${value.replace(/"/g, "")}"`;
+}

package/dist/config.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { dirname, isAbsolute, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { getDefaultMainspringPaths } from "./paths.js";
 const CASPER_HASH_PATTERN = /^(hash-)?[a-f0-9]{64}$/i;
 const CASPER_PACKAGE_HASH_PATTERN = /^(hash-|package-)?[a-f0-9]{64}$/i;
 export function loadConfig(env = process.env) {
@@ -13,7 +14,7 @@ export function loadConfig(env = process.env) {
         memoryAnchorPackageHash: optionalEnv(env.MEMORY_ANCHOR_PACKAGE_HASH),
         submissionEnabled: parseBoolean(env.CASPER_ENABLE_REAL_SUBMISSION),
         clientBin: optionalEnv(env.CASPER_CLIENT_BIN) ?? "casper-client",
-        clientWslDistro: optionalEnv(env.CASPER_CLIENT_WSL_DISTRO),
+        clientWslDistro: process.platform === "win32" ? optionalEnv(env.CASPER_CLIENT_WSL_DISTRO) : null,
         anchorSubmissionMode: parseCasperAnchorSubmissionMode(env.CASPER_ANCHOR_SUBMISSION_MODE),
         gasPriceTolerance: optionalEnv(env.CASPER_GAS_PRICE_TOLERANCE) ?? "10",
         pricingMode: optionalEnv(env.CASPER_PRICING_MODE) ?? "classic",
@@ -37,10 +38,10 @@ export function loadConfig(env = process.env) {
     };
     validateX402Config(x402);
     return {
-        dataDir: resolve(optionalEnv(env.SIGIL_DATA_DIR) ?? ".sigil"),
+        dataDir: resolve(optionalEnv(env.SIGIL_DATA_DIR) ?? getDefaultMainspringPaths(env).dataDir),
         grimoireMasterKey: loadMasterKey(env.GRIMOIRE_MASTER_KEY),
         serverName: optionalEnv(env.SIGIL_MCP_NAME) ?? "mr-mainspring",
-        serverVersion: optionalEnv(env.SIGIL_MCP_VERSION) ?? "0.1.0",
+        serverVersion: optionalEnv(env.SIGIL_MCP_VERSION) ?? "0.1.1",
         storage: loadStorageConfig(env),
         casper,
         x402

package/dist/env-file.d.ts

@@ -1 +1,5 @@
 export declare function loadLocalEnvFile(env?: NodeJS.ProcessEnv): string | null;
+export declare function resolveEnvPath(env?: NodeJS.ProcessEnv): string;
+export declare function ensureGrimoireMasterKey(env?: NodeJS.ProcessEnv, options?: {
+    announce?: boolean;
+}): void;

package/dist/env-file.js

@@ -1,9 +1,11 @@
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { getDefaultMainspringPaths } from "./paths.js";
 export function loadLocalEnvFile(env = process.env) {
     const envPath = resolveEnvPath(env);
-    if (!envPath || !existsSync(envPath)) {
+    if (!existsSync(envPath)) {
         return null;
     }
     const raw = readFileSync(envPath, "utf8");
@@ -14,14 +16,20 @@ export function loadLocalEnvFile(env = process.env) {
     }
     return envPath;
 }
-function resolveEnvPath(env) {
+export function resolveEnvPath(env = process.env) {
     if (env.SIGIL_ENV_FILE?.trim()) {
-        return env.SIGIL_ENV_FILE.trim();
+        return resolve(env.SIGIL_ENV_FILE.trim());
     }
     const backendRoot = dirname(dirname(fileURLToPath(import.meta.url)));
     const repoRoot = dirname(backendRoot);
-    const candidates = [join(process.cwd(), ".env"), join(backendRoot, ".env"), join(repoRoot, ".env")];
-    return candidates.find((candidate) => existsSync(candidate)) ?? candidates.at(-1) ?? null;
+    const defaultEnvFile = getDefaultMainspringPaths(env).envFile;
+    const candidates = [
+        defaultEnvFile,
+        join(process.cwd(), ".env"),
+        join(backendRoot, ".env"),
+        join(repoRoot, ".env")
+    ];
+    return resolve(candidates.find((candidate) => existsSync(candidate)) ?? defaultEnvFile);
 }
 function parseEnv(raw) {
     const entries = [];
@@ -42,6 +50,19 @@ function parseEnv(raw) {
     }
     return entries;
 }
+export function ensureGrimoireMasterKey(env = process.env, options = {}) {
+    if (env.GRIMOIRE_MASTER_KEY)
+        return;
+    const key = randomBytes(32).toString("base64");
+    const targetPath = resolveEnvPath(env);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    const prefix = existsSync(targetPath) && readFileSync(targetPath, "utf8").trim() ? "\n" : "";
+    appendFileSync(targetPath, `${prefix}GRIMOIRE_MASTER_KEY=${key}\n`, "utf8");
+    env.GRIMOIRE_MASTER_KEY = key;
+    if (options.announce !== false) {
+        process.stderr.write(`[mr-mainspring] Generated GRIMOIRE_MASTER_KEY at ${targetPath}\n`);
+    }
+}
 function unquote(value) {
     if ((value.startsWith('"') && value.endsWith('"')) ||
         (value.startsWith("'") && value.endsWith("'"))) {

package/dist/index.js

@@ -1,10 +1,15 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { runCliCommand } from "./cli.js";
 import { loadConfig } from "./config.js";
-import { loadLocalEnvFile } from "./env-file.js";
+import { ensureGrimoireMasterKey, loadLocalEnvFile } from "./env-file.js";
 import { createSigilServer } from "./server.js";
 async function main() {
+    if (runCliCommand(process.argv.slice(2))) {
+        return;
+    }
     loadLocalEnvFile();
+    ensureGrimoireMasterKey();
     const config = loadConfig();
     const server = createSigilServer(config);
     const transport = new StdioServerTransport();

package/dist/paths.d.ts

@@ -0,0 +1,7 @@
+export type MainspringPaths = {
+    appDir: string;
+    envFile: string;
+    dataDir: string;
+    logsDir: string;
+};
+export declare function getDefaultMainspringPaths(env?: NodeJS.ProcessEnv, platformName?: NodeJS.Platform, homeDir?: string): MainspringPaths;

package/dist/paths.js

@@ -0,0 +1,20 @@
+import { homedir, platform } from "node:os";
+import { join, resolve } from "node:path";
+export function getDefaultMainspringPaths(env = process.env, platformName = platform(), homeDir = homedir()) {
+    const appDir = resolve(getDefaultAppDir(env, platformName, homeDir));
+    return {
+        appDir,
+        envFile: join(appDir, ".env"),
+        dataDir: join(appDir, "data"),
+        logsDir: join(appDir, "logs")
+    };
+}
+function getDefaultAppDir(env, platformName, homeDir) {
+    if (platformName === "win32") {
+        return join(env.APPDATA?.trim() || join(homeDir, "AppData", "Roaming"), "MrMainspring");
+    }
+    if (platformName === "darwin") {
+        return join(homeDir, "Library", "Application Support", "MrMainspring");
+    }
+    return join(env.XDG_CONFIG_HOME?.trim() || join(homeDir, ".config"), "mrmainspring");
+}

package/package.json

@@ -1,61 +1,62 @@
-{
+{
   "name": "mrmainspring",
-  "version": "0.1.0",
-  "description": "Mr Mainspring MCP backend with memory, Grimoire policies, audit, Casper anchoring, and x402 settlement boundaries.",
-  "license": "MIT",
-  "type": "module",
-  "bin": {
-    "mainspring": "dist/index.js"
-  },
-  "main": "./dist/server.js",
-  "types": "./dist/server.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/server.d.ts",
-      "import": "./dist/server.js"
-    },
-    "./mcp": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "LICENSE",
-    "README.md",
-    "package.json"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "demo:stdio": "npm run build && tsx scripts/demo-stdio.ts",
-    "demo:x402-http": "tsx scripts/x402-demo-http-server.ts",
-    "demo:x402-sidecars": "tsx scripts/x402-local-sidecars.ts",
-    "demo:x402-sidecars:smoke": "tsx scripts/x402-local-sidecars.ts --smoke",
-    "dev": "tsx src/index.ts",
-    "mcp:stdio": "node dist/index.js",
-    "prepack": "npm run build",
-    "smoke:x402-payment-fetch": "tsx scripts/x402-payment-fetch-smoke.ts",
-    "test": "vitest run",
-    "x402:facilitator": "tsx scripts/x402-facilitator-sidecar.ts",
-    "x402:resource": "tsx scripts/x402-local-sidecars.ts",
-    "x402:signer": "tsx scripts/x402-signer-sidecar.ts"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.13.0",
-    "zod": "^3.25.76"
-  },
-  "devDependencies": {
-    "@types/node": "^22.15.30",
-    "tsx": "^4.19.4",
-    "typescript": "^5.8.3",
-    "vitest": "^4.1.8"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  }
-}
+  "version": "0.1.2",
+  "description": "Mr Mainspring MCP backend with memory, Grimoire policies, audit, Casper anchoring, and x402 settlement boundaries.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "mainspring": "dist/index.js",
+    "mrmainspring": "dist/index.js"
+  },
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./mcp": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "LICENSE",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "demo:stdio": "npm run build && tsx scripts/demo-stdio.ts",
+    "demo:x402-http": "tsx scripts/x402-demo-http-server.ts",
+    "demo:x402-sidecars": "tsx scripts/x402-local-sidecars.ts",
+    "demo:x402-sidecars:smoke": "tsx scripts/x402-local-sidecars.ts --smoke",
+    "dev": "tsx src/index.ts",
+    "mcp:stdio": "node dist/index.js",
+    "prepack": "npm run build",
+    "smoke:x402-payment-fetch": "tsx scripts/x402-payment-fetch-smoke.ts",
+    "test": "vitest run",
+    "x402:facilitator": "tsx scripts/x402-facilitator-sidecar.ts",
+    "x402:resource": "tsx scripts/x402-local-sidecars.ts",
+    "x402:signer": "tsx scripts/x402-signer-sidecar.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.13.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.30",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}