@andespindola/brainlink 0.1.0-alpha.1 → 0.1.0-alpha.10

package/AGENTS.md

@@ -27,12 +27,16 @@ By default, the installed Brainlink CLI uses `$HOME/.brainlink/vault` as its vau
 Use this loop when using Brainlink as memory:
 
 1. Write durable knowledge into Markdown notes.
-2. Link related notes with `[[Note Title]]`.
+2. Link related notes with explicit `[[Note Title]]` wiki links inside the note body.
 3. Add explicit `#tags` for retrieval.
 4. Run `index` after writes.
 5. Run `context "<task or question>"` before answering.
 6. Use the returned sources as grounded context.
 
+`context` is read-only. It does not create notes, backlinks, graph edges or durable memory by itself. A relationship exists only when a Markdown note contains a `[[wiki link]]` to another note and the vault has been indexed after that write.
+
+When an agent adds durable memory, it should connect the new note to at least one existing concept unless the note is intentionally a root concept. Prefer exact note titles in links, for example `[[Architecture]]`, and run `broken-links`, `orphans` or `validate` when the graph looks disconnected.
+
 ## Commands
 
 ```bash
@@ -82,7 +86,7 @@ npm run dev -- watch --vault ./vault
 Start MCP over stdio:
 
 ```bash
-npm run dev -- mcp
+npm run dev:mcp
 ```
 
 Automation-facing CLI commands support `--json`. When invoking through `npm`, use `npm run --silent dev -- ...` so stdout remains valid JSON.

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="./assets/brainlink-logo.svg" alt="Brainlink" width="720">
+</p>
+
 # Brainlink
 
 Local-first memory and knowledge graph for AI agents.
@@ -64,7 +68,7 @@ Markdown is the source of truth. `.brainlink/brainlink.db` is only a rebuildable
 - Agent namespaces under `agents/<agent-id>/`.
 - CLI with machine-readable `--json` output.
 - Short CLI alias: `blink`.
-- Compatible with MCP servers that execute local CLI commands.
+- Built-in MCP stdio server for agent tool integration.
 - Local HTTP API.
 - Realtime graph UI with agent selector and colored knowledge groups.
 
@@ -76,7 +80,7 @@ Requirements:
 - npm
 
 ```bash
-npm install -g @andespindola/brainlink
+npm install -g @andespindola/brainlink@latest
 ```
 
 The package installs two equivalent commands:
@@ -88,6 +92,14 @@ blink --help
 
 Use `brainlink` when clarity matters. Use `blink` for faster daily terminal usage.
 
+The npm package page may show `npm i @andespindola/brainlink`. That installs
+Brainlink as a project dependency. Use `-g` when you want the terminal commands
+available globally, or run it without a global install:
+
+```bash
+npx @andespindola/brainlink@latest --help
+```
+
 ## Agent Autonomous Setup
 
 This section is written for agents. If you are an AI agent operating in a user workspace, use this workflow to install and use Brainlink without requiring the user to run commands manually.
@@ -101,7 +113,7 @@ command -v blink || command -v brainlink
 If neither command exists, install it:
 
 ```bash
-npm install -g @andespindola/brainlink
+npm install -g @andespindola/brainlink@latest
 ```
 
 Then verify:
@@ -177,6 +189,15 @@ blink add "Testing Policy" \
   --content "Run npm run check before final delivery. Related: [[Release Checklist]]. #testing #process"
 ```
 
