@prajwolkc/stk 0.6.1 → 0.7.1

package/dist/mcp/tools/brain.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerBrainTools(server: McpServer): void;

package/dist/mcp/tools/brain.js

@@ -0,0 +1,557 @@
+import { z } from "zod";
+import { loadConfig, enabledServices } from "../../lib/config.js";
+import { getLocalBrainClient, ingestProject, loadBrainStore, saveBrainStore, syncBrain, pushToCloud, pullFromCloud, brainCheck, brainDiagnose, reviewDiff } from "../../services/brain.js";
+import { execSync } from "child_process";
+function getBrainClient() {
+    return getLocalBrainClient();
+}
+export function registerBrainTools(server) {
+    // ──────────────────────────────────────────
+    // Tool: stk_brain_search
+    // ──────────────────────────────────────────
+    server.tool("stk_brain_search", "Search the knowledge base for SaaS patterns, best practices, and architecture examples from top open-source projects (LangChain, Ollama, Transformers, llama.cpp, vLLM, AutoGen, OpenAI Cookbook). Use this when you need to know how successful projects solve specific problems.", {
+        query: z.string().describe("What to search for (e.g., 'authentication', 'real-time updates', 'payment integration')"),
+        category: z.string().optional().describe("Filter: architecture, auth, payments, database, api, deployment, testing, performance, security, ml, realtime, general"),
+    }, async ({ query, category }) => {
+        const brain = getBrainClient();
+        // Try ilike search on content and title
+        const words = query.split(" ").filter(w => w.length > 2);
+        const searchWord = words[0] ?? query;
+        const params = {
+            or: `(title.ilike.%${searchWord}%,content.ilike.%${searchWord}%)`,
+            limit: "10",
+            order: "source",
+        };
+        if (category)
+            params["category"] = `eq.${category}`;
+        const { data, ok } = await brain.query("knowledge", params);
+        if (!ok)
+            return { content: [{ type: "text", text: JSON.stringify({ error: "Query failed", data }) }] };
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        query,
+                        results: (data ?? []).map((r) => ({ source: r.source, category: r.category, title: r.title, content: r.content, tags: r.tags })),
+                        total: data?.length ?? 0,
+                    }, null, 2),
+                }],
+        };
+    });
+    // ──────────────────────────────────────────
+    // Tool: stk_brain_patterns
+    // ──────────────────────────────────────────
+    server.tool("stk_brain_patterns", "Get best practice patterns for a specific feature. Returns how top projects implement auth, payments, real-time, caching, APIs, etc.", {
+        feature: z.string().describe("The feature or pattern (e.g., 'authentication', 'webhooks', 'caching', 'model serving', 'fine-tuning')"),
+    }, async ({ feature }) => {
+        const brain = getBrainClient();
+        const { data, ok } = await brain.query("knowledge", {
+            or: `(title.ilike.%${feature}%,content.ilike.%${feature}%)`,
+            limit: "15",
+            order: "source",
+        });
+        if (!ok)
+            return { content: [{ type: "text", text: JSON.stringify({ error: "Query failed" }) }] };
+        // Group by source
+        const grouped = {};
+        for (const item of data ?? []) {
+            if (!grouped[item.source])
+                grouped[item.source] = [];
+            grouped[item.source].push({ title: item.title, category: item.category, content: item.content });
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        feature,
+                        patterns: grouped,
+                        totalSources: Object.keys(grouped).length,
+                        totalPatterns: data?.length ?? 0,
+                    }, null, 2),
+                }],
+        };
+    });
+    // ──────────────────────────────────────────
+    // Tool: stk_brain_stack
+    // ──────────────────────────────────────────
+    server.tool("stk_brain_stack", "Get recommendations specific to YOUR stack (Supabase + Vercel + Stripe + Node.js). Filters knowledge for patterns matching your technology choices.", {
+        question: z.string().describe("What you want to build or solve (e.g., 'add user auth', 'implement webhooks', 'optimize queries')"),
+    }, async ({ question }) => {
+        const brain = getBrainClient();
+        const words = question.split(" ").filter(w => w.length > 3);
+        const searchWord = words[0] ?? question;
+        const { data, ok } = await brain.query("knowledge", {
+            or: `(content.ilike.%${searchWord}%,title.ilike.%${searchWord}%)`,
+            limit: "10",
+        });
+        if (!ok)
+            return { content: [{ type: "text", text: JSON.stringify({ error: "Query failed" }) }] };
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        question,
+                        stack: ["Supabase", "Vercel", "Stripe", "Node.js/Express"],
+                        recommendations: (data ?? []).map((r) => ({ source: r.source, title: r.title, content: r.content, relevance: r.category })),
+                        total: data?.length ?? 0,
+                    }, null, 2),
+                }],
+        };
+    });
+    // ──────────────────────────────────────────
+    // Tool: stk_brain_learn
+    // ──────────────────────────────────────────
+    server.tool("stk_brain_learn", "Save new knowledge to the brain. Use this to remember patterns, solutions, or learnings for future reference across all projects.", {
+        title: z.string().describe("Short title"),
+        content: z.string().describe("The knowledge — pattern, solution, or best practice"),
+        source: z.string().optional().describe("Where this came from (e.g., 'project:worldchat', 'github:vercel/next.js')"),
+        category: z.string().optional().describe("Category: architecture, auth, payments, database, api, deployment, testing, performance, security, ml, general"),
+        tags: z.array(z.string()).optional().describe("Tags for searchability"),
+    }, async ({ title, content, source, category, tags }) => {
+        const brain = getBrainClient();
+        const { data, ok } = await brain.insert("knowledge", {
+            title,
+            content,
+            source: source ?? "manual",
+            category: category ?? "general",
+            tags: tags ?? [],
+            created_at: new Date().toISOString(),
+        });
+        if (!ok)
+            return { content: [{ type: "text", text: JSON.stringify({ error: "Insert failed", data }) }] };
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ learned: true, title, message: "Knowledge saved. I can recall this in future conversations." }, null, 2),
+                }],
+        };
+    });
+    // ──────────────────────────────────────────
+    // Tool: stk_brain_stats
+    // ──────────────────────────────────────────
+    server.tool("stk_brain_stats", "Check what the brain knows — total knowledge entries, categories, sources, and coverage.", {}, async () => {
+        const brain = getBrainClient();
+        const { data, count } = await brain.query("knowledge", { select: "category,source", limit: "1000" });
+        const categories = {};
+        const sources = {};
+        for (const row of data ?? []) {
+            categories[row.category] = (categories[row.category] || 0) + 1;
+            sources[row.source] = (sources[row.source] || 0) + 1;
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        totalKnowledge: count ?? data?.length ?? 0,
+                        categories,
+                        sources,
+                        topSources: Object.entries(sources)
+                            .sort(([, a], [, b]) => b - a)
+                            .slice(0, 10)
+                            .map(([name, count]) => ({ name, count })),
+                    }, null, 2),
+                }],
+        };
+    });
+    // ──────────────────────────────────────────
+    // Tool: stk_brain_check (PROACTIVE — call before writing code)
+    // ──────────────────────────────────────────
+    server.tool("stk_brain_check", "PROACTIVE: Call this BEFORE implementing a feature or making changes. Searches the brain for known gotchas, past bugs, and patterns relevant to what you're about to build. Returns warnings that can prevent mistakes. Use this whenever you start a non-trivial coding task.", {
+        task: z.string().describe("What you're about to implement (e.g., 'add email verification', 'update user model', 'add webhook endpoint')"),
+    }, async ({ task }) => {
+        const results = brainCheck(task);
+        if (results.length === 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            task,
+                            warnings: [],
+                            message: "No known gotchas found. Proceed carefully.",
+                        }, null, 2),
+                    }],
+            };
+        }
+        const warnings = results.slice(0, 8).map(r => ({
+            title: r.entry.title,
+            warning: r.entry.content,
+            relevance: r.score,
+            matchedTerms: r.matchedTerms,
+            source: r.entry.source,
+            category: r.entry.category,
+        }));
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        task,
+                        warnings,
+                        totalMatches: results.length,
+                        message: `Found ${results.length} relevant entries. Review warnings before coding.`,
+                    }, null, 2),
+                }],
+        };
+    });
+    // ──────────────────────────────────────────
+    // Tool: stk_brain_diagnose (REACTIVE — call when you hit an error)
+    // ──────────────────────────────────────────
+    server.tool("stk_brain_diagnose", "REACTIVE: Call this when you encounter an error or bug. Searches the brain for matching patterns from past issues and returns known solutions. Use this before debugging from scratch — the answer may already be in the brain.", {
+        error: z.string().describe("The error message, bug description, or unexpected behavior you're seeing"),
+    }, async ({ error }) => {
+        const results = brainDiagnose(error);
+        if (results.length === 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error,
+                            solutions: [],
+                            message: "No matching patterns found in the brain. This is a new issue — debug it, fix it, then use stk_brain_learn to save the solution.",
+                        }, null, 2),
+                    }],
+            };
+        }
+        const solutions = results.slice(0, 5).map(r => ({
+            title: r.entry.title,
+            solution: r.entry.content,
+            relevance: r.score,
+            matchedTerms: r.matchedTerms,
+            source: r.entry.source,
+        }));
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        error,
+                        solutions,
+                        totalMatches: results.length,
+                        message: `Found ${results.length} matching patterns. Apply the most relevant solution.`,
+                    }, null, 2),
+                }],
+        };
+    });
+    // ──────────────────────────────────────────
+    // Tool: stk_brain_ingest
+    // ──────────────────────────────────────────
+    server.tool("stk_brain_ingest", "Scan the current project and ingest architecture knowledge into the local brain (~/.stk/brain.json). Automatically reads CLAUDE.md, package.json, Prisma schema, Dockerfile, CI config, and route files. Run this when setting up stk in a new project or after major changes.", {
+        force: z.boolean().optional().default(false).describe("Re-ingest even if already ingested"),
+    }, async ({ force }) => {
+        const store = loadBrainStore();
+        const { projectName, entries, filesScanned } = ingestProject(process.cwd());
+        if (store.projects[projectName] && !force) {
+            const existing = store.projects[projectName];
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            alreadyIngested: true,
+                            projectName,
+                            entries: existing.entries.length,
+                            ingestedAt: existing.ingestedAt,
+                            message: "Already ingested. Use force: true to re-ingest.",
+                        }, null, 2),
+                    }],
+            };
+        }
+        if (entries.length === 0) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ error: "No knowledge extracted. Make sure you're in a project directory with recognizable files." }),
+                    }],
+            };
+        }
+        store.projects[projectName] = {
+            ingestedAt: new Date().toISOString(),
+            projectPath: process.cwd(),
+            entries,
+        };
+        saveBrainStore(store);
+        const categories = {};
+        for (const e of entries) {
+            categories[e.category] = (categories[e.category] || 0) + 1;
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        ingested: true,
+                        projectName,
+                        totalEntries: entries.length,
+                        filesScanned,
+                        categories,
+                        storedAt: "~/.stk/brain.json",
+                    }, null, 2),
+                }],
+        };
+    });
+    // ──────────────────────────────────────────
+    // Tool: stk_brain_sync
+    // ──────────────────────────────────────────
+    server.tool("stk_brain_sync", "Sync brain knowledge between local (~/.stk/brain.json) and cloud (Supabase). Push shares your knowledge with other developers. Pull downloads knowledge from the cloud. Sync does both.", {
+        action: z.enum(["sync", "push", "pull"]).optional().default("sync").describe("sync: push+pull, push: local→cloud, pull: cloud→local"),
+    }, async ({ action }) => {
+        let result;
+        if (action === "push")
+            result = await pushToCloud();
+        else if (action === "pull")
+            result = await pullFromCloud();
+        else
+            result = await syncBrain();
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        action,
+                        pushed: result.pushed,
+                        pulled: result.pulled,
+                        errors: result.errors.length > 0 ? result.errors : undefined,
+                        ok: result.errors.length === 0,
+                    }, null, 2),
+                }],
+        };
+    });
+    // ──────────────────────────────────────────
+    // Tool: stk_brain_review
+    // ──────────────────────────────────────────
+    server.tool("stk_brain_review", "Review code changes against the brain's knowledge base. Checks a git diff or PR for known gotchas per file. Use before merging PRs or after making changes.", {
+        diff: z.string().optional().describe("Raw git diff output"),
+        pr: z.number().optional().describe("GitHub PR number to review"),
+    }, async ({ diff, pr }) => {
+        let diffContent = diff ?? "";
+        // If PR number, fetch diff from GitHub
+        if (pr && !diff) {
+            const token = process.env.GITHUB_TOKEN;
+            let repo = process.env.GITHUB_REPO ?? "";
+            if (!repo) {
+                try {
+                    repo = execSync("git remote get-url origin", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim().replace(/.*github\.com[:/]/, "").replace(/\.git$/, "");
+                }
+                catch { /* */ }
+            }
+            if (repo && token) {
+                try {
+                    const res = await fetch(`https://api.github.com/repos/${repo}/pulls/${pr}`, {
+                        headers: { Authorization: `Bearer ${token}`, Accept: "application/vnd.github.diff" },
+                    });
+                    if (res.ok)
+                        diffContent = await res.text();
+                }
+                catch { /* */ }
+            }
+        }
+        // If no diff provided, get latest commit diff
+        if (!diffContent) {
+            try {
+                diffContent = execSync("git diff HEAD~1", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], maxBuffer: 1024 * 1024 * 5 });
+            }
+            catch { /* */ }
+        }
+        if (!diffContent) {
+            return { content: [{ type: "text", text: JSON.stringify({ error: "No diff available. Provide diff text, PR number, or ensure you're in a git repo." }) }] };
+        }
+        const results = reviewDiff(diffContent);
+        const filesWithWarnings = results.filter(r => r.warnings.length > 0);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        files: results,
+                        summary: {
+                            filesReviewed: results.length,
+                            filesWithWarnings: filesWithWarnings.length,
+                            totalWarnings: filesWithWarnings.reduce((s, r) => s + r.warnings.length, 0),
+                        },
+                    }, null, 2),
+                }],
+        };
+    });
+    // ──────────────────────────────────────────
+    // Tool: stk_brain_claudemd
+    // ──────────────────────────────────────────
+    server.tool("stk_brain_claudemd", "Auto-generate a CLAUDE.md file for the current project. Analyzes the tech stack, project structure, services, and brain knowledge to create comprehensive project instructions for Claude Code.", {
+        projectName: z.string().optional().describe("Project name (auto-detected from stk.config.json if omitted)"),
+        write: z.boolean().optional().default(false).describe("Actually write the CLAUDE.md file to disk. If false, just returns the content for review."),
+    }, async ({ projectName, write }) => {
+        const config = loadConfig();
+        const name = projectName ?? config.name ?? "my-project";
+        const enabled = enabledServices(config);
+        // Detect project info
+        let gitBranch = "";
+        let gitRemote = "";
+        let packageJson = {};
+        try {
+            gitBranch = execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+        }
+        catch { }
+        try {
+            gitRemote = execSync("git remote get-url origin", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+        }
+        catch { }
+        try {
+            const { readFileSync } = await import("fs");
+            packageJson = JSON.parse(readFileSync("package.json", "utf-8"));
+        }
+        catch { }
+        // Detect tech stack
+        const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
+        const stack = [];
+        if (deps?.["next"])
+            stack.push("Next.js");
+        if (deps?.["react"])
+            stack.push("React");
+        if (deps?.["vue"])
+            stack.push("Vue");
+        if (deps?.["express"])
+            stack.push("Express.js");
+        if (deps?.["fastify"])
+            stack.push("Fastify");
+        if (deps?.["@supabase/supabase-js"])
+            stack.push("Supabase");
+        if (deps?.["stripe"])
+            stack.push("Stripe");
+        if (deps?.["prisma"] || deps?.["@prisma/client"])
+            stack.push("Prisma");
+        if (deps?.["mongoose"])
+            stack.push("Mongoose/MongoDB");
+        if (deps?.["redis"] || deps?.["ioredis"])
+            stack.push("Redis");
+        if (deps?.["tailwindcss"])
+            stack.push("Tailwind CSS");
+        if (deps?.["typescript"])
+            stack.push("TypeScript");
+        if (deps?.["zod"])
+            stack.push("Zod");
+        if (stack.length === 0 && Object.keys(deps ?? {}).length > 0) {
+            stack.push("Node.js");
+        }
+        // Detect file structure
+        let fileStructure = "";
+        try {
+            fileStructure = execSync("find . -maxdepth 3 -type f -name '*.ts' -o -name '*.js' -o -name '*.tsx' -o -name '*.jsx' -o -name '*.json' -o -name '*.css' -o -name '*.html' | grep -v node_modules | grep -v dist | grep -v .git | sort | head -40", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+        }
+        catch { }
+        // Build CLAUDE.md
+        const lines = [];
+        lines.push(`# ${name}\n`);
+        // Project overview
+        lines.push(`## Overview\n`);
+        if (packageJson.description)
+            lines.push(`${packageJson.description}\n`);
+        if (stack.length > 0)
+            lines.push(`**Tech Stack:** ${stack.join(", ")}\n`);
+        if (gitRemote)
+            lines.push(`**Repo:** ${gitRemote}`);
+        if (gitBranch)
+            lines.push(`**Main Branch:** ${gitBranch}`);
+        lines.push("");
+        // Services
+        if (enabled.length > 0) {
+            lines.push(`## Services\n`);
+            for (const svc of enabled) {
+                const svcName = svc.charAt(0).toUpperCase() + svc.slice(1);
+                lines.push(`- **${svcName}** — configured and monitored via stk`);
+            }
+            lines.push("");
+        }
+        // Project structure
+        if (fileStructure) {
+            lines.push(`## Project Structure\n`);
+            lines.push("```");
+            lines.push(fileStructure);
+            lines.push("```\n");
+        }
+        // Development commands
+        lines.push(`## Development\n`);
+        if (packageJson.scripts) {
+            lines.push("```bash");
+            if (packageJson.scripts.dev)
+                lines.push(`npm run dev        # Start dev server`);
+            if (packageJson.scripts.build)
+                lines.push(`npm run build      # Build for production`);
+            if (packageJson.scripts.test)
+                lines.push(`npm test           # Run tests`);
+            if (packageJson.scripts.start)
+                lines.push(`npm start          # Start production server`);
+            lines.push("```\n");
+        }
+        // stk tools available
+        lines.push(`## stk Tools Available\n`);
+        lines.push(`This project uses stk for infrastructure monitoring. Available commands:\n`);
+        lines.push(`- \`stk_health\` — Check service health`);
+        lines.push(`- \`stk_status\` — Full project overview`);
+        lines.push(`- \`stk_logs\` — Production logs`);
+        lines.push(`- \`stk_db\` — Query database`);
+        lines.push(`- \`stk_alerts\` — Check for problems`);
+        lines.push(`- \`stk_deploy\` — Deploy to production`);
+        lines.push(`- \`stk_brain_search\` — Search knowledge base`);
+        lines.push(`- \`stk_brain_learn\` — Save patterns for future use`);
+        lines.push("");
+        // Conventions
+        lines.push(`## Conventions\n`);
+        if (deps?.["typescript"]) {
+            lines.push(`- TypeScript strict mode enabled`);
+        }
+        lines.push(`- Use existing patterns in the codebase before introducing new ones`);
+        lines.push(`- Check stk_health before debugging production issues`);
+        lines.push(`- Use stk_brain_search to find how other projects solve similar problems`);
+        lines.push(`- Save useful patterns with stk_brain_learn for future reference`);
+        lines.push("");
+        // Environment
+        lines.push(`## Environment Variables\n`);
+        lines.push(`Environment variables are managed via \`.env\` files. See \`.env.example\` for required variables.`);
+        if (enabled.includes("vercel"))
+            lines.push(`Use \`stk_env_sync\` to compare local vs remote env vars.`);
+        lines.push("");
+        const content = lines.join("\n");
+        if (write) {
+            const { writeFileSync } = await import("fs");
+            writeFileSync("CLAUDE.md", content);
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ written: true, path: "CLAUDE.md", lines: content.split("\n").length }, null, 2),
+                    }],
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ preview: true, content, note: "Call again with write: true to save to disk" }, null, 2),
+                }],
+        };
+    });
+    // ──────────────────────────────────────────
+    // Tool: stk_brain_team
+    // ──────────────────────────────────────────
+    server.tool("stk_brain_team", "Show team brain contributions — who learned what, from which projects, and when. Tracks knowledge sharing across team members.", {}, async () => {
+        const store = loadBrainStore();
+        const allEntries = [...store.global];
+        for (const proj of Object.values(store.projects))
+            allEntries.push(...proj.entries);
+        const contributors = {};
+        for (const entry of allEntries) {
+            const contributor = entry.contributor ?? "auto";
+            if (!contributors[contributor]) {
+                contributors[contributor] = { count: 0, lastActive: entry.created_at, categories: {} };
+            }
+            contributors[contributor].count++;
+            if (entry.created_at > contributors[contributor].lastActive) {
+                contributors[contributor].lastActive = entry.created_at;
+            }
+            contributors[contributor].categories[entry.category] = (contributors[contributor].categories[entry.category] || 0) + 1;
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        totalEntries: allEntries.length,
+                        contributors,
+                        projects: Object.entries(store.projects).map(([name, p]) => ({
+                            name, entries: p.entries.length, ingestedAt: p.ingestedAt,
+                        })),
+                    }, null, 2),
+                }],
+        };
+    });
+} // end registerBrainTools

package/dist/mcp/tools/data.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDataTools(server: McpServer): void;