@unson/brainbase-mcp 0.5.0 → 0.7.0

package/dist/server.js

@@ -16,6 +16,7 @@ import { auditPersonalOsDirectory } from './ontology-ssot.js';
 import { getOntologyImpact, inferPersonalOs, portableOntology, resolveOntologyVersion } from './ontology.js';
 import { loadPersonalOs } from './ssot.js';
 import { getContext, listEntities, onboardingStatus, searchAll, searchPersonalKg } from './tools.js';
+import { createLocalPersonalKnowledgeStore, createPersonalKnowledgeClient, decodePersonalKnowledgeContextHeader, PERSONAL_KNOWLEDGE_CONTRACT_VERSION, validatePersonalKnowledgeContext } from './personal-knowledge.js';
 const argsSchema = z.object({
     dataDir: z.string().optional(),
     query: z.string().optional(),
@@ -35,6 +36,29 @@ const argsSchema = z.object({
     mode: z.never().optional()
 });
 const searchArgsSchema = argsSchema.pick({ dataDir: true, query: true, limit: true, project: true, as_of: true, asOf: true, seedIds: true, steps: true, mode: true }).strict();
+const personalKnowledgeEventSchema = z.object({
+    event_id: z.string().min(1),
+    body: z.string().optional(),
+    content: z.string().optional(),
+    body_hash: z.string().min(1).optional(),
+    occurred_at: z.string().min(1).optional(),
+    captured_at: z.string().min(1).optional(),
+    source: z.unknown().optional(),
+    source_pointer: z.unknown().optional(),
+    parent_episode_id: z.string().min(1).nullable().optional(),
+    permission_snapshot: z.record(z.unknown()).optional(),
+    sensitivity: z.string().min(1).optional(),
+    kind: z.string().min(1).optional(),
+    type: z.string().min(1).optional(),
+    tags: z.array(z.string().min(1)).optional(),
+    metadata: z.record(z.unknown()).optional()
+}).strict();
+const personalKnowledgeContextSchema = z.object({}).strict();
+const personalKnowledgeRegisterSchema = z.object({ event: personalKnowledgeEventSchema }).strict();
+const personalKnowledgeSearchSchema = z.object({
+    query: z.string(),
+    limit: z.number().int().min(1).max(50).optional()
+}).strict();
 const mentionSpanSchema = z.object({
     start: z.number().int().nonnegative(),
     end: z.number().int().positive()
@@ -187,6 +211,61 @@ export const toolDefinitions = [
             }
         }
     },
+    {
+        name: 'personal_knowledge_context',
+        description: 'Return the authenticated v1 personal knowledge context. Identity and storage selection come from trusted configuration, not tool arguments.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {}
+        }
+    },
+    {
+        name: 'personal_knowledge_register',
+        description: 'Register one v1 personal knowledge event in the explicitly configured local or managed context. Caller identity, organization, source, and path are never accepted as event fields.',
+        inputSchema: {
+            type: 'object',
+            required: ['event'],
+            additionalProperties: false,
+            properties: {
+                event: {
+                    type: 'object',
+                    required: ['event_id'],
+                    additionalProperties: false,
+                    properties: {
+                        event_id: { type: 'string', minLength: 1 },
+                        body: { type: 'string' },
+                        content: { type: 'string' },
+                        body_hash: { type: 'string', minLength: 1 },
+                        occurred_at: { type: 'string', minLength: 1 },
+                        captured_at: { type: 'string', minLength: 1 },
+                        source: {},
+                        source_pointer: {},
+                        parent_episode_id: { type: ['string', 'null'] },
+                        permission_snapshot: { type: 'object' },
+                        sensitivity: { type: 'string', minLength: 1 },
+                        kind: { type: 'string', minLength: 1 },
+                        type: { type: 'string', minLength: 1 },
+                        tags: { type: 'array', items: { type: 'string', minLength: 1 } },
+                        metadata: { type: 'object' }
+                    }
+                }
+            }
+        }
+    },
+    {
+        name: 'personal_knowledge_search',
+        description: 'Search the explicitly configured v1 personal knowledge context. The result includes the verified context and never falls back to another store.',
+        inputSchema: {
+            type: 'object',
+            required: ['query'],
+            additionalProperties: false,
+            properties: {
+                query: { type: 'string', minLength: 1, maxLength: 4000 },
+                limit: { type: 'integer', minimum: 1, maximum: 50 }
+            }
+        }
+    },
     {
         name: 'onboarding_status',
         description: 'Report seeded areas, first value demo readiness, missing setup, and local connection status.',
@@ -351,6 +430,29 @@ export const toolDefinitions = [
         }
     }
 ];
