apphud-mcp 0.1.0

package/.env.example

@@ -0,0 +1,23 @@
+NODE_ENV=development
+
+# Required (zero-config auth)
+login=your@apphud.email
+password=your_apphud_password
+
+# Optional
+PORT=8080
+HTTP_ENABLED=false
+MCP_STDIO_ENABLED=true
+
+# Optional auth context defaults
+DEFAULT_TENANT_ID=tenant_default
+DEFAULT_ROLE=admin
+DEFAULT_USER_ID=local_user
+
+# Optional analytics overrides
+APPHUD_ANALYTICS_API_BASE_URL=https://api-legacy.apphud.com
+APPHUD_ANALYTICS_AUTH_HEADER=Cookie
+APPHUD_ANALYTICS_AUTH_PREFIX=
+APPHUD_ANALYTICS_LOGIN_PATH=/sessions
+APPHUD_ANALYTICS_LOGIN_EMAIL_SECRET_REF=login
+APPHUD_ANALYTICS_LOGIN_PASSWORD_SECRET_REF=password

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [Unreleased]
+
+### Added
+
+- Open source contributor documentation (`CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`)
+- GitHub issue and PR templates
+- CI workflow for typecheck, tests, and build
+
+## [0.1.0] - 2026-02-16
+
+### Added
+
+- MCP tools for Apphud customers, webhook ingest, events, metrics, and cohorts
+- HTTP webhook and admin endpoints
+- Postgres and in-memory storage backends
+- RBAC, PII masking, audit logs, and rate limiting
+- CLI packaging for `npx apphud-mcp`

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+## Our Standard
+
+We expect respectful, constructive, and professional collaboration.
+
+Examples of positive behavior:
+
+- giving actionable feedback
+- assuming good intent
+- discussing ideas without personal attacks
+
+Examples of unacceptable behavior:
+
+- harassment, insults, or discrimination
+- doxxing or sharing private information
+- repeated disruptive behavior in issues/PRs
+
+## Enforcement
+
+Project maintainers may remove comments, reject contributions, or restrict access for violations.
+
+## Reporting
+
+Report conduct issues through project maintainers with clear context and evidence.
+
+All reports are reviewed and handled with discretion.

package/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to apphud-mcp
+
+Thanks for contributing.
+
+## Ground Rules
+
+- Keep changes focused and reviewable.
+- Preserve tenant isolation and RBAC behavior.
+- Do not expose secrets or raw PII by default.
+- For behavior changes in tools, update docs and tests in the same PR.
+
+## Local Setup
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+## Branch and PR Flow
+
+1. Create a branch from `main`.
+2. Implement one logical change per PR.
+3. Include in PR description:
+   - problem statement
+   - implementation summary
+   - validation steps and results
+   - backward-compatibility notes
+
+## Required Checks Before PR
+
+```bash
+npm run typecheck
+npm test
+npm run build
+```
+
+If you changed packaging or CLI behavior, also run:
+
+```bash
+npm pack --dry-run
+```
+
+## Docs Requirements
+
+Update docs for any user-visible change:
+
+- `README.md` for setup or behavior changes
+- `docs/tools.md` for tool contract changes
+- `docs/implementation-instructions.md` for integration flow changes
+
+## Security Expectations
+
+- Never commit real API keys, webhook tokens, or DB credentials.
+- Keep secret handling reference-based (`secrets_ref`, `webhook_secret_ref`).
+- If you find a vulnerability, follow `SECURITY.md`.
+
+## Commit Message Style
+
+Use concise imperative messages, for example:
+
+- `Add postgres bootstrap validation`
+- `Document Cursor integration flow`
+
+## Questions
+
+Open a GitHub issue with:
+
+- expected behavior
+- actual behavior
+- reproduction steps
+- logs or payloads with sensitive data redacted

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aso.network
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# apphud-mcp <img src="./assets/apphud-mcp-logo.svg" alt="apphud + mcp" height="28" />
+
+Zero-config MCP server for Apphud Dashboard Analytics.
+
+## Quick Start
+
+1. Optional config file (`apphud-mcp.config.json`):
+
+```json
+{}
+```
+
+2. Cursor MCP config:
+
+```json
+{
+  "mcpServers": {
+    "apphud-mcp": {
+      "command": "node",
+      "args": [
+        "/Users/you/apphud-mcp/dist/src/cli.js",
+        "start",
+        "--config",
+        "/Users/you/apphud-mcp/apphud-mcp.config.json"
+      ],
+      "env": {
+        "login": "your@apphud.email",
+        "password": "your_apphud_password"
+      }
+    }
+  }
+}
+```
+
+3. Restart MCP server in Cursor.
+
+## What Changed
+
+- Default mode is analytics-only.
+- No Apphud app API keys required for basic usage.
+- No Postgres required.
+- No webhook/event-store setup required.
+- Apps are fetched directly from Apphud Dashboard API.
+
+## Basic Checks
+
+Ask MCP to call:
+
+1. `apphud.apps.list`
+2. `apphud.analytics.capabilities.get` (with `app_id` from step 1)
+3. `apphud.analytics.revenue.summary` (for a date range)
+
+## Available Tools
+
+- `apphud.apps.list`
+- `apphud.analytics.events.list`
+- `apphud.analytics.active_subscriptions`
+- `apphud.analytics.capabilities.get`
+- `apphud.analytics.metrics.list`
+- `apphud.analytics.metric.value`
+- `apphud.analytics.metric.timeseries`
+- `apphud.analytics.metric.breakdown`
+- `apphud.analytics.revenue.summary`
+- `apphud.analytics.subscriptions.summary`
+- `apphud.analytics.conversion.trial_to_paid`
+- `apphud.analytics.cohorts.retention`
+- `apphud.analytics.cohorts.ltv`
+- `apphud.analytics.query.raw`
+
+## Development
+
+```bash
+npm install
+npm run ci
+```