+Brainlink does not infer durable graph relationships from generated context. A context result is only a read package for the model. To create a real link in the knowledge graph, the agent must write Markdown that contains an explicit `[[Note Title]]` wiki link and then rebuild the index.
+
+When adding memory, follow this contract:
+
+- Link the new note to at least one existing note when there is a related concept.
+- Use the exact target note title inside `[[...]]`.
+- Add retrieval tags such as `#architecture`, `#decision`, `#runbook` or `#preference`.
+- Do not leave isolated notes unless they are intentionally root concepts.
+
 Rebuild the index:
 
 ```bash
@@ -199,9 +220,9 @@ Use this loop during real work:
 2. Run `blink context "<task>" --agent "$BLINK_AGENT" --json`.
 3. Use returned sources as project memory.
 4. Perform the task.
-5. Save only durable learnings with `blink add`.
+5. Save only durable learnings with `blink add`, including `[[wiki links]]` to related notes.
 6. Run `blink index`.
-7. Validate with `blink validate`.
+7. Validate with `blink validate`, `blink broken-links` and `blink orphans` when graph links matter.
 
 Do not store secrets, credentials, private keys, access tokens or transient chat noise.
 
@@ -313,50 +334,36 @@ This allows `coding-agent` and `research-agent` to both have a note named `Archi
 
 ## MCP Server Integration
 
-Brainlink is not an MCP server. It is a CLI-first memory engine.
-
-An MCP server can use Brainlink by spawning `blink` or `brainlink` as a subprocess and reading `--json` output. This keeps Brainlink decoupled from any specific MCP SDK while still making it usable by MCP-compatible agents.
-
-Minimum integration contract:
+Brainlink ships a stdio MCP server with the npm package:
 
 ```bash
-blink context "<task>" --agent "$BLINK_AGENT" --json
-blink add "Decision Title" --agent "$BLINK_AGENT" --content "Durable memory. #decision"
-blink index
+brainlink-mcp
 ```
 
