@henrikogard/auroradocs-mcp 0.2.1 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ authenticated requests to `https://api.auroradocs.eu`.
 
 The public package is `@henrikogard/auroradocs-mcp` and the executable is
 `aurora-mcp`. The latest published package and current source version are
-`0.2.1`.
+`0.3.0`.
 
 For an end-to-end installation walkthrough, use the dedicated
 [Setup guide](docs/setup.md). AI assistants and client integrators should start
@@ -19,7 +19,8 @@ also apply the bounded [read-only agent profiles](docs/agent-profiles.md).
 - an AuroraDocs account with an AuroraCloud-backed workspace
 - permission to create an MCP token for that workspace
 - a supported local MCP client: Claude Desktop, Claude Code, Codex, or another
-  client that can start a stdio server
+  client that can start a stdio server. Claude Desktop can also install the
+  `.mcpb` bundle from this repository instead of editing JSON.
 
 Browser-only workspaces and Local folders workspaces are not AuroraCloud MCP
 destinations. By default the server does not read a browser tab or local
@@ -88,7 +89,7 @@ in the knowledge-search recipe above.
 ## Configure a client
 
 All examples below use the production AuroraCloud API, a new client credential,
-and package version `0.2.1`. Replace `REDACTED` locally. Do not commit the
+and package version `0.3.0`. Replace `REDACTED` locally. Do not commit the
 resulting configuration. The examples store the token in the client's saved
 configuration, so protect that file as a credential.
 
@@ -111,15 +112,22 @@ MCP-token authentication only.
 
 ### Claude Desktop
 
-Open Claude Desktop's developer settings and edit its MCP configuration. Add
-this server under `mcpServers`, preserving any servers already present:
+For one-click install, pack `auroradocs.mcpb` with `pnpm pack:mcpb` and install
+it from Claude Desktop **Settings → Extensions → Advanced settings → Install
+Extension…**. The extension asks for the AuroraCloud API URL and the MCP token
+(the token is stored in the OS keychain). Optional fields authorize one Obsidian
+vault and a private plan/journal directory.
+
+To configure it by hand, open Claude Desktop's developer settings and edit its
+MCP configuration. Add this server under `mcpServers`, preserving any servers
+already present:
 
 ```json
 {
   "mcpServers": {
     "auroradocs": {
       "command": "npx",
-      "args": ["-y", "@henrikogard/auroradocs-mcp@0.2.1"],
+      "args": ["-y", "@henrikogard/auroradocs-mcp@0.3.0"],
       "env": {
         "AURORA_API_URL": "https://api.auroradocs.eu",
         "AURORA_API_TOKEN": "REDACTED"
@@ -142,7 +150,7 @@ Options must appear before the server name:
 claude mcp add --transport stdio --scope user \
   --env AURORA_API_URL=https://api.auroradocs.eu \
   --env AURORA_API_TOKEN=REDACTED \
-  auroradocs -- npx -y @henrikogard/auroradocs-mcp@0.2.1
+  auroradocs -- npx -y @henrikogard/auroradocs-mcp@0.3.0
 ```
 
 Run `claude mcp get auroradocs` to inspect the saved entry, then use `/mcp` in
@@ -157,7 +165,7 @@ The installed Codex CLI accepts `--env` for local stdio servers:
 codex mcp add \
   --env AURORA_API_URL=https://api.auroradocs.eu \
   --env AURORA_API_TOKEN=REDACTED \