package/SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are provided for the latest minor release line.
+
+| Version | Supported |
+| --- | --- |
+| 0.1.x | Yes |
+| < 0.1.0 | No |
+
+## Reporting a Vulnerability
+
+Please do not open public issues for security vulnerabilities.
+
+Use one of these channels:
+
+1. GitHub private vulnerability reporting (preferred, if enabled).
+2. If unavailable, contact maintainers directly and include:
+   - affected version
+   - reproduction steps
+   - impact assessment
+   - suggested fix (optional)
+
+We aim to acknowledge reports within 3 business days.

package/SUPPORT.md

@@ -0,0 +1,26 @@
+# Support
+
+## Documentation
+
+Start with:
+
+- `README.md`
+- `docs/implementation-instructions.md`
+- `docs/tools.md`
+- `docs/webhook-setup.md`
+- `docs/runbook.md`
+
+## Asking for Help
+
+Open a GitHub issue and include:
+
+- MCP client (Cursor, Claude Desktop, etc.)
+- Node version
+- config snippet (with secrets removed)
+- full error output
+- steps to reproduce
+
+## Security Issues
+
+Do not post vulnerabilities publicly.
+Follow `SECURITY.md`.

package/assets/apphud-mcp-logo.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="300" height="32" viewBox="0 0 300 32" role="img" aria-label="apphud + mcp">
+  <g fill="#0b65d8">
+    <path d="M51.3813 9.68308H54.0644V22.9754H51.2337L50.9383 21.7938C49.7239 22.8441 48.288 23.3692 46.6306 23.3692C44.6285 23.3692 42.9629 22.7046 41.6337 21.3754C40.3208 20.0297 39.6644 18.3477 39.6644 16.3292C39.6644 14.3272 40.3208 12.6615 41.6337 11.3323C42.9629 10.0031 44.6285 9.33846 46.6306 9.33846C48.3208 9.33846 49.7731 9.88 50.9875 10.9631L51.3813 9.68308ZM44.3167 18.9385C45.006 19.6277 45.8675 19.9723 46.9013 19.9723C47.9516 19.9723 48.8213 19.6277 49.5106 18.9385C50.1998 18.2492 50.5444 17.3795 50.5444 16.3292C50.5444 15.279 50.1998 14.4092 49.5106 13.72C48.8213 13.0308 47.9598 12.6862 46.926 12.6862C46.2367 12.6862 45.6131 12.8503 45.0552 13.1785C44.5137 13.4903 44.087 13.9251 43.7752 14.4831C43.4634 15.0246 43.3075 15.64 43.3075 16.3292C43.3075 17.3795 43.6439 18.2492 44.3167 18.9385ZM64.7827 9.33846C66.7847 9.33846 68.4422 10.0031 69.755 11.3323C71.0842 12.6615 71.7488 14.3354 71.7488 16.3538C71.7488 18.3723 71.0842 20.0544 69.755 21.4C68.4258 22.7292 66.7683 23.3938 64.7827 23.3938C63.4206 23.3938 62.1981 23.0246 61.115 22.2862V27.8H57.5212V9.70769H59.9088L60.5242 10.9138C61.7058 9.86359 63.1253 9.33846 64.7827 9.33846ZM61.8781 18.9631C62.5673 19.6523 63.4288 19.9969 64.4627 19.9969C65.5129 19.9969 66.3827 19.6523 67.0719 18.9631C67.7612 18.2738 68.1058 17.4041 68.1058 16.3538C68.1058 15.6646 67.9499 15.041 67.6381 14.4831C67.3263 13.9251 66.8914 13.4903 66.3335 13.1785C65.7919 12.8667 65.1765 12.7108 64.4873 12.7108C63.7981 12.7108 63.1745 12.8667 62.6165 13.1785C62.0586 13.4903 61.6237 13.9251 61.3119 14.4831C61.0165 15.041 60.8688 15.6646 60.8688 16.3538C60.8688 17.4041 61.2053 18.2738 61.8781 18.9631ZM81.5615 9.33846C83.5636 9.33846 85.221 10.0031 86.5338 11.3323C87.8631 12.6615 88.5277 14.3354 88.5277 16.3538C88.5277 18.3723 87.8631 20.0544 86.5338 21.4C85.2046 22.7292 83.5472 23.3938 81.5615 23.3938C80.1995 23.3938 78.9769 23.0246 77.8938 22.2862V27.8H74.3V9.70769H76.6877L77.3031 10.9138C78.4846 9.86359 79.9041 9.33846 81.5615 9.33846ZM78.6569 18.9631C79.3462 19.6523 80.2077 19.9969 81.2415 19.9969C82.2918 19.9969 83.1615 19.6523 83.8508 18.9631C84.54 18.2738 84.8846 17.4041 84.8846 16.3538C84.8846 15.6646 84.7287 15.041 84.4169 14.4831C84.1051 13.9251 83.6703 13.4903 83.1123 13.1785C82.5708 12.8667 81.9554 12.7108 81.2662 12.7108C80.5769 12.7108 79.9533 12.8667 79.3954 13.1785C78.8374 13.4903 78.4026 13.9251 78.0908 14.4831C77.7954 15.041 77.6477 15.6646 77.6477 16.3538C77.6477 17.4041 77.9841 18.2738 78.6569 18.9631ZM98.685 9.38769C100.195 9.38769 101.384 9.8882 102.254 10.8892C103.124 11.8903 103.559 13.2359 103.559 14.9262V23H99.965V15.5169C99.965 14.5159 99.7763 13.7692 99.3988 13.2769C99.0378 12.7846 98.4553 12.5385 97.6512 12.5385C96.7486 12.5385 96.0265 12.8503 95.485 13.4738C94.9435 14.0974 94.6727 14.9426 94.6727 16.0092V23H91.0788V4.90769H94.6727V10.9385C95.7558 9.90461 97.0932 9.38769 98.685 9.38769ZM117.433 21.7446C116.3 22.8277 114.791 23.3692 112.903 23.3692C111.033 23.3692 109.523 22.8195 108.374 21.72C107.242 20.6205 106.676 19.1764 106.676 17.3877V9.70769H110.27V16.9692C110.27 17.921 110.499 18.6677 110.959 19.2092C111.435 19.7344 112.083 19.9969 112.903 19.9969C113.74 19.9969 114.389 19.7344 114.848 19.2092C115.324 18.6677 115.562 17.921 115.562 16.9692V9.70769H119.156V17.3877C119.156 19.1928 118.581 20.6451 117.433 21.7446ZM132.197 4.90769H135.791V23H133.133L132.714 21.8923C131.533 22.8933 130.146 23.3938 128.554 23.3938C127.225 23.3938 126.027 23.0903 124.96 22.4831C123.894 21.8759 123.057 21.039 122.45 19.9723C121.859 18.8892 121.563 17.6831 121.563 16.3538C121.563 15.0246 121.859 13.8267 122.45 12.76C123.057 11.6933 123.894 10.8564 124.96 10.2492C126.027 9.64205 127.225 9.33846 128.554 9.33846C129.9 9.33846 131.114 9.69949 132.197 10.4215V4.90769ZM126.24 18.9631C126.93 19.6523 127.791 19.9969 128.825 19.9969C129.875 19.9969 130.745 19.6523 131.434 18.9631C132.123 18.2574 132.468 17.3877 132.468 16.3538C132.468 15.3036 132.123 14.4338 131.434 13.7446C130.745 13.0554 129.875 12.7108 128.825 12.7108C127.791 12.7108 126.93 13.0554 126.24 13.7446C125.551 14.4338 125.207 15.3036 125.207 16.3538C125.207 17.4041 125.551 18.2738 126.24 18.9631Z"/>
+    <text x="148" y="22" font-family="Segoe UI, Helvetica, Arial, sans-serif" font-size="14" font-weight="600">+ mcp</text>
+  </g>
+</svg>

