@andespindola/brainlink 0.1.0-beta.166 → 0.1.0-beta.168

package/README.md

@@ -717,6 +717,21 @@ When the configured default vault is changed manually in config files, Brainlink
 Use `--global` to write to `$BRAINLINK_HOME/brainlink.config.json`, `--no-migrate` to skip migration, and `--no-index` to skip post-migration indexing.
 `config doctor` is dry-run by default; use `--fix` to apply safe config normalization and allowlist fixes.
 
+### `vaults`
+
+```bash
+blink vaults list
+blink vaults list --json
+blink vaults use /absolute/path/to/vault
+blink vaults use /absolute/path/to/vault --global
+blink vaults delete /absolute/path/to/vault --yes
+blink vaults delete /absolute/path/to/vault --yes --prune-config
+```
+
+Lists known vaults from the configured default, `allowedVaults`, and the built-in default at `$HOME/.brainlink/vault`.
+`vaults use` chooses the default vault without migrating memory; use `migrate-vault` or `config set-vault --migrate-from` when you want to copy Markdown memory between vaults.
+`vaults delete` only deletes local filesystem vaults, requires `--yes`, refuses bucket vaults, and refuses deleting the current default vault. Choose another default first with `vaults use`.
+
 ### `migrate-vault`
 
 ```bash
@@ -1049,6 +1064,89 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
 `autoIndexOnWrite` is optional and defaults to `true`. Set it to `false` to defer indexing after writes.
 `autoCanonicalContextLinks` is optional and defaults to `true`. When enabled, `blink add`, `brainlink_add_note` and `brainlink_add_file` add a canonical `## Context Links` entry to the inferred context hub, creating that hub when needed.
 
