superkit-mcp-server 1.2.8 → 1.3.1

package/README.md

@@ -8,6 +8,16 @@ While the primary purpose is to compund the knowledge of engineering, I will add
 
 🔗 **NPM Package:** [superkit-mcp-server](https://www.npmjs.com/package/superkit-mcp-server)
 
+## Install as Claude Code Plugin
+
+1. Open Claude Code → `/plugin` → **Discover** → **Add source**
+2. Enter: `github:dgkngk/super-kit`
+3. Install: `/plugin install super-kit@dgkngk`
+
+This configures the MCP server automatically and makes all skills, agents, and commands available.
+
+**Requirements:** Node.js 18+ (for `npx superkit-mcp-server@latest`)
+
 ## Directory Structure
 - `agents/`: Contains instructions and guidelines for specialized AI roles (e.g., `data-engineer`).
 - `skills/`: Contains technology-specific or meta skills (patterns, best practices) the agent can load dynamically (e.g., `react-best-practices`).

package/SUPERKIT.md

@@ -1,101 +1,59 @@
 # Super-Kit: Super Engineer Team
 
-You are a member of the Super-Kit team - a specialized group of AI agents collaborating to develop high-quality software.
+> 💡 Full agent/skill/workflow details indexed. Use `search_context` to retrieve relevant sections on demand.
 
-## Role & Responsibilities
-
-You are an AI assistant that analyzes user requirements, assigns tasks to suitable agents, and ensures high-quality delivery adhering to project standards and patterns.
-
-## Workflows
-
-- Primary workflow: `./skills/workflows/primary-workflow.md`
-- Development rules: `./skills/workflows/development-rules.md`
-- Orchestration protocols: `./skills/workflows/orchestration-protocol.md`
-- Documentation management: `./skills/workflows/documentation-management.md`
+You are a member of the Super-Kit team — AI agents collaborating to deliver high-quality software.
 
 ## Team Members
 
-Details about each agent in the `agents/` directory:
-
-| Agent | File | Role |
-|-------|------|------|
-| Planner | [planner.md](agents/planner.md) | Create detailed implementation plans |
-| Scout | [scout.md](agents/scout.md) | Explore codebase structure |
-| Coder | [coder.md](agents/coder.md) | Write clean, efficient code |
-| Tester | [tester.md](agents/tester.md) | Write tests, ensure quality |
-| Reviewer | [reviewer.md](agents/reviewer.md) | Review code, suggest improvements |
-| Debugger | [debugger.md](agents/debugger.md) | Analyze errors and bugs |
-| Git Manager | [git-manager.md](agents/git-manager.md) | Manage version control |
-| Copywriter | [copywriter.md](agents/copywriter.md) | Create marketing content |
-| Database Admin | [database-admin.md](agents/database-admin.md) | Manage database |
-| Researcher | [researcher.md](agents/researcher.md) | Research external resources |
-| UI Designer | [ui-designer.md](agents/ui-designer.md) | UI/UX Design |
-| Docs Manager | [docs-manager.md](agents/docs-manager.md) | Manage documentation |
-| Brainstormer | [brainstormer.md](agents/brainstormer.md) | Generate creative ideas |
-| Fullstack Developer | [fullstack-developer.md](agents/fullstack-developer.md) | Full-stack development |
-| Project Manager | [project-manager.md](agents/project-manager.md) | Project management |
-| Security Auditor | [security-auditor.md](agents/security-auditor.md) | Security audit, vulnerability scanning |
-| Frontend Specialist | [frontend-specialist.md](agents/frontend-specialist.md) | React, Next.js, UI/UX expert |
-| Backend Specialist | [backend-specialist.md](agents/backend-specialist.md) | API, Database, Docker expert |
-| DevOps Engineer | [devops-engineer.md](agents/devops-engineer.md) | CI/CD, Kubernetes, Infrastructure |
-
-## Workflow
-
-1. **Plan first** - Always use /plan before coding
-2. **Scout** - Understand codebase before changes
-3. **Code** - Write code according to plan
-4. **Test** - Write and run tests
-5. **Review** - Code review before commit
-
-## Communication
-
-- Concise, clear
-- Use code blocks for code
-- Explain reasoning
-- Ask when clarification is needed
-
-## 🧠 Learning System (IMPORTANT!)
-
-You have the ability to **LEARN FROM USER FEEDBACK** to avoid repeating mistakes:
-
-### When to save a learning?
-- User corrects your code → **MUST** use `kit_save_learning`
-- User says "incorrect", "wrong", "different style" → **MUST** save
-- User explains preference → Save under category `preference`
-
-### Categories
-- `code_style` - Code style/formatting
-- `bug` - Logic errors you often make
-- `preference` - User preferences
-- `pattern` - Patterns user wants to use
-- `other` - Other
-
-### Example
-```
-When user corrects: "Use arrow function, do not use regular function"
-→ kit_save_learning(category: "code_style", lesson: "User prefers arrow functions over regular functions")
+| Agent | Role |
+|-------|------|
+| Planner | Create detailed implementation plans |
+| Scout | Explore codebase structure |
+| Coder | Write clean, efficient code |
+| Tester | Write tests, ensure quality |
+| Reviewer | Review code, suggest improvements |
+| Debugger | Analyze errors and bugs |
+| Git Manager | Manage version control |
+| Copywriter | Create marketing content |
+| Database Admin | Manage database |
+| Researcher | Research external resources |
+| UI Designer | UI/UX Design |
+| Docs Manager | Manage documentation |
+| Brainstormer | Generate creative ideas |
+| Fullstack Developer | Full-stack development |
+| Project Manager | Project management |
+| Security Auditor | Security audit, vulnerability scanning |
+| Frontend Specialist | React, Next.js, UI/UX expert |
+| Backend Specialist | API, Database, Docker expert |
+| DevOps Engineer | CI/CD, Kubernetes, Infrastructure |
+
+## Critical Workflow Rules
+
+- **Plan first** — Always use /plan before coding
+- **Scout first** — Understand codebase before making changes
+- **Test** — Write and run tests after coding
+- **Review** — Code review before commit
+
+## Compound Loop
 
-When user says: "Always use TypeScript strict mode"
-→ kit_save_learning(category: "preference", lesson: "Always use TypeScript strict mode")
 ```
-
-### Automatic Learning Injection
-- Learnings will be injected into context automatically via hooks
-- Read "🧠 Previous Learnings" section and **APPLY** them
+/explore → /plan → /work → /review → /compound → /housekeeping → repeat
+```
 
 ## Available Tools
 
-**Super-Kit MCP Tools (Global Scope):**
-- `list_superkit_assets` - Lists all available agents, skills, and workflows. Accepts optional `scope` (`"global"` | `"project"` | `"all"`) and `projectPath` params.
-- `load_superkit_agent` - Loads Markdown instructions for an agent (e.g., `data-engineer`).
-- `load_superkit_skill` - Loads Markdown instructions for a skill (e.g., `tech`, `api-patterns`).
-- `load_superkit_workflow` - Loads a workflow guide (e.g., `work`, `explore`).
+**Super-Kit MCP Tools (Global):**
+- `list_superkit_assets` - List all global agents, skills, and workflows
+- `load_superkit_agent` - Load a global agent (e.g., `scout`)
+- `load_superkit_skill` - Load a global skill (e.g., `tech`, `api-patterns`)
+- `load_superkit_workflow` - Load a global workflow (e.g., `work`, `explore`)
 
 **Project-Scoped MCP Tools:**
-- `list_project_assets` - Lists project-scoped agents, skills, and workflows from the `.agents/` folder.
-- `load_project_agent` - Loads a project-scoped agent from `{projectPath}/.agents/agents/`.
-- `load_project_skill` - Loads a project-scoped skill's `SKILL.md` from `{projectPath}/.agents/skills/`.
-- `load_project_workflow` - Loads a project-scoped workflow from `{projectPath}/.agents/workflows/`.
+- `list_project_assets` - List project-scoped assets from `.agents/` folder
+- `load_project_agent` - Load a project-scoped agent
+- `load_project_skill` - Load a project-scoped skill
+- `load_project_workflow` - Load a project-scoped workflow
 
 **Core Development Tools:**
 - `kit_create_checkpoint` - Create checkpoint before changes
@@ -106,89 +64,21 @@ When user says: "Always use TypeScript strict mode"
 - `kit_list_checkpoints` - List checkpoints
 
 **Learning:**
-- `kit_save_learning` - **Save lesson from user feedback**
+- `kit_save_learning` - Save lesson from user feedback
 - `kit_get_learnings` - Read saved learnings
 
-## 🗂️ Project-Based Assets
-
-Any project can define its own agents, skills, and workflows by creating a `.agents/` folder at the project root:
-
-```
-{project-root}/
-└── .agents/
-    ├── agents/       # Custom agent .md files (e.g., my-domain-expert.md)
-    ├── skills/
-    │   ├── tech/     # Tech skill dirs, each containing a SKILL.md
-    │   └── meta/     # Meta skill dirs, each containing a SKILL.md
-    └── workflows/    # Custom workflow .md files (e.g., deploy-staging.md)
-```
-
-**Resolution rules:**
-- Project assets have `"source": "project"` and **complement** (do not replace) global Super-Kit assets.
-- Global Super-Kit assets always have `"source": "global"`.
-- If `.agents/` does not exist, all project-scoped tools return empty results gracefully — no errors.
-
-**When starting work on ANY project, ALWAYS:**
-1. Call `list_project_assets` (or `list_superkit_assets` with `scope: "all"`) to discover project-specific agents, skills, and workflows.
-2. Load project assets with `load_project_agent`, `load_project_skill`, or `load_project_workflow` before falling back to global equivalents.
-3. Use global assets (`load_superkit_agent`, etc.) for anything not covered by the project's `.agents/` folder.
-
-## Documentation Management
-
-- Docs location: `./docs/`
-- Update README.md when adding features
-- Update CHANGELOG.md before release
-- Keep docs in sync with code changes
-
-## 🔄 Compound Behaviors (IMPORTANT!)
-
-Each unit of work must make the next work **easier**, not harder.
+## 🧠 Learning System
 
-### Session Resume (MANDATORY)
+On user correction or preference feedback → **MUST** call `kit_save_learning`.
 
-When starting a new session, **MUST** read:
-```bash
-cat skills/session-resume/SKILL.md
-```
-
-### Search Before Solving
-
-**BEFORE** solving a new problem:
-```bash
-Call MCP `call_tool_compound_manager` { action: "search", terms: ["{keywords}"] }
-```
-
-If solution found → Apply it, do not reinvent the wheel!
-
-### Document After Solving
-
-**AFTER** solving a problem successfully:
-- Run `/compound` to document solution
-- Solution will be saved to `docs/solutions/`
-
-### Critical Patterns
-
-**MUST** read before coding:
-- `docs/solutions/patterns/critical-patterns.md` - 23 patterns to prevent repeated errors
+**Categories:** `code_style` | `bug` | `preference` | `pattern` | `other`
 
-### Health Check
-
-Run daily:
-```bash
-Call MCP `call_tool_compound_manager` { action: "dashboard" }
-```
-**Target**: Grade B or higher
-
-### Compound Loop
-
-```
-/explore → /plan → /work → /review → /compound → /housekeeping → repeat
-```
+Learnings are auto-injected into context. Read "🧠 Previous Learnings" and **APPLY** them.
 
 ## Important Directories
 
 ```
-docs/solutions/       # Knowledge Base - Persistent solutions
+docs/solutions/       # Knowledge Base — Persistent solutions
 docs/decisions/       # Architecture Decision Records
 docs/architecture/    # System architecture
 docs/specs/           # Multi-session specifications
@@ -196,4 +86,4 @@ docs/explorations/    # Deep research artifacts
 skills/               # Modular capabilities
 plans/                # Implementation plans
 todos/                # Tracked work items
-```
+```

package/build/index.js

@@ -3,6 +3,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import * as path from "path";
+import * as os from "os";
 import * as fs from "fs/promises";
 import * as toml from "@iarna/toml";
 import { fileURLToPath } from "url";
@@ -17,9 +18,18 @@ import { bootstrapFolderDocs, checkDocsFreshness, discoverUndocumentedFolders, v
 import { generateChangelog, validateChangelog, archiveCompleted, prePushHousekeeping, } from "./tools/gitTools.js";
 import { validateSpecConsistency, completePlan, validateArchitecture, syncSpec, updateSpecPhase, } from "./tools/archTools.js";
 import { list_project_agents, list_project_skills, list_project_workflows, load_project_agent_file, load_project_skill_file, load_project_workflow_file, } from "./tools/ProjectAssets.js";
+import { ContextManager } from "./tools/contextManager.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const superKitRoot = path.resolve(__dirname, "../");
+const contextManager = new ContextManager({
+    assetsDir: superKitRoot,
+    storeDir: path.join(os.homedir(), ".superkit"),
+});
+// Index in background — does not block server startup
+contextManager.indexAll().catch((err) => {
+    console.error("[superkit] Context indexing failed:", err);
+});
 const server = new Server({
     name: "superkit-mcp-server",
     version: "1.0.0",
@@ -120,22 +130,22 @@ const TOOLS = [
     },
     {
         name: "call_tool_todo_manager",
-        description: `Manages todos. Per-action usage:
-
-• nextId — Returns the next available todo ID. No extra params needed.
-
-• create — Creates a new todo file. Required: title (string), description (1-2 sentence problem statement), priority ("p0"|"p1"|"p2"|"p3"), criteria (string array of acceptance criteria). Optional: projectPath.
-  Example: { action: "create", title: "Add auth", description: "Implement JWT login.", priority: "p2", criteria: ["User can log in", "Token is stored"], projectPath: "." }
-
-• start — Marks a todo as in-progress. Required: todoId = RELATIVE PATH to the todo file, e.g. "todos/001-pending-p2-my-task.md". The file must exist at that path relative to projectPath.
-  Example: { action: "start", todoId: "todos/001-pending-p2-my-task.md", projectPath: "." }
-
-• done — Marks a todo as done. Required: todoId = relative path (same format as start). All acceptance criteria checkboxes must be checked, or pass force: true to bypass.
-  Example: { action: "done", todoId: "todos/001-in-progress-p2-my-task.md", force: true, projectPath: "." }
-
-• complete — Marks a todo as complete (final state). Required: todoId = relative path (same format as start/done).
-  Example: { action: "complete", todoId: "todos/001-done-p2-my-task.md", force: true, projectPath: "." }
-
+        description: `Manages todos. Per-action usage:
+
+• nextId — Returns the next available todo ID. No extra params needed.
+
+• create — Creates a new todo file. Required: title (string), description (1-2 sentence problem statement), priority ("p0"|"p1"|"p2"|"p3"), criteria (string array of acceptance criteria). Optional: projectPath.
+  Example: { action: "create", title: "Add auth", description: "Implement JWT login.", priority: "p2", criteria: ["User can log in", "Token is stored"], projectPath: "." }
+
+• start — Marks a todo as in-progress. Required: todoId = RELATIVE PATH to the todo file, e.g. "todos/001-pending-p2-my-task.md". The file must exist at that path relative to projectPath.
+  Example: { action: "start", todoId: "todos/001-pending-p2-my-task.md", projectPath: "." }
+
+• done — Marks a todo as done. Required: todoId = relative path (same format as start). All acceptance criteria checkboxes must be checked, or pass force: true to bypass.
+  Example: { action: "done", todoId: "todos/001-in-progress-p2-my-task.md", force: true, projectPath: "." }
+
+• complete — Marks a todo as complete (final state). Required: todoId = relative path (same format as start/done).
+  Example: { action: "complete", todoId: "todos/001-done-p2-my-task.md", force: true, projectPath: "." }
+
 ⚠️ IMPORTANT: todoId must be the FULL RELATIVE FILE PATH (e.g. "todos/001-in-progress-p2-my-task.md"), NOT just the numeric ID ("001"). The filename changes with each status transition, so always use the current filename on disk.`,
         inputSchema: {
             type: "object",
@@ -404,6 +414,52 @@ const TOOLS = [
             required: ["workflowName"],
         },
     },
+    {
+        name: "search_context",
+        description: "Semantic search over super-kit agents, skills, workflows, and SUPERKIT.md. Returns the most relevant heading-level chunks. Use BEFORE load_superkit_skill/agent/workflow to find what you need without loading full files.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Natural language search query" },
+                topK: { type: "number", default: 5, description: "Number of results to return (1-20)" },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "index_context",
+        description: "Manually trigger re-indexing of all super-kit context (agents, skills, workflows). Useful after adding new files. Returns indexing stats.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: "store_session_memory",
+        description: "Persist a cross-session memory to super-kit's vector store. Memories are retrieved by semantic similarity in future sessions via recall_memory.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                text: { type: "string", description: "The memory to store (a fact, decision, or pattern)" },
+                tags: { type: "array", items: { type: "string" }, description: "Optional tags for filtering" },
+                ttl_days: { type: "number", enum: [30, 90], default: 30, description: "How long to keep this memory (30 or 90 days)" },
+            },
+            required: ["text"],
+        },
+    },
+    {
+        name: "recall_memory",
+        description: "Search cross-session memories by semantic similarity. Returns memories stored via store_session_memory, ordered by relevance.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "What to search for in past memories" },
+                topK: { type: "number", default: 5, description: "Number of memories to return" },
+            },
+            required: ["query"],
+        },
+    },
 ];
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return { tools: TOOLS };
@@ -826,6 +882,55 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const content = await load_project_workflow_file(args.workflowName, args.projectPath);
             return { content: [{ type: "text", text: content }] };
         }
+        if (request.params.name === "search_context") {
+            const args = request.params.arguments;
+            const topK = Math.min(Math.max(1, args.topK ?? 5), 20);
+            const results = await contextManager.searchContext(args.query, topK);
+            const formatted = results
+                .map((r, i) => `[${i + 1}] ${r.sourceFile} › ${r.headingPath} (score: ${r.score.toFixed(3)})\n${r.content}`)
+                .join("\n\n---\n\n");
+            return { content: [{ type: "text", text: formatted || "No results found." }] };
+        }
+        if (request.params.name === "index_context") {
+            const stats = await contextManager.indexAll();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Context indexed. Files re-embedded: ${stats.indexed}, unchanged: ${stats.skipped}.`,
+                    },
+                ],
+            };
+        }
+        if (request.params.name === "store_session_memory") {
+            const args = request.params.arguments;
+            const ttl = args.ttl_days ?? 30;
+            await contextManager.storeMemory(args.text, args.tags ?? [], ttl);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Memory stored (TTL: ${ttl} days). It will be retrievable via recall_memory.`,
+                    },
+                ],
+            };
+        }
+        if (request.params.name === "recall_memory") {
+            const args = request.params.arguments;
+            const topK = Math.min(Math.max(1, args.topK ?? 5), 20);
+            const results = await contextManager.recallMemory(args.query, topK);
+            if (results.length === 0) {
+                return { content: [{ type: "text", text: "No memories found." }] };
+            }
+            const formatted = results
+                .map((r, i) => {
+                const expires = new Date(r.expiresAt).toISOString().slice(0, 10);
+                const tags = r.tags.length ? ` [${r.tags.join(", ")}]` : "";
+                return `[${i + 1}]${tags} (score: ${r.score.toFixed(3)}, expires: ${expires})\n${r.text}`;
+            })
+                .join("\n\n");
+            return { content: [{ type: "text", text: formatted }] };
+        }
         throw new Error(`Unknown tool: ${request.params.name}`);
     }
     catch (error) {

package/build/tools/contextManager.js

@@ -0,0 +1,153 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { createHash } from 'crypto';
+import { chunkMarkdown } from './markdownChunker.js';
+import { embed, embedOne } from './embedder.js';
+import { ContextVectorStore } from './contextVectorStore.js';
+const VALID_TTLS = new Set([30, 90]);
+export class ContextManager {
+    opts;
+    store;
+    ready = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.store = new ContextVectorStore(opts.storeDir);
+    }
+    isReady() {
+        return this.ready;
+    }
+    /** Scan agents/, skills/, and SUPERKIT.md; return all markdown entries with mtimes. */
+    async discoverFiles() {
+        const entries = [];
+        const base = this.opts.assetsDir;
+        const walk = async (dir, sourceType) => {
+            let items;
+            try {
+                items = await fs.readdir(dir);
+            }
+            catch {
+                return;
+            }
+            for (const item of items) {
+                const abs = path.join(dir, item);
+                const stat = await fs.stat(abs).catch(() => null);
+                if (!stat)
+                    continue;
+                if (stat.isDirectory()) {
+                    await walk(abs, sourceType);
+                }
+                else if (item.endsWith('.md')) {
+                    entries.push({
+                        relativePath: path.relative(base, abs).replace(/\\/g, '/'),
+                        absolutePath: abs,
+                        sourceType,
+                        mtime: stat.mtimeMs,
+                    });
+                }
+            }
+        };
+        await walk(path.join(base, 'agents'), 'agent');
+        await walk(path.join(base, 'skills', 'tech'), 'skill');
+        await walk(path.join(base, 'skills', 'meta'), 'skill');
+        await walk(path.join(base, 'skills', 'workflows'), 'workflow');
+        // SUPERKIT.md itself
+        const superkitPath = path.join(base, 'SUPERKIT.md');
+        const superkitStat = await fs.stat(superkitPath).catch(() => null);
+        if (superkitStat) {
+            entries.push({ relativePath: 'SUPERKIT.md', absolutePath: superkitPath, sourceType: 'system', mtime: superkitStat.mtimeMs });
+        }
+        return entries;
+    }
+    /** Re-embed and store the given file entries. */
+    async indexFiles(files) {
+        if (files.length === 0)
+            return;
+        const allChunks = [];
+        const allTexts = [];
+        const chunkMeta = [];
+        for (const file of files) {
+            const content = await fs.readFile(file.absolutePath, 'utf-8').catch(() => '');
+            if (!content.trim())
+                continue;
+            const chunks = chunkMarkdown(content, file.relativePath, file.sourceType);
+            for (const chunk of chunks) {
+                chunkMeta.push({ chunk, mtime: file.mtime });
+                // Embed heading path + content for better semantic matching
+                allTexts.push(`${chunk.headingPath}\n\n${chunk.content}`);
+            }
+        }
+        if (allTexts.length === 0)
+            return;
+        const vectors = await embed(allTexts);
+        for (let i = 0; i < chunkMeta.length; i++) {
+            allChunks.push({ chunk: chunkMeta[i].chunk, vector: vectors[i], sourceMtime: chunkMeta[i].mtime });
+        }
+        const fileNames = files.map(f => f.relativePath);
+        await this.store.replaceChunksForFiles(fileNames, allChunks);
+    }
+    /**
+     * Index all markdown assets. Incremental: only re-indexes files whose mtime changed.
+     * Safe to call multiple times.
+     */
+    async indexAll() {
+        const discovered = await this.discoverFiles();
+        const mtimeMap = {};
+        for (const f of discovered)
+            mtimeMap[f.relativePath] = f.mtime;
+        const staleRelPaths = await this.store.getStaleFiles(mtimeMap);
+        const staleSet = new Set(staleRelPaths);
+        const toIndex = discovered.filter(f => staleSet.has(f.relativePath));
+        await this.indexFiles(toIndex);
+        this.ready = true;
+        return { indexed: toIndex.length, skipped: discovered.length - toIndex.length };
+    }
+    async searchContext(query, topK = 5) {
+        if (!this.ready) {
+            return [{
+                    sourceFile: 'system',
+                    sourceType: 'system',
+                    headingPath: 'Status',
+                    content: 'Context indexing is in progress. Try again in a few seconds.',
+                    score: 0,
+                }];
+        }
+        const vec = await embedOne(query);
+        const hits = await this.store.searchChunks(vec, topK);
+        return hits.map(h => ({
+            sourceFile: h.chunk.sourceFile,
+            sourceType: h.chunk.sourceType,
+            headingPath: h.chunk.headingPath,
+            content: h.chunk.content,
+            score: h.score,
+        }));
+    }
+    async storeMemory(text, tags, ttlDays) {
+        if (!VALID_TTLS.has(ttlDays))
+            throw new Error('TTL must be 30 or 90 days');
+        const id = createHash('sha1').update(`${Date.now()}::${text}`).digest('hex').slice(0, 16);
+        const vec = await embedOne(text);
+        const now = Date.now();
+        await this.store.upsertMemory({
+            id,
+            text,
+            tags,
+            vector: vec,
+            createdAt: now,
+            expiresAt: now + ttlDays * 24 * 60 * 60 * 1000,
+        });
+    }
+    async recallMemory(query, topK = 5) {
+        const vec = await embedOne(query);
+        const hits = await this.store.searchMemory(vec, topK);
+        return hits.map(h => ({
+            text: h.entry.text,
+            tags: h.entry.tags,
+            score: h.score,
+            createdAt: h.entry.createdAt,
+            expiresAt: h.entry.expiresAt,
+        }));
+    }
+    async pruneMemories() {
+        return this.store.pruneExpiredMemories();
+    }
+}

package/build/tools/contextVectorStore.js

@@ -0,0 +1,131 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+function cosine(a, b) {
+    let dot = 0, na = 0, nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    const denom = Math.sqrt(na) * Math.sqrt(nb);
+    return denom === 0 ? 0 : dot / denom;
+}
+export class ContextVectorStore {
+    storeDir;
+    chunksPath;
+    memoriesPath;
+    chunksCache = null;
+    memoriesCache = null;
+    constructor(storeDir) {
+        this.storeDir = storeDir;
+        this.chunksPath = path.join(storeDir, 'context-index.json');
+        this.memoriesPath = path.join(storeDir, 'memory.json');
+    }
+    async loadChunks() {
+        if (this.chunksCache)
+            return this.chunksCache;
+        try {
+            const raw = await fs.readFile(this.chunksPath, 'utf-8');
+            this.chunksCache = JSON.parse(raw);
+        }
+        catch {
+            this.chunksCache = [];
+        }
+        return this.chunksCache;
+    }
+    async saveChunks(chunks) {
+        this.chunksCache = chunks;
+        await fs.mkdir(this.storeDir, { recursive: true });
+        await fs.writeFile(this.chunksPath, JSON.stringify(chunks), 'utf-8');
+    }
+    async loadMemories() {
+        if (this.memoriesCache)
+            return this.memoriesCache;
+        try {
+            const raw = await fs.readFile(this.memoriesPath, 'utf-8');
+            this.memoriesCache = JSON.parse(raw);
+        }
+        catch {
+            this.memoriesCache = [];
+        }
+        return this.memoriesCache;
+    }
+    async saveMemories(memories) {
+        this.memoriesCache = memories;
+        await fs.mkdir(this.storeDir, { recursive: true });
+        await fs.writeFile(this.memoriesPath, JSON.stringify(memories), 'utf-8');
+    }
+    /**
+     * Upserts chunks. Existing chunks with the same id are replaced.
+     */
+    async upsertChunks(items) {
+        const existing = await this.loadChunks();
+        const byId = new Map(existing.map(c => [c.chunk.id, c]));
+        for (const item of items)
+            byId.set(item.chunk.id, item);
+        await this.saveChunks(Array.from(byId.values()));
+    }
+    /**
+     * Removes all chunks from the given source files and upserts the new ones.
+     * Used during incremental re-indexing.
+     */
+    async replaceChunksForFiles(files, newChunks) {
+        const existing = await this.loadChunks();
+        const fileSet = new Set(files);
+        const kept = existing.filter(c => !fileSet.has(c.chunk.sourceFile));
+        await this.saveChunks([...kept, ...newChunks]);
+    }
+    async searchChunks(queryVector, topK) {
+        const all = await this.loadChunks();
+        return all
+            .map(c => ({ chunk: c.chunk, score: cosine(queryVector, c.vector) }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, topK);
+    }
+    /**
+     * Returns source files whose recorded mtime differs from the provided map,
+     * plus files in the map that have no chunks recorded.
+     */
+    async getStaleFiles(currentMtimes) {
+        const all = await this.loadChunks();
+        // Latest recorded mtime per source file
+        const recorded = new Map();
+        for (const c of all) {
+            const prev = recorded.get(c.chunk.sourceFile) ?? 0;
+            if (c.sourceMtime > prev)
+                recorded.set(c.chunk.sourceFile, c.sourceMtime);
+        }
+        const stale = [];
+        for (const [file, mtime] of Object.entries(currentMtimes)) {
+            const prev = recorded.get(file);
+            if (prev === undefined || prev !== mtime)
+                stale.push(file);
+        }
+        return stale;
+    }
+    async upsertMemory(entry) {
+        const all = await this.loadMemories();
+        const idx = all.findIndex(m => m.id === entry.id);
+        if (idx >= 0)
+            all[idx] = entry;
+        else
+            all.push(entry);
+        await this.saveMemories(all);
+    }
+    async searchMemory(queryVector, topK) {
+        const all = await this.loadMemories();
+        const now = Date.now();
+        return all
+            .filter(m => m.expiresAt > now)
+            .map(entry => ({ entry, score: cosine(queryVector, entry.vector) }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, topK);
+    }
+    async pruneExpiredMemories() {
+        const all = await this.loadMemories();
+        const now = Date.now();
+        const live = all.filter(m => m.expiresAt > now);
+        await this.saveMemories(live);
+        return all.length - live.length;
+    }
+}

package/build/tools/embedder.js

@@ -0,0 +1,46 @@
+import * as os from 'os';
+import * as path from 'path';
+// Lazily initialized pipeline — avoids blocking server startup
+let pipelineInstance = null;
+let loadingPromise = null;
+async function getEmbedder() {
+    if (pipelineInstance)
+        return pipelineInstance;
+    if (loadingPromise)
+        return loadingPromise;
+    loadingPromise = (async () => {
+        // Dynamic import so the module loads lazily at runtime, not at parse time.
+        // This prevents the 5-10s model load from blocking MCP server startup.
+        const { pipeline, env } = await import('@huggingface/transformers');
+        // Cache models in ~/.superkit/models to survive package updates
+        env.cacheDir = path.join(os.homedir(), '.superkit', 'models');
+        pipelineInstance = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { device: 'cpu' });
+        return pipelineInstance;
+    })();
+    return loadingPromise;
+}
+const BATCH_SIZE = 32;
+/**
+ * Embeds an array of texts using all-MiniLM-L6-v2 (384-dim).
+ * Processes in batches of 32 to avoid OOM on large indexes.
+ * Returns a parallel array of vectors.
+ */
+export async function embed(texts) {
+    const extractor = await getEmbedder();
+    const results = [];
+    for (let i = 0; i < texts.length; i += BATCH_SIZE) {
+        const batch = texts.slice(i, i + BATCH_SIZE);
+        const output = await extractor(batch, { pooling: 'mean', normalize: true });
+        // output.data is a flat Float32Array; reshape into vectors of 384
+        const dims = 384;
+        for (let j = 0; j < batch.length; j++) {
+            results.push(Array.from(output.data.slice(j * dims, (j + 1) * dims)));
+        }
+    }
+    return results;
+}
+/** Embeds a single text. Convenience wrapper. */
+export async function embedOne(text) {
+    const [vec] = await embed([text]);
+    return vec;
+}

package/build/tools/markdownChunker.js

@@ -0,0 +1,43 @@
+import { createHash } from 'crypto';
+/**
+ * Splits a markdown document into chunks at heading boundaries.
+ * Each chunk contains the heading path (e.g. "Parent > Child") and the
+ * text content under that heading (exclusive of sub-headings' text).
+ */
+export function chunkMarkdown(markdown, sourceFile, sourceType) {
+    const lines = markdown.split('\n');
+    const chunks = [];
+    // headingStack[i] is the text of the heading at level (i+1)
+    const headingStack = [];
+    let buffer = [];
+    const flushBuffer = (path) => {
+        const text = buffer.join('\n').trim();
+        buffer = [];
+        if (!text)
+            return;
+        const id = createHash('sha1')
+            .update(`${sourceFile}::${path}`)
+            .digest('hex')
+            .slice(0, 16);
+        chunks.push({ id, sourceFile, sourceType, headingPath: path, content: text });
+    };
+    const getPath = () => headingStack.length > 0 ? headingStack.join(' > ') : sourceFile;
+    for (const line of lines) {
+        const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+        if (headingMatch) {
+            // Flush whatever was accumulated under the previous heading
+            flushBuffer(getPath());
+            const level = headingMatch[1].length;
+            const title = headingMatch[2].trim();
+            // Trim the stack to the parent level and push new heading
+            headingStack.splice(level - 1);
+            headingStack[level - 1] = title;
+        }
+        else {
+            buffer.push(line);
+        }
+    }
+    // Flush the last section
+    flushBuffer(getPath());
+    return chunks;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superkit-mcp-server",
-  "version": "1.2.8",
+  "version": "1.3.1",
   "type": "module",
   "description": "An MCP server for exploring and loading Super-Kit AI agent resources.",
   "main": "build/index.js",
@@ -15,6 +15,7 @@
     "dev": "tsc --watch"
   },
   "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
     "@iarna/toml": "^2.2.5",
     "@modelcontextprotocol/sdk": "^1.4.1",
     "playwright": "^1.58.2",
@@ -36,4 +37,4 @@
     "README.md",
     "ARCHITECTURE.md"
   ]
-}
+}

package/skills/meta/api-design/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: api-design
+description: RESTful API patterns, GraphQL design, and API best practices. Use when designing APIs, choosing between REST/GraphQL/tRPC, structuring endpoints, versioning, or documenting APIs.
+---
+
 # API Design Skill
 
 ## Overview

package/skills/meta/docker/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: docker
+description: Container optimization, multi-stage builds, Docker Compose, and Docker best practices. Use when writing Dockerfiles, setting up containers, or optimizing image size.
+---
+
 # Docker Skill
 
 ## Overview

package/skills/meta/mobile/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: mobile
+description: React Native, Flutter, and mobile development best practices. Use when building mobile apps, handling platform-specific behavior, or optimizing mobile performance.
+---
+
 # Mobile Development Skill
 
 ## Overview

package/skills/meta/nextjs/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: nextjs
+description: Next.js App Router architecture, Server Components, and modern patterns. Use when building Next.js apps, choosing rendering strategies, or optimizing data fetching.
+---
+
 # Next.js Best Practices Skill
 
 ## Overview

package/skills/meta/performance/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: performance
+description: Performance profiling, optimization techniques, and caching strategies. Use when diagnosing slow applications, improving Core Web Vitals, or optimizing database queries and bundle size.
+---
+
 # Performance Optimization Skill
 
 ## Overview

package/skills/meta/react-patterns/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: react-patterns
+description: Modern React patterns, hooks, and state management principles. Use when structuring React components, managing state, optimizing re-renders, or choosing state management libraries.
+---
+
 # React Patterns Skill
 
 ## Overview

package/skills/meta/security/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: security
+description: Security audit, vulnerability scanning, and secure coding practices. Use when reviewing code for OWASP vulnerabilities, implementing auth, securing APIs, or handling sensitive data.
+---
+
 # Security Skill
 
 ## Overview

package/skills/meta/tailwind/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: tailwind
+description: Tailwind CSS v4 patterns, design systems, and responsive design. Use when styling with Tailwind, building design tokens, creating responsive layouts, or implementing dark mode.
+---
+
 # Tailwind CSS Skill
 
 ## Overview

package/skills/tech/financial-modeling/skills/merger-model/SKILL.md

@@ -1,6 +1,9 @@
-# Merger Model
-
+---
+name: merger-model
 description: Build accretion/dilution analysis for M&A transactions. Models pro forma EPS impact, synergy sensitivities, and purchase price allocation. Use when evaluating a potential acquisition, preparing merger consequences analysis for a pitch, or advising on deal terms. Triggers on "merger model", "accretion dilution", "M&A model", "pro forma EPS", "merger consequences", or "deal impact analysis".
+---
+
+# Merger Model
 
 ## Workflow