package/dist/src/app.js

@@ -0,0 +1,31 @@
+import { loadEnvConfig } from "./config/env.js";
+import { EnvSecretStore } from "./security/secretStore.js";
+import { RateLimiter } from "./security/rateLimiter.js";
+import { AppService } from "./services/appService.js";
+import { AnalyticsService } from "./services/analyticsService.js";
+import { ApphudClient } from "./services/apphudClient.js";
+import { AuditService } from "./services/auditService.js";
+import { ToolGuard } from "./services/toolGuard.js";
+export function createServiceContainer(options) {
+    const config = options?.config ?? loadEnvConfig();
+    const secretStore = options?.secretStore ?? new EnvSecretStore();
+    const appService = new AppService();
+    const apphudClient = new ApphudClient(config, secretStore);
+    const analyticsService = new AnalyticsService(appService, apphudClient);
+    const auditService = new AuditService(config);
+    const rateLimiter = new RateLimiter(config.rateLimitPerMinute);
+    const toolGuard = new ToolGuard(rateLimiter, auditService);
+    return {
+        config,
+        secretStore,
+        appService,
+        apphudClient,
+        analyticsService,
+        auditService,
+        toolGuard,
+        close: async () => Promise.resolve(),
+    };
+}
+export async function initializeServiceContainer(_container) {
+    return Promise.resolve();
+}

