@prajwolkc/stk 0.1.1 → 0.2.1

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/dist/services/aws.js

@@ -1,4 +1,5 @@
 import { runCheck } from "./checker.js";
+import { createHmac, createHash } from "crypto";
 export async function checkAWS() {
     const accessKey = process.env.AWS_ACCESS_KEY_ID;
     const secretKey = process.env.AWS_SECRET_ACCESS_KEY;
@@ -11,22 +12,50 @@ export async function checkAWS() {
         };
     }
     return runCheck("AWS", async () => {
-        // Use STS GetCallerIdentity — the simplest AWS API call that works with any credentials
+        // AWS STS GetCallerIdentity with Signature V4
+        const service = "sts";
         const host = `sts.${region}.amazonaws.com`;
         const body = "Action=GetCallerIdentity&Version=2011-06-15";
         const now = new Date();
-        // AWS Signature V4 is complex — for a lightweight check we hit the endpoint
-        // and verify we get a response (even 403 means AWS is reachable)
+        const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");
+        const dateStamp = amzDate.slice(0, 8);
+        const bodyHash = sha256(body);
+        const canonicalHeaders = `content-type:application/x-www-form-urlencoded\nhost:${host}\nx-amz-date:${amzDate}\n`;
+        const signedHeaders = "content-type;host;x-amz-date";
+        const canonicalRequest = `POST\n/\n\n${canonicalHeaders}\n${signedHeaders}\n${bodyHash}`;
+        const credentialScope = `${dateStamp}/${region}/${service}/aws4_request`;
+        const stringToSign = `AWS4-HMAC-SHA256\n${amzDate}\n${credentialScope}\n${sha256(canonicalRequest)}`;
+        const signingKey = getSignatureKey(secretKey, dateStamp, region, service);
+        const signature = hmac(signingKey, stringToSign).toString("hex");
+        const authHeader = `AWS4-HMAC-SHA256 Credential=${accessKey}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
         const res = await fetch(`https://${host}/`, {
             method: "POST",
-            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                "X-Amz-Date": amzDate,
+                Authorization: authHeader,
+            },
             body,
         });
-        // 403 = creds not signed but AWS is reachable
-        // 200 = would need full SigV4, which we skip for simplicity
-        if (res.status === 403 || res.ok) {
-            return { detail: `${region} — endpoint reachable` };
-        }
-        throw new Error(`HTTP ${res.status}`);
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status} — invalid credentials`);
+        const text = await res.text();
+        const accountMatch = text.match(/<Account>(.+?)<\/Account>/);
+        const detail = accountMatch
+            ? `account ${accountMatch[1]} (${region})`
+            : `${region} — authenticated`;
+        return { detail };
     });
 }
+function sha256(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+function hmac(key, data) {
+    return createHmac("sha256", key).update(data).digest();
+}
+function getSignatureKey(key, date, region, service) {
+    const kDate = hmac(`AWS4${key}`, date);
+    const kRegion = hmac(kDate, region);
+    const kService = hmac(kRegion, service);
+    return hmac(kService, "aws4_request");
+}

package/dist/services/database.js

@@ -5,16 +5,35 @@ export async function checkDatabase() {
         return { name: "PostgreSQL", status: "skipped", detail: "DATABASE_URL not set" };
     }
     return runCheck("PostgreSQL", async () => {
-        // Parse host and port from DATABASE_URL to do a basic TCP connect check
-        // Full query check would require pg client — keeping deps minimal for now
         const parsed = new URL(url);
         const host = parsed.hostname;
         const port = parseInt(parsed.port || "5432", 10);
+        const dbName = parsed.pathname.replace("/", "") || "unknown";
         const { createConnection } = await import("net");
-        await new Promise((resolve, reject) => {
+        // Attempt a real PostgreSQL startup message handshake
+        const version = await new Promise((resolve, reject) => {
             const socket = createConnection({ host, port, timeout: 5000 }, () => {
-                socket.destroy();
-                resolve();
+                // Send PostgreSQL startup message (protocol v3.0)
+                const user = parsed.username || "postgres";
+                const params = `user\0${user}\0database\0${dbName}\0\0`;
+                const len = 4 + 4 + params.length;
+                const buf = Buffer.alloc(len);
+                buf.writeInt32BE(len, 0);
+                buf.writeInt32BE(196608, 4); // protocol 3.0
+                buf.write(params, 8);
+                socket.write(buf);
+                socket.once("data", (data) => {
+                    socket.destroy();
+                    const tag = String.fromCharCode(data[0]);
+                    // 'R' = AuthenticationRequest (server recognized us as postgres)
+                    // 'E' = Error (but server is responding — it's alive)
+                    if (tag === "R" || tag === "E") {
+                        resolve("protocol ok");
+                    }
+                    else {
+                        resolve("reachable");
+                    }
+                });
             });
             socket.on("error", reject);
             socket.on("timeout", () => {
@@ -22,6 +41,6 @@ export async function checkDatabase() {
                 reject(new Error("connection timeout"));
             });
         });
-        return { detail: `${host}:${port} reachable` };
+        return { detail: `${host}:${port}/${dbName} — ${version}` };
     });
 }

package/dist/services/registry.d.ts

@@ -1,4 +1,5 @@
 import type { CheckResult } from "./checker.js";
 export type HealthChecker = () => Promise<CheckResult>;
+export declare function loadPluginCheckers(): Promise<void>;
 export declare function getChecker(service: string): HealthChecker | null;
 export declare function allCheckerNames(): string[];

package/dist/services/registry.js

@@ -29,9 +29,23 @@ const registry = {
     r2: checkR2,
     stripe: checkStripe,
 };
+let pluginCheckers = {};
+let pluginsLoaded = false;
+export async function loadPluginCheckers() {
+    if (pluginsLoaded)
+        return;
+    try {
+        const { getPluginCheckers } = await import("../lib/plugins.js");
+        pluginCheckers = await getPluginCheckers();
+    }
+    catch {
+        // Plugins not available
+    }
+    pluginsLoaded = true;
+}
 export function getChecker(service) {
-    return registry[service] ?? null;
+    return registry[service] ?? pluginCheckers[service] ?? null;
 }
 export function allCheckerNames() {
-    return Object.keys(registry);
+    return [...Object.keys(registry), ...Object.keys(pluginCheckers)];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prajwolkc/stk",
-  "version": "0.1.1",
+  "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",
@@ -40,16 +41,21 @@
     "build": "tsc",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "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",
     "tsx": "^4.19.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0"
   }
 }