+## Remote MCP Server
+
+Brainlink can run as a centralized MCP service for clustered workloads. This keeps one shared memory service inside the cluster while applications and agents connect to the MCP endpoint over Streamable HTTP.
+
+```bash
+BRAINLINK_MCP_TOKEN="change-me" brainlink mcp-server \
+  --vault /data/vault \
+  --host 0.0.0.0 \
+  --port 3333 \
+  --path /mcp
+```
+
+The server exposes:
+
+```txt
+POST /mcp      MCP Streamable HTTP endpoint
+GET /healthz  liveness probe
+GET /readyz   readiness probe
+```
+
+When `BRAINLINK_MCP_TOKEN` or `--token` is set, MCP requests must include:
+
+```txt
+Authorization: Bearer <token>
+```
+
+For Kubernetes, run Brainlink as a central `Deployment` with a `Service` and a mounted vault volume:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: brainlink-mcp
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: brainlink-mcp
+  template:
+    metadata:
+      labels:
+        app: brainlink-mcp
+    spec:
+      containers:
+        - name: brainlink
+          image: brainlink:latest
+          args: ["brainlink", "mcp-server", "--vault", "/data/vault", "--host", "0.0.0.0", "--port", "3333"]
+          env:
+            - name: BRAINLINK_MCP_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: brainlink-mcp
+                  key: token
+          ports:
+            - containerPort: 3333
+          readinessProbe:
+            httpGet:
+              path: /readyz
+              port: 3333
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: 3333
+          volumeMounts:
+            - name: vault
+              mountPath: /data/vault
+      volumes:
+        - name: vault
+          persistentVolumeClaim:
+            claimName: brainlink-vault
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: brainlink-mcp
+spec:
+  selector:
+    app: brainlink-mcp
+  ports:
+    - port: 3333
+      targetPort: 3333
+```
+
 Use `"embeddingProvider": "none"` when you want FTS-only indexing.
 
 For local security checks, set your Snyk token in the environment:

package/dist/cli/commands/vault-commands.js

@@ -0,0 +1,182 @@
+import { readdir, readFile, rm, stat } from 'node:fs/promises';
+import { extname, isAbsolute, join } from 'node:path';
+import { doctorVault } from '../../application/analyze-vault.js';
+import { defaultBrainlinkConfig, loadBrainlinkConfig, loadRawConfig, writeRawConfig } from '../../infrastructure/config.js';
+import { assertVaultAllowed, isBucketVaultPath, resolveVaultPath } from '../../infrastructure/file-system-vault.js';
+import { print } from '../runtime.js';
+const excludedDirectories = new Set(['.git', 'node_modules', 'dist']);
+const resolveScope = (globalOption) => globalOption ? 'global' : 'local';
+const normalizeVaultPath = (vault) => assertVaultAllowed(vault, []);
+const uniqueValues = (values) => Array.from(new Set(values));
+const sameVault = (left, right) => normalizeVaultPath(left) === normalizeVaultPath(right);
+const isDirectory = async (path) => {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+const countMarkdownFiles = async (directory) => {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const counts = await Promise.all(entries.map(async (entry) => {
+        const absolutePath = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            return excludedDirectories.has(entry.name) ? 0 : countMarkdownFiles(absolutePath);
+        }
+        return entry.isFile() && extname(entry.name).toLowerCase() === '.md' ? 1 : 0;
+    }));
+    return counts.reduce((total, count) => total + count, 0);
+};
+const readIndexedDocumentCount = async (vaultPath) => {
+    try {
+        const raw = await readFile(join(vaultPath, '.brainlink', 'index.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed.documents) ? parsed.documents.length : null;
+    }
+    catch {
+        return null;
+    }
+};
+const addCandidate = (state, path, source) => {
+    const normalized = normalizeVaultPath(path);
+    const current = state.get(normalized);
+    return new Map(state).set(normalized, {
+        path: normalized,
+        sources: uniqueValues([...(current?.sources ?? []), source])
+    });
+};
+const listVaultEntries = async () => {
+    const config = await loadBrainlinkConfig();
+    const candidates = [config.vault, ...config.allowedVaults, defaultBrainlinkConfig.vault].reduce((state, path, index) => addCandidate(state, path, index === 0 ? 'configured' : path === defaultBrainlinkConfig.vault ? 'default' : 'allowed'), new Map());
+    const entries = await Promise.all(Array.from(candidates.values()).map(async (candidate) => {
+        if (isBucketVaultPath(candidate.path)) {
+            return {
+                path: candidate.path,
+                sources: candidate.sources,
+                current: sameVault(candidate.path, config.vault),
+                kind: 'bucket',
+                exists: null,
+                markdownCount: null,
+                indexedDocumentCount: null
+            };
+        }
+        const path = resolveVaultPath(candidate.path);
+        const exists = await isDirectory(path);
+        return {
+            path,
+            sources: candidate.sources,
+            current: sameVault(path, config.vault),
+            kind: 'local',
+            exists,
+            markdownCount: exists ? await countMarkdownFiles(path) : null,
+            indexedDocumentCount: exists ? await readIndexedDocumentCount(path) : null
+        };
+    }));
+    return entries.sort((left, right) => Number(right.current) - Number(left.current) || left.path.localeCompare(right.path));
+};
+const removeVaultFromAllowedVaults = async (vaultPath) => {
+    const scopes = ['local', 'global'];
+    await Promise.all(scopes.map(async (scope) => {
+        const rawConfig = await loadRawConfig(scope);
+        const allowedVaults = Array.isArray(rawConfig.allowedVaults)
+            ? rawConfig.allowedVaults.filter((path) => typeof path === 'string')
+            : [];
+        const nextAllowedVaults = allowedVaults.filter((path) => !sameVault(path, vaultPath));
+        if (nextAllowedVaults.length === allowedVaults.length) {
+            return;
+        }
+        await writeRawConfig(scope, {
+            ...rawConfig,
+            allowedVaults: nextAllowedVaults
+        });
+    }));
+};
+export const registerVaultCommands = (program) => {
+    const vaultsCommand = program.command('vaults').description('list, choose and delete Brainlink vaults');
+    vaultsCommand
+        .command('list')
+        .option('--json', 'print machine-readable JSON')
+        .description('list known Brainlink vaults from config and defaults')
+        .action(async (options) => {
+        const config = await loadBrainlinkConfig();
+        const vaults = await listVaultEntries();
+        print(options.json, {
+            currentVault: config.vault,
+            vaults
+        }, () => vaults
+            .map((vault) => {
+            const status = vault.exists === null ? 'remote' : vault.exists ? 'exists' : 'missing';
+            const counts = vault.markdownCount === null
+                ? ''
+                : ` markdown=${vault.markdownCount} indexed=${vault.indexedDocumentCount ?? 'unknown'}`;
+            return `${vault.current ? '* ' : '  '}${vault.path} [${vault.sources.join(',')}; ${status}; ${vault.kind}]${counts}`;
+        })
+            .join('\n'));
+    });
+    vaultsCommand
+        .command('use <vault>')
+        .option('--global', 'write to global config in $BRAINLINK_HOME/brainlink.config.json')
+        .option('--no-allowlist', 'do not append the vault to allowedVaults in the target config file')
+        .option('--json', 'print machine-readable JSON')
+        .description('choose the default Brainlink vault without migrating memory')
+        .action(async (vault, options) => {
+        const scope = resolveScope(options.global);
+        const before = await loadBrainlinkConfig();
+        const targetVault = normalizeVaultPath(vault);
+        const rawConfig = await loadRawConfig(scope);
+        const shouldAllowlist = options.allowlist !== false;
+        const allowedVaults = Array.isArray(rawConfig.allowedVaults)
+            ? rawConfig.allowedVaults.filter((path) => typeof path === 'string')
+            : [];
+        const nextAllowedVaults = shouldAllowlist ? uniqueValues([...allowedVaults, targetVault]) : allowedVaults;
+        const configPath = await writeRawConfig(scope, {
+            ...rawConfig,
+            vault: targetVault,
+            allowedVaults: nextAllowedVaults
+        });
+        const doctor = await doctorVault(targetVault);
+        print(options.json, {
+            scope,
+            configPath,
+            previousVault: before.vault,
+            vault: targetVault,
+            doctor
+        }, () => `Default ${scope} vault set to ${targetVault} in ${configPath}.`);
+    });
+    vaultsCommand
+        .command('delete <vault>')
+        .option('--yes', 'confirm destructive vault deletion')
+        .option('--prune-config', 'remove the vault from allowedVaults after deletion')
+        .option('--json', 'print machine-readable JSON')
+        .description('delete a local filesystem vault after explicit confirmation')
+        .action(async (vault, options) => {
+        const config = await loadBrainlinkConfig();
+        const targetVault = normalizeVaultPath(vault);
+        if (isBucketVaultPath(targetVault)) {
+            throw new Error('Refusing to delete bucket vaults from the CLI. Remove bucket data with your storage provider tooling.');
+        }
+        const absoluteVault = resolveVaultPath(targetVault);
+        if (!isAbsolute(absoluteVault)) {
+            throw new Error(`Refusing to delete non-absolute vault path: ${absoluteVault}`);
+        }
+        if (sameVault(absoluteVault, config.vault)) {
+            throw new Error('Refusing to delete the current default vault. Choose another default with `blink vaults use <vault>` first.');
+        }
+        if (options.yes !== true) {
+            throw new Error('Refusing to delete vault without --yes.');
+        }
+        const existed = await isDirectory(absoluteVault);
+        if (existed) {
+            await rm(absoluteVault, { recursive: true, force: false });
+        }
+        if (options.pruneConfig) {
+            await removeVaultFromAllowedVaults(absoluteVault);
+        }
+        print(options.json, {
+            vault: absoluteVault,
+            deleted: existed,
+            prunedConfig: options.pruneConfig === true
+        }, () => `${existed ? 'Deleted' : 'Vault did not exist'}: ${absoluteVault}`);
+    });
+};

package/dist/cli/commands/write-commands.js

@@ -20,6 +20,7 @@ import { loadBrainlinkConfig } from '../../infrastructure/config.js';
 import { assertVaultAllowed, ensureVault, isBucketVaultPath } from '../../infrastructure/file-system-vault.js';
 import { getBootstrapPolicy, getBootstrapSessionStatus, touchBootstrapSession } from '../../infrastructure/session-state.js';
 import { addVolatileMemory, clearVolatileMemory } from '../../infrastructure/volatile-memory.js';
+import { startRemoteMcpServer } from '../../mcp/http-server.js';
 import { installAgentIntegration } from './agent-commands.js';
 import { parsePositiveInteger, print, resolveOptions } from '../runtime.js';
 const resolveAddContent = (options) => {
@@ -1105,6 +1106,38 @@ export const registerWriteCommands = (program) => {
                 ? ' (auto-open disabled)'
                 : ''}`);
     });