package/dist/src/cli.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { access, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildExampleSimpleConfig } from "./config/env.js";
+import { startFromConfig } from "./index.js";
+export function parseArgs(argv) {
+    const [rawCommand, ...rest] = argv;
+    const helpRequested = rawCommand === "--help" || rawCommand === "-h" || argv.includes("--help") || argv.includes("-h");
+    const command = helpRequested ? "help" : rawCommand === "init-config" || rawCommand === "help" ? rawCommand : "start";
+    const args = rawCommand === command ? rest : argv;
+    const readArgValue = (flag) => {
+        const index = args.indexOf(flag);
+        if (index < 0) {
+            return undefined;
+        }
+        return args[index + 1];
+    };
+    return {
+        command,
+        options: {
+            configPath: readArgValue("--config"),
+            configJson: readArgValue("--config-json"),
+            out: readArgValue("--out"),
+            force: args.includes("--force"),
+        },
+    };
+}
+function printHelp() {
+    console.error(`apphud-mcp
+
+Usage:
+  apphud-mcp start [--config <path>] [--config-json '<json>']
+  apphud-mcp init-config [--out <path>] [--force]
+`);
+}
+async function ensureWritable(filePath, force = false) {
+    if (force) {
+        return;
+    }
+    try {
+        await access(filePath, constants.F_OK);
+        throw new Error(`File already exists: ${filePath}. Use --force to overwrite.`);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith("File already exists")) {
+            throw error;
+        }
+    }
+}
+async function writeConfigTemplate(outPath, force = false) {
+    const absPath = path.resolve(outPath);
+    await ensureWritable(absPath, force);
+    const template = buildExampleSimpleConfig();
+    await writeFile(absPath, `${JSON.stringify(template, null, 2)}\n`, "utf8");
+    console.error(`Config template created: ${absPath}`);
+}
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    switch (parsed.command) {
+        case "help":
+            printHelp();
+            return;
+        case "init-config": {
+            const outPath = parsed.options.out ?? "./apphud-mcp.config.json";
+            await writeConfigTemplate(outPath, parsed.options.force ?? false);
+            return;
+        }
+        case "start":
+        default: {
+            const runtime = await startFromConfig(parsed.options);
+            process.on("SIGINT", () => {
+                runtime
+                    .shutdown()
+                    .then(() => process.exit(0))
+                    .catch(() => process.exit(1));
+            });
+            process.on("SIGTERM", () => {
+                runtime
+                    .shutdown()
+                    .then(() => process.exit(0))
+                    .catch(() => process.exit(1));
+            });
+        }
+    }
+}
+const isDirectRun = process.argv[1] ? path.resolve(process.argv[1]) === fileURLToPath(import.meta.url) : false;
+if (isDirectRun) {
+    main().catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    });
+}