-  auroradocs -- npx -y @henrikogard/auroradocs-mcp@0.2.1
+  auroradocs -- npx -y @henrikogard/auroradocs-mcp@0.3.0
 ```
 
 Run `codex mcp get auroradocs` to inspect the saved entry.
@@ -169,7 +177,7 @@ Use this valid generic JSON shape when a client accepts an MCP server object:
 ```json
 {
   "command": "npx",
-  "args": ["-y", "@henrikogard/auroradocs-mcp@0.2.1"],
+  "args": ["-y", "@henrikogard/auroradocs-mcp@0.3.0"],
   "env": {
     "AURORA_API_URL": "https://api.auroradocs.eu",
     "AURORA_API_TOKEN": "REDACTED"
@@ -220,9 +228,12 @@ E2EE all stop before AuroraDocs writes.
 
 Imports run in resume-safe batches, keep private plan metadata plus a
 content-free progress journal outside the vault, survive MCP process restarts,
-and never modify the source. Back up both systems first and start
-with a small test workspace. See [Obsidian import](docs/obsidian-import.md) for
-configuration, mapping, consent, recovery, and fidelity limits.
+and never modify the source. Custom-database plans use the same private state
+directory. `list_workspaces` re-reads the current grant set from AuroraCloud, so
+a new or revoked grant is visible without restarting the MCP process. Back up
+both systems first and start with a small test workspace. See
+[Obsidian import](docs/obsidian-import.md) for configuration, mapping, consent,
+recovery, and fidelity limits.
 
 Analysis rejects more than 256 MiB of eligible Markdown/Canvas source files,
 and hidden, plugin, Git, cache, trash, and other ignored paths cannot be read as
@@ -262,7 +273,8 @@ the old token. Tokens cannot be extended or recovered.
 ## Security model
 
 - The MCP protocol process is local and stdio-only; AuroraDocs does not provide
-  a hosted MCP HTTP, SSE, or OAuth endpoint.
+  a hosted MCP HTTP, SSE, or OAuth endpoint. The server speaks MCP 2026-07-28
+  and still serves 2025-era stdio clients.
 - AuroraCloud checks workspace membership, token scopes, the member's current
   role, expiry, revocation, rate limits, and audit events on requests.
 - E2EE content that is locked or unavailable is reported that way. The server

package/dist/customDatabasePlans.d.ts

@@ -0,0 +1,6 @@
+import { type CustomDatabasePlan } from './customDatabases.js';
+export declare function storeCustomDatabasePlan(plan: CustomDatabasePlan): void;
+export declare function getStoredCustomDatabasePlan(workspaceId: string, planId: string): CustomDatabasePlan | null;
+export declare function clearCustomDatabasePlansForTests(): void;
+export declare function writeCustomDatabasePlan(plan: CustomDatabasePlan, env?: Record<string, string | undefined>): Promise<string | null>;
+export declare function readCustomDatabasePlan(workspaceId: string, planId: string, env?: Record<string, string | undefined>): Promise<CustomDatabasePlan | null>;

package/dist/customDatabasePlans.js

@@ -0,0 +1,96 @@
+import { lstat, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { hashCustomDatabasePlan, } from './customDatabases.js';
+import { ToolInputError } from './errors.js';
+import { mcpStatePersistenceEnabled, resolveMcpStateDir, writeMcpStateFile, } from './mcpState.js';
+const PLAN_STORE = new Map();
+const PLAN_MAX_BYTES = 1 * 1024 * 1024;
+const PLAN_STORE_LIMIT = 100;
+function planKey(workspaceId, planId) {
+    return `${workspaceId}:${planId}`;
+}
+function isPersistedPlanId(planId) {
+    return /^[A-Za-z0-9_-]{1,128}$/.test(planId);
+}
+function planFileName(planId) {
+    if (!isPersistedPlanId(planId))
+        throw new ToolInputError('Invalid custom database plan ID');
+    return `custom-database-plan-${planId}.json`;
+}
+function pruneExpired(now = Date.now()) {
+    for (const [key, plan] of PLAN_STORE) {
+        if (Date.parse(plan.expiresAt) <= now)
+            PLAN_STORE.delete(key);
+    }
+    while (PLAN_STORE.size >= PLAN_STORE_LIMIT) {
+        const oldest = PLAN_STORE.keys().next().value;
+        if (!oldest)
+            break;
+        PLAN_STORE.delete(oldest);
+    }
+}
+function assertPersistedPlan(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid persisted custom database plan');
+    const plan = value;
+    if (typeof plan.planId !== 'string'
+        || typeof plan.planHash !== 'string'
+        || typeof plan.workspaceId !== 'string'
+        || typeof plan.createdAt !== 'string'
+        || typeof plan.expiresAt !== 'string'
+        || !Number.isFinite(Date.parse(plan.createdAt))
+        || !Number.isFinite(Date.parse(plan.expiresAt))
+        || hashCustomDatabasePlan(plan) !== plan.planHash) {
+        throw new Error('Invalid persisted custom database plan');
+    }
+}
+export function storeCustomDatabasePlan(plan) {
+    pruneExpired();
+    PLAN_STORE.set(planKey(plan.workspaceId, plan.planId), plan);
+}
+export function getStoredCustomDatabasePlan(workspaceId, planId) {
+    pruneExpired();
+    return PLAN_STORE.get(planKey(workspaceId, planId)) ?? null;
+}
+export function clearCustomDatabasePlansForTests() {
+    if (process.env['NODE_ENV'] !== 'test') {
+        throw new Error('clearCustomDatabasePlansForTests is only available in test environments');
+    }
+    PLAN_STORE.clear();
+}
+export async function writeCustomDatabasePlan(plan, env = process.env) {
+    storeCustomDatabasePlan(plan);
+    if (!mcpStatePersistenceEnabled(env))
+        return null;
+    const serialized = `${JSON.stringify(plan, null, 2)}\n`;
+    return writeMcpStateFile(resolveMcpStateDir(env), planFileName(plan.planId), serialized, PLAN_MAX_BYTES);
+}
+export async function readCustomDatabasePlan(workspaceId, planId, env = process.env) {
+    const memory = getStoredCustomDatabasePlan(workspaceId, planId);
+    if (memory)
+        return memory;
+    if (!isPersistedPlanId(planId))
+        return null;
+    if (!mcpStatePersistenceEnabled(env) && !env['AURORA_MCP_STATE_DIR']?.trim())
+        return null;
+    const file = path.join(resolveMcpStateDir(env), planFileName(planId));
+    let serialized;
+    try {
+        const info = await lstat(file);
+        if (info.isSymbolicLink() || !info.isFile() || info.size > PLAN_MAX_BYTES) {
+            throw new Error('Invalid persisted custom database plan file');
+        }
+        serialized = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    const value = JSON.parse(serialized);
+    assertPersistedPlan(value);
+    if (value.planId !== planId || value.workspaceId !== workspaceId)
+        return null;
+    storeCustomDatabasePlan(value);
+    return value;
+}

package/dist/index.js

@@ -19,10 +19,9 @@
  *   AURORA_API_EMAIL     AuroraCloud user email (legacy/dev fallback)
  *   AURORA_API_PASSWORD  AuroraCloud user password (legacy/dev fallback)
  */
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import { authenticate } from './auroraClient.js';
 import { createAuroraMcpServer } from './server.js';
-// ── Main ─────────────────────────────────────────────────────────────────────
 async function main() {
     let context;
     try {
@@ -35,9 +34,7 @@ async function main() {
         process.stderr.write('AuroraDocs MCP authentication failed.\n');
         process.exit(1);
     }
-    const server = createAuroraMcpServer(context);
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
+    serveStdio(() => createAuroraMcpServer(context));
     process.stderr.write('AuroraDocs MCP server running.\n');
 }
 main().catch(() => {

package/dist/mcpState.d.ts

@@ -0,0 +1,4 @@
+export declare function resolveMcpStateDir(env?: Record<string, string | undefined>): string;
+export declare function mcpStatePersistenceEnabled(env?: Record<string, string | undefined>): boolean;
+export declare function ensureMcpStateDirectory(stateDir: string): Promise<void>;
+export declare function writeMcpStateFile(stateDir: string, fileName: string, serialized: string, maxBytes: number): Promise<string>;

package/dist/mcpState.js

@@ -0,0 +1,46 @@
+import { randomBytes } from 'node:crypto';
+import { chmod, lstat, mkdir, open, rename, unlink } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+export function resolveMcpStateDir(env = process.env) {
+    const raw = env['AURORA_MCP_STATE_DIR']?.trim();
+    return path.resolve(raw || path.join(os.homedir(), '.auroradocs-mcp'));
+}
+export function mcpStatePersistenceEnabled(env = process.env) {
+    if (env['AURORA_MCP_STATE_DIR']?.trim())
+        return true;
+    return env['NODE_ENV'] !== 'test';
+}
+export async function ensureMcpStateDirectory(stateDir) {
+    await mkdir(stateDir, { recursive: true, mode: 0o700 });
+    const info = await lstat(stateDir);
+    if (info.isSymbolicLink() || !info.isDirectory())
+        throw new Error('MCP state path must be a real directory');
+    await chmod(stateDir, 0o700);
+}
+export async function writeMcpStateFile(stateDir, fileName, serialized, maxBytes) {
+    if (!/^[A-Za-z0-9._-]{1,180}$/.test(fileName))
+        throw new Error('Invalid MCP state file name');
+    await ensureMcpStateDirectory(stateDir);
+    const destination = path.join(stateDir, fileName);
+    const temporary = path.join(stateDir, `.${fileName}.${randomBytes(8).toString('hex')}.tmp`);
+    if (Buffer.byteLength(serialized) > maxBytes)
+        throw new Error('MCP state file exceeds its safety limit');
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+        await handle.writeFile(serialized, 'utf8');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(temporary, destination);
+        await chmod(destination, 0o600);
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => { });
+        throw error;
+    }
+    return destination;
+}

package/dist/mcpSurfaces.d.ts

@@ -1,4 +1,4 @@
-import type { CompleteRequest, CompleteResult, GetPromptResult, ListPromptsResult, ListResourceTemplatesResult, ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
+import type { CompleteRequest, CompleteResult, GetPromptResult, ListPromptsResult, ListResourceTemplatesResult, ReadResourceResult } from '@modelcontextprotocol/server';
 import type { AuroraConnectionContext } from './contracts.js';
 export declare function getAuroraServerInstructions(): string;
 export declare function completeAuroraArgument(params: CompleteRequest['params'], context: AuroraConnectionContext): Promise<CompleteResult>;

package/dist/obsidian/config.js

@@ -1,5 +1,5 @@
-import os from 'node:os';
 import path from 'node:path';
+import { resolveMcpStateDir } from '../mcpState.js';
 function isInside(parent, candidate) {
     const relative = path.relative(parent, candidate);
     return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
@@ -11,8 +11,7 @@ export function resolveObsidianConfig(env = process.env) {
     if (!path.isAbsolute(rawRoot))
         throw new Error('AURORA_OBSIDIAN_VAULT_ROOT must be an absolute path.');
     const vaultRoot = path.resolve(rawRoot);
-    const rawStateDir = env['AURORA_MCP_STATE_DIR']?.trim();
-    const stateDir = path.resolve(rawStateDir || path.join(os.homedir(), '.auroradocs-mcp'));
+    const stateDir = resolveMcpStateDir(env);
     if (isInside(vaultRoot, stateDir)) {
         throw new Error('AURORA_MCP_STATE_DIR must be outside the authorized Obsidian vault.');
     }

package/dist/obsidian/consent.d.ts

@@ -1,3 +1,4 @@
+import type { ElicitRequestFormParams } from '@modelcontextprotocol/server';
 export type ObsidianConsentPreview = {
     planId: string;
     planHash: string;
@@ -33,10 +34,13 @@ export type ObsidianConsentDecision = {
     source: 'tool_input' | 'elicitation';
 };
 export type ObsidianConsentRequest = (preview: ObsidianConsentPreview) => Promise<ObsidianConsentResponse>;
+export declare class ObsidianElicitationRequired extends Error {
+    readonly preview: ObsidianConsentPreview;
+    constructor(preview: ObsidianConsentPreview);
+}
 export declare function buildObsidianConsentElicitation(preview: ObsidianConsentPreview): ElicitRequestFormParams;
 export declare function decideObsidianImportConsent(input: {
     confirmed?: unknown;
     preview: ObsidianConsentPreview;
     requestConsent?: ObsidianConsentRequest;
 }): Promise<ObsidianConsentDecision>;
-import type { ElicitRequestFormParams } from '@modelcontextprotocol/sdk/types.js';

package/dist/obsidian/consent.js

@@ -1,3 +1,11 @@
+export class ObsidianElicitationRequired extends Error {
+    preview;
+    constructor(preview) {
+        super('Obsidian import requires form elicitation');
+        this.name = 'ObsidianElicitationRequired';
+        this.preview = preview;
+    }
+}
 export function buildObsidianConsentElicitation(preview) {
     return {
         mode: 'form',
@@ -43,7 +51,9 @@ export async function decideObsidianImportConsent(input) {
     try {
         response = await input.requestConsent(input.preview);
     }
-    catch {
+    catch (error) {
+        if (error instanceof ObsidianElicitationRequired)
+            throw error;
         return { outcome: 'cancelled', source: 'elicitation' };
     }
     if (response.action === 'decline')

package/dist/obsidian/importer.d.ts

@@ -2,6 +2,10 @@ import type { AuroraAttachmentUpload, AuroraImportCapabilities, AuroraObjectReco
 import { type ObjectTypeDef, type ObjectTypeSchema, type PropertyValueType } from '../customDatabases.js';
 import { type StoredObsidianImportPlan } from './importPlan.js';
 import type { AuthorizedVault } from './vaultAccess.js';
+export type ObsidianImportProgress = {
+    completed: number;
+    total: number;
+};
 export type ObsidianImportDependencies = {
     getCapabilities(workspaceId: string): Promise<AuroraImportCapabilities>;
     listObjectTypes(workspaceId: string): Promise<ObjectTypeDef[]>;
@@ -49,4 +53,5 @@ export type ObsidianImportBatchResult = {
 export declare function runObsidianImportBatch(stored: StoredObsidianImportPlan, vault: AuthorizedVault, stateDir: string, options?: {
     batchSize?: number;
     dependencies?: ObsidianImportDependencies;
+    onProgress?: (progress: ObsidianImportProgress) => void | Promise<void>;
 }): Promise<ObsidianImportBatchResult>;

package/dist/obsidian/importer.js

@@ -198,6 +198,12 @@ export async function runObsidianImportBatch(stored, vault, stateDir, options =
     journal.status = 'in_progress';
     journal.updatedAt = dependencies.now().toISOString();
     await writeImportJournal(stateDir, journal);
+    const total = stored.plan.entries.length;
+    const reportProgress = async () => {
+        const completed = Object.values(journal.entries).filter((entry) => entry.status === 'complete').length;
+        await options.onProgress?.({ completed, total });
+    };
+    await reportProgress();
     const warnings = [];
     const selection = selectPendingEntries(stored.plan.entries, journal, batchSize);
     const pending = selection.entries;
@@ -456,5 +462,6 @@ export async function runObsidianImportBatch(stored, vault, stateDir, options =
     const result = resultFromJournal(stored, journal, warnings);
     journal.updatedAt = dependencies.now().toISOString();
     await writeImportJournal(stateDir, journal);
+    await reportProgress();
     return result;
 }

package/dist/server.d.ts

@@ -1,3 +1,3 @@
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Server } from '@modelcontextprotocol/server';
 import type { AuroraConnectionContext } from './contracts.js';
 export declare function createAuroraMcpServer(context: AuroraConnectionContext): Server;

package/dist/server.js

@@ -1,70 +1,131 @@
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { CallToolRequestSchema, CompleteRequestSchema, ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { inputRequired, inputResponse, ProtocolError, ProtocolErrorCode, Server, } from '@modelcontextprotocol/server';
+import { listGrantedWorkspaces } from './auroraClient.js';
 import { ToolInputError, toSafeToolError } from './errors.js';
 import { getAuroraPromptDefinitions, getAuroraPrompt, getAuroraResourceTemplates, getAuroraServerInstructions, completeAuroraArgument, readAuroraResource, } from './mcpSurfaces.js';
 import { executeToolCall, toMcpToolCallResult } from './tools.js';
 import { getToolDefinitions } from './toolCatalog.js';
 import { SERVER_VERSION } from './version.js';
-import { buildObsidianConsentElicitation } from './obsidian/consent.js';
+import { buildObsidianConsentElicitation, ObsidianElicitationRequired } from './obsidian/consent.js';
+const LIST_CACHE = { ttlMs: 300_000, cacheScope: 'private' };
+const READ_CACHE = { ttlMs: 0, cacheScope: 'private' };
+function clientSupportsFormElicitation(ctx, server) {
+    const envelope = ctx.mcpReq.envelope;
+    const elicitation = envelope?.clientCapabilities?.elicitation ?? server.getClientCapabilities()?.elicitation;
+    if (!elicitation)
+        return false;
+    if (Object.hasOwn(elicitation, 'form'))
+        return Boolean(elicitation.form);
+    return Object.keys(elicitation).length === 0;
+}
+function withCacheHint(result, ctx, hint) {
+    if (!ctx.mcpReq.envelope)
+        return result;
+    return { ...result, ...hint };
+}
 export function createAuroraMcpServer(context) {
     const server = new Server({ name: 'auroradocs-mcp', version: SERVER_VERSION }, {
         capabilities: { tools: {}, prompts: {}, resources: {}, completions: {} },
         instructions: getAuroraServerInstructions(),
+        cacheHints: {
+            'tools/list': LIST_CACHE,
+            'prompts/list': LIST_CACHE,
+            'resources/templates/list': LIST_CACHE,
+            'resources/read': READ_CACHE,
+            'server/discover': LIST_CACHE,
+        },
     });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    const refreshClientGrants = context.kind === 'client'
+        ? () => listGrantedWorkspaces()
+        : undefined;
+    server.setRequestHandler('tools/list', async (_request, ctx) => withCacheHint({
         tools: getToolDefinitions(),
-    }));
-    server.setRequestHandler(CompleteRequestSchema, async (request) => {
+    }, ctx, LIST_CACHE));
+    server.setRequestHandler('completion/complete', async (request, _ctx) => {
         try {
             return await completeAuroraArgument(request.params, context);
         }
         catch (error) {
             if (error instanceof ToolInputError)
-                throw new McpError(ErrorCode.InvalidParams, error.message);
-            throw new McpError(ErrorCode.InternalError, toSafeToolError(error).message);
+                throw new ProtocolError(ProtocolErrorCode.InvalidParams, error.message);
+            throw new ProtocolError(ProtocolErrorCode.InternalError, toSafeToolError(error).message);
         }
     });
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    server.setRequestHandler('tools/call', async (request, ctx) => {
         const { name, arguments: args } = request.params;
-        const formElicitation = server.getClientCapabilities()?.elicitation?.form;
-        const result = await executeToolCall(name, (args ?? {}), context, {
-            requestObsidianImportConsent: formElicitation
-                ? async (preview) => {
-                    const response = await server.elicitInput(buildObsidianConsentElicitation(preview));
-                    return { action: response.action, content: response.content };
-                }
-                : undefined,
-        });
-        return toMcpToolCallResult(result);
+        const formElicitation = clientSupportsFormElicitation(ctx, server);
+        const progressToken = ctx.mcpReq._meta?.progressToken;
+        try {
+            const result = await executeToolCall(name, (args ?? {}), context, {
+                refreshClientGrants,
+                reportProgress: progressToken === undefined
+                    ? undefined
+                    : async (progress) => {
+                        await ctx.mcpReq.notify({
+                            method: 'notifications/progress',
+                            params: {
+                                progressToken,
+                                progress: progress.completed,
+                                total: progress.total,
+                            },
+                        });
+                    },
+                requestObsidianImportConsent: formElicitation
+                    ? async (preview) => {
+                        const view = inputResponse(ctx.mcpReq.inputResponses, 'consent');
+                        if (view.kind === 'missing')
+                            throw new ObsidianElicitationRequired(preview);
+                        if (view.kind === 'elicit') {
+                            return {
+                                action: view.action === 'accept' ? 'accept' : view.action === 'decline' ? 'decline' : 'cancel',
+                                content: view.content,
+                            };
+                        }
+                        throw new ObsidianElicitationRequired(preview);
+                    }
+                    : undefined,
+            });
+            const definition = getToolDefinitions().find((tool) => tool.name === name);
+            return server.projectCallToolResult(toMcpToolCallResult(result), definition?.outputSchema);
+        }
+        catch (error) {
+            if (error instanceof ObsidianElicitationRequired) {
+                return inputRequired({
+                    inputRequests: {
+                        consent: inputRequired.elicit(buildObsidianConsentElicitation(error.preview)),
+                    },
+                });
+            }
+            throw error;
+        }
     });
-    server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    server.setRequestHandler('prompts/list', async (_request, ctx) => withCacheHint({
         prompts: getAuroraPromptDefinitions(),
-    }));
-    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    }, ctx, LIST_CACHE));
+    server.setRequestHandler('prompts/get', async (request) => {
         try {
             return getAuroraPrompt(request.params.name, request.params.arguments ?? {});
         }
         catch (error) {
             if (error instanceof ToolInputError)
-                throw new McpError(ErrorCode.InvalidParams, error.message);
+                throw new ProtocolError(ProtocolErrorCode.InvalidParams, error.message);
             throw error;
         }
     });
-    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+    server.setRequestHandler('resources/templates/list', async (_request, ctx) => withCacheHint({
         resourceTemplates: getAuroraResourceTemplates(),
-    }));
-    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    }, ctx, LIST_CACHE));
+    server.setRequestHandler('resources/read', async (request, ctx) => {
         try {
-            return await readAuroraResource(request.params.uri, context);
+            return withCacheHint(await readAuroraResource(request.params.uri, context), ctx, READ_CACHE);
         }
         catch (error) {
             if (error instanceof ToolInputError)
-                throw new McpError(ErrorCode.InvalidParams, error.message);
+                throw new ProtocolError(ProtocolErrorCode.InvalidParams, error.message);
             const safeError = toSafeToolError(error);
             const code = safeError.code === 'not_found'
-                ? ErrorCode.InvalidParams
-                : ErrorCode.InternalError;
-            throw new McpError(code, safeError.message);
+                ? ProtocolErrorCode.InvalidParams
+                : ProtocolErrorCode.InternalError;
+            throw new ProtocolError(code, safeError.message);
         }
     });
     return server;

package/dist/tools.d.ts

@@ -5,7 +5,7 @@ import type { CustomDatabasePlan, CustomDatabaseRecipe, ObjectTypeDef } from './
 import { getObsidianImportPlanPage } from './obsidian/importPlan.js';
 import type { ObsidianImportPlanPreview } from './obsidian/importPlan.js';
 import { type ObsidianConsentPreview, type ObsidianConsentRequest } from './obsidian/consent.js';
-import { type ObsidianImportBatchResult } from './obsidian/importer.js';
+import { type ObsidianImportBatchResult, type ObsidianImportProgress } from './obsidian/importer.js';
 import { type ObsidianImportStatus } from './obsidian/journal.js';
 import type { StoredObsidianImportPlan } from './obsidian/importPlan.js';
 import type { AuroraConnectionContext, Availability, GrantedWorkspace, ProjectChangesResult, ProjectContextResult, ToolErrorResult } from './contracts.js';
@@ -203,6 +203,8 @@ export type ToolExecutionOptions = {
     requestObsidianImportConsent?: ObsidianConsentRequest;
     runObsidianImport?: (stored: StoredObsidianImportPlan, batchSize: number) => Promise<ObsidianImportBatchResult>;
     now?: () => Date;
+    refreshClientGrants?: () => Promise<GrantedWorkspace[]>;
+    reportProgress?: (progress: ObsidianImportProgress) => void | Promise<void>;
 };
 export declare function resolveWorkspace(context: AuroraConnectionContext, input: Record<string, unknown>): string;
 export declare function executeToolCall(name: string, input: Record<string, unknown>, connection: AuroraConnectionContext | string, options?: ToolExecutionOptions): Promise<ToolResult>;

package/dist/tools.js

@@ -16,8 +16,9 @@ import { resolveObsidianConfig } from './obsidian/config.js';
 import { openAuthorizedVault } from './obsidian/vaultAccess.js';
 import { analyzeObsidianVault } from './obsidian/analyzer.js';
 import { assertCurrentObsidianImportPlan, buildObsidianImportPlan, getObsidianImportPlanPage, getStoredObsidianImportPlan, readObsidianImportPlan, storeObsidianImportPlan, summarizeObsidianImportPlan, writeObsidianImportPlan, } from './obsidian/importPlan.js';
-import { decideObsidianImportConsent, } from './obsidian/consent.js';
+import { decideObsidianImportConsent, ObsidianElicitationRequired, } from './obsidian/consent.js';
 import { runObsidianImportBatch } from './obsidian/importer.js';
+import { readCustomDatabasePlan, writeCustomDatabasePlan, } from './customDatabasePlans.js';
 import { readImportJournal, summarizeImportJournal } from './obsidian/journal.js';
 export function buildMcpObjectPropertyResult(input) {
     const computedLabels = new Map();
@@ -93,7 +94,6 @@ function invalidInput(message) {
 function notFound(message) {
     return { type: 'error', code: 'not_found', message, retryable: false };
 }
-const CUSTOM_DATABASE_PLANS = new Map();
 async function loadStoredObsidianImportPlan(workspaceId, planId) {
     const memory = getStoredObsidianImportPlan(workspaceId, planId);
     if (memory)
@@ -131,20 +131,6 @@ function cloneRecipe(recipe) {
         } : {}),
     };
 }
-function storeCustomDatabasePlan(plan) {
-    const now = Date.now();
-    for (const [key, value] of CUSTOM_DATABASE_PLANS) {
-        if (Date.parse(value.expiresAt) <= now)
-            CUSTOM_DATABASE_PLANS.delete(key);
-    }
-    while (CUSTOM_DATABASE_PLANS.size >= 100) {
-        const oldest = CUSTOM_DATABASE_PLANS.keys().next().value;
-        if (!oldest)
-            break;
-        CUSTOM_DATABASE_PLANS.delete(oldest);
-    }
-    CUSTOM_DATABASE_PLANS.set(`${plan.workspaceId}:${plan.planId}`, plan);
-}
 function optionalPresentation(input, key) {
     if (!Object.hasOwn(input, key))
         return undefined;
@@ -401,17 +387,41 @@ export function resolveWorkspace(context, input) {
     }
     return matches[0].workspaceId;
 }
+async function refreshClientGrants(context, options) {
+    if (context.kind !== 'client' || !options.refreshClientGrants)
+        return;
+    const workspaces = await options.refreshClientGrants();
+    context.workspaces.splice(0, context.workspaces.length, ...workspaces);
+}
 export async function executeToolCall(name, input, connection, options = {}) {
     try {
         const context = normalizeConnectionContext(connection);
-        if (name === 'list_workspaces')
+        if (name === 'list_workspaces') {
+            await refreshClientGrants(context, options);
             return { type: 'workspaces', workspaces: context.workspaces };
+        }
         if (name === 'get_mcp_tool_coverage' || name === 'get_mcp_workflow_recipes' || name === 'get_custom_database_recipes') {
             return await executeToolCallUnsafe(name, input, context.kind === 'legacy_workspace' ? context.defaultWorkspaceId : '', options);
         }
-        return await executeToolCallUnsafe(name, input, resolveWorkspace(context, input), options);
+        try {
+            return await executeToolCallUnsafe(name, input, resolveWorkspace(context, input), options);
+        }
+        catch (error) {
+            if (error instanceof ObsidianElicitationRequired)
+                throw error;
+            if (!(error instanceof ToolInputError)
+                || error.message !== 'Workspace selector does not match an available grant'
+                || context.kind !== 'client'
+                || !options.refreshClientGrants) {
+                throw error;
+            }
+            await refreshClientGrants(context, options);
+            return await executeToolCallUnsafe(name, input, resolveWorkspace(context, input), options);
+        }
     }
     catch (error) {
+        if (error instanceof ObsidianElicitationRequired)
+            throw error;
         return toSafeToolError(error);
     }
 }
@@ -645,7 +655,10 @@ async function executeToolCallUnsafe(name, input, workspaceId, options) {
                     throw new ToolInputError(error instanceof Error ? error.message : 'Obsidian vault authorization is unavailable');
                 }
                 const vault = await openAuthorizedVault(config);
-                return runObsidianImportBatch(approved, vault, config.stateDir, { batchSize: size });
+                return runObsidianImportBatch(approved, vault, config.stateDir, {
+                    batchSize: size,
+                    onProgress: options.reportProgress,
+                });
             });
             return { type: 'obsidian_import_batch', result: await run(stored, batchSize.value) };
         }
@@ -700,7 +713,7 @@ async function executeToolCallUnsafe(name, input, workspaceId, options) {
                 existingTypes: objectTypes,
                 assumptions: Array.isArray(input['assumptions']) ? input['assumptions'].map((entry) => String(entry).trim()).filter(Boolean).slice(0, 20) : [],
             });
-            storeCustomDatabasePlan(plan);
+            await writeCustomDatabasePlan(plan);
             return { type: 'custom_database_plan', plan, summary: summarizeCustomDatabasePlan(plan) };
         }
         case 'apply_custom_database_plan': {
@@ -708,7 +721,7 @@ async function executeToolCallUnsafe(name, input, workspaceId, options) {
             const planHash = readString(input['plan_hash']);
             if (!planId || !planHash)
                 return invalidInput('Plan ID and plan hash are required');
-            const plan = CUSTOM_DATABASE_PLANS.get(`${workspaceId}:${planId}`);
+            const plan = await readCustomDatabasePlan(workspaceId, planId);
             if (!plan || plan.planHash !== planHash)
                 return invalidInput('The custom database plan is missing, expired, or does not match the approved hash');
             const existingTypes = await listAuroraObjectTypes(workspaceId);

package/docs/agent-guide.md

@@ -5,7 +5,7 @@ MCP server. The server also sends a shorter version as MCP initialization
 instructions, so compatible clients receive the core workspace, approval,
 citation, and untrusted-content rules when they connect.
 
-This guide describes the published `0.2.1` package, including custom-database,
+This guide describes the published `0.3.0` package, including custom-database,
 template, Obsidian, and initialization-instruction support.
 
 ## Start every session safely

package/docs/obsidian-import.md

@@ -1,7 +1,7 @@
 # Obsidian import
 
-> **Available in 0.2.1:** these tools require the published 0.2.1 package or
-> newer.
+> **Available since 0.2.1:** these tools require the published `0.3.0` package
+> or newer.
 
 The importer converts one explicitly authorized local Obsidian vault into an
 AuroraCloud-backed AuroraDocs workspace. It is analyze-first, consent-gated,
@@ -35,8 +35,10 @@ Configure the local MCP child process with:
 `AURORA_OBSIDIAN_VAULT_ROOT` is required and must be an absolute real
 directory. `AURORA_MCP_STATE_DIR` is optional and must remain outside the
 vault; by default the server uses a private `.auroradocs-mcp` directory for the
-current user. Removing the root variable disables all Obsidian tools while
-ordinary AuroraCloud tools keep working.
+current user. That directory also stores reviewable custom-database plans.
+Removing the root variable disables all Obsidian tools while ordinary
+AuroraCloud tools keep working. Import batches report progress on the
+originating tool call when the client sends a progress token.
 
 This environment setting authorizes read-only analysis only. The reader never
 scans parents or siblings, follows symlinks, runs plugins, reads `.git`, trash,

package/docs/security.md

@@ -30,8 +30,9 @@ reuse one token across unrelated clients.
 
 The package runs locally over stdio. It does not listen on a network port and
 AuroraDocs does not currently offer a hosted HTTP, SSE, WebSocket, or OAuth MCP
-endpoint. `https://api.auroradocs.eu` is the AuroraCloud REST API used by the
-local process, not an MCP endpoint.
+endpoint. The local process speaks MCP 2026-07-28 and still serves 2025-era
+stdio clients. `https://api.auroradocs.eu` is the AuroraCloud REST API used by
+the local process, not an MCP endpoint.
 
 Do not expose the stdio process through a network proxy or paste its credential
 into an arbitrary hosted agent service.
@@ -79,7 +80,8 @@ not scanned and cannot be read as attachments. No parser fetches remote URLs and
 modified.
 
 Import requires a separate, exact plan ID/hash acceptance. Form-capable MCP
-clients receive an elicitation request; only protocol `accept` with
+clients receive a form elicitation (a 2026 multi-round-trip `input_required`
+result, or a 2025 `elicitation/create` request). Only protocol `accept` with
 `confirmed: true` and unchanged policy choices proceeds. Decline, cancel,
 malformed content, changed choices, or an unavailable elicitation client without
 a later exact confirmation performs zero writes. Plans are workspace-bound,
@@ -92,7 +94,8 @@ uploads use one parent-bound MCP route and stable idempotency keys; the MCP
 cannot list, replace, or delete arbitrary files through that boundary.
 
 The private state lives outside the vault in a 0700 directory with 0600 files
-and atomic replacement. The persisted approved plan stores bounded policies,
+and atomic replacement. Custom-database plans use that same directory so apply
+survives an MCP restart. The persisted approved plan stores bounded policies,
 inferred schemas, planned IDs, warnings, and relative source paths needed for
 restart revalidation, but no note bodies, frontmatter values, attachment bytes,
 tokens, credentials, or absolute paths. The separate resume journal stores

package/docs/setup.md

@@ -1,7 +1,7 @@
 # Setup
 
 This guide connects a local MCP client to owner-approved AuroraCloud workspace
-grants with `@henrikogard/auroradocs-mcp@0.2.1`. The server runs locally over
+grants with `@henrikogard/auroradocs-mcp@0.3.0`. The server runs locally over
 stdio; it is not a hosted MCP endpoint.
 
 ## Requirements
@@ -9,7 +9,8 @@ stdio; it is not a hosted MCP endpoint.
 - Node.js 20 or newer, with `npx` available to the MCP client
 - an AuroraDocs account and an AuroraCloud-backed workspace
 - workspace owner or admin permission to create an MCP key
-- Claude Desktop, Claude Code, Codex, or another stdio-capable MCP client
+- Claude Desktop, Claude Code, Codex, or another stdio-capable MCP client.
+  Claude Desktop can install the `.mcpb` bundle instead of a JSON server entry.
 
 Browser-only and Local folders workspaces are not supported.
 
@@ -62,7 +63,7 @@ Every new client entry provides these values:
 | `AURORA_API_URL` | `https://api.auroradocs.eu` |
 | `AURORA_API_TOKEN` | the one-time `aur_mcp_client_` credential |
 
-For the `0.2.1` Obsidian importer, add these only after backing up the source
+For the `0.3.0` Obsidian importer, add these only after backing up the source
 vault and choosing a test destination:
 
 | Variable | Value |
@@ -80,7 +81,7 @@ Generic stdio configuration:
 ```json
 {
   "command": "npx",
-  "args": ["-y", "@henrikogard/auroradocs-mcp@0.2.1"],
+  "args": ["-y", "@henrikogard/auroradocs-mcp@0.3.0"],
   "env": {
     "AURORA_API_URL": "https://api.auroradocs.eu",
     "AURORA_API_TOKEN": "REDACTED"
@@ -88,6 +89,13 @@ Generic stdio configuration:
 }
 ```
 
+Claude Desktop can install a local `.mcpb` bundle instead of that JSON. From a
+checkout run `pnpm pack:mcpb`, then in Claude Desktop open **Settings →
+Extensions → Advanced settings → Install Extension…** and choose
+`auroradocs.mcpb`. Enter the API URL and MCP token there. The token is stored
+in the OS keychain. Optional fields authorize one Obsidian vault and a private
+state directory.
+
 For Hermes and OpenClaw, restrict exposed tools to the read-only profile in
 [Agent profiles](agent-profiles.md). Never expose the credential to an agent
 prompt, logs, or committed configuration.
@@ -156,7 +164,7 @@ servers, then restart Claude Desktop:
   "mcpServers": {
     "auroradocs": {
       "command": "npx",
-      "args": ["-y", "@henrikogard/auroradocs-mcp@0.2.1"],
+      "args": ["-y", "@henrikogard/auroradocs-mcp@0.3.0"],
       "env": {
         "AURORA_API_URL": "https://api.auroradocs.eu",
         "AURORA_WORKSPACE_ID": "WORKSPACE_ID",
@@ -174,7 +182,7 @@ claude mcp add --transport stdio --scope user \
   --env AURORA_API_URL=https://api.auroradocs.eu \
   --env AURORA_WORKSPACE_ID=WORKSPACE_ID \
   --env AURORA_API_TOKEN=REDACTED \
-  auroradocs -- npx -y @henrikogard/auroradocs-mcp@0.2.1
+  auroradocs -- npx -y @henrikogard/auroradocs-mcp@0.3.0
 ```
 
 Run `claude mcp get auroradocs` to inspect the saved entry.
@@ -186,7 +194,7 @@ codex mcp add \
   --env AURORA_API_URL=https://api.auroradocs.eu \
   --env AURORA_WORKSPACE_ID=WORKSPACE_ID \
   --env AURORA_API_TOKEN=REDACTED \
-  auroradocs -- npx -y @henrikogard/auroradocs-mcp@0.2.1
+  auroradocs -- npx -y @henrikogard/auroradocs-mcp@0.3.0
 ```
 
 Run `codex mcp get auroradocs` to inspect the saved entry.

package/docs/tools.md

@@ -1,6 +1,6 @@
 # Tools and scopes
 
-AuroraDocs MCP `0.2.1` exposes the tools below to a connected client. An
+AuroraDocs MCP `0.3.0` exposes the tools below to a connected client. An
 `aur_mcp_client_` credential can discover its independently granted workspaces
 with `list_workspaces`; every workspace data call then selects one grant with
 `workspace_id` or an unambiguous `workspace_alias`. A legacy `aur_mcp_` token
@@ -59,7 +59,7 @@ including object lookup and startup membership verification.
 
 | Tool | What it does | Scopes |
 | --- | --- | --- |
-| `list_workspaces` | List only the workspaces independently granted to a client credential. | Client credential; no workspace selector |
+| `list_workspaces` | List only the workspaces independently granted to a client credential. Re-reads the live grant set from AuroraCloud. | Client credential; no workspace selector |
 | `search_objects` | Search object titles, optionally by type. | `read:objects` |
 | `search` | Alias for `search_objects`. | `read:objects` |
 | `list_objects` | List object metadata, optionally by type. | `read:objects` |

package/docs/troubleshooting.md

@@ -12,10 +12,10 @@ logs, screenshots, issues, or support messages. Use the token fingerprint from
 | Server exits with `AURORA_WORKSPACE_ID environment variable is required` | A legacy `aur_mcp_` token is missing its pinned workspace ID. | Copy it again from MCP Access. Client credentials must use `aur_mcp_client_` and omit this variable. |
 | Server exits with `AURORA_API_URL environment variable is required` | The API URL is missing. | Set it to `https://api.auroradocs.eu`. Do not add `/mcp`. |
 | Authentication is missing | `AURORA_API_TOKEN` was not passed to the child process. | Add the MCP token environment variable to the server entry. Do not use email/password authentication. |
-| Client shows no tools | The stdio process failed, is still connecting, or the client has stale configuration. | Inspect the client's MCP status, confirm the command is `npx -y @henrikogard/auroradocs-mcp@0.2.1`, then restart the client. |
+| Client shows no tools | The stdio process failed, is still connecting, or the client has stale configuration. | Inspect the client's MCP status, confirm the command is `npx -y @henrikogard/auroradocs-mcp@0.3.0`, then restart the client. |
 | JSON configuration will not load | Invalid JSON, usually a missing comma or an overwritten outer `mcpServers` object. | Validate the file as JSON and merge the server entry with existing entries. JSON cannot contain comments. |
 | Works in a terminal but not the desktop client | Desktop apps often use a different PATH and environment. | For client mode, pass the API URL and token; for legacy mode, also pass `AURORA_WORKSPACE_ID`. Restart the desktop app. |
-| Client credential reports an ambiguous workspace | The data call omitted a selector or an alias matches more than one grant. | Call `list_workspaces`, then pass one exact `workspace_id` or unambiguous `workspace_alias`. |
+| Client credential reports an ambiguous workspace | The data call omitted a selector or an alias matches more than one grant. | Call `list_workspaces`, then pass one exact `workspace_id` or unambiguous `workspace_alias`. `list_workspaces` re-reads grants from AuroraCloud; a new grant does not require restarting the MCP process. |
 | Obsidian tools say `AURORA_OBSIDIAN_VAULT_ROOT` is required | Local vault access is intentionally disabled. | Add one absolute vault path to the local MCP process only after backing it up, then restart the client. Normal AuroraCloud tools do not need this variable. |
 | Vault or state path is rejected | The root is relative/symlinked, changed identity, or the plan/journal directory is inside the vault. | Use a real absolute vault directory and a separate private `AURORA_MCP_STATE_DIR`; never weaken the path checks. |
 | Vault analysis exceeds its source limit | Eligible Markdown, Canvas, and Templates configuration files total more than 256 MiB. | Split or archive the vault before analysis; ignored plugin/cache/Git data does not count and cannot be imported as attachments. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henrikogard/auroradocs-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "description": "AuroraCloud-first MCP server that exposes AuroraDocs workspace data to Claude Desktop and other AI agents",
@@ -34,7 +34,8 @@
     "test": "NODE_ENV=test tsx --test src/*.test.ts src/obsidian/*.test.ts",
     "test:live-smoke-contract": "NODE_ENV=test node --import tsx --test scripts/auroracloudLiveSmoke.test.mjs",
     "test:docs": "node --test scripts/docsContract.test.mjs",
-    "test:contracts": "node --test scripts/checkWiring.test.mjs scripts/packageContentsCore.test.mjs",
+    "test:contracts": "node --test scripts/checkWiring.test.mjs scripts/packageContentsCore.test.mjs scripts/mcpbManifest.test.mjs",
+    "pack:mcpb": "node scripts/packMcpb.mjs",
     "test:stdio": "pnpm build && tsx --test test/stdio.integration.test.ts",
     "typecheck": "tsc --noEmit",
     "build": "tsc -p tsconfig.build.json",
@@ -45,10 +46,11 @@
     "auroracloud-live-smoke": "tsx scripts/auroracloudLiveSmoke.ts"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/server": "^2.0.0",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0",
     "@types/node": "^26.1.1",
     "tsx": "^4.19.0",
     "typescript": "~7.0.2"