@prajwolkc/stk 0.2.0 → 0.3.0

package/README.md

@@ -158,6 +158,53 @@ GITHUB_TOKEN=
 GITHUB_REPO=owner/repo   # or auto-detected from git remote
 ```
 
+## Claude Code / MCP Integration
+
+`stk` ships with a built-in MCP server so Claude Code can use your infrastructure as native tools.
+
+### Setup
+
+1. Install stk globally:
+
+```bash
+npm install -g @prajwolkc/stk
+```
+
+2. Add to your project's `.mcp.json` (create it in your project root):
+
+```json
+{
+  "mcpServers": {
+    "stk": {
+      "command": "stk-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+3. Restart Claude Code. Approve the stk MCP server when prompted.
+
+### What Claude can do
+
+| Tool | Description |
+|------|-------------|
+| `stk_health` | Check if all services are up before writing code |
+| `stk_status` | Full overview: git, services, deploys, issues |
+| `stk_doctor` | Diagnose misconfig and missing env vars |
+| `stk_logs` | Read production logs to understand bugs |
+| `stk_todo_list` | See what needs to be worked on |
+| `stk_todo_add` | Create GitHub issues |
+| `stk_deploy` | Push code and trigger deploys |
+| `stk_config` | Read the project's stack config |
+
+### Example prompts
+
+- *"Check if all my services are healthy"*
+- *"What errors are in my production logs?"*
+- *"What should I work on next?"*
+- *"Deploy this and verify it worked"*
+
 ## Development
 
 ```bash

package/dist/commands/health.js

@@ -3,6 +3,7 @@ import chalk from "chalk";
 import ora from "ora";
 import { loadConfig, enabledServices } from "../lib/config.js";
 import { getChecker, allCheckerNames, loadPluginCheckers } from "../services/registry.js";
+import { jsonOutput } from "../lib/output.js";
 const STATUS_ICON = {
     healthy: chalk.green("✓"),
     degraded: chalk.yellow("~"),
@@ -19,21 +20,25 @@ export const healthCommand = new Command("health")
     .description("Check the health of all connected services")
     .option("-v, --verbose", "Show latency and extra detail")
     .option("-a, --all", "Check all known services, not just configured ones")
+    .option("-j, --json", "Output as JSON")
     .action(async (opts) => {
     const config = loadConfig();
-    const spinner = ora("Checking services...").start();
     await loadPluginCheckers();
     const serviceList = opts.all
         ? allCheckerNames()
         : enabledServices(config);
     if (serviceList.length === 0) {
-        spinner.stop();
+        if (opts.json) {
+            jsonOutput({ services: [], summary: "no services configured" });
+            return;
+        }
         console.log();
         console.log(chalk.yellow("  No services configured."));
         console.log(chalk.dim(`  Run ${chalk.white("stk init")} to set up your project, or ${chalk.white("stk health --all")} to check everything.`));
         console.log();
         return;
     }
+    const spinner = opts.json ? null : ora("Checking services...").start();
     const checks = serviceList.map((name) => {
         const checker = getChecker(name);
         if (!checker) {
@@ -46,7 +51,26 @@ export const healthCommand = new Command("health")
         return checker();
     });
     const results = await Promise.all(checks);
-    spinner.stop();
+    spinner?.stop();
+    // JSON output
+    if (opts.json) {
+        const down = results.filter((r) => r.status === "down");
+        jsonOutput({
+            project: config.name,
+            services: results,
+            summary: {
+                healthy: results.filter((r) => r.status === "healthy").length,
+                down: down.length,
+                skipped: results.filter((r) => r.status === "skipped").length,
+                total: results.length,
+            },
+            ok: down.length === 0,
+        });
+        if (down.length > 0)
+            process.exitCode = 1;
+        return;
+    }
+    // Human output
     console.log();
     console.log(chalk.bold(`  ${config.name} — Service Health`));
     console.log(chalk.dim("  ─────────────────────────────────────────"));

package/dist/lib/output.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared output helper. When --json is passed, commands collect data
+ * and call jsonOutput() instead of console.log with chalk.
+ */
+export declare function setJsonMode(enabled: boolean): void;
+export declare function isJsonMode(): boolean;
+export declare function jsonOutput(data: unknown): void;

package/dist/lib/output.js

@@ -0,0 +1,14 @@
+/**
+ * Shared output helper. When --json is passed, commands collect data
+ * and call jsonOutput() instead of console.log with chalk.
+ */
+let jsonMode = false;
+export function setJsonMode(enabled) {
+    jsonMode = enabled;
+}
+export function isJsonMode() {
+    return jsonMode;
+}
+export function jsonOutput(data) {
+    console.log(JSON.stringify(data, null, 2));
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * stk MCP Server
+ *
+ * Exposes your entire infrastructure as tools for Claude Code.
+ * Claude can check health, read logs, deploy, manage issues, and diagnose
+ * problems — all through structured tool calls.
+ */
+export {};

package/dist/mcp/server.js

@@ -0,0 +1,1027 @@
+#!/usr/bin/env node
+/**
+ * stk MCP Server
+ *
+ * Exposes your entire infrastructure as tools for Claude Code.
+ * Claude can check health, read logs, deploy, manage issues, and diagnose
+ * problems — all through structured tool calls.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadConfig, enabledServices } from "../lib/config.js";
+import { getChecker, allCheckerNames, loadPluginCheckers } from "../services/registry.js";
+import { execSync } from "child_process";
+const server = new McpServer({
+    name: "stk",
+    version: "0.2.0",
+});
+// ──────────────────────────────────────────
+// Tool: stk_health
+// ──────────────────────────────────────────
+server.tool("stk_health", "Check the health of all configured infrastructure services (databases, deploy providers, storage, billing). Returns structured results with status, latency, and details for each service.", {
+    all: z.boolean().optional().describe("Check all known services, not just configured ones"),
+}, async ({ all }) => {
+    await loadPluginCheckers();
+    const config = loadConfig();
+    const serviceList = all ? allCheckerNames() : enabledServices(config);
+    const checks = serviceList.map(async (name) => {
+        const checker = getChecker(name);
+        if (!checker) {
+            return { name, status: "skipped", detail: `unknown service "${name}"` };
+        }
+        return checker();
+    });
+    const results = await Promise.all(checks);
+    const down = results.filter((r) => r.status === "down");
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    project: config.name,
+                    services: results,
+                    summary: {
+                        healthy: results.filter((r) => r.status === "healthy").length,
+                        down: down.length,
+                        skipped: results.filter((r) => r.status === "skipped").length,
+                        total: results.length,
+                    },
+                    ok: down.length === 0,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ──────────────────────────────────────────
+// Tool: stk_status
+// ──────────────────────────────────────────
+server.tool("stk_status", "Get a complete status overview: git state, service health, last deploy, and open issues — everything in one call.", {}, async () => {
+    const config = loadConfig();
+    const status = { project: config.name };
+    // Git
+    try {
+        status.git = {
+            branch: execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim(),
+            dirty: execSync("git status --porcelain", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim().split("\n").filter(Boolean).length,
+            lastCommit: execSync('git log -1 --format="%s"', { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim(),
+            lastCommitAge: execSync('git log -1 --format="%cr"', { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim(),
+        };
+    }
+    catch {
+        status.git = null;
+    }
+    // Services
+    await loadPluginCheckers();
+    const serviceList = enabledServices(config);
+    if (serviceList.length > 0) {
+        const checks = serviceList.map(async (name) => {
+            const checker = getChecker(name);
+            if (!checker)
+                return { name, status: "skipped" };
+            return checker();
+        });
+        const results = await Promise.all(checks);
+        status.services = {
+            healthy: results.filter((r) => r.status === "healthy").length,
+            down: results.filter((r) => r.status === "down").map((r) => r.name),
+            skipped: results.filter((r) => r.status === "skipped").length,
+            total: results.length,
+        };
+    }
+    else {
+        status.services = { total: 0, note: "no services configured" };
+    }
+    // Deploy
+    if (process.env.VERCEL_TOKEN) {
+        try {
+            const res = await fetch("https://api.vercel.com/v6/deployments?limit=1", {
+                headers: { Authorization: `Bearer ${process.env.VERCEL_TOKEN}` },
+            });
+            const data = (await res.json());
+            const dep = data.deployments?.[0];
+            if (dep) {
+                status.lastDeploy = {
+                    provider: "vercel",
+                    state: dep.readyState ?? dep.state,
+                    url: dep.url,
+                    created: dep.created,
+                };
+            }
+        }
+        catch { /* skip */ }
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify(status, null, 2) }],
+    };
+});
+// ──────────────────────────────────────────
+// Tool: stk_doctor
+// ──────────────────────────────────────────
+server.tool("stk_doctor", "Diagnose infrastructure configuration issues. Checks for missing env vars, mismatched config, invalid URLs, and suggests fixes with documentation links.", {}, async () => {
+    const config = loadConfig();
+    const enabled = enabledServices(config);
+    const issues = [];
+    const ENV_REQS = {
+        railway: { required: ["RAILWAY_API_TOKEN"], optional: ["RAILWAY_PROJECT_ID", "RAILWAY_ENVIRONMENT_ID", "RAILWAY_SERVICE_ID"] },
+        vercel: { required: ["VERCEL_TOKEN"], optional: ["VERCEL_PROJECT_ID"] },
+        fly: { required: ["FLY_API_TOKEN"], optional: ["FLY_APP_NAME"] },
+        render: { required: ["RENDER_API_KEY"], optional: [] },
+        aws: { required: ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"], optional: ["AWS_REGION"] },
+        database: { required: ["DATABASE_URL"], optional: [] },
+        mongodb: { required: ["MONGODB_URL"], optional: [] },
+        redis: { required: ["REDIS_URL"], optional: [] },
+        supabase: { required: ["SUPABASE_URL"], optional: ["SUPABASE_SERVICE_KEY"] },
+        r2: { required: ["CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_TOKEN"], optional: [] },
+        stripe: { required: ["STRIPE_SECRET_KEY"], optional: [] },
+    };
+    for (const svc of enabled) {
+        const reqs = ENV_REQS[svc];
+        if (!reqs)
+            continue;
+        const missingReq = reqs.required.filter((v) => !process.env[v]);
+        const missingOpt = reqs.optional.filter((v) => !process.env[v]);
+        if (missingReq.length > 0) {
+            issues.push({ level: "error", service: svc, message: `Missing required: ${missingReq.join(", ")}` });
+        }
+        else {
+            issues.push({ level: "ok", service: svc, message: "Configured correctly" });
+        }
+        if (missingOpt.length > 0) {
+            issues.push({ level: "warn", service: svc, message: `Missing optional: ${missingOpt.join(", ")}`, fix: "Needed for logs, env sync, deploy watching" });
+        }
+    }
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    project: config.name,
+                    issues,
+                    summary: {
+                        errors: issues.filter((i) => i.level === "error").length,
+                        warnings: issues.filter((i) => i.level === "warn").length,
+                        ok: issues.filter((i) => i.level === "ok").length,
+                    },
+                }, null, 2),
+            }],
+    };
+});
+// ──────────────────────────────────────────
+// Tool: stk_logs
+// ──────────────────────────────────────────
+server.tool("stk_logs", "Fetch recent production logs from Railway, Vercel, or other deploy providers. Useful for diagnosing errors and understanding runtime behavior.", {
+    provider: z.enum(["railway", "vercel"]).optional().describe("Which provider to fetch logs from (auto-detects if omitted)"),
+    lines: z.number().optional().default(30).describe("Number of log lines to fetch"),
+}, async ({ provider, lines }) => {
+    // Railway logs
+    if ((provider === "railway" || !provider) && process.env.RAILWAY_API_TOKEN) {
+        const token = process.env.RAILWAY_API_TOKEN;
+        const projectId = process.env.RAILWAY_PROJECT_ID;
+        const serviceId = process.env.RAILWAY_SERVICE_ID;
+        if (!projectId) {
+            return { content: [{ type: "text", text: JSON.stringify({ error: "RAILWAY_PROJECT_ID not set" }) }] };
+        }
+        // Get latest deployment
+        const serviceFilter = serviceId ? `serviceId: "${serviceId}",` : "";
+        const depRes = await fetch("https://backboard.railway.com/graphql/v2", {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+            body: JSON.stringify({
+                query: `{ deployments(first: 1, input: { projectId: "${projectId}", ${serviceFilter} }) { edges { node { id } } } }`,
+            }),
+        });
+        const depData = (await depRes.json());
+        const deploymentId = depData.data?.deployments?.edges?.[0]?.node?.id;
+        if (!deploymentId) {
+            return { content: [{ type: "text", text: JSON.stringify({ error: "No deployments found" }) }] };
+        }
+        const logRes = await fetch("https://backboard.railway.com/graphql/v2", {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+            body: JSON.stringify({
+                query: `{ deploymentLogs(deploymentId: "${deploymentId}", limit: ${lines}) { timestamp message severity } }`,
+            }),
+        });
+        const logData = (await logRes.json());
+        const logs = logData.data?.deploymentLogs ?? [];
+        return {
+            content: [{ type: "text", text: JSON.stringify({ provider: "railway", deploymentId, logs }, null, 2) }],
+        };
+    }
+    // Vercel logs
+    if ((provider === "vercel" || !provider) && process.env.VERCEL_TOKEN) {
+        const token = process.env.VERCEL_TOKEN;
+        const depRes = await fetch("https://api.vercel.com/v6/deployments?limit=1", {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        const depData = (await depRes.json());
+        const dep = depData.deployments?.[0];
+        if (!dep) {
+            return { content: [{ type: "text", text: JSON.stringify({ error: "No deployments found" }) }] };
+        }
+        const logRes = await fetch(`https://api.vercel.com/v2/deployments/${dep.uid}/events`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        const events = (await logRes.json());
+        const logs = Array.isArray(events)
+            ? events
+                .filter((e) => e.type === "stdout" || e.type === "stderr")
+                .slice(-lines)
+                .map((e) => ({
+                timestamp: new Date(e.created).toISOString(),
+                message: e.payload?.text ?? e.text ?? "",
+                severity: e.type === "stderr" ? "ERROR" : "INFO",
+            }))
+            : [];
+        return {
+            content: [{ type: "text", text: JSON.stringify({ provider: "vercel", deploymentUrl: dep.url, logs }, null, 2) }],
+        };
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify({ error: "No log provider available. Set RAILWAY_API_TOKEN or VERCEL_TOKEN." }) }],
+    };
+});
+// ──────────────────────────────────────────
+// Tool: stk_todo_list
+// ──────────────────────────────────────────
+server.tool("stk_todo_list", "List open GitHub issues for this project. Helps understand what needs to be worked on.", {
+    label: z.string().optional().describe("Filter by label"),
+    limit: z.number().optional().default(15).describe("Max issues to return"),
+}, async ({ label, limit }) => {
+    const config = loadConfig();
+    const repo = config.github?.repo ?? process.env.GITHUB_REPO ?? detectGitHubRepo();
+    const token = process.env.GITHUB_TOKEN;
+    if (!repo) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: "Could not detect GitHub repo. Set GITHUB_REPO or add github.repo to stk.config.json" }) }] };
+    }
+    const params = new URLSearchParams({
+        state: "open",
+        per_page: String(limit),
+        sort: "updated",
+        direction: "desc",
+    });
+    if (label)
+        params.set("labels", label);
+    const headers = { Accept: "application/vnd.github+json" };
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    const res = await fetch(`https://api.github.com/repos/${repo}/issues?${params}`, { headers });
+    if (!res.ok) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: `GitHub API: ${res.status}` }) }] };
+    }
+    const issues = (await res.json());
+    const filtered = issues
+        .filter((i) => !i.pull_request)
+        .map((i) => ({
+        number: i.number,
+        title: i.title,
+        labels: i.labels.map((l) => l.name),
+        assignee: i.assignee?.login ?? null,
+        created: i.created_at,
+        url: i.html_url,
+    }));
+    return {
+        content: [{ type: "text", text: JSON.stringify({ repo, issues: filtered }, null, 2) }],
+    };
+});
+// ──────────────────────────────────────────
+// Tool: stk_todo_add
+// ──────────────────────────────────────────
+server.tool("stk_todo_add", "Create a new GitHub issue for this project.", {
+    title: z.string().describe("Issue title"),
+    body: z.string().optional().describe("Issue body/description"),
+    labels: z.array(z.string()).optional().describe("Labels to add"),
+}, async ({ title, body, labels }) => {
+    const config = loadConfig();
+    const repo = config.github?.repo ?? process.env.GITHUB_REPO ?? detectGitHubRepo();
+    const token = process.env.GITHUB_TOKEN;
+    if (!repo || !token) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: "Need GITHUB_TOKEN and repo to create issues" }) }] };
+    }
+    const payload = { title };
+    if (body)
+        payload.body = body;
+    if (labels)
+        payload.labels = labels;
+    const res = await fetch(`https://api.github.com/repos/${repo}/issues`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/vnd.github+json",
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(payload),
+    });
+    if (!res.ok) {
+        const data = (await res.json());
+        return { content: [{ type: "text", text: JSON.stringify({ error: data.message ?? `HTTP ${res.status}` }) }] };
+    }
+    const issue = (await res.json());
+    return {
+        content: [{ type: "text", text: JSON.stringify({ created: true, number: issue.number, url: issue.html_url }, null, 2) }],
+    };
+});
+// ──────────────────────────────────────────
+// Tool: stk_deploy
+// ──────────────────────────────────────────
+server.tool("stk_deploy", "Push current branch to remote and trigger deploys. Use with caution — this pushes code to production.", {
+    skipPush: z.boolean().optional().describe("Skip git push, just report current deploy status"),
+}, async ({ skipPush }) => {
+    const config = loadConfig();
+    const branch = config.deploy?.branch ?? "main";
+    if (!skipPush) {
+        try {
+            const currentBranch = execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+            if (currentBranch !== branch) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: `On branch "${currentBranch}", not "${branch}". Switch branches first.` }) }],
+                };
+            }
+            execSync(`git push origin ${branch}`, { encoding: "utf-8", stdio: "pipe" });
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: `Git push failed: ${err.message}` }) }],
+            };
+        }
+    }
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    pushed: !skipPush,
+                    branch,
+                    providers: config.deploy?.providers ?? [],
+                    note: "Deploy triggered. Use stk_health to verify after a few minutes.",
+                }, null, 2),
+            }],
+    };
+});
+// ──────────────────────────────────────────
+// Tool: stk_config
+// ──────────────────────────────────────────
+server.tool("stk_config", "Read the current stk configuration for this project. Shows which services are enabled, deploy settings, and project name.", {}, async () => {
+    const config = loadConfig();
+    return {
+        content: [{ type: "text", text: JSON.stringify(config, null, 2) }],
+    };
+});
+// ──────────────────────────────────────────
+// Tool: stk_db
+// ──────────────────────────────────────────
+server.tool("stk_db", "Query your Supabase database directly. Run SELECT queries, check row counts, inspect table data — all from chat. Only read operations are allowed for safety.", {
+    query: z.string().optional().describe("SQL query to run (SELECT only for safety)"),
+    table: z.string().optional().describe("Shorthand: just provide a table name to SELECT * with a limit"),
+    limit: z.number().optional().describe("Max rows to return (default 20)"),
+}, async ({ query, table, limit: rawLimit }) => {
+    const limit = rawLimit ?? 20;
+    const url = process.env.SUPABASE_URL;
+    const key = process.env.SUPABASE_SERVICE_KEY;
+    if (!url || !key) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: "SUPABASE_URL or SUPABASE_SERVICE_KEY not set" }) }] };
+    }
+    // If table shorthand is used, build a simple query
+    let sql = query ?? "";
+    if (table && !query) {
+        sql = `SELECT * FROM ${table} ORDER BY created_at DESC LIMIT ${limit}`;
+    }
+    if (!sql && !table) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: "Provide either a 'query' or 'table' parameter" }) }] };
+    }
+    // Safety: only allow read operations
+    const normalized = sql.trim().toUpperCase();
+    if (!normalized.startsWith("SELECT") && !normalized.startsWith("WITH")) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: "Only SELECT/WITH queries are allowed for safety. Use Supabase dashboard for mutations." }) }] };
+    }
+    try {
+        const res = await fetch(`${url}/rest/v1/rpc/`, {
+            method: "POST",
+            headers: {
+                apikey: key,
+                Authorization: `Bearer ${key}`,
+                "Content-Type": "application/json",
+                Prefer: "return=representation",
+            },
+            body: JSON.stringify({}),
+        });
+        // Use PostgREST query instead of RPC for better compatibility
+        // Parse table name from SQL for simple queries
+        const tableMatch = sql.match(/FROM\s+["']?(\w+)["']?/i);
+        const targetTable = table ?? tableMatch?.[1];
+        if (targetTable) {
+            const restRes = await fetch(`${url}/rest/v1/${targetTable}?select=*&limit=${limit}`, {
+                headers: {
+                    apikey: key,
+                    Authorization: `Bearer ${key}`,
+                    "Content-Type": "application/json",
+                    Prefer: "count=exact",
+                },
+            });
+            if (!restRes.ok) {
+                const errText = await restRes.text();
+                return { content: [{ type: "text", text: JSON.stringify({ error: `Query failed: ${errText}` }) }] };
+            }
+            const contentRange = restRes.headers.get("content-range");
+            const totalCount = contentRange ? contentRange.split("/")[1] : "unknown";
+            const data = await restRes.json();
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            table: targetTable,
+                            totalRows: totalCount,
+                            returned: Array.isArray(data) ? data.length : 0,
+                            data,
+                        }, null, 2),
+                    }],
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify({ error: "Could not parse table name from query. Use the 'table' parameter instead." }) }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: err.message }) }] };
+    }
+});
+// ──────────────────────────────────────────
+// Tool: stk_analytics
+// ──────────────────────────────────────────
+server.tool("stk_analytics", "Get live app analytics: total users, posts, payments, revenue, and recent activity. Pulls data from Supabase and Stripe in one call.", {}, async () => {
+    const results = {};
+    // Supabase stats
+    const url = process.env.SUPABASE_URL;
+    const key = process.env.SUPABASE_SERVICE_KEY;
+    if (url && key) {
+        const headers = {
+            apikey: key,
+            Authorization: `Bearer ${key}`,
+            Prefer: "count=exact",
+        };
+        // Get table counts in parallel
+        const [postsRes, usersRes, paymentsRes] = await Promise.all([
+            fetch(`${url}/rest/v1/posts?select=id&limit=0`, { headers }).catch(() => null),
+            fetch(`${url}/rest/v1/users?select=id&limit=0`, { headers }).catch(() => null),
+            fetch(`${url}/rest/v1/payments?select=id&limit=0`, { headers }).catch(() => null),
+        ]);
+        const getCount = (res) => {
+            if (!res?.ok)
+                return null;
+            const range = res.headers.get("content-range");
+            return range ? parseInt(range.split("/")[1]) || 0 : null;
+        };
+        results.supabase = {
+            totalPosts: getCount(postsRes),
+            totalUsers: getCount(usersRes),
+            totalPayments: getCount(paymentsRes),
+        };
+        // Recent posts (last 24h)
+        const oneDayAgo = Math.floor(Date.now() / 1000) - 86400;
+        const recentRes = await fetch(`${url}/rest/v1/posts?select=id&timestamp=gte.${oneDayAgo}&limit=0`, { headers: { ...headers, Prefer: "count=exact" } }).catch(() => null);
+        results.supabase.postsLast24h = getCount(recentRes);
+        // Recent users with paid posts
+        const paidUsersRes = await fetch(`${url}/rest/v1/users?select=id&paid_posts_available=gt.0&limit=0`, { headers: { ...headers, Prefer: "count=exact" } }).catch(() => null);
+        results.supabase.usersWithPaidPosts = getCount(paidUsersRes);
+    }
+    // Stripe stats
+    const stripeKey = process.env.STRIPE_SECRET_KEY;
+    if (stripeKey) {
+        try {
+            // Balance
+            const balRes = await fetch("https://api.stripe.com/v1/balance", {
+                headers: { Authorization: `Bearer ${stripeKey}` },
+            });
+            const balData = await balRes.json();
+            // Recent charges
+            const chargesRes = await fetch("https://api.stripe.com/v1/charges?limit=100", {
+                headers: { Authorization: `Bearer ${stripeKey}` },
+            });
+            const chargesData = await chargesRes.json();
+            const charges = chargesData.data ?? [];
+            const totalRevenue = charges.reduce((sum, c) => sum + (c.status === "succeeded" ? c.amount : 0), 0);
+            results.stripe = {
+                balance: balData.available?.map((b) => `${(b.amount / 100).toFixed(2)} ${b.currency.toUpperCase()}`) ?? [],
+                totalCharges: charges.length,
+                successfulCharges: charges.filter((c) => c.status === "succeeded").length,
+                totalRevenue: `${(totalRevenue / 100).toFixed(2)}`,
+                mode: stripeKey.startsWith("sk_live") ? "live" : "test",
+            };
+        }
+        catch (err) {
+            results.stripe = { error: err.message };
+        }
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify({ analytics: results }, null, 2) }],
+    };
+});
+// ──────────────────────────────────────────
+// Tool: stk_alerts
+// ──────────────────────────────────────────
+server.tool("stk_alerts", "Scan for problems across your entire stack: failed deploys, down services, error logs, Stripe failures, and database issues. Returns actionable alerts.", {}, async () => {
+    await loadPluginCheckers();
+    const config = loadConfig();
+    const alerts = [];
+    // 1. Check all service health
+    const serviceList = enabledServices(config);
+    const checks = serviceList.map(async (name) => {
+        const checker = getChecker(name);
+        if (!checker)
+            return null;
+        return checker();
+    });
+    const results = (await Promise.all(checks)).filter(Boolean);
+    for (const r of results) {
+        if (r.status === "down") {
+            alerts.push({ level: "critical", source: r.name, message: `Service is DOWN: ${r.detail ?? "unreachable"}` });
+        }
+        else if (r.status === "degraded") {
+            alerts.push({ level: "warning", source: r.name, message: `Service degraded: ${r.detail ?? "slow response"}` });
+        }
+        else if (r.latency && r.latency > 3000) {
+            alerts.push({ level: "warning", source: r.name, message: `High latency: ${r.latency}ms` });
+        }
+    }
+    // 2. Check Vercel for failed deploys
+    if (process.env.VERCEL_TOKEN) {
+        try {
+            const res = await fetch("https://api.vercel.com/v6/deployments?limit=5", {
+                headers: { Authorization: `Bearer ${process.env.VERCEL_TOKEN}` },
+            });
+            const data = await res.json();
+            for (const dep of data.deployments ?? []) {
+                const state = dep.readyState ?? dep.state;
+                if (state === "ERROR" || state === "CANCELED") {
+                    alerts.push({ level: "critical", source: "Vercel", message: `Deploy ${state}: ${dep.url ?? dep.uid}` });
+                }
+            }
+        }
+        catch { /* skip */ }
+    }
+    // 3. Check Stripe for recent failures
+    if (process.env.STRIPE_SECRET_KEY) {
+        try {
+            const res = await fetch("https://api.stripe.com/v1/charges?limit=20", {
+                headers: { Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}` },
+            });
+            const data = await res.json();
+            const failed = (data.data ?? []).filter((c) => c.status === "failed");
+            if (failed.length > 0) {
+                alerts.push({ level: "warning", source: "Stripe", message: `${failed.length} failed charge(s) in recent transactions` });
+            }
+        }
+        catch { /* skip */ }
+    }
+    // 4. Check for error logs in Vercel
+    if (process.env.VERCEL_TOKEN) {
+        try {
+            const depRes = await fetch("https://api.vercel.com/v6/deployments?limit=1", {
+                headers: { Authorization: `Bearer ${process.env.VERCEL_TOKEN}` },
+            });
+            const depData = await depRes.json();
+            const dep = depData.deployments?.[0];
+            if (dep) {
+                const logRes = await fetch(`https://api.vercel.com/v2/deployments/${dep.uid}/events`, {
+                    headers: { Authorization: `Bearer ${process.env.VERCEL_TOKEN}` },
+                });
+                const events = await logRes.json();
+                if (Array.isArray(events)) {
+                    const errors = events.filter((e) => e.type === "stderr");
+                    if (errors.length > 5) {
+                        alerts.push({ level: "warning", source: "Vercel Logs", message: `${errors.length} stderr entries in latest deploy` });
+                    }
+                }
+            }
+        }
+        catch { /* skip */ }
+    }
+    if (alerts.length === 0) {
+        alerts.push({ level: "info", source: "stk", message: "All clear — no issues detected" });
+    }
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    project: config.name,
+                    alerts,
+                    summary: {
+                        critical: alerts.filter((a) => a.level === "critical").length,
+                        warnings: alerts.filter((a) => a.level === "warning").length,
+                        ok: alerts.every((a) => a.level === "info"),
+                    },
+                }, null, 2),
+            }],
+    };
+});
+// ──────────────────────────────────────────
+// Tool: stk_rollback
+// ──────────────────────────────────────────
+server.tool("stk_rollback", "Rollback to a previous Vercel deployment. Lists recent deploys and can promote an older one to production.", {
+    deployId: z.string().optional().describe("Deployment ID to rollback to. If omitted, lists recent deployments to choose from."),
+    confirm: z.boolean().optional().default(false).describe("Must be true to actually execute the rollback"),
+}, async ({ deployId, confirm }) => {
+    const token = process.env.VERCEL_TOKEN;
+    if (!token) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: "VERCEL_TOKEN not set" }) }] };
+    }
+    // List recent deployments
+    const depRes = await fetch("https://api.vercel.com/v6/deployments?limit=10", {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    const depData = await depRes.json();
+    const deployments = (depData.deployments ?? []).map((d) => ({
+        id: d.uid,
+        url: d.url,
+        state: d.readyState ?? d.state,
+        created: new Date(d.created).toISOString(),
+        target: d.target ?? "preview",
+    }));
+    if (!deployId) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        message: "Recent deployments — provide a deployId to rollback",
+                        deployments,
+                    }, null, 2),
+                }],
+        };
+    }
+    if (!confirm) {
+        const target = deployments.find((d) => d.id === deployId);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        message: "Rollback requires confirmation. Call again with confirm: true",
+                        target: target ?? deployId,
+                    }, null, 2),
+                }],
+        };
+    }
+    // Execute rollback by promoting the old deployment
+    try {
+        // Get the deployment's project
+        const detailRes = await fetch(`https://api.vercel.com/v13/deployments/${deployId}`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        const detail = await detailRes.json();
+        const projectId = detail.projectId;
+        if (!projectId) {
+            return { content: [{ type: "text", text: JSON.stringify({ error: "Could not determine project from deployment" }) }] };
+        }
+        // Create a new deployment based on the old one (redeploy)
+        const rollbackRes = await fetch(`https://api.vercel.com/v13/deployments`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                name: detail.name,
+                deploymentId: deployId,
+                target: "production",
+            }),
+        });
+        if (!rollbackRes.ok) {
+            const errData = await rollbackRes.json();
+            return { content: [{ type: "text", text: JSON.stringify({ error: errData.error?.message ?? `HTTP ${rollbackRes.status}` }) }] };
+        }
+        const rollbackData = await rollbackRes.json();
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        rolledBack: true,
+                        newDeploymentId: rollbackData.id,
+                        url: rollbackData.url,
+                        note: "Rollback triggered. Use stk_health to verify.",
+                    }, null, 2),
+                }],
+        };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: err.message }) }] };
+    }
+});
+// ──────────────────────────────────────────
+// Tool: stk_env_sync
+// ──────────────────────────────────────────
+server.tool("stk_env_sync", "Compare and sync environment variables between local .env and Vercel. Shows which vars are missing, extra, or mismatched.", {
+    action: z.enum(["diff", "pull", "push"]).optional().default("diff").describe("diff: compare local vs remote. pull: download remote to .env.pulled. push: upload local to Vercel."),
+    confirm: z.boolean().optional().default(false).describe("Required for push action"),
+}, async ({ action, confirm }) => {
+    const token = process.env.VERCEL_TOKEN;
+    const projectId = process.env.VERCEL_PROJECT_ID;
+    // Read local .env
+    let localVars = {};
+    try {
+        const { readFileSync } = await import("fs");
+        const envContent = readFileSync(".env", "utf-8");
+        for (const line of envContent.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const eqIdx = trimmed.indexOf("=");
+            if (eqIdx > 0) {
+                localVars[trimmed.slice(0, eqIdx)] = trimmed.slice(eqIdx + 1);
+            }
+        }
+    }
+    catch {
+        localVars = {};
+    }
+    if (!token) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        localVars: Object.keys(localVars),
+                        remote: "VERCEL_TOKEN not set — cannot fetch remote env vars",
+                    }, null, 2),
+                }],
+        };
+    }
+    // Fetch Vercel env vars
+    let remoteVars = {};
+    const envUrl = projectId
+        ? `https://api.vercel.com/v9/projects/${projectId}/env`
+        : null;
+    if (envUrl) {
+        try {
+            const res = await fetch(envUrl, {
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            const data = await res.json();
+            for (const env of data.envs ?? []) {
+                remoteVars[env.key] = env.value ?? "(encrypted)";
+            }
+        }
+        catch { /* skip */ }
+    }
+    const localKeys = new Set(Object.keys(localVars));
+    const remoteKeys = new Set(Object.keys(remoteVars));
+    const onlyLocal = [...localKeys].filter((k) => !remoteKeys.has(k));
+    const onlyRemote = [...remoteKeys].filter((k) => !localKeys.has(k));
+    const shared = [...localKeys].filter((k) => remoteKeys.has(k));
+    if (action === "diff" || !action) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        localCount: localKeys.size,
+                        remoteCount: remoteKeys.size,
+                        onlyInLocal: onlyLocal,
+                        onlyInRemote: onlyRemote,
+                        inBoth: shared.length,
+                        note: projectId ? undefined : "Set VERCEL_PROJECT_ID for remote env comparison",
+                    }, null, 2),
+                }],
+        };
+    }
+    if (action === "pull") {
+        const { writeFileSync } = await import("fs");
+        const lines = Object.entries(remoteVars).map(([k, v]) => `${k}=${v}`);
+        writeFileSync(".env.pulled", lines.join("\n") + "\n");
+        return {
+            content: [{ type: "text", text: JSON.stringify({ pulled: true, file: ".env.pulled", count: lines.length }) }],
+        };
+    }
+    if (action === "push") {
+        if (!confirm) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ message: "Push requires confirm: true. This will overwrite remote env vars.", varsToUpload: onlyLocal.length + shared.length }) }],
+            };
+        }
+        if (!projectId || !envUrl) {
+            return { content: [{ type: "text", text: JSON.stringify({ error: "VERCEL_PROJECT_ID required for push" }) }] };
+        }
+        let uploaded = 0;
+        for (const [key, value] of Object.entries(localVars)) {
+            await fetch(envUrl, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    key,
+                    value,
+                    type: "encrypted",
+                    target: ["production", "preview", "development"],
+                }),
+            });
+            uploaded++;
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify({ pushed: true, uploaded }) }],
+        };
+    }
+    return { content: [{ type: "text", text: JSON.stringify({ error: "Unknown action" }) }] };
+});
+// ──────────────────────────────────────────
+// Tool: stk_perf
+// ──────────────────────────────────────────
+server.tool("stk_perf", "Check performance across your stack: Supabase query latency, table sizes, Vercel deploy times, and API response times.", {
+    tables: z.array(z.string()).optional().describe("Specific Supabase tables to benchmark (defaults to all detected)"),
+}, async ({ tables }) => {
+    const perf = {};
+    // Supabase performance
+    const url = process.env.SUPABASE_URL;
+    const key = process.env.SUPABASE_SERVICE_KEY;
+    if (url && key) {
+        const headers = {
+            apikey: key,
+            Authorization: `Bearer ${key}`,
+            Prefer: "count=exact",
+        };
+        // Auto-detect tables or use provided list
+        const tablesToCheck = tables ?? ["posts", "users", "payments"];
+        const tableStats = [];
+        for (const table of tablesToCheck) {
+            const start = Date.now();
+            try {
+                const res = await fetch(`${url}/rest/v1/${table}?select=id&limit=0`, {
+                    headers,
+                });
+                const latency = Date.now() - start;
+                const range = res.headers.get("content-range");
+                const count = range ? parseInt(range.split("/")[1]) || 0 : null;
+                let status = "fast";
+                if (latency > 1000)
+                    status = "slow";
+                else if (latency > 500)
+                    status = "moderate";
+                tableStats.push({ table, rowCount: count, queryLatency: latency, status });
+            }
+            catch {
+                tableStats.push({ table, rowCount: null, queryLatency: Date.now() - start, status: "error" });
+            }
+        }
+        // API latency test
+        const apiStart = Date.now();
+        await fetch(`${url}/rest/v1/`, { headers }).catch(() => null);
+        const apiLatency = Date.now() - apiStart;
+        perf.supabase = {
+            apiLatency,
+            tables: tableStats,
+            recommendation: tableStats.some((t) => t.status === "slow")
+                ? "Some queries are slow. Consider adding database indexes."
+                : tableStats.some((t) => (t.rowCount ?? 0) > 10000)
+                    ? "Large tables detected. Ensure you have indexes on frequently queried columns."
+                    : "Performance looks good.",
+        };
+    }
+    // Vercel deploy performance
+    if (process.env.VERCEL_TOKEN) {
+        try {
+            const res = await fetch("https://api.vercel.com/v6/deployments?limit=5", {
+                headers: { Authorization: `Bearer ${process.env.VERCEL_TOKEN}` },
+            });
+            const data = await res.json();
+            const deploys = (data.deployments ?? []).map((d) => {
+                const buildDuration = d.buildingAt && d.ready
+                    ? Math.round((d.ready - d.buildingAt) / 1000)
+                    : null;
+                return {
+                    id: d.uid,
+                    state: d.readyState ?? d.state,
+                    buildDuration: buildDuration ? `${buildDuration}s` : "unknown",
+                    created: new Date(d.created).toISOString(),
+                };
+            });
+            perf.vercel = {
+                recentDeploys: deploys,
+                avgBuildTime: deploys.filter((d) => d.buildDuration !== "unknown").length > 0
+                    ? "see individual deploys"
+                    : "no build data available",
+            };
+        }
+        catch { /* skip */ }
+    }
+    // Stripe API latency
+    if (process.env.STRIPE_SECRET_KEY) {
+        const start = Date.now();
+        await fetch("https://api.stripe.com/v1/balance", {
+            headers: { Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}` },
+        }).catch(() => null);
+        perf.stripe = { apiLatency: Date.now() - start };
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify({ performance: perf }, null, 2) }],
+    };
+});
+// ──────────────────────────────────────────
+// Tool: stk_cost
+// ──────────────────────────────────────────
+server.tool("stk_cost", "Track costs across your stack: Stripe fees, Vercel usage, Supabase plan details. Get a unified view of what you're spending.", {}, async () => {
+    const costs = {};
+    // Stripe revenue & fees
+    if (process.env.STRIPE_SECRET_KEY) {
+        try {
+            const stripeKey = process.env.STRIPE_SECRET_KEY;
+            // Balance
+            const balRes = await fetch("https://api.stripe.com/v1/balance", {
+                headers: { Authorization: `Bearer ${stripeKey}` },
+            });
+            const balData = await balRes.json();
+            // Recent balance transactions for fee tracking
+            const txRes = await fetch("https://api.stripe.com/v1/balance_transactions?limit=100", {
+                headers: { Authorization: `Bearer ${stripeKey}` },
+            });
+            const txData = await txRes.json();
+            const transactions = txData.data ?? [];
+            const totalFees = transactions.reduce((sum, t) => sum + (t.fee || 0), 0);
+            const totalGross = transactions.reduce((sum, t) => sum + (t.amount > 0 ? t.amount : 0), 0);
+            const totalNet = transactions.reduce((sum, t) => sum + (t.net || 0), 0);
+            costs.stripe = {
+                mode: stripeKey.startsWith("sk_live") ? "live" : "test",
+                balance: balData.available?.map((b) => ({
+                    amount: (b.amount / 100).toFixed(2),
+                    currency: b.currency.toUpperCase(),
+                })) ?? [],
+                recentTransactions: transactions.length,
+                totalGross: (totalGross / 100).toFixed(2),
+                totalFees: (totalFees / 100).toFixed(2),
+                totalNet: (totalNet / 100).toFixed(2),
+                feePercentage: totalGross > 0 ? ((totalFees / totalGross) * 100).toFixed(1) + "%" : "N/A",
+            };
+        }
+        catch (err) {
+            costs.stripe = { error: err.message };
+        }
+    }
+    // Vercel usage
+    if (process.env.VERCEL_TOKEN) {
+        try {
+            // Get team/user info for billing context
+            const userRes = await fetch("https://api.vercel.com/v2/user", {
+                headers: { Authorization: `Bearer ${process.env.VERCEL_TOKEN}` },
+            });
+            const userData = await userRes.json();
+            // Count deployments
+            const depRes = await fetch("https://api.vercel.com/v6/deployments?limit=100", {
+                headers: { Authorization: `Bearer ${process.env.VERCEL_TOKEN}` },
+            });
+            const depData = await depRes.json();
+            const deployments = depData.deployments ?? [];
+            // Deployments this month
+            const monthStart = new Date();
+            monthStart.setDate(1);
+            monthStart.setHours(0, 0, 0, 0);
+            const thisMonth = deployments.filter((d) => new Date(d.created) >= monthStart);
+            costs.vercel = {
+                plan: userData.user?.billing?.plan ?? "unknown",
+                deploymentsThisMonth: thisMonth.length,
+                totalDeployments: deployments.length,
+                note: "Vercel free tier includes 100 deployments/day. Check vercel.com/dashboard for detailed billing.",
+            };
+        }
+        catch { /* skip */ }
+    }
+    // Supabase usage estimate
+    if (process.env.SUPABASE_URL && process.env.SUPABASE_SERVICE_KEY) {
+        const url = process.env.SUPABASE_URL;
+        const key = process.env.SUPABASE_SERVICE_KEY;
+        const headers = {
+            apikey: key,
+            Authorization: `Bearer ${key}`,
+            Prefer: "count=exact",
+        };
+        const tableCounts = {};
+        for (const table of ["posts", "users", "payments"]) {
+            try {
+                const res = await fetch(`${url}/rest/v1/${table}?select=id&limit=0`, { headers });
+                const range = res.headers.get("content-range");
+                tableCounts[table] = range ? parseInt(range.split("/")[1]) || 0 : null;
+            }
+            catch {
+                tableCounts[table] = null;
+            }
+        }
+        const totalRows = Object.values(tableCounts).reduce((s, v) => s + (v ?? 0), 0);
+        costs.supabase = {
+            tables: tableCounts,
+            totalRows,
+            note: "Supabase free tier: 500MB database, 1GB storage, 50k monthly active users. Check supabase.com/dashboard for detailed usage.",
+        };
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify({ costs }, null, 2) }],
+    };
+});
+// Helper
+function detectGitHubRepo() {
+    try {
+        const url = execSync("git remote get-url origin", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+        const match = url.match(/github\.com[:/]([^/]+\/[^/.]+)/);
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// Start
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prajwolkc/stk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "One CLI to deploy, monitor, and debug your entire stack. Health checks, deploy watching, env sync, logs, and GitHub issues — all from one command.",
   "type": "module",
   "license": "MIT",
@@ -26,7 +26,8 @@
     "developer-tools"
   ],
   "bin": {
-    "stk": "dist/index.js"
+    "stk": "dist/index.js",
+    "stk-mcp": "dist/mcp/server.js"
   },
   "files": [
     "dist",
@@ -45,9 +46,11 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
-    "ora": "^8.2.0"
+    "ora": "^8.2.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^22.13.0",