-Example Node.js wrapper inside an external MCP server:
-
-```js
-import { execFile } from 'node:child_process'
-import { promisify } from 'node:util'
-
-const execFileAsync = promisify(execFile)
+Example MCP client configuration:
 
-export const brainlinkContext = async ({ vault, agent, query }) => {
-  const { stdout } = await execFileAsync('blink', [
-    'context',
-    query,
-    '--vault',
-    vault,
-    '--agent',
-    agent,
-    '--mode',
-    'hybrid',
-    '--json'
-  ])
-
-  return JSON.parse(stdout)
+```json
+{
+  "mcpServers": {
+    "brainlink": {
+      "command": "brainlink-mcp"
+    }
+  }
 }
 ```
 
-Recommended MCP tools exposed by the external server:
+Available tools:
+
+- `brainlink_context`: read indexed context for a task or question.
+- `brainlink_search`: search indexed notes.
+- `brainlink_add_note`: write durable Markdown memory and reindex.
+- `brainlink_index`: rebuild the vault index.
+- `brainlink_validate`: validate broken links and orphan notes.
+- `brainlink_graph`: read indexed graph nodes and links.
+- `brainlink_broken_links`: list unresolved wiki links.
+- `brainlink_orphans`: list disconnected notes.
 
-- `brainlink_context`: calls `blink context ... --json`.
-- `brainlink_search`: calls `blink search ... --json`.
-- `brainlink_add_note`: calls `blink add ... --json`, then `blink index`.
-- `brainlink_graph`: calls `blink graph ... --json`.
-- `brainlink_validate`: calls `blink validate ... --json`.
+The same linking rule applies through MCP: `brainlink_context` is read-only, and real graph links require Markdown notes with explicit `[[wiki links]]` followed by indexing.
 
 ## Graph UI
 
@@ -388,7 +395,7 @@ blink server --vault ./vault --no-index
 
 The HTTP API is read-only and exists only to power the graph UI and local inspection workflows.
 
-The server refuses non-loopback hosts by default. Use `--allow-public` only behind your own authentication, authorization and TLS.
+The server always refuses non-loopback hosts. Brainlink HTTP only runs on localhost.
 
 Routes:
 
@@ -563,7 +570,7 @@ blink server --vault ./vault --watch
 
 Starts the local read-only graph UI and HTTP API.
 
-To bind outside localhost, pass `--allow-public` and put the server behind your own auth and TLS.
+The HTTP server only binds to loopback hosts such as `127.0.0.1`, `localhost` or `::1`.
 
 ## Machine-Readable Output
 
@@ -691,7 +698,6 @@ Detailed notes:
 - Semantic search uses SQLite embedding buckets to narrow candidates before cosine scoring.
 - `embeddingProvider` currently supports `local` and `none`.
 - Link resolution is title-based inside each agent namespace, with `shared` as fallback.
-- No embedded MCP server is shipped; MCP integration is done by external servers wrapping the CLI.
 - HTTP API is local and unauthenticated.
 - Watch mode depends on the platform filesystem watcher.
 
@@ -712,6 +718,7 @@ The alpha includes local semantic retrieval. Remote embedding providers, remote
 Brainlink is local-first by default.
 
 - Do not expose the HTTP server publicly without authentication.
+- Brainlink HTTP is localhost-only and refuses non-loopback hosts.
 - Brainlink blocks common secret patterns by default when adding notes. Use `--allow-sensitive` only for intentional, protected vaults.
 - Do not store secrets, credentials, API keys or regulated personal data unless the vault is protected by your own storage controls.
 - Treat `.brainlink/brainlink.db` as disposable derived data.

package/SECURITY.md

@@ -5,7 +5,7 @@ Brainlink is local-first.
 ## Defaults
 
 - The HTTP server binds to `127.0.0.1` by default.
-- The HTTP server refuses non-loopback hosts unless `--allow-public` is passed.
+- The HTTP server always refuses non-loopback hosts.
 - The HTTP server is read-only and does not expose note creation, indexing or update routes.
 - The SQLite database is a derived local index.
 - Markdown files are user-owned source data.
@@ -14,7 +14,7 @@ Brainlink is local-first.
 
 ## Remote Exposure
 
-Do not expose the HTTP server on a public interface without adding authentication, authorization and transport security.
+Brainlink HTTP is intentionally localhost-only. It does not support binding to a public interface.
 
 ## Sensitive Memory
 

package/assets/brainlink-logo.svg

@@ -0,0 +1,25 @@
+<svg width="900" height="220" viewBox="0 0 900 220" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">Brainlink</title>
+  <desc id="desc">Brainlink logo with a linked memory graph mark and wordmark.</desc>
+  <rect width="900" height="220" fill="transparent"/>
+  <g transform="translate(42 24)">
+    <rect x="6" y="6" width="160" height="160" rx="36" fill="#F8FAFC"/>
+    <rect x="6" y="6" width="160" height="160" rx="36" stroke="#111827" stroke-width="8"/>
+    <path d="M47 84C47 65.225 62.225 50 81 50H92C110.775 50 126 65.225 126 84C126 102.775 110.775 118 92 118H81C62.225 118 47 102.775 47 84Z" stroke="#111827" stroke-width="12" stroke-linecap="round"/>
+    <path d="M67 84C67 76.268 73.268 70 81 70H92C99.732 70 106 76.268 106 84C106 91.732 99.732 98 92 98H81C73.268 98 67 91.732 67 84Z" fill="#FFFFFF"/>
+    <path d="M54 132L43 121L54 110" stroke="#2563EB" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
+    <path d="M118 110L129 121L118 132" stroke="#2563EB" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
+    <circle cx="55" cy="43" r="12" fill="#14B8A6"/>
+    <circle cx="121" cy="43" r="12" fill="#2563EB"/>
+    <circle cx="86" cy="136" r="12" fill="#111827"/>
+    <path d="M66.5 47.5L109.5 47.5" stroke="#94A3B8" stroke-width="7" stroke-linecap="round"/>
+    <path d="M62 54L79 125" stroke="#94A3B8" stroke-width="7" stroke-linecap="round"/>
+    <path d="M115 54L92 125" stroke="#94A3B8" stroke-width="7" stroke-linecap="round"/>
+  </g>
+  <g transform="translate(244 68)">
+    <text x="0" y="62" fill="#111827" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="72" font-weight="760">Brainlink</text>
+    <text x="4" y="102" fill="#475569" font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="24" font-weight="500">Local-first memory for AI agents</text>
+    <path d="M0 124H268" stroke="#14B8A6" stroke-width="8" stroke-linecap="round"/>
+    <path d="M292 124H392" stroke="#2563EB" stroke-width="8" stroke-linecap="round"/>
+  </g>
+</svg>

package/dist/application/server/host-security.js

@@ -1,6 +1,6 @@
 export const isLoopbackHost = (host) => host === 'localhost' || host === '::1' || host === '[::1]' || host.startsWith('127.');
-export const assertPublicBindAllowed = (host, allowPublic = false) => {
-    if (!allowPublic && !isLoopbackHost(host)) {
-        throw new Error(`Refusing to bind Brainlink server to non-loopback host ${host}. Pass --allow-public only behind your own auth and TLS.`);
+export const assertLoopbackHost = (host) => {
+    if (!isLoopbackHost(host)) {
+        throw new Error(`Refusing to bind Brainlink server to non-loopback host ${host}. Brainlink HTTP only runs on localhost.`);
     }
 };

package/dist/application/start-server.js

@@ -1,11 +1,11 @@
 import { createServer } from 'node:http';
 import { indexVault } from './index-vault.js';
 import { startVaultWatcher } from './watch-vault.js';
-import { assertPublicBindAllowed } from './server/host-security.js';
+import { assertLoopbackHost } from './server/host-security.js';
 import { contentTypes, createJsonResponse, isHttpError } from './server/http.js';
 import { route } from './server/routes.js';
 export const startServer = async (input) => {
-    assertPublicBindAllowed(input.host, input.allowPublic);
+    assertLoopbackHost(input.host);
     if (input.shouldIndex) {
         await indexVault(input.vaultPath);
     }

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

@@ -89,7 +89,6 @@ export const registerWriteCommands = (program) => {
         .option('-p, --port <port>', 'server port', '4321')
         .option('--no-index', 'skip indexing before starting the server')
         .option('-w, --watch', 'watch markdown files and reindex on changes')
-        .option('--allow-public', 'allow binding the server to a non-loopback host')
         .option('--json', 'print machine-readable JSON')
         .description('start a local web UI for the knowledge graph')
         .action(async (options) => {
@@ -99,8 +98,7 @@ export const registerWriteCommands = (program) => {
             host: options.host ?? resolved.config.host,
             port: parsePositiveInteger(options.port ?? String(resolved.config.port), resolved.config.port),
             shouldIndex: options.index,
-            shouldWatch: Boolean(options.watch),
-            allowPublic: Boolean(options.allowPublic)
+            shouldWatch: Boolean(options.watch)
         });
         print(options.json, { url: server.url, watch: Boolean(options.watch), readonly: true }, () => `Brainlink graph server running at ${server.url}`);
     });

package/dist/cli/main.js

@@ -1,8 +1,15 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import { basename } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { registerReadCommands } from './commands/read-commands.js';
 import { registerWriteCommands } from './commands/write-commands.js';
+const readPackageVersion = () => {
+    const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
+    const metadata = JSON.parse(readFileSync(packagePath, 'utf8'));
+    return metadata.version ?? '0.0.0';
+};
 const program = new Command();
 const cliName = basename(process.argv[1] ?? 'brainlink');
 const displayName = cliName === 'blink' ? 'blink' : 'brainlink';
@@ -11,7 +18,7 @@ program
     .name(displayName)
     .alias(aliasName)
     .description('Local-first knowledge memory for agents')
-    .version('0.1.0');
+    .version(readPackageVersion());
 registerWriteCommands(program);
 registerReadCommands(program);
 program.parseAsync().catch((error) => {

package/dist/mcp/main.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createBrainlinkMcpServer } from './server.js';
+const server = createBrainlinkMcpServer();
+const transport = new StdioServerTransport();
+server.connect(transport).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exitCode = 1;
+});

package/dist/mcp/server.js

@@ -0,0 +1,59 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { addNoteInputSchema, addNoteTool, brokenLinksInputSchema, brokenLinksTool, contextInputSchema, contextTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, searchInputSchema, searchTool, validateInputSchema, validateTool } from './tools.js';
+const readPackageVersion = () => {
+    const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
+    const metadata = JSON.parse(readFileSync(packagePath, 'utf8'));
+    return metadata.version ?? '0.0.0';
+};
+export const createBrainlinkMcpServer = () => {
+    const server = new McpServer({
+        name: 'brainlink',
+        title: 'Brainlink',
+        version: readPackageVersion(),
+        description: 'Local-first Markdown memory tools for AI agents.'
+    });
+    server.registerTool('brainlink_context', {
+        title: 'Build Brainlink Context',
+        description: 'Read indexed Brainlink memory for a task or question. This is read-only and does not create graph links.',
+        inputSchema: contextInputSchema
+    }, contextTool);
+    server.registerTool('brainlink_search', {
+        title: 'Search Brainlink Memory',
+        description: 'Search indexed Brainlink notes with FTS, semantic or hybrid retrieval.',
+        inputSchema: searchInputSchema
+    }, searchTool);
+    server.registerTool('brainlink_add_note', {
+        title: 'Add Brainlink Note',
+        description: 'Write durable Markdown memory, then reindex the vault. Include explicit [[wiki links]] for connected graph memory.',
+        inputSchema: addNoteInputSchema
+    }, addNoteTool);
+    server.registerTool('brainlink_index', {
+        title: 'Index Brainlink Vault',
+        description: 'Rebuild the local Brainlink index from Markdown notes.',
+        inputSchema: indexInputSchema
+    }, indexTool);
+    server.registerTool('brainlink_validate', {
+        title: 'Validate Brainlink Vault',
+        description: 'Validate indexed graph health, including broken links and orphan notes.',
+        inputSchema: validateInputSchema
+    }, validateTool);
+    server.registerTool('brainlink_graph', {
+        title: 'Read Brainlink Graph',
+        description: 'Read indexed graph nodes and wiki-link edges.',
+        inputSchema: graphInputSchema
+    }, graphTool);
+    server.registerTool('brainlink_broken_links', {
+        title: 'List Brainlink Broken Links',
+        description: 'List unresolved indexed wiki links.',
+        inputSchema: brokenLinksInputSchema
+    }, brokenLinksTool);
+    server.registerTool('brainlink_orphans', {
+        title: 'List Brainlink Orphans',
+        description: 'List indexed notes without incoming or outgoing graph links.',
+        inputSchema: orphansInputSchema
+    }, orphansTool);
+    return server;
+};

package/dist/mcp/tools.js

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+import { getBrokenLinksReport, getOrphansReport, validateVault } from '../application/analyze-vault.js';
+import { addNote } from '../application/add-note.js';
+import { buildContextPackage } from '../application/build-context.js';
+import { getGraph } from '../application/get-graph.js';
+import { indexVault } from '../application/index-vault.js';
+import { searchKnowledge } from '../application/search-knowledge.js';
+import { sanitizeSearchMode } from '../infrastructure/config.js';
+import { loadBrainlinkConfig } from '../infrastructure/config.js';
+import { assertVaultAllowed } from '../infrastructure/file-system-vault.js';
+const positiveInteger = (fallback) => z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .transform((value) => value ?? fallback);
+const vaultInput = {
+    vault: z.string().min(1).optional().describe('Vault directory. Omit to use the configured Brainlink default vault.')
+};
+const agentInput = {
+    agent: z.string().min(1).optional().describe('Agent memory namespace. Omit to read shared/default indexed memory.')
+};
+const searchModeInput = {
+    mode: z.enum(['fts', 'semantic', 'hybrid']).optional().describe('Search mode. Defaults to the Brainlink config value.')
+};
+const resolveVault = async (vault) => {
+    const config = await loadBrainlinkConfig();
+    return assertVaultAllowed(vault ?? config.vault, config.allowedVaults);
+};
+const jsonResult = (value) => ({
+    content: [
+        {
+            type: 'text',
+            text: JSON.stringify(value, null, 2)
+        }
+    ],
+    structuredContent: value
+});
+export const contextInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    ...searchModeInput,
+    query: z.string().min(1).describe('Task or question to retrieve Brainlink context for.'),
+    limit: positiveInteger(12).describe('Maximum search results before context selection.'),
+    tokens: positiveInteger(2000).describe('Maximum estimated context tokens.')
+};
+export const searchInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    ...searchModeInput,
+    query: z.string().min(1).describe('Search query.'),
+    limit: positiveInteger(10).describe('Maximum result count.')
+};
+export const addNoteInputSchema = {
+    ...vaultInput,
+    title: z.string().min(1).describe('Markdown note title.'),
+    content: z
+        .string()
+        .min(1)
+        .describe('Durable Markdown memory. Include explicit [[wiki links]] and #tags when the memory should be connected.'),
+    agent: z.string().min(1).optional().default('shared').describe('Agent memory namespace. Defaults to shared.'),
+    allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.')
+};
+export const indexInputSchema = {
+    ...vaultInput
+};
+export const validateInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const graphInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const brokenLinksInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const orphansInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const contextTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const config = await loadBrainlinkConfig();
+    const mode = sanitizeSearchMode(input.mode, config.defaultSearchMode);
+    const contextPackage = await buildContextPackage(vault, input.query, input.limit, input.tokens, input.agent, mode);
+    return jsonResult({
+        vault,
+        agent: input.agent,
+        mode,
+        ...contextPackage
+    });
+};
+export const searchTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const config = await loadBrainlinkConfig();
+    const mode = sanitizeSearchMode(input.mode, config.defaultSearchMode);
+    const results = await searchKnowledge(vault, input.query, input.limit, input.agent, mode);
+    return jsonResult({
+        vault,
+        agent: input.agent,
+        query: input.query,
+        limit: input.limit,
+        mode,
+        results
+    });
+};
+export const addNoteTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const path = await addNote(vault, input.title, input.content, input.agent, {
+        allowSensitive: input.allowSensitive
+    });
+    const index = await indexVault(vault);
+    return jsonResult({
+        vault,
+        title: input.title,
+        agent: input.agent,
+        path,
+        index
+    });
+};
+export const indexTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const result = await indexVault(vault);
+    return jsonResult({
+        vault,
+        ...result
+    });
+};
+export const validateTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const validation = await validateVault(vault, input.agent);
+    return jsonResult({
+        vault,
+        agent: input.agent,
+        ...validation
+    });
+};
+export const graphTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const graph = await getGraph(vault, input.agent);
+    return jsonResult({
+        vault,
+        agent: input.agent,
+        ...graph
+    });
+};
+export const brokenLinksTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const brokenLinks = await getBrokenLinksReport(vault, input.agent);
+    return jsonResult({
+        vault,
+        agent: input.agent,
+        brokenLinks
+    });
+};
+export const orphansTool = async (input) => {
+    const vault = await resolveVault(input.vault);
+    const orphans = await getOrphansReport(vault, input.agent);
+    return jsonResult({
+        vault,
+        agent: input.agent,
+        orphans
+    });
+};

package/docs/AGENT_USAGE.md

@@ -138,6 +138,41 @@ Rules:
 - Prefer summaries over raw transcripts.
 - Preserve dates when the timing matters.
 
+## Linking Contract
+
+Brainlink only builds graph edges from Markdown `[[wiki links]]`.
+
+The `context` command is read-only. It retrieves indexed notes and returns a compact package for the model, but it does not write memory, create backlinks, infer relationships or modify the graph. If an agent reads context and then learns something durable, the agent must write a note with explicit links before that knowledge becomes connected memory.
+
+Required write behavior:
+
+1. Choose a clear title for the new note.
+2. Look for an existing related concept with `search`, `links` or `backlinks`.
+3. Add at least one `[[Existing Note Title]]` link unless the note is intentionally a root concept.
+4. Add useful `#tags` for retrieval.
+5. Run `index` after the write.
+6. Run `validate`, `broken-links` or `orphans` when the graph should be connected.
+
+Good linked note:
+
+```bash
+blink add "SQLite Index Rebuild" \
+  --agent coding-agent \
+  --content "Legacy derived indexes without agent columns are rebuilt because SQLite is disposable. Related: [[Architecture]], [[Agent Namespaces]]. #sqlite #architecture #decision"
+blink index
+blink validate --agent coding-agent
+```
+
+Poor disconnected note:
+
+```bash
+blink add "SQLite Index Rebuild" \
+  --agent coding-agent \
+  --content "We rebuild old indexes now."
+```
+
+The poor note may be searchable, but it will not create graph links, backlinks or useful traversal paths.
+
 ## Read Policy
 
 Before answering a memory-dependent question, run:
