apphud-mcp 0.1.0

package/dist/src/domain/constants.js

@@ -0,0 +1,56 @@
+export const TOOL_PERMISSIONS = {
+    analyst: new Set([
+        "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",
+    ]),
+    support: new Set([
+        "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",
+    ]),
+    admin: new Set([
+        "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",
+    ]),
+};
+export const METRIC_REVENUE_EVENT_TYPES = [
+    "trial_converted",
+    "subscription_started",
+    "renewal",
+    "refund",
+];

package/dist/src/domain/models.js

@@ -0,0 +1 @@
+export {};

package/dist/src/errors/toolError.js

@@ -0,0 +1,40 @@
+export class ApphudMcpError extends Error {
+    code;
+    details;
+    actionHint;
+    statusCode;
+    constructor(code, message, options) {
+        super(message);
+        this.name = "ApphudMcpError";
+        this.code = code;
+        this.details = options?.details;
+        this.actionHint = options?.actionHint;
+        this.statusCode = options?.statusCode ?? 500;
+    }
+    toToolError() {
+        return {
+            code: this.code,
+            message: this.message,
+            details: this.details,
+            action_hint: this.actionHint,
+        };
+    }
+}
+export function isApphudMcpError(error) {
+    return error instanceof ApphudMcpError;
+}
+export function toToolError(error) {
+    if (isApphudMcpError(error)) {
+        return error.toToolError();
+    }
+    if (error instanceof Error) {
+        return {
+            code: "INTERNAL_ERROR",
+            message: error.message,
+        };
+    }
+    return {
+        code: "INTERNAL_ERROR",
+        message: "Unexpected error",
+    };
+}

package/dist/src/http/server.js

@@ -0,0 +1,24 @@
+import express from "express";
+import { toToolError } from "../errors/toolError.js";
+function sendError(res, error) {
+    res.status(500).json(toToolError(error));
+}
+export function createHttpServer(container) {
+    const app = express();
+    app.disable("x-powered-by");
+    app.get("/health", async (_req, res) => {
+        res.status(200).json({ status: "ok" });
+    });
+    app.get("/status", async (_req, res) => {
+        res.status(200).json({
+            status: "ok",
+            mode: "analytics_only",
+            node_env: container.config.nodeEnv,
+            timestamp: new Date().toISOString(),
+        });
+    });
+    app.use((error, _req, res, _next) => {
+        sendError(res, error);
+    });
+    return app;
+}

package/dist/src/index.js

@@ -0,0 +1,47 @@
+import { createServiceContainer, initializeServiceContainer } from "./app.js";
+import { loadEnvConfig } from "./config/env.js";
+import { createHttpServer } from "./http/server.js";
+import { startMcpStdioServer } from "./mcp/server.js";
+export async function startRuntime(container) {
+    await initializeServiceContainer(container);
+    let httpServer;
+    if (container.config.httpEnabled) {
+        const app = createHttpServer(container);
+        await new Promise((resolve) => {
+            httpServer = app.listen(container.config.port, () => {
+                console.error(`HTTP server listening on port ${container.config.port}`);
+                resolve();
+            });
+        });
+    }
+    if (container.config.mcpStdioEnabled) {
+        startMcpStdioServer(container)
+            .then(() => {
+            console.error("MCP stdio transport started");
+        })
+            .catch((error) => {
+            console.error("Failed to start MCP stdio server", error);
+            process.exitCode = 1;
+        });
+    }
+    async function shutdown() {
+        if (httpServer) {
+            await new Promise((resolve, reject) => {
+                httpServer?.close((error) => {
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+                    resolve();
+                });
+            });
+        }
+        await container.close();
+    }
+    return { shutdown };
+}
+export async function startFromConfig(options = {}) {
+    const config = loadEnvConfig(options);
+    const container = createServiceContainer({ config });
+    return startRuntime(container);
+}

package/dist/src/mcp/server.js

