@unson/brainbase-mcp 0.2.4 → 0.3.1

package/dist/projects.js

@@ -1,3 +1,4 @@
+import { buildCanonicalEdge } from './canonical-edge-builder.js';
 export function parseProjectSource(value) {
     const [areaRaw, labelRaw, refRaw] = value.split('|').map((part) => part.trim());
     const area = parseProjectSourceArea(areaRaw);
@@ -74,6 +75,43 @@ export function buildProjectRegistrationPlan(input) {
         tags: ['project', 'principle'],
         updatedAt: now
     }));
+    const decisionEntities = decisions.map((decision) => ({
+        id: decision.id,
+        type: 'decision',
+        name: decision.title,
+        summary: decision.decision,
+        tags: decision.tags,
+        metadata: {
+            rationale: decision.rationale,
+            projectId
+        }
+    }));
+    const canonicalEntities = [
+        { ...projectEntity, type: 'project' },
+        ...stakeholderEntities.map((entity) => ({ ...entity, type: 'person' })),
+        ...decisionEntities
+    ];
+    const participationEdges = stakeholders.map((stakeholder) => {
+        const personId = `person-${stableHash(stakeholder.person)}`;
+        return buildCanonicalEdge({
+            fromId: personId,
+            relation: 'participates_in',
+            toId: projectId,
+            role: stakeholder.role,
+            context: stakeholder.context,
+            provenance: {
+                sourceKind: 'onboarding',
+                sourceId: `relationship-${stableHash(`${name}|${stakeholder.person}|${stakeholder.context}`)}`
+            }
+        });
+    });
+    const governanceEdges = decisions.map((decision) => buildCanonicalEdge({
+        fromId: decision.id,
+        relation: 'governs',
+        toId: projectId,
+        context: decision.decision,
+        provenance: { sourceKind: 'onboarding', sourceId: decision.id }
+    }));
     return {
         goal: 'Review project registration before promoting it into canonical Brainbase SSOT.',
         canonicalWrites: false,
@@ -91,6 +129,8 @@ export function buildProjectRegistrationPlan(input) {
         stakeholders,
         writes: {
             graphEntities: [projectEntity, ...stakeholderEntities],
+            canonicalEntities,
+            canonicalEdges: [...participationEdges, ...governanceEdges],
             relationships,
             personalKg,
             decisions

package/dist/relation-registry.d.ts

@@ -0,0 +1,11 @@
+import type { CanonicalEntityKind, CoreRelation } from './types.js';
+export interface CanonicalRelationDefinition {
+    id: CoreRelation;
+    from: CanonicalEntityKind;
+    to: CanonicalEntityKind;
+    meaning: string;
+    scopeTraversal: 'none' | 'project_direct' | 'project_transitive';
+    traversalDirection: 'none' | 'forward' | 'reverse';
+}
+export declare const canonicalRelationRegistry: Readonly<Record<CoreRelation, Readonly<CanonicalRelationDefinition>>>;
+export declare function getCanonicalRelation(relation: string): Readonly<CanonicalRelationDefinition>;

package/dist/relation-registry.js

@@ -0,0 +1,66 @@
+const definitions = {
+    member_of: {
+        id: 'member_of',
+        from: 'person',
+        to: 'org',
+        meaning: 'A person is a member of an organization.',
+        scopeTraversal: 'none',
+        traversalDirection: 'none'
+    },
+    participates_in: {
+        id: 'participates_in',
+        from: 'person',
+        to: 'project',
+        meaning: 'A person participates in a project.',
+        scopeTraversal: 'project_direct',
+        traversalDirection: 'forward'
+    },
+    accountable_for: {
+        id: 'accountable_for',
+        from: 'person',
+        to: 'project',
+        meaning: 'A person is accountable for a project outcome or decision.',
+        scopeTraversal: 'project_direct',
+        traversalDirection: 'forward'
+    },
+    owned_by: {
+        id: 'owned_by',
+        from: 'project',
+        to: 'org',
+        meaning: 'A project is owned by an organization.',
+        scopeTraversal: 'project_direct',
+        traversalDirection: 'reverse'
+    },
+    governs: {
+        id: 'governs',
+        from: 'decision',
+        to: 'project',
+        meaning: 'A durable decision or principle governs a project.',
+        scopeTraversal: 'project_direct',
+        traversalDirection: 'forward'
+    },
+    supersedes: {
+        id: 'supersedes',
+        from: 'decision',
+        to: 'decision',
+        meaning: 'A durable decision explicitly supersedes another decision.',
+        scopeTraversal: 'project_transitive',
+        traversalDirection: 'forward'
+    }
+};
+export const canonicalRelationRegistry = deepFreeze(definitions);
+export function getCanonicalRelation(relation) {
+    const definition = canonicalRelationRegistry[relation];
+    if (!definition) {
+        throw new Error(`ONTOLOGY-RELATION-UNKNOWN: unsupported canonical relation ${JSON.stringify(relation)}`);
+    }
+    return definition;
+}
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const nested of Object.values(value))
+            deepFreeze(nested);
+    }
+    return value;
+}