@@ -396,19 +431,38 @@ blink watch --vault ./vault
 
 This process watches Markdown files and rebuilds the index after changes.
 
-### Use From An External MCP Server
+### Use From MCP
+
+Brainlink ships a stdio MCP server:
+
+```bash
+brainlink-mcp
+```
+
+Example MCP client configuration:
 
-Brainlink does not ship an MCP server. An MCP server can use Brainlink by executing the CLI and parsing `--json`.
+```json
+{
+  "mcpServers": {
+    "brainlink": {
+      "command": "brainlink-mcp"
+    }
+  }
+}
+```
 
-Recommended wrapper mapping:
+Available MCP tools:
 
-- `brainlink_context`: run `blink context "<query>" --vault <vault> --agent <agent> --mode hybrid --json`.
-- `brainlink_search`: run `blink search "<query>" --vault <vault> --agent <agent> --mode hybrid --json`.
-- `brainlink_add_note`: run `blink add "<title>" --vault <vault> --agent <agent> --content "<content>" --json`, then `blink index`.
-- `brainlink_graph`: run `blink graph --vault <vault> --agent <agent> --json`.
-- `brainlink_validate`: run `blink validate --vault <vault> --agent <agent> --json`.
+- `brainlink_context`
+- `brainlink_search`
+- `brainlink_add_note`
+- `brainlink_index`
+- `brainlink_validate`
+- `brainlink_graph`
+- `brainlink_broken_links`
+- `brainlink_orphans`
 