@@ -0,0 +1,435 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { toToolError } from "../errors/toolError.js";
+import { resolveAuth } from "../security/authResolver.js";
+const authSchema = z
+    .object({
+    tenant_id: z.string().min(1),
+    role: z.enum(["analyst", "support", "admin"]),
+    actor_id: z.string().min(1).optional(),
+})
+    .optional();
+const analyticsPlatformSchema = z.enum(["ios", "android", "web"]);
+const analyticsFiltersSchema = z
+    .record(z.union([z.string(), z.number(), z.boolean(), z.null()]))
+    .optional();
+const analyticsEventsFiltersSchema = z
+    .object({
+    user_id: z.string().min(1).optional(),
+    product_id: z.string().min(1).optional(),
+    event_type: z.string().min(1).optional(),
+    country: z.string().min(1).optional(),
+    platform: analyticsPlatformSchema.optional(),
+})
+    .optional();
+function jsonResult(payload, isError = false) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
+        isError: isError || undefined,
+    };
+}
+export function createMcpServer(container) {
+    const server = new McpServer({
+        name: "apphud-mcp",
+        version: "0.2.0",
+    });
+    server.tool("apphud.apps.list", "List apps available in authenticated Apphud dashboard account", {
+        tenant_id: z.string().optional(),
+        auth: authSchema,
+        include_raw: z.boolean().optional(),
+    }, async (input) => {
+        const auth = resolveAuth(input, container.config);
+        try {
+            const result = await container.toolGuard.run(auth, "apphud.apps.list", async () => container.analyticsService.appsList(auth, {
+                include_raw: input.include_raw,
+            }));
+            return jsonResult(result);
+        }
+        catch (error) {
+            return jsonResult(toToolError(error), true);
+        }
+    });
+    server.tool("apphud.analytics.events.list", "List raw subscription events from Apphud dashboard event feed", {
+        tenant_id: z.string().optional(),
+        auth: authSchema,
+        app_id: z.string().min(1).optional(),
+        apphud_app_id: z.string().min(1).optional(),
+        from: z.string().datetime(),
+        to: z.string().datetime(),
+        limit: z.number().int().min(1).max(500).optional(),
+        cursor: z.string().min(1).optional(),
+        filters: analyticsEventsFiltersSchema,
+        include_raw: z.boolean().optional(),
+    }, async (input) => {
+        const auth = resolveAuth(input, container.config);
+        try {
+            const result = await container.toolGuard.run(auth, "apphud.analytics.events.list", async () => container.analyticsService.eventsList(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                from: input.from,
+                to: input.to,
+                limit: input.limit,
+                cursor: input.cursor,
+                filters: input.filters,
+                include_raw: input.include_raw,
+            }), { appId: input.app_id ?? input.apphud_app_id });
+            return jsonResult(result);
+        }
+        catch (error) {
+            return jsonResult(toToolError(error), true);
+        }
+    });
+    server.tool("apphud.analytics.active_subscriptions", "Fetch active paid subscriptions directly from Apphud analytics endpoint", {
+        tenant_id: z.string().optional(),
+        auth: authSchema,
+        app_id: z.string().min(1).optional(),
+        apphud_app_id: z.string().min(1).optional(),
+        platform: analyticsPlatformSchema.optional(),
+        include_raw: z.boolean().optional(),
+    }, async (input) => {
+        const auth = resolveAuth(input, container.config);
+        try {
+            const result = await container.toolGuard.run(auth, "apphud.analytics.active_subscriptions", async () => container.analyticsService.activeSubscriptions(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                platform: input.platform,
+                include_raw: input.include_raw,
+            }), { appId: input.app_id ?? input.apphud_app_id });
+            return jsonResult(result);
+        }
+        catch (error) {
+            return jsonResult(toToolError(error), true);
+        }
+    });
+    server.tool("apphud.analytics.capabilities.get", "Get analytics capabilities and available metrics", {
+        tenant_id: z.string().optional(),
+        auth: authSchema,
+        app_id: z.string().min(1).optional(),
+        apphud_app_id: z.string().min(1).optional(),
+        include_raw: z.boolean().optional(),
+    }, async (input) => {
+        const auth = resolveAuth(input, container.config);
+        try {
+            const result = await container.toolGuard.run(auth, "apphud.analytics.capabilities.get", async () => container.analyticsService.capabilities(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                include_raw: input.include_raw,
+            }), { appId: input.app_id ?? input.apphud_app_id });
+            return jsonResult(result);
+        }
+        catch (error) {
+            return jsonResult(toToolError(error), true);
+        }
+    });
+    server.tool("apphud.analytics.metrics.list", "List analytics metric keys", {
+        tenant_id: z.string().optional(),
+        auth: authSchema,
+        app_id: z.string().min(1).optional(),
+        apphud_app_id: z.string().min(1).optional(),
+        include_raw: z.boolean().optional(),
+    }, async (input) => {
+        const auth = resolveAuth(input, container.config);
+        try {
+            const result = await container.toolGuard.run(auth, "apphud.analytics.metrics.list", async () => container.analyticsService.metricsList(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                include_raw: input.include_raw,
+            }), { appId: input.app_id ?? input.apphud_app_id });
+            return jsonResult(result);
+        }
+        catch (error) {
+            return jsonResult(toToolError(error), true);
+        }
+    });
+    server.tool("apphud.analytics.metric.value", "Get single metric value for period/snapshot", {
+        tenant_id: z.string().optional(),
+        auth: authSchema,
+        app_id: z.string().min(1).optional(),
+        apphud_app_id: z.string().min(1).optional(),
+        metric_key: z.string().min(1),
+        from: z.string().datetime().optional(),
+        to: z.string().datetime().optional(),
+        platform: analyticsPlatformSchema.optional(),
+        filters: analyticsFiltersSchema,
+        include_raw: z.boolean().optional(),
+    }, async (input) => {
+        const auth = resolveAuth(input, container.config);
+        try {
+            const result = await container.toolGuard.run(auth, "apphud.analytics.metric.value", async () => container.analyticsService.metricValue(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                metric_key: input.metric_key,
+                from: input.from,
+                to: input.to,
+                platform: input.platform,
+                filters: input.filters,
+                include_raw: input.include_raw,
+            }), { appId: input.app_id ?? input.apphud_app_id });
+            return jsonResult(result);
+        }
+        catch (error) {
+            return jsonResult(toToolError(error), true);
+        }
+    });
+    server.tool("apphud.analytics.metric.timeseries", "Get metric timeseries by date range", {
+        tenant_id: z.string().optional(),
+        auth: authSchema,
+        app_id: z.string().min(1).optional(),
+        apphud_app_id: z.string().min(1).optional(),
+        metric_key: z.string().min(1),
+        from: z.string().datetime(),
+        to: z.string().datetime(),
+        granularity: z.enum(["day", "week"]).optional(),
+        platform: analyticsPlatformSchema.optional(),
+        filters: analyticsFiltersSchema,
+        include_raw: z.boolean().optional(),
+    }, async (input) => {
+        const auth = resolveAuth(input, container.config);
+        try {
+            const result = await container.toolGuard.run(auth, "apphud.analytics.metric.timeseries", async () => container.analyticsService.metricTimeseries(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                metric_key: input.metric_key,
+                from: input.from,
+                to: input.to,
+                granularity: input.granularity,
+                platform: input.platform,
+                filters: input.filters,
+                include_raw: input.include_raw,
+            }), { appId: input.app_id ?? input.apphud_app_id });
+            return jsonResult(result);
+        }
+        catch (error) {
+            return jsonResult(toToolError(error), true);
+        }
+    });
+    server.tool("apphud.analytics.metric.breakdown", "Get metric breakdown by dimension", {
+        tenant_id: z.string().optional(),
+        auth: authSchema,
+        app_id: z.string().min(1).optional(),
+        apphud_app_id: z.string().min(1).optional(),
+        metric_key: z.string().min(1),
+        from: z.string().datetime(),
+        to: z.string().datetime(),
+        dimension: z.string().min(1),
+        granularity: z.enum(["day", "week"]).optional(),
+        platform: analyticsPlatformSchema.optional(),
+        filters: analyticsFiltersSchema,
+        limit: z.number().int().min(1).max(200).optional(),
+        include_raw: z.boolean().optional(),
+    }, async (input) => {
+        const auth = resolveAuth(input, container.config);
+        try {
+            const result = await container.toolGuard.run(auth, "apphud.analytics.metric.breakdown", async () => container.analyticsService.metricBreakdown(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                metric_key: input.metric_key,
+                from: input.from,
+                to: input.to,
+                dimension: input.dimension,
+                granularity: input.granularity,
+                platform: input.platform,
+                filters: input.filters,
+                limit: input.limit,
+                include_raw: input.include_raw,
+            }), { appId: input.app_id ?? input.apphud_app_id });
+            return jsonResult(result);
+        }
+        catch (error) {
+            return jsonResult(toToolError(error), true);
+        }
+    });
+    server.tool("apphud.analytics.revenue.summary", "Get revenue summary for date range", {
+        tenant_id: z.string().optional(),
+        auth: authSchema,
+        app_id: z.string().min(1).optional(),
+        apphud_app_id: z.string().min(1).optional(),
+        from: z.string().datetime(),
+        to: z.string().datetime(),
+        platform: analyticsPlatformSchema.optional(),
+        filters: analyticsFiltersSchema,
+        compare_prev_period: z.boolean().optional(),
+        include_raw: z.boolean().optional(),
+    }, async (input) => {
+        const auth = resolveAuth(input, container.config);
+        try {
+            const result = await container.toolGuard.run(auth, "apphud.analytics.revenue.summary", async () => container.analyticsService.revenueSummary(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                from: input.from,
+                to: input.to,
+                platform: input.platform,
+                filters: input.filters,
+                compare_prev_period: input.compare_prev_period,
+                include_raw: input.include_raw,
+            }), { appId: input.app_id ?? input.apphud_app_id });
+            return jsonResult(result);
+        }
+        catch (error) {
+            return jsonResult(toToolError(error), true);
+        }
+    });
+    server.tool("apphud.analytics.subscriptions.summary", "Get subscriptions KPI summary", {
+        tenant_id: z.string().optional(),
+        auth: authSchema,
+        app_id: z.string().min(1).optional(),
+        apphud_app_id: z.string().min(1).optional(),
+        from: z.string().datetime().optional(),
+        to: z.string().datetime().optional(),
+        platform: analyticsPlatformSchema.optional(),
+        filters: analyticsFiltersSchema,
+        include_raw: z.boolean().optional(),
+    }, async (input) => {
+        const auth = resolveAuth(input, container.config);
+        try {
+            const result = await container.toolGuard.run(auth, "apphud.analytics.subscriptions.summary", async () => container.analyticsService.subscriptionsSummary(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                from: input.from,
+                to: input.to,
+                platform: input.platform,
+                filters: input.filters,
+                include_raw: input.include_raw,
+            }), { appId: input.app_id ?? input.apphud_app_id });
+            return jsonResult(result);
+        }
+        catch (error) {
+            return jsonResult(toToolError(error), true);
+        }
+    });
+    server.tool("apphud.analytics.conversion.trial_to_paid", "Get trial to paid conversion summary", {
+        tenant_id: z.string().optional(),
+        auth: authSchema,
+        app_id: z.string().min(1).optional(),
+        apphud_app_id: z.string().min(1).optional(),
+        from: z.string().datetime(),
+        to: z.string().datetime(),
+        platform: analyticsPlatformSchema.optional(),
+        filters: analyticsFiltersSchema,
+        include_raw: z.boolean().optional(),
+    }, async (input) => {
+        const auth = resolveAuth(input, container.config);
+        try {
+            const result = await container.toolGuard.run(auth, "apphud.analytics.conversion.trial_to_paid", async () => container.analyticsService.conversionTrialToPaid(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                from: input.from,
+                to: input.to,
+                platform: input.platform,
+                filters: input.filters,
+                include_raw: input.include_raw,
+            }), { appId: input.app_id ?? input.apphud_app_id });
+            return jsonResult(result);
+        }
+        catch (error) {
+            return jsonResult(toToolError(error), true);
+        }
+    });
+    server.tool("apphud.analytics.cohorts.retention", "Get cohorts retention from analytics", {
+        tenant_id: z.string().optional(),
+        auth: authSchema,
+        app_id: z.string().min(1).optional(),
+        apphud_app_id: z.string().min(1).optional(),
+        from: z.string().datetime(),
+        to: z.string().datetime(),
+        granularity: z.enum(["day", "week"]).optional(),
+        max_periods: z.number().int().min(1).max(104).optional(),
+        platform: analyticsPlatformSchema.optional(),
+        filters: analyticsFiltersSchema,
+        include_raw: z.boolean().optional(),
+    }, async (input) => {
+        const auth = resolveAuth(input, container.config);
+        try {
+            const result = await container.toolGuard.run(auth, "apphud.analytics.cohorts.retention", async () => container.analyticsService.cohortsRetention(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                from: input.from,
+                to: input.to,
+                granularity: input.granularity,
+                max_periods: input.max_periods,
+                platform: input.platform,
+                filters: input.filters,
+                include_raw: input.include_raw,
+            }), { appId: input.app_id ?? input.apphud_app_id });
+            return jsonResult(result);
+        }
+        catch (error) {
+            return jsonResult(toToolError(error), true);
+        }
+    });
+    server.tool("apphud.analytics.cohorts.ltv", "Get cohorts cumulative LTV from analytics", {
+        tenant_id: z.string().optional(),
+        auth: authSchema,
+        app_id: z.string().min(1).optional(),
+        apphud_app_id: z.string().min(1).optional(),
+        from: z.string().datetime(),
+        to: z.string().datetime(),
+        granularity: z.enum(["day", "week"]).optional(),
+        max_periods: z.number().int().min(1).max(104).optional(),
+        platform: analyticsPlatformSchema.optional(),
+        filters: analyticsFiltersSchema,
+        include_raw: z.boolean().optional(),
+    }, async (input) => {
+        const auth = resolveAuth(input, container.config);
+        try {
+            const result = await container.toolGuard.run(auth, "apphud.analytics.cohorts.ltv", async () => container.analyticsService.cohortsLtv(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                from: input.from,
+                to: input.to,
+                granularity: input.granularity,
+                max_periods: input.max_periods,
+                platform: input.platform,
+                filters: input.filters,
+                include_raw: input.include_raw,
+            }), { appId: input.app_id ?? input.apphud_app_id });
+            return jsonResult(result);
+        }
+        catch (error) {
+            return jsonResult(toToolError(error), true);
+        }
+    });
+    server.tool("apphud.analytics.query.raw", "Low-level analytics query tool (value/timeseries/breakdown/raw)", {
+        tenant_id: z.string().optional(),
+        auth: authSchema,
+        app_id: z.string().min(1).optional(),
+        apphud_app_id: z.string().min(1).optional(),
+        query: z.object({
+            shape: z.enum(["value", "timeseries", "breakdown", "raw"]),
+            metric_key: z.string().optional(),
+            from: z.string().datetime().optional(),
+            to: z.string().datetime().optional(),
+            granularity: z.enum(["day", "week"]).optional(),
+            dimension: z.string().optional(),
+            endpoint_path: z.string().optional(),
+            method: z.enum(["GET", "POST"]).optional(),
+            query_params: z.record(z.string()).optional(),
+            body: z.record(z.unknown()).optional(),
+            filters: analyticsFiltersSchema,
+            platform: analyticsPlatformSchema.optional(),
+            limit: z.number().int().min(1).max(500).optional(),
+        }),
+        include_raw: z.boolean().optional(),
+    }, async (input) => {
+        const auth = resolveAuth(input, container.config);
+        try {
+            const result = await container.toolGuard.run(auth, "apphud.analytics.query.raw", async () => container.analyticsService.queryRaw(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                query: input.query,
+                include_raw: input.include_raw,
+            }), { appId: input.app_id ?? input.apphud_app_id });
+            return jsonResult(result);
+        }
+        catch (error) {
+            return jsonResult(toToolError(error), true);
+        }
+    });
+    return server;
+}
+export async function startMcpStdioServer(container) {
+    const server = createMcpServer(container);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/src/security/authResolver.js

@@ -0,0 +1,43 @@
+import { ApphudMcpError } from "../errors/toolError.js";
+const VALID_ROLES = ["analyst", "support", "admin"];
+export function resolveAuth(input, config) {
+    const tenantId = input?.auth?.tenant_id ?? input?.tenant_id ?? config.defaultTenantId;
+    const role = input?.auth?.role ?? config.defaultRole;
+    const actorId = input?.auth?.actor_id ?? config.defaultUserId ?? "unknown_actor";
+    if (!tenantId || !role) {
+        throw new ApphudMcpError("UNAUTHORIZED", "Auth context is required", {
+            statusCode: 401,
+            actionHint: "Pass auth.tenant_id and auth.role in tool input or configure DEFAULT_TENANT_ID/DEFAULT_ROLE",
+        });
+    }
+    if (!VALID_ROLES.includes(role)) {
+        throw new ApphudMcpError("UNAUTHORIZED", `Invalid role: ${role}`, {
+            statusCode: 401,
+        });
+    }
+    return {
+        tenantId,
+        role,
+        actorId,
+    };
+}
+export function resolveHttpAuth(headers) {
+    const tenantId = headerValue(headers["x-tenant-id"]);
+    const role = headerValue(headers["x-role"]);
+    const actorId = headerValue(headers["x-user-id"]) ?? "http_actor";
+    if (!tenantId || !role) {
+        throw new ApphudMcpError("UNAUTHORIZED", "x-tenant-id and x-role headers are required", {
+            statusCode: 401,
+        });
+    }
+    if (!VALID_ROLES.includes(role)) {
+        throw new ApphudMcpError("UNAUTHORIZED", `Invalid role: ${role}`, { statusCode: 401 });
+    }
+    return { tenantId, role, actorId };
+}
+function headerValue(value) {
+    if (!value) {
+        return undefined;
+    }
+    return Array.isArray(value) ? value[0] : value;
+}

package/dist/src/security/rateLimiter.js

@@ -0,0 +1,22 @@
+import { ApphudMcpError } from "../errors/toolError.js";
+export class RateLimiter {
+    maxPerMinute;
+    buckets = new Map();
+    constructor(maxPerMinute) {
+        this.maxPerMinute = maxPerMinute;
+    }
+    assertLimit(key) {
+        const now = Date.now();
+        const minuteAgo = now - 60_000;
+        const bucket = this.buckets.get(key) ?? { hits: [] };
+        bucket.hits = bucket.hits.filter((timestamp) => timestamp >= minuteAgo);
+        if (bucket.hits.length >= this.maxPerMinute) {
+            throw new ApphudMcpError("RATE_LIMITED", "Rate limit exceeded", {
+                statusCode: 429,
+                details: { key, max_per_minute: this.maxPerMinute },
+            });
+        }
+        bucket.hits.push(now);
+        this.buckets.set(key, bucket);
+    }
+}

package/dist/src/security/rbac.js

@@ -0,0 +1,11 @@
+import { TOOL_PERMISSIONS } from "../domain/constants.js";
+import { ApphudMcpError } from "../errors/toolError.js";
+export function assertToolAccess(auth, toolName) {
+    const allowed = TOOL_PERMISSIONS[auth.role];
+    if (!allowed.has(toolName)) {
+        throw new ApphudMcpError("FORBIDDEN", `Role ${auth.role} cannot call ${toolName}`, {
+            statusCode: 403,
+            details: { role: auth.role, tool: toolName },
+        });
+    }
+}