package/dist/server.d.ts

@@ -8,6 +8,15 @@ export declare const toolDefinitions: readonly [{
             readonly dataDir: {
                 readonly type: "string";
             };
+            readonly project: {
+                readonly type: "string";
+                readonly description: "Optional canonical project ID, name, or alias.";
+            };
+            readonly as_of: {
+                readonly type: "string";
+                readonly format: "date-time";
+                readonly description: "RFC 3339 validity instant. Defaults to now.";
+            };
         };
     };
 }, {
@@ -40,6 +49,15 @@ export declare const toolDefinitions: readonly [{
             readonly limit: {
                 readonly type: "number";
             };
+            readonly project: {
+                readonly type: "string";
+                readonly description: "Optional canonical project ID, name, or alias.";
+            };
+            readonly as_of: {
+                readonly type: "string";
+                readonly format: "date-time";
+                readonly description: "RFC 3339 validity instant. Defaults to now.";
+            };
         };
     };
 }, {
@@ -380,7 +398,7 @@ export declare const toolDefinitions: readonly [{
                 readonly type: "string";
             };
             readonly ontologyVersion: {
-                readonly enum: readonly ["0.0.0", "1.0.0"];
+                readonly enum: readonly ["0.0.0", "1.0.0", "2.0.0"];
             };
         };
     };
@@ -398,7 +416,7 @@ export declare const toolDefinitions: readonly [{
                 readonly format: "date-time";
             };
             readonly ontologyVersion: {
-                readonly enum: readonly ["0.0.0", "1.0.0"];
+                readonly enum: readonly ["0.0.0", "1.0.0", "2.0.0"];
             };
         };
     };
@@ -413,6 +431,72 @@ export declare const toolDefinitions: readonly [{
             };
         };
     };
+}, {
+    readonly name: "resolve_entity";
+    readonly description: "Resolve mentions in text to canonical Graph v2 entity IDs and return a privacy-safe evidence receipt.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["text", "asOf"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly dataDir: {
+                readonly type: "string";
+                readonly description: "Optional Personal OS directory.";
+            };
+            readonly text: {
+                readonly type: "string";
+                readonly description: "Text whose entity mentions should be resolved. The text is hashed, not stored in the receipt.";
+            };
+            readonly asOf: {
+                readonly type: "string";
+                readonly format: "date-time";
+                readonly description: "RFC 3339 instant used for temporal entity and edge validity.";
+            };
+            readonly mentionSpans: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly required: readonly ["start", "end"];
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly start: {
+                            readonly type: "integer";
+                            readonly minimum: 0;
+                        };
+                        readonly end: {
+                            readonly type: "integer";
+                            readonly minimum: 1;
+                        };
+                    };
+                };
+            };
+            readonly projectScope: {
+                readonly type: "object";
+                readonly required: readonly ["projectIds"];
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly projectIds: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly items: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                    };
+                    readonly policy: {
+                        readonly enum: readonly ["strict", "prefer_project", "allow_global_fallback"];
+                    };
+                };
+            };
+            readonly entityTypes: {
+                readonly type: "array";
+                readonly minItems: 1;
+                readonly items: {
+                    readonly enum: readonly ["person", "org", "project", "decision"];
+                };
+            };
+        };
+    };
 }];
 export declare function callBrainbaseTool(name: string, rawArgs?: unknown): Promise<unknown>;
 export declare function createServer(): Server;