-External wrappers should set `BRAINLINK_ALLOWED_VAULTS` before invoking the CLI:
+MCP clients can pass `vault` and `agent` arguments per tool call. Set `BRAINLINK_ALLOWED_VAULTS` when exposing Brainlink to an external agent process so a tool cannot pass arbitrary vault paths:
 
 ```bash
 export BRAINLINK_ALLOWED_VAULTS="/absolute/path/to/project-vault"
@@ -453,6 +507,12 @@ Output:
 
 Agents should include source paths in their reasoning or final answer when the user needs traceability.
 
+Non-goals:
+
+- `context` must not be treated as a write operation.
+- Retrieved context must not be assumed to create graph edges.
+- Backlinks are derived only from indexed `[[wiki links]]`.
+
 ## Operational Rules
 
 - Re-run `index` after modifying notes.
@@ -461,6 +521,8 @@ Agents should include source paths in their reasoning or final answer when the u
 - Do not manually edit the database.
 - Keep generated context short enough for the target model.
 - Prefer specific queries over broad queries.
+- Write explicit `[[wiki links]]` when durable memory should be connected.
+- Check `orphans` before assuming the graph is healthy.
 
 ## Failure Modes
 
@@ -488,6 +550,6 @@ Weak retrieval usually means:
 
 - Search supports FTS, local semantic embeddings, SQLite semantic buckets and hybrid ranking.
 - Local embeddings are deterministic and provider-free; remote embedding providers are not implemented yet.
-- MCP integration is external: wrap the CLI from your own MCP server.
+- MCP integration is available through the `brainlink-mcp` stdio server.
 - HTTP API is local and unauthenticated.
 - Watch mode depends on platform filesystem watcher behavior.

package/docs/ARCHITECTURE.md

@@ -167,20 +167,18 @@ HTTP request
 
 The HTTP API is local-first and unauthenticated. It is meant for local agents, browser UI, and development workflows.
 
-## External MCP Flow
+## MCP Flow
 
-Brainlink does not contain an MCP server. MCP compatibility is achieved by an external MCP server wrapping the CLI.
+Brainlink includes a stdio MCP server for agent integrations.
 
 ```txt
 MCP client