+const managedPersonalKnowledgeToolNames = new Set([
+    'personal_knowledge_context',
+    'personal_knowledge_register',
+    'personal_knowledge_search'
+]);
+function isPersonalKnowledgeTool(name) {
+    return managedPersonalKnowledgeToolNames.has(name);
+}
+function configuredPersonalKnowledgeMode() {
+    const configuredMode = process.env.BRAINBASE_PERSONAL_KNOWLEDGE_MODE?.trim()
+        || process.env.BRAINBASE_PERSONAL_KG_STORAGE_MODE?.trim()
+        || 'local';
+    if (configuredMode === 'local' || configuredMode === 'managed_cloud') {
+        return configuredMode;
+    }
+    throw new Error(`Unsupported Personal Knowledge mode: ${configuredMode}.`);
+}
+function configuredToolDefinitions() {
+    if (configuredPersonalKnowledgeMode() === 'managed_cloud') {
+        return toolDefinitions.filter((tool) => isPersonalKnowledgeTool(tool.name));
+    }
+    return [...toolDefinitions];
+}
 let embeddingProvider;
 let embeddingProviderInitialized = false;
 function configuredEmbeddingProvider() {
@@ -360,7 +462,84 @@ function configuredEmbeddingProvider() {
     }
     return embeddingProvider;
 }