package/dist/server.js

@@ -1,8 +1,13 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { ConnectedOnboardingRuntime } from './connected-onboarding.js';
+import { validateCanonicalGraph } from './canonical-graph.js';
+import { resolveText } from './entity-resolution.js';
 import { resolveDataDir } from './paths.js';
 import { auditPersonalOsDirectory } from './ontology-ssot.js';
 import { getOntologyImpact, inferPersonalOs, portableOntology, resolveOntologyVersion } from './ontology.js';
@@ -15,7 +20,34 @@ const argsSchema = z.object({
     type: z.enum(['person', 'org', 'project', 'relationship', 'decision']).optional(),
     fromVersion: z.string().optional(),
     ontologyVersion: z.string().optional(),
-    asOf: z.string().datetime({ offset: true }).optional()
+    asOf: z.string().datetime({ offset: true }).optional(),
+    project: z.string().min(1).optional(),
+    as_of: z.string().datetime({ offset: true }).optional()
+});
+const mentionSpanSchema = z.object({
+    start: z.number().int().nonnegative(),
+    end: z.number().int().positive()
+}).strict().refine((span) => span.end > span.start, { message: 'mention span end must be after start' });
+const resolveEntitySchema = z.object({
+    dataDir: z.string().optional(),
+    text: z.string(),
+    asOf: z.string().datetime({ offset: true }),
+    mentionSpans: z.array(mentionSpanSchema).optional(),
+    projectScope: z.object({
+        projectIds: z.array(z.string().min(1)).min(1),
+        policy: z.enum(['strict', 'prefer_project', 'allow_global_fallback']).optional()
+    }).strict().optional(),
+    entityTypes: z.array(z.enum(['person', 'org', 'project', 'decision'])).min(1).optional()
+}).strict().superRefine((value, context) => {
+    for (const [index, span] of (value.mentionSpans ?? []).entries()) {
+        if (span.end > value.text.length) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['mentionSpans', index, 'end'],
+                message: 'mention span must be within text'
+            });
+        }
+    }
 });
 const sourceInventorySchema = z.object({
     id: z.string(),
@@ -89,7 +121,9 @@ export const toolDefinitions = [
         inputSchema: {
             type: 'object',
             properties: {
-                dataDir: { type: 'string' }
+                dataDir: { type: 'string' },
+                project: { type: 'string', description: 'Optional canonical project ID, name, or alias.' },
+                as_of: { type: 'string', format: 'date-time', description: 'RFC 3339 validity instant. Defaults to now.' }
             }
         }
     },
@@ -113,7 +147,9 @@ export const toolDefinitions = [
             properties: {
                 dataDir: { type: 'string' },
                 query: { type: 'string' },
-                limit: { type: 'number' }
+                limit: { type: 'number' },
+                project: { type: 'string', description: 'Optional canonical project ID, name, or alias.' },
+                as_of: { type: 'string', format: 'date-time', description: 'RFC 3339 validity instant. Defaults to now.' }
             }
         }
     },
@@ -230,7 +266,7 @@ export const toolDefinitions = [
             type: 'object',
             properties: {
                 dataDir: { type: 'string' },
-                ontologyVersion: { enum: ['0.0.0', '1.0.0'] }
+                ontologyVersion: { enum: ['0.0.0', '1.0.0', '2.0.0'] }
             }
         }
     },
