@andespindola/brainlink 0.1.0-alpha.6 → 0.1.0-alpha.7

package/AGENTS.md

@@ -86,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

@@ -64,7 +64,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.
 
@@ -330,50 +330,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
 
@@ -708,7 +694,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.
 

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

@@ -431,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 does not ship an MCP server. An MCP server can use Brainlink by executing the CLI and parsing `--json`.
+Brainlink ships a stdio MCP server:
 
-Recommended wrapper mapping:
+```bash
+brainlink-mcp
+```
+
+Example MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "brainlink": {
+      "command": "brainlink-mcp"
+    }
+  }
+}
+```
+
+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"
@@ -531,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/brainlink",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.7",
   "description": "Local-first knowledge memory for agents with Markdown, backlinks, indexing and context retrieval.",
   "type": "module",
   "license": "MIT",
@@ -25,7 +25,8 @@
   ],
   "bin": {
     "brainlink": "dist/cli/main.js",
-    "blink": "dist/cli/main.js"
+    "blink": "dist/cli/main.js",
+    "brainlink-mcp": "dist/mcp/main.js"
   },
   "files": [
     "dist",
@@ -44,6 +45,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 +53,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",