+    program
+        .command('mcp-server')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('-h, --host <host>', 'remote MCP server host', '0.0.0.0')
+        .option('-p, --port <port>', 'remote MCP server port', '3333')
+        .option('--path <path>', 'remote MCP endpoint path', '/mcp')
+        .option('--token <token>', 'bearer token required for MCP requests')
+        .option('--no-index', 'skip indexing before starting the MCP server')
+        .option('--json', 'print machine-readable JSON')
+        .description('start a remote MCP server for centralized cluster access')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const token = options.token ?? process.env.BRAINLINK_MCP_TOKEN;
+        const server = await startRemoteMcpServer({
+            vaultPath: resolved.vault,
+            agent: resolved.agent,
+            host: options.host ?? '0.0.0.0',
+            port: parsePositiveInteger(options.port ?? '3333', 3333),
+            path: options.path ?? '/mcp',
+            token,
+            shouldIndex: options.index
+        });
+        print(options.json, {
+            url: server.url,
+            healthUrl: server.healthUrl,
+            readyUrl: server.readyUrl,
+            vault: resolved.vault,
+            agent: resolved.agent ?? '*',
+            auth: token === undefined ? 'disabled' : 'bearer'
+        }, () => `Brainlink remote MCP server running at ${server.url} (health: ${server.healthUrl}, readiness: ${server.readyUrl})`);
+    });
     program
         .command('quickstart')
         .option('-v, --vault <vault>', 'vault directory')