-  -> external MCP server
-  -> child_process execFile("blink", ["context", ..., "--json"])
-  -> Brainlink CLI
+  -> brainlink-mcp
   -> application use case
-  -> JSON stdout
+  -> MCP tool result
 ```
 
-This keeps the package CLI-first and avoids coupling the core project to one MCP SDK.
+The MCP adapter stays thin. It validates tool inputs, resolves the configured vault and calls the same application use cases used by the CLI.
 
 ## Link Resolution
 

package/docs/RELEASE.md

@@ -32,7 +32,7 @@ blink context "release smoke" --vault ./tmp-vault --mode hybrid --json
 blink server --vault ./tmp-vault --host 127.0.0.1 --port 4321
 ```
 
-9. Verify the server refuses accidental public binds:
+9. Verify the server refuses public binds:
 
 ```bash
 blink server --vault ./tmp-vault --host 0.0.0.0
@@ -47,10 +47,18 @@ blink server --vault ./tmp-vault --host 0.0.0.0
 
 The preferred path is the `Publish npm` GitHub Actions workflow:
 
+- Push to `main`: runs checks, pack smoke, then publishes the package to npm with `latest` when `package.json` contains a version that is not already published.
 - GitHub Release `published`: runs checks, pack smoke, then publishes to npm with provenance.
 - Manual `workflow_dispatch`: runs a dry run by default. Disable `dry_run` only for an intentional manual publish.
+- Manual `workflow_dispatch` accepts an optional `dist_tag` override. Use `latest` only when the default npm install command should resolve to that version.
 - Prerelease versions publish under their prerelease dist-tag, for example `0.1.0-alpha.1` publishes with `--tag alpha`.
 
+On `main`, the publish job checks npm before publishing. If the version already exists, it automatically bumps the package inside the runner to the next available version before checks, packing and publishing. For example, `0.1.0-alpha.4` becomes `0.1.0-alpha.5`.
+
+The automatic bump is intentionally not pushed back to `main`. The branch stays protected, and npm remains the source of truth for the latest published package version.
+
+Manual and GitHub Release publishes do not auto-bump. If their version already exists, they skip `npm publish` because npm versions are immutable.
+
 For emergency local publishing of scoped public packages:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.10",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",
@@ -25,10 +25,12 @@
   ],
   "bin": {
     "brainlink": "dist/cli/main.js",
-    "blink": "dist/cli/main.js"
+    "blink": "dist/cli/main.js",
+    "brainlink-mcp": "dist/mcp/main.js"
   },
   "files": [
     "dist",
+    "assets",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
@@ -44,6 +46,7 @@
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "npm run clean && tsc -p tsconfig.json",
     "dev": "tsx src/cli/main.ts",
+    "dev:mcp": "tsx src/mcp/main.ts",
     "test": "vitest run --config vitest.config.ts",
     "check": "npm run build && npm run test",
     "benchmark:large": "tsx src/benchmarks/large-vault.ts",
@@ -51,8 +54,10 @@
     "pack:smoke": "npm pack --dry-run"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.9.0",
-    "commander": "^14.0.2"
+    "commander": "^14.0.2",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",