package/dist/src/config/env.js

@@ -0,0 +1,249 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import "dotenv/config";
+const VALID_ROLES = new Set(["analyst", "support", "admin"]);
+const VALID_STORAGE_BACKENDS = new Set(["postgres", "memory"]);
+const VALID_APP_STATUSES = new Set(["active", "disabled"]);
+function parseNumber(value, fallback) {
+    if (value === undefined || value === null || value === "") {
+        return fallback;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+function parseBoolean(value, fallback) {
+    if (value === undefined || value === null || value === "") {
+        return fallback;
+    }
+    if (typeof value === "boolean") {
+        return value;
+    }
+    return ["1", "true", "yes", "on"].includes(value.toLowerCase());
+}
+function parseRole(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    if (!VALID_ROLES.has(value)) {
+        return undefined;
+    }
+    return value;
+}
+function readConfigFile(filePath) {
+    const absPath = path.resolve(filePath);
+    try {
+        const raw = readFileSync(absPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {};
+        }
+        throw error;
+    }
+}
+function parseConfigJson(json) {
+    return JSON.parse(json);
+}
+function parseStorageBackend(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    if (!VALID_STORAGE_BACKENDS.has(value)) {
+        return undefined;
+    }
+    return value;
+}
+function toSafeAppId(rawValue, fallbackIndex) {
+    const normalized = rawValue
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 64);
+    if (normalized.length > 0) {
+        return normalized;
+    }
+    return `app_${fallbackIndex + 1}`;
+}
+function parseBootstrapApps(value, options) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const apps = [];
+    const usedAppIds = new Set();
+    for (let index = 0; index < value.length; index += 1) {
+        const raw = value[index];
+        if (!raw || typeof raw !== "object") {
+            continue;
+        }
+        const candidate = raw;
+        if (typeof candidate.secrets_ref !== "string") {
+            continue;
+        }
+        const displayName = (typeof candidate.name === "string" && candidate.name.trim().length > 0
+            ? candidate.name
+            : undefined) ??
+            (typeof candidate.app_name === "string" && candidate.app_name.trim().length > 0
+                ? candidate.app_name
+                : undefined) ??
+            (typeof candidate.app_id === "string" && candidate.app_id.trim().length > 0 ? candidate.app_id : undefined);
+        if (!displayName) {
+            continue;
+        }
+        const tenantId = (typeof candidate.tenant_id === "string" && candidate.tenant_id.trim().length > 0
+            ? candidate.tenant_id
+            : undefined) ??
+            options.defaultTenantId ??
+            "tenant_default";
+        let appId = (typeof candidate.app_id === "string" && candidate.app_id.trim().length > 0
+            ? candidate.app_id.trim()
+            : undefined) ?? toSafeAppId(displayName, index);
+        while (usedAppIds.has(appId)) {
+            appId = `${appId}_${index + 1}`;
+        }
+        usedAppIds.add(appId);
+        const status = VALID_APP_STATUSES.has(candidate.status)
+            ? candidate.status
+            : "active";
+        apps.push({
+            appId,
+            tenantId,
+            name: displayName,
+            status,
+            secretsRef: candidate.secrets_ref,
+            webhookSecretRef: typeof candidate.webhook_secret_ref === "string" ? candidate.webhook_secret_ref : undefined,
+        });
+    }
+    return apps;
+}
+function parseEnvAppsJson(value, options) {
+    if (!value) {
+        return [];
+    }
+    try {
+        return parseBootstrapApps(JSON.parse(value), options);
+    }
+    catch {
+        return [];
+    }
+}
+function maybeReadSimpleConfig(options) {
+    if (options.configJson) {
+        return parseConfigJson(options.configJson);
+    }
+    if (options.configPath) {
+        return readConfigFile(options.configPath);
+    }
+    if (process.env.APPHUD_MCP_CONFIG) {
+        return parseConfigJson(process.env.APPHUD_MCP_CONFIG);
+    }
+    if (process.env.APPHUD_MCP_CONFIG_PATH) {
+        return readConfigFile(process.env.APPHUD_MCP_CONFIG_PATH);
+    }
+    return {};
+}
+export function loadEnvConfig(options = {}) {
+    const simpleConfig = maybeReadSimpleConfig(options);
+    const databaseUrlRaw = simpleConfig.database_url ?? process.env.DATABASE_URL;
+    const databaseUrl = typeof databaseUrlRaw === "string" && databaseUrlRaw.trim().length > 0 ? databaseUrlRaw : undefined;
+    const parsedStorageBackend = parseStorageBackend(simpleConfig.storage?.backend) ?? parseStorageBackend(process.env.STORAGE_BACKEND);
+    const storageBackend = parsedStorageBackend ?? (databaseUrl ? "postgres" : "memory");
+    if (storageBackend === "postgres" && !databaseUrl) {
+        throw new Error("DATABASE_URL is required for postgres storage backend. Set database_url or switch to storage.backend=memory");
+    }
+    const defaultTenantIdRaw = simpleConfig.defaults?.tenant_id ?? process.env.DEFAULT_TENANT_ID;
+    const defaultTenantId = typeof defaultTenantIdRaw === "string" && defaultTenantIdRaw.trim().length > 0
+        ? defaultTenantIdRaw
+        : "tenant_default";
+    const defaultRole = parseRole(simpleConfig.defaults?.role) ?? parseRole(process.env.DEFAULT_ROLE) ?? "admin";
+    const configApps = parseBootstrapApps(simpleConfig.apps, { defaultTenantId });
+    const envApps = parseEnvAppsJson(process.env.APPHUD_MCP_APPS_JSON, { defaultTenantId });
+    const bootstrapApps = configApps.length > 0 ? configApps : envApps;
+    const analyticsApiBaseUrlRaw = simpleConfig.apphud?.analytics_api_base_url ?? process.env.APPHUD_ANALYTICS_API_BASE_URL;
+    const analyticsApiBaseUrl = typeof analyticsApiBaseUrlRaw === "string" && analyticsApiBaseUrlRaw.trim().length > 0
+        ? analyticsApiBaseUrlRaw
+        : "https://api-legacy.apphud.com";
+    const analyticsAuthHeaderRaw = simpleConfig.apphud?.analytics_auth_header ?? process.env.APPHUD_ANALYTICS_AUTH_HEADER;
+    const analyticsAuthHeader = typeof analyticsAuthHeaderRaw === "string" && analyticsAuthHeaderRaw.trim().length > 0
+        ? analyticsAuthHeaderRaw
+        : "Cookie";
+    const analyticsAuthPrefixRaw = simpleConfig.apphud?.analytics_auth_prefix ?? process.env.APPHUD_ANALYTICS_AUTH_PREFIX;
+    const analyticsAuthPrefix = typeof analyticsAuthPrefixRaw === "string" ? analyticsAuthPrefixRaw : "";
+    const analyticsLoginEmailSecretRefRaw = simpleConfig.apphud?.analytics_login_email_secret_ref ?? process.env.APPHUD_ANALYTICS_LOGIN_EMAIL_SECRET_REF;
+    const analyticsLoginEmailSecretRef = typeof analyticsLoginEmailSecretRefRaw === "string" && analyticsLoginEmailSecretRefRaw.trim().length > 0
+        ? analyticsLoginEmailSecretRefRaw
+        : "login";
+    const analyticsLoginPasswordSecretRefRaw = simpleConfig.apphud?.analytics_login_password_secret_ref ?? process.env.APPHUD_ANALYTICS_LOGIN_PASSWORD_SECRET_REF;
+    const analyticsLoginPasswordSecretRef = typeof analyticsLoginPasswordSecretRefRaw === "string" && analyticsLoginPasswordSecretRefRaw.trim().length > 0
+        ? analyticsLoginPasswordSecretRefRaw
+        : "password";
+    return {
+        nodeEnv: simpleConfig.node_env ?? process.env.NODE_ENV ?? "development",
+        port: parseNumber(simpleConfig.transport?.port ?? process.env.PORT, 8080),
+        databaseUrl,
+        storageBackend,
+        bootstrapApps,
+        defaultTenantId,
+        defaultRole,
+        defaultUserId: typeof simpleConfig.defaults?.user_id === "string" && simpleConfig.defaults.user_id.trim().length > 0
+            ? simpleConfig.defaults.user_id
+            : typeof process.env.DEFAULT_USER_ID === "string" && process.env.DEFAULT_USER_ID.trim().length > 0
+                ? process.env.DEFAULT_USER_ID
+                : "local_user",
+        customerSnapshotTtlMinutes: parseNumber(simpleConfig.limits?.customer_snapshot_ttl_minutes ?? process.env.CUSTOMER_SNAPSHOT_TTL_MINUTES, 10),
+        rateLimitPerMinute: parseNumber(simpleConfig.limits?.rate_limit_per_minute ?? process.env.RATE_LIMIT_PER_MINUTE, 120),
+        auditHashSalt: simpleConfig.security?.audit_hash_salt ?? process.env.AUDIT_HASH_SALT ?? "dev-salt",
+        apphudCustomersApiBaseUrl: simpleConfig.apphud?.customers_api_base_url ??
+            process.env.APPHUD_CUSTOMERS_API_BASE_URL ??
+            "https://api.apphud.com/v1/customers",
+        apphudCustomersApiAuthHeader: simpleConfig.apphud?.auth_header ?? process.env.APPHUD_CUSTOMERS_API_AUTH_HEADER ?? "Authorization",
+        apphudCustomersApiAuthPrefix: simpleConfig.apphud?.auth_prefix ?? process.env.APPHUD_CUSTOMERS_API_AUTH_PREFIX ?? "Bearer ",
+        apphudAnalyticsApiBaseUrl: analyticsApiBaseUrl,
+        apphudAnalyticsAuthHeader: analyticsAuthHeader,
+        apphudAnalyticsAuthPrefix: analyticsAuthPrefix,
+        apphudAnalyticsAuthSecretRef: simpleConfig.apphud?.analytics_auth_secret_ref ??
+            process.env.APPHUD_ANALYTICS_AUTH_SECRET_REF,
+        apphudAnalyticsLoginPath: simpleConfig.apphud?.analytics_login_path ??
+            process.env.APPHUD_ANALYTICS_LOGIN_PATH ??
+            "/sessions",
+        apphudAnalyticsLoginEmailSecretRef: analyticsLoginEmailSecretRef,
+        apphudAnalyticsLoginPasswordSecretRef: analyticsLoginPasswordSecretRef,
+        apphudWebhookTokenHeader: simpleConfig.security?.webhook_token_header ?? process.env.APPHUD_WEBHOOK_TOKEN_HEADER ?? "x-apphud-token",
+        httpEnabled: parseBoolean(simpleConfig.transport?.http_enabled ?? process.env.HTTP_ENABLED, false),
+        mcpStdioEnabled: parseBoolean(simpleConfig.transport?.mcp_stdio_enabled ?? process.env.MCP_STDIO_ENABLED, true),
+    };
+}
+export function buildExampleSimpleConfig() {
+    return {
+        storage: {
+            backend: "memory",
+        },
+        defaults: {
+            tenant_id: "tenant_default",
+            role: "admin",
+            user_id: "local_user",
+        },
+        transport: {
+            port: 8080,
+            http_enabled: false,
+            mcp_stdio_enabled: true,
+        },
+        limits: {
+            customer_snapshot_ttl_minutes: 10,
+            rate_limit_per_minute: 120,
+        },
+        security: {
+            audit_hash_salt: "replace-me",
+            webhook_token_header: "x-apphud-token",
+        },
+        apphud: {
+            analytics_api_base_url: "https://api-legacy.apphud.com",
+            analytics_auth_header: "Cookie",
+            analytics_auth_prefix: "",
+            analytics_login_path: "/sessions",
+            analytics_login_email_secret_ref: "login",
+            analytics_login_password_secret_ref: "password",
+        },
+    };
+}