package/dist/cli/main.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { registerAgentCommands } from './commands/agent-commands.js';
 import { registerConfigCommands } from './commands/config-commands.js';
 import { registerReadCommands } from './commands/read-commands.js';
+import { registerVaultCommands } from './commands/vault-commands.js';
 import { registerWriteCommands } from './commands/write-commands.js';
 const readPackageVersion = () => {
     const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
@@ -24,6 +25,7 @@ program
 registerWriteCommands(program);
 registerReadCommands(program);
 registerConfigCommands(program);
+registerVaultCommands(program);
 registerAgentCommands(program);
 program.parseAsync().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);

package/dist/mcp/http-server.js

@@ -0,0 +1,97 @@
+import { createServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { indexVault } from '../application/index-vault.js';
+import { createBrainlinkMcpServer } from './server.js';
+import { runStartupBootstrap } from './startup.js';
+const normalizePath = (path) => {
+    const trimmed = path.trim();
+    if (trimmed.length === 0) {
+        return '/mcp';
+    }
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+};
+const writeJson = (response, statusCode, value) => {
+    response.writeHead(statusCode, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store'
+    });
+    response.end(`${JSON.stringify(value)}\n`);
+};
+const readBearerToken = (authorization) => {
+    const value = Array.isArray(authorization) ? authorization[0] : authorization;
+    const match = value?.match(/^Bearer\s+(.+)$/i);
+    return match?.[1]?.trim();
+};
+const isAuthorized = (expectedToken, authorization) => expectedToken === undefined || readBearerToken(authorization) === expectedToken;
+export const startRemoteMcpServer = async (input) => {
+    const mcpPath = normalizePath(input.path);
+    const startup = await runStartupBootstrap();
+    if (input.shouldIndex) {
+        await indexVault(input.vaultPath);
+    }
+    if (startup.error) {
+        console.error(`Brainlink MCP startup bootstrap warning: ${startup.error}`);
+    }
+    const server = createServer(async (request, response) => {
+        const url = new URL(request.url ?? '/', `http://${request.headers.host ?? input.host}`);
+        if (url.pathname === '/healthz') {
+            writeJson(response, 200, { ok: true });
+            return;
+        }
+        if (url.pathname === '/readyz') {
+            writeJson(response, startup.error ? 503 : 200, {
+                ok: !startup.error,
+                vault: input.vaultPath,
+                agent: input.agent ?? startup.agent ?? '*',
+                ...(startup.error ? { error: startup.error } : {})
+            });
+            return;
+        }
+        if (url.pathname !== mcpPath) {
+            writeJson(response, 404, { error: 'Not found' });
+            return;
+        }
+        if (!isAuthorized(input.token, request.headers.authorization)) {
+            writeJson(response, 401, { error: 'Unauthorized' });
+            return;
+        }
+        try {
+            const mcpServer = createBrainlinkMcpServer();
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                enableJsonResponse: true
+            });
+            await mcpServer.connect(transport);
+            await transport.handleRequest(request, response);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            writeJson(response, 500, { error: message });
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(input.port, input.host, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const port = typeof address === 'object' && address ? address.port : input.port;
+    const publicHost = input.host === '0.0.0.0' ? '127.0.0.1' : input.host;
+    const baseUrl = `http://${publicHost}:${port}`;
+    return {
+        url: `${baseUrl}${mcpPath}`,
+        healthUrl: `${baseUrl}/healthz`,
+        readyUrl: `${baseUrl}/readyz`,
+        close: () => new Promise((resolve, reject) => {
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        })
+    };
+};

package/docs/AGENT_USAGE.md

@@ -58,6 +58,20 @@ Guardrails for benchmark acceptance are configured with `searchPack.guardrailMin
 `autoIndexOnWrite` (default: `true`) controls whether `add` and MCP write tools index right after writing.
 `autoCanonicalContextLinks` (default: `true`) controls whether CLI/MCP write tools add canonical `## Context Links` to inferred context hubs.
 
+## Central MCP Service
+
+For clustered applications, run Brainlink as one central MCP service and let workloads connect to it over Streamable HTTP:
+
+```bash
+BRAINLINK_MCP_TOKEN="change-me" brainlink mcp-server \
+  --vault /data/vault \
+  --host 0.0.0.0 \
+  --port 3333 \
+  --path /mcp
+```
+
+The central service exposes `/mcp` for MCP clients plus `/healthz` and `/readyz` for platform probes. Use a Kubernetes `Service` for internal discovery, mount the Markdown vault through a persistent volume, and pass `Authorization: Bearer <token>` from clients when `BRAINLINK_MCP_TOKEN` or `--token` is configured.
+
 ## Agent Namespaces
 
 Each agent writes into a dedicated namespace under `agents/<agent-id>/`:
@@ -371,6 +385,19 @@ blink config set-vault /absolute/path/to/vault --global
 
 `config set-vault` updates Brainlink config through CLI. By default it writes local `brainlink.config.json`, appends the vault to `allowedVaults`, and migrates markdown when the target is empty.
 
+### Manage Known Vaults
+
+```bash
+blink vaults list
+blink vaults use /absolute/path/to/vault
+blink vaults use /absolute/path/to/vault --global
+blink vaults delete /absolute/path/to/vault --yes
+```
+
+`vaults list` shows the configured default vault, allowlisted vaults and the built-in default vault, including local existence and Markdown/index counts when available.
+`vaults use` switches the default vault without migrating memory.
+`vaults delete` deletes only local filesystem vaults, requires `--yes`, and refuses deleting the current default vault.
+
 ### Migrate Vaults Explicitly
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-beta.166",
+  "version": "0.1.0-beta.168",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",
@@ -48,6 +48,7 @@
     "build": "npm run clean && npx --yes snyk test && tsc -p tsconfig.json",
     "dev": "tsx src/cli/main.ts",
     "dev:mcp": "tsx src/mcp/main.ts",
+    "dev:mcp:http": "tsx src/cli/main.ts mcp-server",
     "brainlink:sync": "bash scripts/brainlink-sync.sh",
     "security": "npx --yes snyk test",
     "test": "vitest run --config vitest.config.ts",