@prajwolkc/stk 0.2.0 → 0.2.1

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,385 @@
+#!/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) }],
+    };
+});
+// 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.2.1",
   "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",