+function configuredPersonalKnowledgeContext() {
+    const encoded = process.env.BRAINBASE_PERSONAL_KNOWLEDGE_CONTEXT?.trim()
+        || process.env.BRAINBASE_PERSONAL_CONTEXT?.trim();
+    if (encoded)
+        return decodePersonalKnowledgeContextHeader(encoded);
+    const scope = process.env.BRAINBASE_PERSONAL_KNOWLEDGE_SCOPE?.trim()
+        || process.env.BRAINBASE_PERSONAL_SCOPE?.trim()
+        || 'organization_private';
+    const owner = process.env.BRAINBASE_PERSONAL_KNOWLEDGE_OWNER_PERSON_ID?.trim()
+        || process.env.BRAINBASE_PERSON_ID?.trim();
+    const source = process.env.BRAINBASE_PERSONAL_KNOWLEDGE_SOURCE_ID?.trim()
+        || process.env.BRAINBASE_PERSONAL_SOURCE_ID?.trim();
+    const organization = process.env.BRAINBASE_PERSONAL_KNOWLEDGE_ORGANIZATION_ID?.trim()
+        || process.env.BRAINBASE_ORGANIZATION_ID?.trim();
+    if (!owner || !source) {
+        throw new Error('Managed Personal Knowledge requires owner person and source configuration.');
+    }
+    return validatePersonalKnowledgeContext({
+        contract_version: PERSONAL_KNOWLEDGE_CONTRACT_VERSION,
+        scope,
+        owner_person_id: owner,
+        organization_id: scope === 'personal_owned' ? null : organization,
+        source_id: source
+    });
+}
+function configuredPersonalKnowledgeRuntime() {
+    const configuredMode = configuredPersonalKnowledgeMode();
+    if (configuredMode === 'local') {
+        const encodedContext = process.env.BRAINBASE_PERSONAL_KNOWLEDGE_CONTEXT?.trim()
+            || process.env.BRAINBASE_PERSONAL_CONTEXT?.trim();
+        if (encodedContext) {
+            const context = decodePersonalKnowledgeContextHeader(encodedContext);
+            if (context.scope !== 'personal_owned' || context.organization_id !== null) {
+                throw new Error('OSS local Personal Knowledge requires a personal_owned context.');
+            }
+            return createLocalPersonalKnowledgeStore({ context });
+        }
+        return createLocalPersonalKnowledgeStore();
+    }
+    const apiUrl = process.env.BRAINBASE_PERSONAL_KNOWLEDGE_API_URL?.trim()
+        || process.env.BRAINBASE_PERSONAL_KG_MANAGED_CLOUD_API_URL?.trim();
+    if (!apiUrl)
+        throw new Error('Managed Personal Knowledge requires an explicit API URL.');
+    const token = process.env.BRAINBASE_PERSONAL_KNOWLEDGE_TOKEN
+        || process.env.BRAINBASE_PERSONAL_KG_TOKEN;
+    if (!token?.trim())
+        throw new Error('Managed Personal Knowledge requires an authenticated token.');
+    return createPersonalKnowledgeClient({
+        mode: 'managed_cloud',
+        apiUrl,
+        expectedContext: configuredPersonalKnowledgeContext(),
+        token
+    });
+}
+async function callPersonalKnowledgeTool(name, rawArgs) {
+    const runtime = configuredPersonalKnowledgeRuntime();
+    if (name === 'personal_knowledge_context') {
+        personalKnowledgeContextSchema.parse(rawArgs ?? {});
+        return runtime.getContext();
+    }
+    if (name === 'personal_knowledge_register') {
+        const args = personalKnowledgeRegisterSchema.parse(rawArgs ?? {});
+        return runtime.register(args.event);
+    }
+    if (name === 'personal_knowledge_search') {
+        const args = personalKnowledgeSearchSchema.parse(rawArgs ?? {});
+        return runtime.search(args.query, args.limit);
+    }
+    throw new Error(`Unknown Personal Knowledge tool: ${name}`);
+}
 export async function callBrainbaseTool(name, rawArgs = {}) {
+    const mode = configuredPersonalKnowledgeMode();
+    if (mode === 'managed_cloud' && !isPersonalKnowledgeTool(name)) {
+        throw new Error('managed_cloud Personal Knowledge MCP only permits personal_knowledge_context, personal_knowledge_register, and personal_knowledge_search.');
+    }
+    if (isPersonalKnowledgeTool(name)) {
+        return callPersonalKnowledgeTool(name, rawArgs);
+    }
     if (name in connectedSchemas) {
         return callConnectedOnboardingTool(name, rawArgs);
     }
@@ -688,7 +867,7 @@ export function createServer() {
         }
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: [...toolDefinitions]
+        tools: configuredToolDefinitions()
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const result = await callBrainbaseTool(request.params.name, request.params.arguments);

package/dist/ssot.d.ts

@@ -3,7 +3,7 @@ import type { PersonalOs } from './types.js';
 export declare function initializePersonalOs(dataDir: string): Promise<void>;
 export declare function loadPersonalOs(dataDir: string): Promise<PersonalOs>;
 export declare function mutatePersonalOs(dataDir: string, mutator: (current: PersonalOs) => PersonalOs | Promise<PersonalOs>): Promise<PersonalOs>;
-export declare function mutatePersonalOsWithSidecar<T>(dataDir: string, sidecarPath: string, mutator: (current: PersonalOs) => {
+export declare function mutatePersonalOsWithSidecar<T>(dataDir: string, sidecarPath: string, mutator: (current: PersonalOs, sidecarContent?: string) => {
     next: PersonalOs;
     sidecarContent: string;
     result: T;
@@ -12,6 +12,11 @@ export declare function mutatePersonalOsWithSidecar<T>(dataDir: string, sidecarP
     sidecarContent: string;
     result: T;
 }>): Promise<T>;
+/**
+ * Reads a sidecar while holding the canonical SSOT lock. A missing sidecar is
+ * returned as undefined so a first mutation can create it transactionally.
+ */
+export declare function readPersonalOsSidecar(dataDir: string, sidecarPath: string): Promise<string | undefined>;
 export type CanonicalGraphMigrationExecution = CanonicalGraphMigrationPlan & {
     expectedInputDigest: string;
     written: boolean;

package/dist/ssot.js

@@ -5,6 +5,7 @@ import { hostname } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve, win32 } from 'node:path';
 import { z } from 'zod';
 import { validateCanonicalGraph } from './canonical-graph.js';
+import { assertFoundationCatalog } from './foundation-catalog.js';
 import { assertOntologyValid } from './ontology.js';
 import { planCanonicalGraphMigration } from './ontology-migration.js';
 import { emptyGraph, emptyRelationships, schemaTemplates } from './templates.js';
@@ -91,13 +92,25 @@ export async function mutatePersonalOsWithSidecar(dataDir, sidecarPath, mutator)
         await recoverTransactions(dataDir);
         assertCompleteCanonicalSet(dataDir, await canonicalPresence(dataDir));
         const current = await loadPersonalOsUnlocked(dataDir);
-        const mutation = await mutator(current);
+        const mutation = await mutator(current, await readOptionalSidecar(dataDir, sidecarPath));
         const normalized = { ...mutation.next, dataDir, sourceCount: current.sourceCount };
         validateAggregate(normalized);
         await commitAggregate(dataDir, normalized, 'mutation', [{ relativePath: sidecarPath, content: mutation.sidecarContent }]);
         return mutation.result;
     });
 }
+/**
+ * Reads a sidecar while holding the canonical SSOT lock. A missing sidecar is
+ * returned as undefined so a first mutation can create it transactionally.
+ */
+export async function readPersonalOsSidecar(dataDir, sidecarPath) {
+    assertSafeSidecarPath(sidecarPath);
+    return withSsotLock(dataDir, async () => {
+        await recoverTransactions(dataDir);
+        assertCompleteCanonicalSet(dataDir, await canonicalPresence(dataDir));
+        return readOptionalSidecar(dataDir, sidecarPath);
+    });
+}
 /**
  * Plans or atomically applies the canonical Graph migration.
  *
@@ -172,11 +185,22 @@ async function commitAggregate(dataDir, next, mode, sidecars = []) {
         await mkdir(previousDir, { recursive: true });
         await copyCanonicalSet(dataDir, previousDir);
         for (const sidecar of sidecars) {
-            await mkdir(dirname(join(previousDir, sidecar.relativePath)), { recursive: true });
-            await copyFile(join(dataDir, sidecar.relativePath), join(previousDir, sidecar.relativePath));
+            if (await exists(join(dataDir, sidecar.relativePath))) {
+                await mkdir(dirname(join(previousDir, sidecar.relativePath)), { recursive: true });
+                await copyFile(join(dataDir, sidecar.relativePath), join(previousDir, sidecar.relativePath));
+            }
         }
     }
-    const metadata = { version: 1, mode, ...(sidecars.length > 0 ? { sidecarFiles: sidecars.map((item) => item.relativePath) } : {}) };
+    const sidecarFiles = sidecars.map((item) => item.relativePath);
+    const previousSidecarFiles = mode === 'mutation'
+        ? (await Promise.all(sidecars.map(async (item) => (await exists(join(dataDir, item.relativePath))) ? item.relativePath : undefined))).filter((item) => item !== undefined)
+        : [];
+    const metadata = {
+        version: 1,
+        mode,
+        ...(sidecarFiles.length > 0 ? { sidecarFiles } : {}),
+        ...(mode === 'mutation' && sidecarFiles.length > 0 ? { previousSidecarFiles } : {})
+    };
     await writeFile(join(stagingDir, 'transaction.json'), `${JSON.stringify(metadata, null, 2)}\n`);
     await writeFile(join(stagingDir, 'PREPARED'), '');
     await rename(stagingDir, transactionDir);
@@ -224,7 +248,13 @@ async function recoverTransaction(dataDir, transactionDir) {
     if (process.env.BRAINBASE_SSOT_FAIL_RECOVERY === '1') {
         throw new Error(`Injected SSOT transaction recovery failure for ${transactionDir}`);
     }
-    await publishCanonicalSet(dataDir, retainedDir, `recovery-${randomUUID()}`, false, metadata.sidecarFiles ?? []);
+    const previousSidecarFiles = metadata.mode === 'initialization'
+        ? metadata.sidecarFiles ?? []
+        : metadata.previousSidecarFiles ?? metadata.sidecarFiles ?? [];
+    await publishCanonicalSet(dataDir, retainedDir, `recovery-${randomUUID()}`, false, previousSidecarFiles);
+    if (metadata.mode === 'mutation') {
+        await removeSidecars(dataDir, (metadata.sidecarFiles ?? []).filter((path) => !previousSidecarFiles.includes(path)));
+    }
     await rm(transactionDir, { recursive: true, force: true });
 }
 async function publishCanonicalSet(dataDir, retainedDir, token, allowInjectedFailure, sidecarFiles = []) {
@@ -256,6 +286,12 @@ async function publishCanonicalSet(dataDir, retainedDir, token, allowInjectedFai
         }
     }
 }
+async function removeSidecars(dataDir, relativePaths) {
+    for (const relativePath of relativePaths) {
+        assertSafeSidecarPath(relativePath);
+        await rm(join(dataDir, relativePath), { force: true });
+    }
+}
 async function writeAggregate(targetDir, os) {
     await writeFile(join(targetDir, 'graph.json'), `${JSON.stringify(os.graph, null, 2)}\n`);
     await writeFile(join(targetDir, 'relationships.json'), `${JSON.stringify(os.relationships, null, 2)}\n`);
@@ -268,6 +304,8 @@ function validateAggregate(os) {
     os.decisions.forEach((decision) => decisionSchema.parse(decision));
     assertOntologyValid(os);
     validateCanonicalGraph(os.graph);
+    if (os.graph.version === 2)
+        assertFoundationCatalog(os.graph.foundation);
 }
 function parseGraph(value) {
     try {
@@ -283,8 +321,13 @@ function parseGraph(value) {
         }
         validateCanonicalGraph(value, { allowDuplicateEntityIds: true });
     }
+    if (isGraphV2(value))
+        assertFoundationCatalog(value.foundation);
     return value;
 }
+function isGraphV2(value) {
+    return typeof value === 'object' && value !== null && value.version === 2;
+}
 function serializeJsonl(values) {
     return values.length === 0 ? '' : `${values.map((value) => JSON.stringify(value)).join('\n')}\n`;
 }
@@ -405,8 +448,13 @@ async function readTransactionMetadata(transactionDir) {
     if (value.sidecarFiles !== undefined && (!Array.isArray(value.sidecarFiles) || value.sidecarFiles.some((path) => typeof path !== 'string'))) {
         throw new Error(`Invalid registered SSOT transaction sidecars in ${transactionDir}`);
     }
+    if (value.previousSidecarFiles !== undefined && (!Array.isArray(value.previousSidecarFiles) || value.previousSidecarFiles.some((path) => typeof path !== 'string'))) {
+        throw new Error(`Invalid registered SSOT transaction previous sidecars in ${transactionDir}`);
+    }
     for (const path of value.sidecarFiles ?? [])
         assertSafeSidecarPath(path);
+    for (const path of value.previousSidecarFiles ?? [])
+        assertSafeSidecarPath(path);
     return value;
 }
 function assertSafeSidecarPath(relativePath) {
@@ -439,6 +487,16 @@ async function exists(path) {
         return false;
     }
 }
+async function readOptionalSidecar(dataDir, sidecarPath) {
+    try {
+        return await readFile(join(dataDir, sidecarPath), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
 async function readJson(filePath) {
     try {
         return JSON.parse(await readFile(filePath, 'utf8'));

package/dist/streamable-http.d.ts

@@ -0,0 +1,42 @@
+import { type IncomingMessage, type Server as HttpServer, type ServerResponse } from 'node:http';
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+type MaybePromise<T> = T | Promise<T>;
+export interface StreamableHttpRequestScope<Auth = AuthInfo> {
+    requestId: string;
+    method: string;
+    path: string;
+    auth?: Auth;
+    sessionId?: string;
+}
+export interface StreamableHttpRequestScopeInput<Auth = AuthInfo> {
+    request: IncomingMessage;
+    requestId: string;
+    auth?: Auth;
+    sessionId?: string;
+}
+export interface StreamableHttpHealthScope {
+    request: IncomingMessage;
+    requestId: string;
+}
+export interface StreamableHttpDependencies<Auth = AuthInfo> {
+    /** Return null to reject the request. Undefined means anonymous access. */
+    authenticate?: (request: IncomingMessage) => MaybePromise<Auth | null>;
+    /** Build one MCP server for each initialized MCP session. */
+    createServer: (scope: StreamableHttpRequestScope<Auth>) => MaybePromise<Server>;
+    /** Add application request context without coupling the transport to an app. */
+    requestScope?: (input: StreamableHttpRequestScopeInput<Auth>) => MaybePromise<Partial<StreamableHttpRequestScope<Auth>>>;
+    /** Health is deliberately independent from MCP authentication and application routes. */
+    health?: (scope: StreamableHttpHealthScope) => MaybePromise<unknown>;
+    bodyLimitBytes?: number;
+    mcpPath?: string;
+    healthPath?: string;
+}
+export interface StreamableHttpHandler {
+    handle(request: IncomingMessage, response: ServerResponse): Promise<void>;
+    close(): Promise<void>;
+    readonly activeSessionCount: number;
+}
+export declare function createStreamableHttpHandler<Auth = AuthInfo>(dependencies: StreamableHttpDependencies<Auth>): StreamableHttpHandler;
+export declare function createStreamableHttpServer<Auth = AuthInfo>(dependencies: StreamableHttpDependencies<Auth>): HttpServer;
+export {};