@andespindola/brainlink 0.1.0-alpha.5 → 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/docs/RELEASE.md

@@ -53,9 +53,9 @@ The preferred path is the `Publish npm` GitHub Actions workflow:
 - 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 to the next available version before checks, packing and publishing. For example, `0.1.0-alpha.4` becomes `0.1.0-alpha.5`.
+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`.
 
-After a successful automatic bump publish, the workflow commits the updated `package.json` and `package-lock.json` back to `main` with `[skip publish]` to avoid a publish loop.
+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.
 

package/package.json

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