mrmainspring 0.1.0 → 0.1.1

package/README.md

@@ -1,47 +1,49 @@
-# Mr Mainspring
-
-Installable MCP backend for local agent demos. It exposes memory, Grimoire
-policy/secret storage, payment intent tools, audit trail tools, Casper anchoring
-boundaries, and x402 settlement-provider wiring.
-
-## Install
-
+# Mr Mainspring
+
+Installable MCP backend for local agent demos. It exposes memory, Grimoire
+policy/secret storage, payment intent tools, audit trail tools, Casper anchoring
+boundaries, and x402 settlement-provider wiring.
+
+## Install
+
 ```bash
 npm install -g mrmainspring
+mainspring setup cursor
 ```
 
 Run the stdio MCP server:
-
-```bash
-mainspring
-```
-
-For local development from this repository:
-
-```bash
-npm run build
-npm run mcp:stdio
-```
-
+
+```bash
+mainspring
+```
+
+For local development from this repository:
+
+```bash
+npm run build
+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.
-
-Important package boundaries:
-
-- Keep `.env`, `.sigil/`, 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`.
-- The signer private key must live outside the repository workspace.
-
-## Library Entry
-
-```ts
-import { createSigilServer } from "mrmainspring";
-```
-
-The CLI entry is also exported as `mrmainspring/mcp`, but importing it starts
-the stdio server; use the package bin for normal MCP client configuration.
+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`, 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`.
+- The signer private key must live outside the repository workspace.
+
+## Library Entry
+
+```ts
+import { createSigilServer } from "mrmainspring";
+```
+
+The CLI entry is also exported as `mrmainspring/mcp`, but importing it starts
+the stdio server; use the package bin for normal MCP client configuration.

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) {
@@ -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,6 +1,6 @@
 {
-  "name": "mrmainspring",
-  "version": "0.1.0",
+  "name": "mrmainspring",
+  "version": "0.1.1",
   "description": "Mr Mainspring MCP backend with memory, Grimoire policies, audit, Casper anchoring, and x402 settlement boundaries.",
   "license": "MIT",
   "type": "module",