@prajwolkc/stk 0.5.1 → 0.6.1

package/dist/mcp/server.js

@@ -11,7 +11,7 @@ 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 { getLocalBrainClient, ingestProject, loadBrainStore, saveBrainStore, syncBrain, pushToCloud, pullFromCloud } from "../services/brain.js";
+import { getLocalBrainClient, ingestProject, loadBrainStore, saveBrainStore, syncBrain, pushToCloud, pullFromCloud, brainCheck, brainDiagnose } from "../services/brain.js";
 import { execSync } from "child_process";
 const server = new McpServer({
     name: "stk",
@@ -1163,6 +1163,83 @@ server.tool("stk_brain_stats", "Check what the brain knows — total knowledge e
     };
 });
 // ──────────────────────────────────────────
+// Tool: stk_brain_check
+// ──────────────────────────────────────────
+server.tool("stk_brain_check", "PROACTIVE GOTCHA DETECTION — Run this BEFORE implementing any feature or fixing any bug. Searches the brain for known gotchas, pitfalls, and patterns related to your task. Returns warnings ranked by relevance so you can avoid repeating past mistakes. Claude should call this automatically before writing code.", {
+    task: z.string().describe("What you're about to implement or fix (e.g., 'add email verification', 'update user model', 'fix auth redirect')"),
+}, 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 with caution — this might be new territory.",
+                    }, null, 2),
+                }],
+        };
+    }
+    const warnings = results.slice(0, 5).map(r => ({
+        title: r.entry.title,
+        content: 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 pattern(s). Review warnings before coding.`,
+                }, null, 2),
+            }],
+    };
+});
+// ──────────────────────────────────────────
+// Tool: stk_brain_diagnose
+// ──────────────────────────────────────────
+server.tool("stk_brain_diagnose", "ERROR PATTERN MATCHING — Run this when you encounter an error or bug. Searches the brain for matching patterns from past issues and returns known solutions. Claude should call this automatically when debugging.", {
+    error: z.string().describe("The error message, symptom, or bug description (e.g., 'redirect not working after verification', 'emails not sending', 'prisma field undefined')"),
+}, async ({ error }) => {
+    const results = brainDiagnose(error);
+    if (results.length === 0) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        error,
+                        solutions: [],
+                        message: "No matching patterns found. This is a new issue — after fixing it, use stk_brain_learn to save the pattern.",
+                    }, 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 pattern(s). Apply relevant solutions.`,
+                }, 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.", {
@@ -1244,6 +1321,83 @@ server.tool("stk_brain_sync", "Sync brain knowledge between local (~/.stk/brain.
     };
 });
 // ──────────────────────────────────────────
+// 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_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.", {

package/dist/services/brain.d.ts

@@ -63,4 +63,17 @@ export declare function pushToCloud(): Promise<SyncResult>;
 export declare function pullFromCloud(): Promise<SyncResult>;
 /** Full sync: push local → cloud, then pull cloud → local */
 export declare function syncBrain(): Promise<SyncResult>;
+interface ScoredEntry {
+    entry: KnowledgeEntry;
+    score: number;
+    matchedTerms: string[];
+}
+/** Search brain with relevance scoring — returns entries ranked by how many terms match */
+export declare function smartSearch(terms: string[], category?: string): ScoredEntry[];
+/** Extract relevant terms from a task description */
+export declare function extractTerms(description: string): string[];
+/** Proactive check — find gotchas relevant to a task before coding */
+export declare function brainCheck(taskDescription: string): ScoredEntry[];
+/** Diagnose an error — find matching patterns from past issues */
+export declare function brainDiagnose(error: string): ScoredEntry[];
 export {};

package/dist/services/brain.js

@@ -524,3 +524,90 @@ export async function syncBrain() {
         errors: [...pushResult.errors, ...pullResult.errors],
     };
 }
+/** Search brain with relevance scoring — returns entries ranked by how many terms match */
+export function smartSearch(terms, category) {
+    const store = loadBrainStore();
+    let entries = getAllEntries(store);
+    if (category) {
+        entries = entries.filter(e => e.category === category);
+    }
+    const normalizedTerms = terms.map(t => t.toLowerCase());
+    const scored = [];
+    for (const entry of entries) {
+        const searchText = `${entry.title} ${entry.content} ${entry.tags.join(" ")}`.toLowerCase();
+        const matchedTerms = [];
+        let score = 0;
+        for (const term of normalizedTerms) {
+            if (searchText.includes(term)) {
+                matchedTerms.push(term);
+                // Title match scores higher
+                if (entry.title.toLowerCase().includes(term))
+                    score += 3;
+                // Tag match scores high
+                else if (entry.tags.some(t => t.toLowerCase().includes(term)))
+                    score += 2;
+                // Content match
+                else
+                    score += 1;
+            }
+        }
+        // Boost gotcha/debugging entries
+        if (entry.tags.some(t => ["gotcha", "debugging", "bug", "fix", "issue"].includes(t))) {
+            score *= 1.5;
+        }
+        if (score > 0) {
+            scored.push({ entry, score, matchedTerms });
+        }
+    }
+    return scored.sort((a, b) => b.score - a.score);
+}
+/** Extract relevant terms from a task description */
+export function extractTerms(description) {
+    const stopWords = new Set([
+        "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+        "have", "has", "had", "do", "does", "did", "will", "would", "could",
+        "should", "may", "might", "shall", "can", "need", "must", "to", "of",
+        "in", "for", "on", "with", "at", "by", "from", "as", "into", "about",
+        "like", "through", "after", "before", "between", "under", "above",
+        "and", "but", "or", "not", "no", "so", "if", "then", "than", "too",
+        "very", "just", "also", "how", "what", "when", "where", "why", "which",
+        "that", "this", "these", "those", "it", "its", "i", "we", "you", "they",
+        "me", "us", "my", "our", "your", "add", "implement", "create", "build",
+        "make", "want", "get", "set", "use", "new", "update", "change",
+    ]);
+    const words = description.toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, " ")
+        .split(/\s+/)
+        .filter(w => w.length > 2 && !stopWords.has(w));
+    // Also extract multi-word phrases
+    const phrases = [];
+    const desc = description.toLowerCase();
+    const commonPhrases = [
+        "email verification", "password reset", "auth state", "user select",
+        "prisma select", "react context", "protected route", "refresh token",
+        "rate limit", "soft delete", "multi-tenant", "org scoping",
+        "file upload", "webhook", "cron job", "background job",
+        "api key", "role based", "permission", "middleware",
+    ];
+    for (const phrase of commonPhrases) {
+        if (desc.includes(phrase))
+            phrases.push(phrase);
+    }
+    return [...new Set([...words, ...phrases])];
+}
+/** Proactive check — find gotchas relevant to a task before coding */
+export function brainCheck(taskDescription) {
+    const terms = extractTerms(taskDescription);
+    return smartSearch(terms);
+}
+/** Diagnose an error — find matching patterns from past issues */
+export function brainDiagnose(error) {
+    const terms = extractTerms(error);
+    // Add error-specific terms
+    const errorTerms = error.toLowerCase()
+        .replace(/[^a-z0-9\s]/g, " ")
+        .split(/\s+/)
+        .filter(w => w.length > 3);
+    const allTerms = [...new Set([...terms, ...errorTerms])];
+    return smartSearch(allTerms);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prajwolkc/stk",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "One CLI to deploy, monitor, debug, and learn about your entire stack. Infrastructure monitoring, knowledge base brain, deploy watching, and GitHub issues — all from one command.",
   "type": "module",
   "license": "MIT",