@kinqs/brainrouter-mcp-server 0.3.4

package/dist/tools/memory_search.js

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { memoryEngine } from '../memory/engine.js';
+export const memorySearchToolSchema = {
+    name: 'memory_search',
+    description: 'Perform a semantic or keyword search across memory records. ' +
+        'Use this when automatic recall was insufficient. ' +
+        'Optionally pass `asOf` (ISO 8601) to query what memories were valid at a specific point in time, ' +
+        'or `filters` to narrow by type / scene / time window / priority / skillTag.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            userId: { type: 'string', description: 'User identifier for isolation' },
+            query: { type: 'string', description: 'Search query' },
+            sessionKey: { type: 'string', description: 'Session identifier' },
+            activeSkill: { type: 'string', description: 'Current active skill boost' },
+            limit: { type: 'number', description: 'Max results to return (default 10)' },
+            asOf: {
+                type: 'string',
+                description: 'Optional ISO 8601 timestamp for point-in-time recall. ' +
+                    'Returns memories that existed AND were valid at this moment. ' +
+                    'Example: "2025-03-15T12:00:00.000Z"',
+            },
+            filters: {
+                type: 'object',
+                description: 'Optional filters narrowing the candidate pool before ranking.',
+                properties: {
+                    types: { type: 'array', items: { type: 'string' }, description: "Whitelist of memory types (e.g. ['instruction', 'feedback'])." },
+                    scenes: { type: 'array', items: { type: 'string' }, description: 'Whitelist of contextual focus scene names.' },
+                    capturedAfter: { type: 'string', description: 'ISO 8601 lower bound on created_time.' },
+                    capturedBefore: { type: 'string', description: 'ISO 8601 upper bound on created_time.' },
+                    minPriority: { type: 'number', description: 'Drop records whose stored priority is below this threshold (0-100).' },
+                    skillTag: { type: 'string', description: 'Restrict to records produced under this skill tag.' },
+                },
+            },
+        },
+        required: ['query', 'sessionKey'],
+    },
+};
+export const memorySearchSchema = z.object({
+    userId: z.string().optional(),
+    query: z.string(),
+    sessionKey: z.string(),
+    activeSkill: z.string().optional(),
+    limit: z.number().int().positive().optional(),
+    asOf: z.string().optional(),
+    filters: z.object({
+        types: z.array(z.string()).optional(),
+        scenes: z.array(z.string()).optional(),
+        capturedAfter: z.string().optional(),
+        capturedBefore: z.string().optional(),
+        minPriority: z.number().optional(),
+        skillTag: z.string().optional(),
+    }).optional(),
+});
+export async function handleMemorySearch(args, options) {
+    const params = memorySearchSchema.parse(args);
+    const effectiveUserId = params.userId ?? options?.defaultUserId ?? "default";
+    try {
+        // Point-in-time search path
+        if (params.asOf) {
+            const result = memoryEngine.searchAsOf(effectiveUserId, params.query, params.asOf, params.limit ?? 10);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        // Standard recall path
+        const result = await memoryEngine.recall({
+            userId: effectiveUserId,
+            sessionKey: params.sessionKey,
+            query: params.query,
+            activeSkill: params.activeSkill,
+            filters: params.filters,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [{ type: 'text', text: `memory_search failed: ${err.message}` }],
+        };
+    }
+}

package/dist/tools/search_skills.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import type { Registry } from '../registry.js';
+export declare const searchSkillsSchema: z.ZodObject<{
+    query: z.ZodString;
+    scope: z.ZodDefault<z.ZodOptional<z.ZodEnum<["global", "local", "all"]>>>;
+}, "strip", z.ZodTypeAny, {
+    scope: "global" | "local" | "all";
+    query: string;
+}, {
+    query: string;
+    scope?: "global" | "local" | "all" | undefined;
+}>;
+export declare function searchSkills(registry: Registry, args: z.infer<typeof searchSkillsSchema>): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/tools/search_skills.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export const searchSkillsSchema = z.object({
+    query: z.string(),
+    scope: z.enum(['global', 'local', 'all']).optional().default('all'),
+});
+export async function searchSkills(registry, args) {
+    const results = registry.searchSkills(args.query, args.scope);
+    const sanitized = results.map(({ filePath, ...rest }) => rest);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(sanitized, null, 2),
+            },
+        ],
+    };
+}

