@nuzo/mcp-server 0.1.0 → 0.1.2

package/README.md

@@ -12,7 +12,7 @@ diagnostics.
 Run a published version with:
 
 ```bash
-npx --yes @nuzo/mcp-server@<version>
+npm exec --yes --package=@nuzo/mcp-server@<version> -- nuzo-mcp-server
 ```
 
 Use a fixed version in host plugins and automated configuration. Do not depend

package/dist/handlers.d.ts

@@ -18,6 +18,15 @@ export interface RecallHookToolInput {
     project_scope?: string;
     limit?: number;
 }
+export interface SuggestCaptureToolInput {
+    content: string;
+    kind: MemoryKind;
+    scope: string;
+    tags: string[];
+    source: string;
+    confidence?: number;
+    reason: string;
+}
 export interface ListToolInput {
     scope?: string;
     tags: string[];
@@ -25,6 +34,7 @@ export interface ListToolInput {
 }
 export interface UpdateToolInput {
     id: string;
+    expected_revision?: number;
     content?: string;
     kind?: MemoryKind;
     scope?: string;
@@ -36,6 +46,7 @@ export interface HistoryToolInput {
 }
 export interface ForgetToolInput {
     id: string;
+    expected_revision?: number;
     mode: "archive" | "delete";
     confirm: boolean;
     reason?: string;
@@ -79,6 +90,7 @@ export interface MemoryToolHandlers {
     recall(input: RecallToolInput): Promise<{
         results: Array<{
             id: string;
+            revision: number;
             content: string;
             kind: MemoryKind;
             scope: MemoryScope;
@@ -97,6 +109,7 @@ export interface MemoryToolHandlers {
         limit: number;
         results: Array<{
             id: string;
+            revision: number;
             content: string;
             kind: MemoryKind;
             scope: MemoryScope;
@@ -105,6 +118,13 @@ export interface MemoryToolHandlers {
             reason: string;
         }>;
     }>;
+    suggestCapture(input: SuggestCaptureToolInput): Promise<{
+        status: "ready" | "duplicate";
+        memory_writes: false;
+        requires_confirmation: true;
+        draft: CaptureSuggestionToolDraft;
+        duplicate: MemoryToolRecord | null;
+    }>;
     list(input: ListToolInput): Promise<{
         memories: MemoryToolRecord[];
     }>;
@@ -156,6 +176,7 @@ export interface MemoryToolHandlers {
 }
 export type MemoryToolRecord = {
     id: string;
+    revision: number;
     content: string;
     kind: MemoryKind;
     scope: MemoryScope;
@@ -175,4 +196,13 @@ export type MemoryToolEvent = {
     payload: Record<string, unknown>;
     created_at: string;
 };
+export type CaptureSuggestionToolDraft = {
+    content: string;
+    kind: MemoryKind;
+    scope: MemoryScope;
+    tags: string[];
+    source: string;
+    confidence: number;
+    reason: string;
+};
 export declare function createMemoryToolHandlers(service: MemoryService, options?: MemoryToolHandlerOptions): MemoryToolHandlers;

package/dist/handlers.js

@@ -1,3 +1,4 @@
+import { memoryToolNames } from "./tool-contract.js";
 export function createMemoryToolHandlers(service, options = {}) {
     return {
         async remember(input) {
@@ -51,6 +52,27 @@ export function createMemoryToolHandlers(service, options = {}) {
                 results: results.map(toRecallOutput),
             };
         },
+        async suggestCapture(input) {
+            const suggestInput = {
+                content: input.content,
+                kind: input.kind,
+                scope: input.scope,
+                tags: input.tags,
+                source: input.source,
+                reason: input.reason,
+            };
+            if (input.confidence !== undefined) {
+                suggestInput.confidence = input.confidence;
+            }
+            const result = await service.suggestCapture(suggestInput);
+            return {
+                status: result.status,
+                memory_writes: false,
+                requires_confirmation: true,
+                draft: toSuggestionDraftOutput(result.draft),
+                duplicate: result.duplicate ? toToolRecord(result.duplicate) : null,
+            };
+        },
         async list(input) {
             const listInput = {
                 includeArchived: input.include_archived,
@@ -71,6 +93,9 @@ export function createMemoryToolHandlers(service, options = {}) {
                 id: input.id,
                 actor: "nuzo:mcp",
             };
+            if (input.expected_revision !== undefined) {
+                updateInput.expectedRevision = input.expected_revision;
+            }
             if (input.content !== undefined) {
                 updateInput.content = input.content;
             }
@@ -111,6 +136,9 @@ export function createMemoryToolHandlers(service, options = {}) {
                 confirm: input.confirm,
                 actor: "nuzo:mcp",
             };
+            if (input.expected_revision !== undefined) {
+                forgetInput.expectedRevision = input.expected_revision;
+            }
             if (input.reason !== undefined) {
                 forgetInput.reason = input.reason;
             }
@@ -222,19 +250,7 @@ export function createMemoryToolHandlers(service, options = {}) {
                     archived_memories: archivedMemories,
                     total_memories: totalMemories,
                 },
-                tools: [
-                    "memory.remember",
-                    "memory.recall",
-                    "memory.recall_hook",
-                    "memory.list",
-                    "memory.update",
-                    "memory.history",
-                    "memory.forget",
-                    "memory.forget_many",
-                    "memory.export",
-                    "memory.import",
-                    "memory.doctor",
-                ],
+                tools: [...memoryToolNames],
                 warnings,
             };
         },
@@ -276,6 +292,7 @@ function clampRecallHookLimit(limit) {
 function toRecallOutput(result) {
     return {
         id: result.memory.id,
+        revision: result.memory.revision,
         content: result.memory.content,
         kind: result.memory.kind,
         scope: result.memory.scope,
@@ -284,9 +301,21 @@ function toRecallOutput(result) {
         reason: result.reason,
     };
 }
+function toSuggestionDraftOutput(draft) {
+    return {
+        content: draft.content,
+        kind: draft.kind,
+        scope: draft.scope,
+        tags: draft.tags,
+        source: draft.source,
+        confidence: draft.confidence,
+        reason: draft.reason,
+    };
+}
 function toToolRecord(memory) {
     return {
         id: memory.id,
+        revision: memory.revision,
         content: memory.content,
         kind: memory.kind,
         scope: memory.scope,

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { type MemoryService } from "@nuzo/memory-core";
+import { type MemoryService, type MemoryScope } from "@nuzo/memory-core";
 import type { MemoryDoctorDiagnostics } from "./handlers.js";
 export interface NuzoMcpServerOptions {
     storePath?: string;
+    authorizedScopes?: readonly MemoryScope[];
     doctorDiagnostics?: MemoryDoctorDiagnostics;
 }
 export interface NuzoMcpServerRuntime {

package/dist/index.js

@@ -6,22 +6,28 @@ import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { createMemoryService, DefaultPolicyEngine, RandomIdGenerator, RegexSecretScanner, SQLiteMemoryDatabase, SystemClock, memoryScopePattern, memoryTagPattern, schemaVersion, } from "@nuzo/memory-core";
+import { createMemoryService, DefaultPolicyEngine, RandomIdGenerator, RegexSecretScanner, SQLiteMemoryDatabase, SystemClock, memoryLimits, memoryScopePattern, memoryTagPattern, schemaVersion, } from "@nuzo/memory-core";
 import { createMemoryToolHandlers } from "./handlers.js";
 const defaultStorePath = resolve(homedir(), ".nuzo", "memory", "memories.sqlite");
-const scopeSchema = z.string().regex(memoryScopePattern);
+const scopeSchema = z.string().max(memoryLimits.scopeLength).regex(memoryScopePattern);
 const tagSchema = z.string().regex(memoryTagPattern);
+const memoryIdSchema = z.string().min(1).max(memoryLimits.identifierLength);
+const exportDateSchema = z.string().max(memoryLimits.dateLength);
 export function createNuzoMcpServer(options = {}) {
     return createNuzoMcpServerRuntime(options).server;
 }
 export function createNuzoMcpServerRuntime(options = {}) {
     const storePath = options.storePath ?? defaultStorePath;
     const database = openDatabase(storePath);
-    const service = createService(database);
+    const serviceOptions = {};
+    if (options.authorizedScopes !== undefined) {
+        serviceOptions.authorizedScopes = options.authorizedScopes;
+    }
+    const service = createService(database, serviceOptions);
     let closed = false;
     const server = new McpServer({
         name: "nuzo",
-        version: "0.1.0",
+        version: "0.1.2",
     });
     registerMemoryTools(server, service, {
         storePath,
@@ -54,11 +60,11 @@ export function registerMemoryTools(server, service, options = {}) {
     server.registerTool("memory.remember", {
         description: "Store a local Nuzo memory.",
         inputSchema: {
-            content: z.string().min(1),
+            content: z.string().min(1).max(memoryLimits.contentLength),
             kind: z.enum(["preference", "project_decision", "fact", "instruction", "note"]),
             scope: scopeSchema.default("user:default"),
-            tags: z.array(tagSchema).default([]),
-            source: z.string().min(1).default("nuzo:mcp"),
+            tags: z.array(tagSchema).max(memoryLimits.tags).default([]),
+            source: z.string().min(1).max(memoryLimits.sourceLength).default("nuzo:mcp"),
             confidence: z.number().min(0).max(1).optional(),
         },
     }, async (input) => {
@@ -77,7 +83,7 @@ export function registerMemoryTools(server, service, options = {}) {
     server.registerTool("memory.recall", {
         description: "Recall relevant local Nuzo memories.",
         inputSchema: {
-            query: z.string().min(1),
+            query: z.string().min(1).max(memoryLimits.queryLength),
             scope: scopeSchema.default("user:default"),
             limit: z.number().int().min(1).max(50).default(8),
             include_global: z.boolean().default(false),
@@ -88,7 +94,7 @@ export function registerMemoryTools(server, service, options = {}) {
     server.registerTool("memory.recall_hook", {
         description: "Prototype read-only recall entrypoint for host lifecycle hooks. It never captures or creates memories.",
         inputSchema: {
-            task_context: z.string().min(1),
+            task_context: z.string().min(1).max(8000),
             project_scope: scopeSchema.optional(),
             limit: z.number().int().min(1).max(8).default(5),
         },
@@ -102,11 +108,36 @@ export function registerMemoryTools(server, service, options = {}) {
         }
         return jsonToolResult(await handlers.recallHook(recallHookInput));
     });
+    server.registerTool("memory.suggest_capture", {
+        description: "Validate a proposed capture draft without creating memory. Confirmed writes still use memory.remember.",
+        inputSchema: {
+            content: z.string().min(1).max(memoryLimits.contentLength),
+            kind: z.enum(["preference", "project_decision", "fact", "instruction", "note"]),
+            scope: scopeSchema.default("user:default"),
+            tags: z.array(tagSchema).max(memoryLimits.tags).default([]),
+            source: z.string().min(1).max(memoryLimits.sourceLength).default("nuzo:capture-suggestion"),
+            confidence: z.number().min(0).max(1).optional(),
+            reason: z.string().min(1).max(memoryLimits.reasonLength),
+        },
+    }, async (input) => {
+        const suggestInput = {
+            content: input.content,
+            kind: input.kind,
+            scope: input.scope,
+            tags: input.tags,
+            source: input.source,
+            reason: input.reason,
+        };
+        if (input.confidence !== undefined) {
+            suggestInput.confidence = input.confidence;
+        }
+        return jsonToolResult(await handlers.suggestCapture(suggestInput));
+    });
     server.registerTool("memory.list", {
         description: "List local Nuzo memories.",
         inputSchema: {
             scope: scopeSchema.optional(),
-            tags: z.array(tagSchema).default([]),
+            tags: z.array(tagSchema).max(memoryLimits.tags).default([]),
             include_archived: z.boolean().default(false),
         },
     }, async (input) => {
@@ -122,17 +153,21 @@ export function registerMemoryTools(server, service, options = {}) {
     server.registerTool("memory.update", {
         description: "Update a local Nuzo memory.",
         inputSchema: {
-            id: z.string().min(1),
-            content: z.string().optional(),
+            id: memoryIdSchema,
+            expected_revision: z.number().int().min(1).optional(),
+            content: z.string().max(memoryLimits.contentLength).optional(),
             kind: z.enum(["preference", "project_decision", "fact", "instruction", "note"]).optional(),
             scope: scopeSchema.optional(),
-            tags: z.array(tagSchema).optional(),
+            tags: z.array(tagSchema).max(memoryLimits.tags).optional(),
             confidence: z.number().min(0).max(1).optional(),
         },
     }, async (input) => {
         const updateInput = {
             id: input.id,
         };
+        if (input.expected_revision !== undefined) {
+            updateInput.expected_revision = input.expected_revision;
+        }
         if (input.content !== undefined) {
             updateInput.content = input.content;
         }
@@ -153,7 +188,7 @@ export function registerMemoryTools(server, service, options = {}) {
     server.registerTool("memory.history", {
         description: "List audit events for one Nuzo memory ID.",
         inputSchema: {
-            id: z.string().min(1),
+            id: memoryIdSchema,
         },
     }, async (input) => {
         const historyInput = {
@@ -164,10 +199,11 @@ export function registerMemoryTools(server, service, options = {}) {
     server.registerTool("memory.forget", {
         description: "Archive or delete a local Nuzo memory.",
         inputSchema: {
-            id: z.string().min(1),
+            id: memoryIdSchema,
+            expected_revision: z.number().int().min(1).optional(),
             mode: z.enum(["archive", "delete"]).default("archive"),
             confirm: z.boolean().default(false),
-            reason: z.string().optional(),
+            reason: z.string().max(memoryLimits.reasonLength).optional(),
         },
     }, async (input) => {
         const forgetInput = {
@@ -175,6 +211,9 @@ export function registerMemoryTools(server, service, options = {}) {
             mode: input.mode,
             confirm: input.confirm,
         };
+        if (input.expected_revision !== undefined) {
+            forgetInput.expected_revision = input.expected_revision;
+        }
         if (input.reason !== undefined) {
             forgetInput.reason = input.reason;
         }
@@ -184,12 +223,12 @@ export function registerMemoryTools(server, service, options = {}) {
         description: "Preview or apply a filtered bulk archive/delete operation.",
         inputSchema: {
             scope: scopeSchema.optional(),
-            tags: z.array(tagSchema).default([]),
+            tags: z.array(tagSchema).max(memoryLimits.tags).default([]),
             all: z.boolean().default(false),
             mode: z.enum(["archive", "delete"]).default("archive"),
             confirm: z.boolean().default(false),
             dry_run: z.boolean().default(true),
-            reason: z.string().optional(),
+            reason: z.string().max(memoryLimits.reasonLength).optional(),
         },
     }, async (input) => {
         const forgetInput = {
@@ -211,7 +250,7 @@ export function registerMemoryTools(server, service, options = {}) {
         description: "Export local Nuzo memories as a versioned JSON document.",
         inputSchema: {
             scope: scopeSchema.optional(),
-            tags: z.array(tagSchema).default([]),
+            tags: z.array(tagSchema).max(memoryLimits.tags).default([]),
             include_archived: z.boolean().default(false),
         },
     }, async (input) => {
@@ -230,19 +269,19 @@ export function registerMemoryTools(server, service, options = {}) {
             document: z.object({
                 format: z.literal("nuzo-memory-export"),
                 version: z.literal(1),
-                exported_at: z.string(),
+                exported_at: exportDateSchema,
                 memories: z.array(z.object({
                     scope: scopeSchema,
                     kind: z.enum(["preference", "project_decision", "fact", "instruction", "note"]),
-                    content: z.string(),
-                    tags: z.array(tagSchema),
-                    source: z.string().min(1),
+                    content: z.string().max(memoryLimits.contentLength),
+                    tags: z.array(tagSchema).max(memoryLimits.tags),
+                    source: z.string().min(1).max(memoryLimits.sourceLength),
                     confidence: z.number().min(0).max(1),
-                    created_at: z.string(),
-                    updated_at: z.string(),
-                    last_used_at: z.string().nullable(),
-                    archived_at: z.string().nullable(),
-                })),
+                    created_at: exportDateSchema,
+                    updated_at: exportDateSchema,
+                    last_used_at: exportDateSchema.nullable(),
+                    archived_at: exportDateSchema.nullable(),
+                })).max(memoryLimits.importItems),
             }),
             scope: scopeSchema.optional(),
             dry_run: z.boolean().default(false),
@@ -297,7 +336,7 @@ function isMainModule() {
     }
 }
 function openDatabase(storePath) {
-    mkdirSync(dirname(storePath), { recursive: true });
+    mkdirSync(dirname(storePath), { recursive: true, mode: 0o700 });
     return new SQLiteMemoryDatabase({ path: storePath });
 }
 function isStoreWritable(storePath) {
@@ -310,17 +349,24 @@ function isStoreWritable(storePath) {
         return false;
     }
 }
-function createService(database) {
+function createService(database, options = {}) {
     return createMemoryService({
         store: database,
         searchIndex: database,
         auditLog: database,
         clock: new SystemClock(),
         ids: new RandomIdGenerator(),
-        policy: new DefaultPolicyEngine(new RegexSecretScanner()),
+        policy: new DefaultPolicyEngine(new RegexSecretScanner(), toPolicyOptions(options)),
         transactions: database,
     });
 }
+function toPolicyOptions(options) {
+    const policyOptions = {};
+    if (options.authorizedScopes !== undefined) {
+        policyOptions.allowedScopes = options.authorizedScopes;
+    }
+    return policyOptions;
+}
 function jsonToolResult(value) {
     return {
         content: [

package/dist/tool-contract.d.ts

@@ -0,0 +1,3 @@
+export declare const memoryToolNames: readonly ["memory.remember", "memory.recall", "memory.recall_hook", "memory.suggest_capture", "memory.list", "memory.update", "memory.history", "memory.forget", "memory.forget_many", "memory.export", "memory.import", "memory.doctor"];
+export declare const sortedMemoryToolNames: ("memory.remember" | "memory.recall" | "memory.recall_hook" | "memory.suggest_capture" | "memory.list" | "memory.update" | "memory.history" | "memory.forget" | "memory.forget_many" | "memory.export" | "memory.import" | "memory.doctor")[];
+export type MemoryToolName = typeof memoryToolNames[number];

package/dist/tool-contract.js

@@ -0,0 +1,15 @@
+export const memoryToolNames = [
+    "memory.remember",
+    "memory.recall",
+    "memory.recall_hook",
+    "memory.suggest_capture",
+    "memory.list",
+    "memory.update",
+    "memory.history",
+    "memory.forget",
+    "memory.forget_many",
+    "memory.export",
+    "memory.import",
+    "memory.doctor",
+];
+export const sortedMemoryToolNames = [...memoryToolNames].sort();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuzo/mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for Nuzo.",
   "keywords": [
     "ai-agents",
@@ -33,7 +33,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@nuzo/memory-core": "0.1.0",
+    "@nuzo/memory-core": "0.1.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.1.13"
   },