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

package/README.md

@@ -1049,6 +1049,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/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/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>/`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-beta.166",
+  "version": "0.1.0-beta.167",
   "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",