package/dist/tools/update_doc.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import type { Registry } from '../registry.js';
+export declare const updateDocSchema: z.ZodObject<{
+    name: z.ZodString;
+    section: z.ZodString;
+    content: z.ZodString;
+    createIfMissing: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    content: string;
+    section: string;
+    createIfMissing: boolean;
+}, {
+    name: string;
+    content: string;
+    section: string;
+    createIfMissing?: boolean | undefined;
+}>;
+export declare function updateDoc(registry: Registry, args: z.infer<typeof updateDocSchema>): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/tools/update_doc.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { join } from 'path';
+import { updateDocSection } from '../writer.js';
+export const updateDocSchema = z.object({
+    name: z.string(),
+    section: z.string(),
+    content: z.string(),
+    createIfMissing: z.boolean().optional().default(true),
+});
+export async function updateDoc(registry, args) {
+    const localRoot = registry.getLocalRoot();
+    if (!localRoot) {
+        throw new Error('No local root detected. Documentation updates are only allowed in project repositories.');
+    }
+    const manifest = registry.getDoc(args.name);
+    let filePath;
+    if (manifest) {
+        filePath = manifest.filePath;
+    }
+    else {
+        if (!args.createIfMissing) {
+            throw new Error(`Document "${args.name}" not found.`);
+        }
+        filePath = join(localRoot, 'docs', `${args.name}.md`);
+    }
+    updateDocSection(filePath, args.section, args.content, localRoot, args.createIfMissing);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Successfully updated section "${args.section}" in ${manifest ? manifest.name : args.name}.`,
+            },
+        ],
+    };
+}

package/dist/tools/update_skill.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import type { Registry } from '../registry.js';
+export declare const updateSkillSchema: z.ZodObject<{
+    name: z.ZodString;
+    section: z.ZodEnum<["overview", "workflow", "usage", "detailed_instructions", "checklist", "full"]>;
+    content: z.ZodString;
+    targetScope: z.ZodOptional<z.ZodEnum<["global", "local"]>>;
+    project: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    content: string;
+    section: "overview" | "workflow" | "usage" | "detailed_instructions" | "checklist" | "full";
+    project?: string | undefined;
+    targetScope?: "global" | "local" | undefined;
+}, {
+    name: string;
+    content: string;
+    section: "overview" | "workflow" | "usage" | "detailed_instructions" | "checklist" | "full";
+    project?: string | undefined;
+    targetScope?: "global" | "local" | undefined;
+}>;
+export declare function updateSkill(registry: Registry, args: z.infer<typeof updateSkillSchema>): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    metadata: {
+        scope: import("../types.js").SkillScope;
+    };
+}>;

package/dist/tools/update_skill.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { mkdirSync } from 'fs';
+import { updateSkillSection } from '../writer.js';
+export const updateSkillSchema = z.object({
+    name: z.string(),
+    section: z.enum(['overview', 'workflow', 'usage', 'detailed_instructions', 'checklist', 'full']),
+    content: z.string(),
+    targetScope: z.enum(['global', 'local']).optional(),
+    project: z.string().optional(),
+});
+export async function updateSkill(registry, args) {
+    const manifest = registry.getSkill(args.name);
+    if (!manifest) {
+        throw new Error(`Skill "${args.name}" not found.`);
+    }
+    const localRoot = registry.getLocalRoot();
+    const globalRoot = registry.getGlobalRoot();
+    const localProjectName = registry.getLocalProjectName();
+    // Decide where to write
+    const scope = args.targetScope ?? (manifest.scope === 'global' ? 'local' : 'local');
+    const targetRoot = scope === 'global' ? globalRoot : localRoot;
+    if (!targetRoot) {
+        throw new Error(`No ${scope} root detected.`);
+    }
+    let filePath = manifest.filePath;
+    if (scope === 'global') {
+        // We want to write to global. If it's currently local, we determine the global destination.
+        if (manifest.scope === 'local') {
+            const project = args.project ?? manifest.project ?? localProjectName;
+            if (!project) {
+                throw new Error('Project name is required to promote a skill to global scope.');
+            }
+            const baseFolder = 'projects';
+            const projectFolder = project;
+            const globalSkillDir = join(globalRoot, baseFolder, projectFolder, 'skills', manifest.category, manifest.name);
+            filePath = join(globalSkillDir, 'SKILL.md');
+            if (!readFileSync(filePath, { flag: 'a+' })) {
+                mkdirSync(globalSkillDir, { recursive: true });
+                const localContent = readFileSync(manifest.filePath, 'utf-8');
+                writeFileSync(filePath, localContent, 'utf-8');
+            }
+        }
+    }
+    else {
+        // Default/Local scope: shadow global if necessary
+        if (!localRoot) {
+            throw new Error('Local root not detected. Cannot update local skills.');
+        }
+        if (manifest.scope === 'global') {
+            // In local repos, we MUST use projects/ folder
+            const project = localProjectName;
+            if (!project) {
+                throw new Error('Project name is required to shadow a global skill locally.');
+            }
+            const localSkillDir = join(localRoot, 'projects', project, 'skills', manifest.category, manifest.name);
+            const localSkillPath = join(localSkillDir, 'SKILL.md');
+            if (!readFileSync(localSkillPath, { flag: 'a+' })) {
+                mkdirSync(localSkillDir, { recursive: true });
+                const globalContent = readFileSync(manifest.filePath, 'utf-8');
+                writeFileSync(localSkillPath, globalContent, 'utf-8');
+            }
+            filePath = localSkillPath;
+        }
+    }
+    updateSkillSection(filePath, args.section, args.content, targetRoot);
+    registry.refresh();
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Successfully updated section "${args.section}" of skill "${args.name}" in ${scope} registry.`,
+            },
+        ],
+        metadata: {
+            scope: registry.getSkill(args.name)?.scope ?? scope,
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+export type SkillScope = 'global' | 'local';
+export type DocCategory = 'api' | 'design' | 'schema' | 'deployment' | 'hooks' | 'strategy' | 'other';
+/**
+ * Every named section extractable from a SKILL.md.
+ * Ordered cheapest → most expensive by token count.
+ */
+export type SkillSection = 'description' | 'overview' | 'when_to_use' | 'workflow' | 'usage' | 'detailed_instructions' | 'phases' | 'checklist' | 'red_flags' | 'rationalizations' | 'full';
+export interface SkillManifest {
+    /** kebab-case slug matching directory name and frontmatter `name` */
+    name: string;
+    /** subcategory folder: agent | api | devops | lifecycle | design | … */
+    category: string;
+    /** from YAML frontmatter `description` field */
+    description: string;
+    /** absolute path to SKILL.md */
+    filePath: string;
+    /** global = BrainRouter repo; local = downstream project repo */
+    scope: SkillScope;
+    /** Optional project name for project-specific skills */
+    project?: string;
+}
+export interface DocManifest {
+    /** lowercase slug e.g. "api", "design", "schema" */
+    name: string;
+    category: DocCategory;
+    /** absolute path to the doc file */
+    filePath: string;
+    lastModified: Date;
+}
+export interface PersonaManifest {
+    /** kebab-case e.g. "code-reviewer", "security-auditor" */
+    name: string;
+    filePath: string;
+}
+export interface ReferenceManifest {
+    /** kebab-case e.g. "security-checklist", "testing-patterns" */
+    name: string;
+    filePath: string;
+}
+/** The unit returned to an agent — extracted content + provenance. */
+export interface Fragment {
+    /** The extracted text content */
+    content: string;
+    /** Relative path for traceability (e.g. "skills/agent/bootstrap/SKILL.md") */
+    source: string;
+    /** Only present for skill fragments */
+    scope?: SkillScope;
+    /** Rough token estimate: Math.ceil(content.length / 4) */
+    tokenEstimate: number;
+}
+export interface RegistryConfig {
+    /** Absolute path to BrainRouter repo root (always resolved from __dirname) */
+    globalRoot: string;
+    /** Absolute path to downstream project repo root (optional) */
+    localRoot?: string;
+    /** Name of the local project (from brainrouter.config.json) */
+    localProjectName?: string;
+}
+/** Shape of brainrouter.config.json in a downstream repo */
+export interface BrainRouterConfig {
+    project?: string;
+    techStack?: string[];
+    localSkillsPath?: string;
+    localDocsPath?: string;
+    activeCategories?: string[];
+}
+export interface CreateSkillResult {
+    created: true;
+    path: string;
+    tokenEstimate: number;
+}
+export interface UpdateSkillResult {
+    updated: true;
+    path: string;
+    scope: SkillScope;
+}
+export interface UpdateDocResult {
+    updated: true;
+    path: string;
+    section: string;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// ─────────────────────────────────────────────
+// BrainRouter MCP Server — Shared Types
+// ─────────────────────────────────────────────
+export {};

package/dist/writer.d.ts

@@ -0,0 +1,30 @@
+import type { SkillSection } from './types.js';
+export interface ScaffoldSkillParams {
+    name: string;
+    category: string;
+    description: string;
+    targetRoot: string;
+    project?: string;
+    overview?: string;
+    when_to_use?: string;
+    workflow?: string[];
+    usage?: string;
+    checklist?: string[];
+}
+/**
+ * Create a new SKILL.md in the specified registry.
+ * Returns the absolute path of the created file.
+ */
+export declare function scaffoldSkill(params: ScaffoldSkillParams): string;
+/**
+ * Update a named ## section in an existing SKILL.md.
+ * If section is "full", replaces the entire body content.
+ * Returns the absolute path of the updated file.
+ */
+export declare function updateSkillSection(filePath: string, section: Extract<SkillSection, 'overview' | 'workflow' | 'usage' | 'detailed_instructions' | 'checklist' | 'full'>, newContent: string, targetRoot: string): string;
+/**
+ * Update a named ## section in a project doc (API.md, Design.md, etc.).
+ * If createIfMissing is true and the section doesn't exist, it is appended.
+ * Returns the absolute path of the updated file.
+ */
+export declare function updateDocSection(filePath: string, sectionHeading: string, newContent: string, targetRoot: string, createIfMissing?: boolean): string;

package/dist/writer.js

@@ -0,0 +1,220 @@
+// ─────────────────────────────────────────────
+// BrainRouter MCP Server — Safe Writer
+// Creates and updates markdown files in localRoot or globalRoot.
+// ─────────────────────────────────────────────
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { resolve, join, relative, dirname, basename } from 'path';
+import matter from 'gray-matter';
+// ─── Safety Guard ────────────────────────────
+/**
+ * Throws if targetPath is not inside allowedRoot.
+ * Prevents unauthorized writes outside project roots.
+ */
+function assertInsideRoot(targetPath, allowedRoot) {
+    const resolvedTarget = resolve(targetPath);
+    const resolvedRoot = resolve(allowedRoot);
+    const rel = relative(resolvedRoot, resolvedTarget);
+    if (rel.startsWith('..') || resolvedTarget === resolvedRoot) {
+        throw new Error(`WRITE BLOCKED: "${targetPath}" is outside the allowed root "${allowedRoot}".`);
+    }
+    // Block writes to the universal skills folder to prevent agents from modifying core skills
+    const firstPart = rel.split('/')[0];
+    if (firstPart === 'skills') {
+        throw new Error(`WRITE BLOCKED: Modifying the universal "skills/" folder is not allowed. All skills must be stored in "projects/".`);
+    }
+}
+// ─── Skill Authoring Template ────────────────
+/**
+ * Generates a canonical SKILL.md from the skill-authoring template structure.
+ */
+function buildSkillTemplate(params) {
+    const { name, category, description, overview, when_to_use, workflow, usage, checklist } = params;
+    const workflowSection = workflow?.length
+        ? workflow.map((step, i) => `${i + 1}. ${step}`).join('\n')
+        : '1. [Step 1]\n2. [Step 2]\n3. [Step 3]';
+    const checklistSection = checklist?.length
+        ? checklist.map((item) => `- [ ] ${item}`).join('\n')
+        : '- [ ] [Verification item 1]\n- [ ] [Verification item 2]';
+    return `---
+name: ${name}
+category: ${category}
+description: ${description}
+---
+
+# ${name
+        .split('-')
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(' ')}
+
+## Overview
+${overview ?? '[One-two sentences explaining what this skill does and why it matters.]'}
+
+## When to Use
+${when_to_use ?? '- [Triggering condition 1]\n- [Triggering condition 2]\n- NOT for: [exclusions]'}
+
+## Workflow
+
+${workflowSection}
+
+## Usage
+
+\`\`\`bash
+# [Example command or trigger phrase]
+\`\`\`
+
+${usage ? `${usage}\n\n` : ''}## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| [Excuse an agent might use to skip a step] | [Why that excuse is wrong] |
+
+## Red Flags
+- [Observable sign that this skill is being violated]
+
+## Verification
+${checklistSection}
+`;
+}
+/**
+ * Create a new SKILL.md in the specified registry.
+ * Returns the absolute path of the created file.
+ */
+export function scaffoldSkill(params) {
+    const { name, category, targetRoot, project, ...rest } = params;
+    // Skills MUST follow projects/<project_name>/skills/<category>/<name>/ structure
+    if (!project) {
+        throw new Error('Project name is required to create a skill.');
+    }
+    const baseFolder = 'projects';
+    const projectFolder = project;
+    const skillDir = join(targetRoot, baseFolder, projectFolder, 'skills', category, name);
+    const skillPath = join(skillDir, 'SKILL.md');
+    assertInsideRoot(skillPath, targetRoot);
+    if (existsSync(skillPath)) {
+        throw new Error(`Skill "${name}" already exists at "${skillPath}". Use update_skill to modify it.`);
+    }
+    mkdirSync(skillDir, { recursive: true });
+    const content = buildSkillTemplate({ name, category, ...rest });
+    writeFileSync(skillPath, content, 'utf-8');
+    return skillPath;
+}
+// ─── Section Update ──────────────────────────
+const UPDATABLE_SECTIONS = {
+    overview: ['overview'],
+    workflow: ['workflow', 'core process', 'the workflow', 'steps', 'process'],
+    usage: ['usage', 'example usage', 'examples'],
+    detailed_instructions: ['detailed instructions', 'instructions'],
+    checklist: ['verification', 'required checks'],
+};
+/**
+ * Update a named ## section in an existing SKILL.md.
+ * If section is "full", replaces the entire body content.
+ * Returns the absolute path of the updated file.
+ */
+export function updateSkillSection(filePath, section, newContent, targetRoot) {
+    assertInsideRoot(filePath, targetRoot);
+    const raw = readFileSync(filePath, 'utf-8');
+    const parsed = matter(raw);
+    if (section === 'full') {
+        // Replace entire body, preserve frontmatter
+        const updated = matter.stringify(newContent, parsed.data);
+        writeFileSync(filePath, updated, 'utf-8');
+        return filePath;
+    }
+    const aliases = UPDATABLE_SECTIONS[section] ?? [section.replace(/_/g, ' ')];
+    const lines = parsed.content.split('\n');
+    const result = [];
+    let inTarget = false;
+    let replaced = false;
+    for (const line of lines) {
+        const h2Match = line.match(/^##\s+(.+)/);
+        if (h2Match) {
+            const heading = h2Match[1].trim().toLowerCase();
+            if (aliases.some((a) => heading.includes(a))) {
+                inTarget = true;
+                result.push(line); // keep the heading
+                result.push('');
+                result.push(newContent.trim());
+                result.push(''); // Ensure blank line before next section
+                replaced = true;
+                continue;
+            }
+            else if (inTarget) {
+                inTarget = false;
+            }
+        }
+        if (!inTarget)
+            result.push(line);
+    }
+    if (!replaced) {
+        // Section not found — append it
+        result.push('');
+        result.push(`## ${section.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase())}`);
+        result.push('');
+        result.push(newContent.trim());
+        result.push('');
+    }
+    const updatedBody = result.join('\n');
+    const updatedFile = matter.stringify(updatedBody, parsed.data);
+    writeFileSync(filePath, updatedFile, 'utf-8');
+    return filePath;
+}
+// ─── Doc Update ─────────────────────────────
+/**
+ * Update a named ## section in a project doc (API.md, Design.md, etc.).
+ * If createIfMissing is true and the section doesn't exist, it is appended.
+ * Returns the absolute path of the updated file.
+ */
+export function updateDocSection(filePath, sectionHeading, newContent, targetRoot, createIfMissing = true) {
+    assertInsideRoot(filePath, targetRoot);
+    mkdirSync(dirname(filePath), { recursive: true });
+    let raw = '';
+    if (existsSync(filePath)) {
+        raw = readFileSync(filePath, 'utf-8');
+    }
+    else {
+        if (!createIfMissing) {
+            throw new Error(`File "${filePath}" not found.`);
+        }
+        const name = basename(filePath, '.md').toUpperCase();
+        raw = `# ${name}\n`;
+    }
+    const lines = raw.split('\n');
+    const result = [];
+    let inTarget = false;
+    let replaced = false;
+    for (const line of lines) {
+        const h2Match = line.match(/^##\s+(.+)/);
+        if (h2Match) {
+            const heading = h2Match[1].trim().toLowerCase();
+            if (heading.includes(sectionHeading.toLowerCase())) {
+                inTarget = true;
+                result.push(line);
+                result.push('');
+                result.push(newContent.trim());
+                result.push(''); // Ensure blank line before next section
+                replaced = true;
+                continue;
+            }
+            else if (inTarget) {
+                inTarget = false;
+            }
+        }
+        if (!inTarget)
+            result.push(line);
+    }
+    if (!replaced) {
+        if (!createIfMissing) {
+            throw new Error(`Section "${sectionHeading}" not found in "${filePath}".`);
+        }
+        result.push('');
+        result.push(`## ${sectionHeading}`);
+        result.push('');
+        result.push(newContent.trim());
+        result.push('');
+    }
+    writeFileSync(filePath, result.join('\n'), 'utf-8');
+    // Ensure the directory for the file exists (already should, but safe)
+    mkdirSync(dirname(filePath), { recursive: true });
+    return filePath;
+}

package/docs/TEMPLATE ONLY

@@ -0,0 +1 @@
+E