@@ -242,7 +278,7 @@ export const toolDefinitions = [
             properties: {
                 dataDir: { type: 'string' },
                 asOf: { type: 'string', format: 'date-time' },
-                ontologyVersion: { enum: ['0.0.0', '1.0.0'] }
+                ontologyVersion: { enum: ['0.0.0', '1.0.0', '2.0.0'] }
             }
         }
     },
@@ -255,12 +291,52 @@ export const toolDefinitions = [
                 fromVersion: { type: 'string' }
             }
         }
+    },
+    {
+        name: 'resolve_entity',
+        description: 'Resolve mentions in text to canonical Graph v2 entity IDs and return a privacy-safe evidence receipt.',
+        inputSchema: {
+            type: 'object',
+            required: ['text', 'asOf'],
+            additionalProperties: false,
+            properties: {
+                dataDir: { type: 'string', description: 'Optional Personal OS directory.' },
+                text: { type: 'string', description: 'Text whose entity mentions should be resolved. The text is hashed, not stored in the receipt.' },
+                asOf: { type: 'string', format: 'date-time', description: 'RFC 3339 instant used for temporal entity and edge validity.' },
+                mentionSpans: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        required: ['start', 'end'],
+                        additionalProperties: false,
+                        properties: { start: { type: 'integer', minimum: 0 }, end: { type: 'integer', minimum: 1 } }
+                    }
+                },
+                projectScope: {
+                    type: 'object',
+                    required: ['projectIds'],
+                    additionalProperties: false,
+                    properties: {
+                        projectIds: { type: 'array', minItems: 1, items: { type: 'string', minLength: 1 } },
+                        policy: { enum: ['strict', 'prefer_project', 'allow_global_fallback'] }
+                    }
+                },
+                entityTypes: {
+                    type: 'array',
+                    minItems: 1,
+                    items: { enum: ['person', 'org', 'project', 'decision'] }
+                }
+            }
+        }
     }
 ];
 export async function callBrainbaseTool(name, rawArgs = {}) {
     if (name in connectedSchemas) {
         return callConnectedOnboardingTool(name, rawArgs);
     }
+    if (name === 'resolve_entity') {
+        return callResolveEntityTool(rawArgs);
+    }
     const args = argsSchema.parse(rawArgs ?? {});
     const dataDir = resolveDataDir(args.dataDir);
     switch (name) {
@@ -316,21 +392,25 @@ export async function callBrainbaseTool(name, rawArgs = {}) {
                 ...portableOntology
             };
         case 'audit_ontology':
-            return auditPersonalOsDirectory(dataDir, { ontologyVersion: resolveOntologyVersion(args.ontologyVersion) });
+            return auditPersonalOsDirectory(dataDir, {
+                ontologyVersion: args.ontologyVersion === undefined
+                    ? undefined
+                    : resolveOntologyVersion(args.ontologyVersion)
+            });
         case 'ontology_impact':
             return getOntologyImpact(args.fromVersion);
     }
     const os = await loadPersonalOs(dataDir);
     switch (name) {
         case 'get_context':
-            return getContext(os);
+            return getContext(os, { project: args.project, asOf: args.as_of ?? args.asOf });
         case 'list_entities':
             return listEntities(os, args.type);
         case 'search':
             if (!args.query) {
                 throw new Error('search requires query');
             }
-            return { results: searchAll(os, args.query, args.limit) };
+            return { results: searchAll(os, args.query, args.limit, { project: args.project, asOf: args.as_of ?? args.asOf }) };
         case 'search_personal_kg':
             if (!args.query) {
                 throw new Error('search_personal_kg requires query');
@@ -341,12 +421,81 @@ export async function callBrainbaseTool(name, rawArgs = {}) {
         case 'infer_decisions':
             return inferPersonalOs(os, {
                 asOf: args.asOf,
-                ontologyVersion: resolveOntologyVersion(args.ontologyVersion)
+                ontologyVersion: args.ontologyVersion === undefined
+                    ? undefined
+                    : resolveOntologyVersion(args.ontologyVersion)
             });
         default:
             throw new Error(`Unknown tool: ${name}`);
     }
 }
+async function callResolveEntityTool(rawArgs) {
+    const args = resolveEntitySchema.parse(rawArgs ?? {});
+    const dataDir = resolveDataDir(args.dataDir);
+    const graphPath = join(dataDir, 'graph.json');
+    let serialized;
+    try {
+        serialized = await readFile(graphPath, 'utf8');
+    }
+    catch {
+        return blockedResolution(args, 'unavailable', 'graph_unavailable');
+    }
+    let graph;
+    try {
+        graph = JSON.parse(serialized);
+    }
+    catch {
+        return blockedResolution(args, 'invalid', 'graph_invalid');
+    }
+    try {
+        validateCanonicalGraph(graph);
+    }
+    catch {
+        return blockedResolution(args, 'invalid', 'graph_invalid');
+    }
+    if (isGraphVersion(graph, 1)) {
+        return {
+            status: 'migration_required',
+            graphSchemaVersion: 1,
+            requiredAction: 'migrate_graph_v2'
+        };
+    }
+    if (!isGraphVersion(graph, 2)) {
+        return blockedResolution(args, 'invalid', 'graph_invalid');
+    }
+    const receipt = resolveText({
+        text: args.text,
+        ...(args.mentionSpans ? { mentionSpans: args.mentionSpans } : {}),
+        ...(args.projectScope ? { projectScope: args.projectScope } : {}),
+        asOf: args.asOf,
+        ...(args.entityTypes ? { entityTypes: args.entityTypes } : {}),
+        source: {
+            authority: 'local_graph',
+            status: 'complete',
+            revision: createHash('sha256').update(serialized).digest('hex'),
+            graph: graph
+        }
+    }).receipt;
+    return { status: 'verified', receipt };
+}
+function blockedResolution(args, sourceStatus, issueCode) {
+    const receipt = resolveText({
+        text: args.text,
+        ...(args.mentionSpans ? { mentionSpans: args.mentionSpans } : {}),
+        ...(args.projectScope ? { projectScope: args.projectScope } : {}),
+        asOf: args.asOf,
+        ...(args.entityTypes ? { entityTypes: args.entityTypes } : {}),
+        source: {
+            authority: 'local_graph',
+            status: sourceStatus,
+            issues: [{ code: issueCode, message: issueCode }]
+        }
+    }).receipt;
+    return { status: 'unverified', receipt };
+}
+function isGraphVersion(graph, version) {
+    return Boolean(graph && typeof graph === 'object' && 'version' in graph && graph.version === version);
+}
 async function callConnectedOnboardingTool(name, rawArgs) {
     const schema = connectedSchemas[name];
     const args = schema.parse(rawArgs ?? {});

package/dist/skills.js

@@ -27,11 +27,14 @@ const SKILL_DEFINITIONS = {
             '2. `brainbase onboard:start --target codex|claude|codecode` を実行し、本人、プロジェクト、関係者、判断基準の最小候補を確認する。',
             '3. ユーザーが明示的に承認した事実だけを `brainbase onboard:seed` で保存する。',
             '4. `brainbase onboard:install --target codex|claude|codecode --dry-run` でMCP設定を確認し、承認後に実設定へ反映して対象エージェントを再起動する。',
-            '5. 新しい実際のエージェントで、Brainbaseの `get_context` と `search` を使うよう明示して最初の現実の依頼を実行する。',
-            '6. 実回答、使われた保存済み文脈、未確認事項をユーザーへ示し、本人に役立ったかを確認する。ここまでを10分以内の初回価値候補ジャーニーとして測る。',
-            '7. CLIの `onboard:demo` は必要なら接続前のプレビューに使えるが、CLIサンプルは初回価値の達成証拠にしない。',
-            '8. 本人が役立つと確認した後だけ、必要に応じてsource診断、追加候補、Skills、ルーティンへ進む。',
-            '9. 継続利用するプロジェクトの詳細が必要なら、本人確認後に `brainbase onboard:projects --write` で登録する。',
+            '5. 新しい実際のエージェントで、Brainbaseの `resolve_entity`、`get_context`、`search` を使うよう明示して最初の現実の依頼を実行する。',
+            '6. 内部準備の宣言を挟まず、利用者向け回答の先頭を「覚えていたこと」にする。続けて「つながったこと」「次にできること」の3節を短い箇条書きで示す。確認済みの事実と未確認事項は混ぜず、初回表示に表は使わない。',
+            '7. 正規ID、関係経路、Receipt digest、生のtool trace、source file名は「詳細」に分け、ホストが対応する場合は折りたたむ。利用者が求めない限り初回の本文へ並べない。',
+            '8. 内部Skillの読み込み、検索の再試行、tool orchestrationは説明しない。失敗によって結果や次の行動が変わる場合だけ示す。',
+            '9. その実回答について本人に役立ったかを確認する。取得開始からここまでを10分以内の初回価値候補ジャーニーとして測る。',
+            '10. CLIの `onboard:demo` は必要なら接続前のプレビューに使えるが、CLIサンプルは初回価値の達成証拠にしない。',
+            '11. 本人が役立つと確認した後だけ、必要に応じてsource診断、追加候補、Skills、ルーティンへ進む。',
+            '12. 継続利用するプロジェクトの詳細が必要なら、本人確認後に `brainbase onboard:projects --write` で登録する。',
             '',
             '## 安全ルール',
             '',
@@ -113,7 +116,7 @@ const SKILL_DEFINITIONS = {
             '3. どの候補idを承認、却下、修正するかをユーザーに確認する。',
             '4. まず `brainbase onboard:apply --from <candidate-file> --select <id>` でdry-runする。手入力の事実には `brainbase onboard:seed` を使う。',
             '5. `--write` は明示的な承認後にだけ使い、canonical filesへ書き込む。',
-            '6. `brainbase doctor` を実行し、必要に応じてBrainbase MCPの `get_context` または `search` で承認済み事実が見えることを確認する。',
+            '6. `brainbase doctor` を実行し、Brainbase MCPの `resolve_entity`、`get_context`、`search` で承認済み事実と正規ID接続が見えることを確認する。',
             '',
             '## 安全ルール',
             '',

package/dist/ssot.d.ts

@@ -1,3 +1,4 @@
+import { type CanonicalGraphMigrationPlan } from './ontology-migration.js';
 import type { PersonalOs } from './types.js';
 export declare function initializePersonalOs(dataDir: string): Promise<void>;
 export declare function loadPersonalOs(dataDir: string): Promise<PersonalOs>;
@@ -11,3 +12,18 @@ export declare function mutatePersonalOsWithSidecar<T>(dataDir: string, sidecarP
     sidecarContent: string;
     result: T;
 }>): Promise<T>;
+export type CanonicalGraphMigrationExecution = CanonicalGraphMigrationPlan & {
+    expectedInputDigest: string;
+    written: boolean;
+};
+/**
+ * Plans or atomically applies the canonical Graph migration.
+ *
+ * The input is always recovered, read, and planned while holding the same
+ * lock used by every canonical SSOT writer. Omitting `write` is a byte-safe
+ * preview; a blocked or already-current plan is never committed.
+ */
+export declare function migrateCanonicalGraph(dataDir: string, options?: {
+    write?: boolean;
+    expectedInputDigest?: string;
+}): Promise<CanonicalGraphMigrationExecution>;