@coffer-org/server 3.4.0 → 5.0.0

package/dist/file-fields.js

@@ -87,38 +87,65 @@ export function dropUnchangedFileFields(m, input, stored) {
     }
     return out ?? input;
 }
+function normalizeFileValue(raw, field, path, issues) {
+    const parsed = jsonValue(raw);
+    const isArray = Array.isArray(parsed);
+    const items = (isArray ? parsed : [parsed]);
+    const out = [];
+    let failed = false;
+    for (const it of items) {
+        if (typeof it !== 'object' || it === null || typeof it.name !== 'string') {
+            issues.push({ field, code: 'file_not_uploaded', path });
+            failed = true;
+            continue;
+        }
+        const resolved = resolveEntry(it);
+        if (!resolved) {
+            issues.push({ field, code: 'file_not_uploaded', params: { name: it.name }, path });
+            failed = true;
+            continue;
+        }
+        out.push(resolved);
+    }
+    if (failed)
+        return null;
+    return { value: isArray ? out : out[0] };
+}
 function normalizeLevel(fields, data, path) {
     const issues = [];
     for (const [key, f] of fieldEntries(fields)) {
-        if (f.prim !== 'file')
-            continue;
         if (!(key in data))
             continue;
-        const raw = data[key];
-        if (raw == null || raw === '')
+        if (f.prim === 'file') {
+            const raw = data[key];
+            if (raw == null || raw === '')
+                continue;
+            const r = normalizeFileValue(raw, key, [...path, key], issues);
+            if (r)
+                data[key] = r.value;
+            continue;
+        }
+        if (!f.parts?.some((p) => p.meta.prim === 'file'))
             continue;
-        const parsed = jsonValue(raw);
-        const isArray = Array.isArray(parsed);
-        const items = (isArray ? parsed : [parsed]);
-        const out = [];
-        let failed = false;
-        for (const it of items) {
-            if (typeof it !== 'object' || it === null || typeof it.name !== 'string') {
-                issues.push({ field: key, code: 'file_not_uploaded', path: [...path, key] });
-                failed = true;
+        const obj = jsonValue(data[key]);
+        if (obj == null || typeof obj !== 'object' || Array.isArray(obj))
+            continue;
+        const row = obj;
+        let touched = false;
+        for (const p of f.parts) {
+            if (p.meta.prim !== 'file')
+                continue;
+            const raw = row[p.role];
+            if (raw == null || raw === '')
                 continue;
-            }
-            const resolved = resolveEntry(it);
-            if (!resolved) {
-                issues.push({ field: key, code: 'file_not_uploaded', params: { name: it.name }, path: [...path, key] });
-                failed = true;
+            const r = normalizeFileValue(raw, key, [...path, key, p.role], issues);
+            if (!r)
                 continue;
-            }
-            out.push(resolved);
+            row[p.role] = r.value;
+            touched = true;
         }
-        if (failed)
-            continue;
-        data[key] = isArray ? out : out[0];
+        if (touched)
+            data[key] = row;
     }
     for (const c of collectionGroups(fields)) {
         const rows = data[c.key];

package/dist/frontend-agent.d.ts

@@ -1 +1 @@
-export declare function frontendInstructions(): Promise<string | null>;
+export declare function frontendInstructions(siteUrl: string): Promise<string | null>;

package/dist/frontend-agent.js

@@ -10,9 +10,8 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { getLogger } from '@coffer-org/sdk/logger';
-import { configuredPublicUrl } from "./public-url.js";
 const log = getLogger('frontend-agent');
-export async function frontendInstructions() {
+export async function frontendInstructions(siteUrl) {
     const dist = process.env['WEB_DIST'];
     if (!dist)
         return null;
@@ -27,7 +26,7 @@ export async function frontendInstructions() {
             log.warn(`frontend ${rel} exports no agent() — no site-link instructions`);
             return null;
         }
-        const text = await mod.agent({ siteUrl: await configuredPublicUrl() });
+        const text = await mod.agent({ siteUrl });
         return typeof text === 'string' && text.trim() ? text : null;
     }
     catch (e) {

package/dist/global-search.js

@@ -1,5 +1,5 @@
 import { textSearchKeys, titleKey, recordTitle, storageColumnsFor } from '@coffer-org/sdk/shelf';
-import { tokenize } from '@coffer-org/core/search';
+import { tokenize } from '@coffer-org/sdk/search';
 import { getLogger } from '@coffer-org/sdk/logger';
 import { getEm } from "./db.js";
 import { rowMatch } from "./records-api.js";

package/dist/index.js

@@ -17,6 +17,7 @@ import { resolveEmbed } from "./embed.js";
 import { resolveWithinHome, filterSort, listDir } from "./fs-list.js";
 import { initPlugins, teardownPlugins, readDisabled, purgePluginData, getPluginSettings, getPlugins, } from "./plugin-runtime.js";
 import { registerPluginsApi } from "./plugins-api.js";
+import { orchestratorDiagnostics } from "./orchestrator/index.js";
 import { registerPluginUserApi, registerPluginAdminApi } from "./plugin-user-api.js";
 import { registerAuthApi, resolveRequestUser, requireAdmin, PUBLIC_API_PATHS } from "./auth-api.js";
 import { registerMcpHttp } from "./mcp-http.js";
@@ -30,12 +31,13 @@ import { showcaseList, showcaseListAll, showcaseCount, UnknownShowcaseError } fr
 import { getActiveRegistry } from "./registry-context.js";
 import { maskTree, preserveTree } from "./field-masking.js";
 import { writePluginSettings } from "./settings-write.js";
+import { findSettingsGroup, settingsGroups } from "./settings-groups.js";
 import { rootLogger, getLogger } from "./log.js";
 import { uploadsDir } from "./uploads.js";
 import { mimeForName } from "./file-fields.js";
 import { verifyUploadTicket } from "./upload-ticket.js";
 import { setPluginState } from "./plugin-state.js";
-import { SEARCH_STATE_PLUGIN, SEARCH_CURSOR_KEY } from "./search-indexer.js";
+import { SEARCH_STATE_NAMESPACE, SEARCH_CURSOR_KEY } from "./search-indexer.js";
 import { globalSearch } from "./global-search.js";
 import { applySmartRanking, getRecordActivity, markRecordViewed, setRecordFavorite } from "./record-activity.js";
 import { tracksRecordActivity } from "./record-activity-policy.js";
@@ -191,8 +193,6 @@ app.patch('/api/plugins/:id', async (req, reply) => {
     const p = plugins.find((x) => x.id === id);
     if (!p)
         return reply.code(404).send({ error: 'unknown_plugin' });
-    if (id === 'core')
-        return reply.code(400).send({ error: 'core_required' });
     const disabled = await readDisabled();
     if (!enabled) {
         const dependents = plugins.filter((x) => !disabled.has(x.id) && x.id !== id && x.dependsOn.includes(id));
@@ -215,7 +215,7 @@ app.patch('/api/plugins/:id', async (req, reply) => {
     }
     await fork.flush();
     if (enabled) {
-        await setPluginState(SEARCH_STATE_PLUGIN, SEARCH_CURSOR_KEY, '0');
+        await setPluginState(SEARCH_STATE_NAMESPACE, SEARCH_CURSOR_KEY, '0');
     }
     return { ok: true, restartRequired: true };
 });
@@ -227,8 +227,6 @@ app.delete('/api/plugins/:id/data', async (req, reply) => {
     const p = plugins.find((x) => x.id === id);
     if (!p)
         return reply.code(404).send({ error: 'unknown_plugin' });
-    if (id === 'core')
-        return reply.code(400).send({ error: 'core_required' });
     const disabled = await readDisabled();
     const dependents = plugins.filter((x) => !disabled.has(x.id) && x.id !== id && x.dependsOn.includes(id));
     if (dependents.length) {
@@ -286,14 +284,9 @@ app.post('/api/plugins/update-all', async (req, reply) => {
 app.post('/api/system/update', async (req, reply) => {
     if (!requireAdmin(req, reply))
         return;
-    const assets = await discoverPluginAssets();
     const runtime = await discoverRuntime();
-    const core = assets.find((a) => a.id === 'core');
-    const [coreLatest, runtimeLatest] = await Promise.all([
-        core && !core.local ? checkLatestVersion(core.packageName) : Promise.resolve(null),
-        runtime && !runtime.local ? checkLatestVersion(runtime.packageName) : Promise.resolve(null),
-    ]);
-    const targets = resolveBaseTargets(assets, runtime, coreLatest, runtimeLatest);
+    const runtimeLatest = runtime && !runtime.local ? await checkLatestVersion(runtime.packageName) : null;
+    const targets = resolveBaseTargets(runtime, runtimeLatest);
     if (targets.length === 0)
         return reply.code(400).send({ error: 'no_update_available' });
     const result = await runNpmInstall(targets.map((t) => `${t.packageName}@${t.to}`), process.cwd());
@@ -303,29 +296,30 @@ app.post('/api/system/update', async (req, reply) => {
     reply.send({ ok: true, updated: targets.map(({ id, from, to }) => ({ id, from, to })) });
     setTimeout(() => process.exit(0), 500);
 });
-app.get('/api/plugins/:id/settings', async (req, reply) => {
+app.post('/api/system/orchestrator-diagnostics', async (req, reply) => {
+    if (!requireAdmin(req, reply))
+        return;
+    reply.send(await orchestratorDiagnostics());
+});
+app.get('/api/settings', async () => (await settingsGroups()).map((g) => ({ id: g.id, label: g.label, fields: g.fields })));
+app.get('/api/settings/:id', async (req, reply) => {
     if (!requireAdmin(req, reply))
         return;
     const { id } = req.params;
-    const plugins = await getPlugins();
-    const p = plugins.find((x) => x.id === id);
-    if (!p || !p.settings || p.settings.fields.length === 0) {
+    const group = await findSettingsGroup(id);
+    if (!group)
         return reply.code(404).send({ error: 'no_settings' });
-    }
-    const row = await getPluginSettings(id);
-    return maskTree(p.settings.fields, row);
+    return maskTree(group.fields, await getPluginSettings(id));
 });
-app.put('/api/plugins/:id/settings', (req, reply) => {
+app.put('/api/settings/:id', (req, reply) => {
     if (!requireAdmin(req, reply))
         return;
     return guard(reply, async () => {
         const { id } = req.params;
-        const plugins = await getPlugins();
-        const p = plugins.find((x) => x.id === id);
-        if (!p || !p.settings || p.settings.fields.length === 0) {
+        const group = await findSettingsGroup(id);
+        if (!group)
             return reply.code(404).send({ error: 'no_settings' });
-        }
-        const row = await writePluginSettings(getEm().fork(), id, (req.body ?? {}), req.user.login, plugins);
+        const row = await writePluginSettings(getEm().fork(), id, (req.body ?? {}), req.user.login);
         return { ok: true, row };
     });
 });

package/dist/mcp-contract/client.d.ts

@@ -0,0 +1,24 @@
+export declare class ConnectionError extends Error {
+}
+export declare class NotFoundError extends Error {
+}
+export declare class ValidationError extends Error {
+    issues: unknown[];
+    constructor(issues: unknown[]);
+}
+export interface ListQuery {
+    folderId?: string;
+    limit?: number;
+    [field: string]: string | number | undefined;
+}
+export interface CofferClientApi {
+    getSchema(): Promise<unknown>;
+    listRecords(library: string, shelf: string, query?: ListQuery): Promise<unknown>;
+    getRecord(library: string, shelf: string, id: number): Promise<unknown>;
+    createRecord(library: string, shelf: string, fields: Record<string, unknown>): Promise<unknown>;
+    updateRecord(library: string, shelf: string, id: number, fields: Record<string, unknown>): Promise<unknown>;
+    deleteRecord(library: string, shelf: string, id: number): Promise<unknown>;
+    listTrash(): Promise<unknown>;
+    restoreRecord(library: string, shelf: string, id: number): Promise<unknown>;
+    purgeRecord(library: string, shelf: string, id: number): Promise<unknown>;
+}

package/dist/mcp-contract/client.js

@@ -0,0 +1,12 @@
+export class ConnectionError extends Error {
+}
+export class NotFoundError extends Error {
+}
+export class ValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super('validation');
+        this.issues = issues;
+        this.name = 'ValidationError';
+    }
+}

package/dist/mcp-contract/schema.d.ts

@@ -0,0 +1,46 @@
+export interface ShelfIndexEntry {
+    library: string;
+    libraryLabel: string;
+    shelf: string;
+    label: string;
+}
+export interface FieldInfo {
+    key: string;
+    kind: string;
+    prim: string;
+    required: boolean;
+    relation?: {
+        library: string;
+        shelf: string;
+    };
+    options?: unknown[];
+    fields?: FieldInfo[];
+    multiple?: true;
+    derived?: true;
+    write?: string;
+}
+export declare const FILE_WRITE_HINT: string;
+export declare const SOURCE_WRITE_HINT: string;
+export declare const DERIVED_WRITE_HINT: string;
+export declare const serverOwnedPartsHint: (roles: string[]) => string;
+export interface ShelfDescription {
+    library: string;
+    shelf: string;
+    label: string;
+    fields: FieldInfo[];
+}
+interface SchemaClient {
+    getSchema(): Promise<unknown>;
+}
+export declare function flattenFields(items: unknown[]): FieldInfo[];
+export declare class SchemaCache {
+    private client;
+    private cached?;
+    constructor(client: SchemaClient);
+    refresh(): void;
+    private load;
+    index(): Promise<ShelfIndexEntry[]>;
+    describeShelf(library: string, shelf: string): Promise<ShelfDescription>;
+    private find;
+}
+export {};

package/dist/mcp-contract/schema.js

@@ -0,0 +1,90 @@
+export const FILE_WRITE_HINT = 'Uploaded file only: {"name":"<filename returned by POST /api/upload>"} ' +
+    '(or an array of those when the field is multiple). ' +
+    'A remote URL is rejected — the server stores files, not links. ' +
+    'To add one: call create_upload_ticket, POST the bytes to the absolute upload_url it returns with that ' +
+    'Bearer token, then write the returned name. mime and size are set by the server; ' +
+    'sending them changes nothing. To remove a file, drop its entry from the array ' +
+    '(or clear the field) — an existing entry cannot be edited in place.';
+export const SOURCE_WRITE_HINT = 'plain text — write the full content as a string. Content must be valid UTF-8 text; binary content is rejected. ' +
+    'Capped per field (default 256 KB) — content over the cap fails with source_too_large. ' +
+    'Read-only in the web UI (people can only replace it by uploading a file).';
+export const DERIVED_WRITE_HINT = 'Read-only — the server recomputes this field from other fields of the record on every write ' +
+    'and rejects any value sent for it. To change it, change what it is computed from.';
+export const serverOwnedPartsHint = (roles) => `Partly read-only — the server owns ${roles.map((r) => `\`${r}\``).join(', ')} in this value and ` +
+    `computes ${roles.length > 1 ? 'them' : 'it'} on every write. Send the other roles only; anything ` +
+    `sent for these is discarded, and a read returns the server's value.`;
+function serverOwnedRoles(t) {
+    const parts = t.parts ?? [];
+    return parts.filter((p) => p.mode === 'computedStored').map((p) => p.role);
+}
+function hasValue(el) {
+    const type = el?.type;
+    return type !== undefined && typeof type === 'object';
+}
+function hasChildren(el) {
+    return typeof el === 'object' && el !== null && Array.isArray(el.fields);
+}
+function isStorageGroup(el) {
+    return el.scope === 'nest';
+}
+export function flattenFields(items) {
+    const out = [];
+    const push = (key, t) => out.push({
+        key,
+        kind: t.kind,
+        prim: t.prim,
+        required: t.required,
+        ...(t.relation ? { relation: t.relation } : {}),
+        ...(t.options ? { options: t.options } : {}),
+        ...(t.prim === 'file' ? { write: FILE_WRITE_HINT } : {}),
+        ...(serverOwnedRoles(t).length ? { write: serverOwnedPartsHint(serverOwnedRoles(t)) } : {}),
+        ...(t.kind === 'source' ? { write: SOURCE_WRITE_HINT } : {}),
+        ...(t.derived ? { derived: true, write: DERIVED_WRITE_HINT } : {}),
+    });
+    for (const it of items) {
+        if (hasValue(it) && 'key' in it)
+            push(it.key, it.type);
+        else if (hasChildren(it) && isStorageGroup(it))
+            out.push({
+                key: it.key,
+                kind: 'group',
+                prim: 'group',
+                required: it.required === true,
+                ...(it.multiple ? { multiple: true } : {}),
+                fields: flattenFields(it.fields),
+            });
+        else if (hasChildren(it))
+            out.push(...flattenFields(it.fields));
+    }
+    return out;
+}
+export class SchemaCache {
+    client;
+    cached;
+    constructor(client) {
+        this.client = client;
+    }
+    refresh() {
+        this.cached = undefined;
+    }
+    async load(force = false) {
+        if (force || !this.cached)
+            this.cached = (await this.client.getSchema());
+        return this.cached;
+    }
+    async index() {
+        const libraries = await this.load();
+        return libraries.flatMap((v) => v.shelves.map((m) => ({ library: v.id, libraryLabel: v.label, shelf: m.shelf, label: m.label })));
+    }
+    async describeShelf(library, shelf) {
+        let m = this.find(await this.load(), library, shelf);
+        if (!m)
+            m = this.find(await this.load(true), library, shelf);
+        if (!m)
+            throw new Error(`unknown_shelf ${library}/${shelf}`);
+        return { library, shelf, label: m.label, fields: flattenFields(m.fields) };
+    }
+    find(libraries, library, shelf) {
+        return libraries.find((v) => v.id === library)?.shelves.find((m) => m.shelf === shelf);
+    }
+}

package/dist/mcp-contract/tools.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import { type CofferClientApi } from './client.ts';
+import { SchemaCache } from './schema.ts';
+export interface ToolResult {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    isError?: boolean;
+}
+export interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: z.ZodRawShape;
+    handler: (args: Record<string, unknown>) => Promise<ToolResult>;
+}
+export declare const LIST_DEFAULT_LIMIT = 25;
+export declare const LIST_MAX_LIMIT = 200;
+export declare function buildTools(client: CofferClientApi, cache: SchemaCache): ToolDef[];

package/dist/mcp-contract/tools.js

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+import { ValidationError, NotFoundError, ConnectionError } from "./client.js";
+const ok = (data) => ({
+    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+});
+const fail = (text) => ({ content: [{ type: 'text', text }], isError: true });
+const ISSUE_HINTS = {
+    file_remote_url: 'a file field stores an uploaded file, not a remote URL',
+    file_unknown_key: 'a file entry may only carry name, mime and size',
+    file_name: 'name must be a bare filename, without a path',
+    file_not_uploaded: 'no file by that name has been uploaded',
+};
+const FILE_RECIPE = '\n\nTo put a file in a file/image/media field:\n' +
+    '1. create_upload_ticket → {token, upload_url} — upload_url is the absolute address to post to\n' +
+    '2. curl -H "Authorization: Bearer <token>" -F "file=@<local path>" <upload_url> → {"name":"<filename>"}\n' +
+    '3. write the field as {"name":"<filename>"} (or an array of those).\n' +
+    'Downloading a remote image is your side of the job: fetch it to a local file first, then upload that file. ' +
+    'mime and size are set by the server. To remove a file, drop its entry — entries cannot be edited in place.';
+async function guard(fn) {
+    try {
+        return ok(await fn());
+    }
+    catch (e) {
+        if (e instanceof ValidationError) {
+            const lines = e.issues.map((i) => {
+                const o = i;
+                const code = o.code ?? 'invalid';
+                const hint = ISSUE_HINTS[code];
+                return `- ${o.field ?? '?'}: ${code}${hint ? ` — ${hint}` : ''}`;
+            });
+            const fileIssue = e.issues.some((i) => (i.code ?? '').startsWith('file_'));
+            return fail(`Validation error:\n${lines.join('\n')}${fileIssue ? FILE_RECIPE : ''}`);
+        }
+        if (e instanceof NotFoundError)
+            return fail('Record or shelf not found.');
+        if (e instanceof ConnectionError)
+            return fail(e.message);
+        return fail(`Unexpected error: ${e.message}`);
+    }
+}
+export const LIST_DEFAULT_LIMIT = 25;
+export const LIST_MAX_LIMIT = 200;
+export function buildTools(client, cache) {
+    const library = z.string().describe('Library identifier, e.g. "things"');
+    const shelf = z.string().describe('Shelf identifier, e.g. "item"');
+    const id = z.coerce.number().int().describe('record id');
+    return [
+        {
+            name: 'list_libraries',
+            description: 'Lightweight index of all libraries and shelves (library, shelf, label). Starting point for exploring content.',
+            inputSchema: {},
+            handler: () => guard(() => cache.index()),
+        },
+        {
+            name: 'describe_shelf',
+            description: 'Detailed shelf schema: fields with kind/prim/required and relation/options. A collection is one entry with ' +
+                'multiple:true and its row shape in fields[]. A field with derived:true is computed by the server and rejects ' +
+                'writes — omit it when writing. Call BEFORE create_record/update_record.',
+            inputSchema: { library, shelf },
+            handler: (a) => guard(() => cache.describeShelf(a.library, a.shelf)),
+        },
+        {
+            name: 'refresh_schema',
+            description: 'Re-read the schema from the server. Call after enabling/installing a plugin (server restart required).',
+            inputSchema: {},
+            handler: async () => {
+                cache.refresh();
+                return ok({ refreshed: true });
+            },
+        },
+        {
+            name: 'list_records',
+            description: `List records of a shelf, one page at a time. q — free-text search over the shelf's text fields ` +
+                `(this is how you FIND a record by part of its name: q "minisforum" matches "Minisforum UM790"); ` +
+                `filters — exact field match; folderId — folder filter; ` +
+                `limit — page size (default ${LIST_DEFAULT_LIMIT}, max ${LIST_MAX_LIMIT}); offset — rows to skip. ` +
+                `Returns {rows, total, limit, offset}: "total" is how many records match IN FULL, so answer "how many do I have" ` +
+                `from it instead of listing everything, and never conclude a record is missing from one unfiltered page — ` +
+                `search with q first.`,
+            inputSchema: {
+                library,
+                shelf,
+                q: z.string().optional().describe('Free-text search over text fields; matches partial words'),
+                filters: z
+                    .record(z.string(), z.union([z.string(), z.number()]))
+                    .optional()
+                    .describe('Exact field=value match'),
+                folderId: z.string().optional(),
+                limit: z.number().int().positive().optional(),
+                offset: z.number().int().nonnegative().optional(),
+            },
+            handler: async (a) => guard(async () => {
+                const q = { ...a.filters };
+                if (a.folderId !== undefined)
+                    q.folderId = a.folderId;
+                if (typeof a.q === 'string' && a.q.trim())
+                    q.q = a.q.trim();
+                const limit = Math.min(typeof a.limit === 'number' ? a.limit : LIST_DEFAULT_LIMIT, LIST_MAX_LIMIT);
+                q.limit = limit;
+                const offset = typeof a.offset === 'number' ? a.offset : 0;
+                if (offset > 0)
+                    q.offset = offset;
+                const res = await client.listRecords(a.library, a.shelf, q);
+                const paged = res;
+                const rows = Array.isArray(res) ? res : Array.isArray(paged.rows) ? paged.rows : [];
+                const total = typeof paged.total === 'number' ? paged.total : rows.length;
+                return { rows, total, limit, offset };
+            }),
+        },
+        {
+            name: 'get_record',
+            description: 'A single record by id (with _extends, if any).',
+            inputSchema: { library, shelf, id },
+            handler: (a) => guard(() => client.getRecord(a.library, a.shelf, a.id)),
+        },
+        {
+            name: 'create_record',
+            description: 'Create a record. fields — an object of field values (see describe_shelf). name is required.',
+            inputSchema: { library, shelf, fields: z.record(z.string(), z.unknown()).describe('Record field values') },
+            handler: (a) => guard(() => client.createRecord(a.library, a.shelf, a.fields)),
+        },
+        {
+            name: 'update_record',
+            description: 'Partial record update. fields — only the fields to change. Read the record first, call describe_shelf first, and preserve every unmentioned field; never overwrite conflicts silently.',
+            inputSchema: { library, shelf, id, fields: z.record(z.string(), z.unknown()) },
+            handler: (a) => guard(() => client.updateRecord(a.library, a.shelf, a.id, a.fields)),
+        },
+        {
+            name: 'delete_record',
+            description: 'Move a record to the trash by id (reversible soft-delete; data remains in the database). Read the complete record first and get explicit user confirmation for a non-obvious deletion. Never blank fields to simulate deletion.',
+            inputSchema: { library, shelf, id },
+            handler: (a) => guard(() => client.deleteRecord(a.library, a.shelf, a.id)),
+        },
+        {
+            name: 'list_trash',
+            description: 'List every record currently in the trash, including its full data. Use this before restoring or permanently purging a record; normal list_records/get_record calls hide trashed records.',
+            inputSchema: {},
+            handler: () => guard(() => client.listTrash()),
+        },
+        {
+            name: 'restore_record',
+            description: 'Restore a record from the trash. Inspect it with list_trash first and confirm the target if the user did not name the exact record.',
+            inputSchema: { library, shelf, id },
+            handler: (a) => guard(() => client.restoreRecord(a.library, a.shelf, a.id)),
+        },
+        {
+            name: 'purge_record',
+            description: 'Permanently delete a record that is already in the trash. This is irreversible: inspect list_trash and require explicit user confirmation immediately before calling it.',
+            inputSchema: {
+                library,
+                shelf,
+                id,
+                confirmed: z.literal(true).describe('Must be true only after the user explicitly confirmed permanent deletion'),
+            },
+            handler: async (a) => a.confirmed === true
+                ? guard(() => client.purgeRecord(a.library, a.shelf, a.id))
+                : fail('Permanent deletion requires explicit user confirmation.'),
+        },
+    ];
+}

package/dist/mcp-http.js

@@ -1,12 +1,14 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { collectMcpTools, resolveRagDeps, buildDomainSections, buildMcpInstructions } from "./mcp-tools.js";
+import { collectMcpTools, resolveRagDeps, buildDomainSections, buildMcpInstructions, siteSection, } from "./mcp-tools.js";
+import { configuredPublicUrl } from "./public-url.js";
 import { getLogger } from "./log.js";
 const log = getLogger('mcp-http');
 export async function buildMcpServer(role, actor) {
     const rag = await resolveRagDeps();
     const tools = (await collectMcpTools({ rag, includeAdmin: role === 'admin', actor })).filter((t) => role === 'admin' || t.role === 'member');
-    const sections = await buildDomainSections();
+    const site = await siteSection(await configuredPublicUrl());
+    const sections = [...(await buildDomainSections()), ...(site ? [site] : [])];
     const server = new McpServer({ name: 'coffer', version: '1.0.0' }, { instructions: buildMcpInstructions(sections) });
     const registerTool = server.registerTool.bind(server);
     for (const t of tools) {

package/dist/mcp-local.d.ts

@@ -1,4 +1,4 @@
-import type { CofferClientApi } from '@coffer-org/mcp/client';
+import type { CofferClientApi } from './mcp-contract/client.ts';
 export declare function mapError(e: unknown): never;
 export declare function splitListQuery(raw: Record<string, unknown>): {
     query: Record<string, unknown>;

package/dist/mcp-local.js

@@ -1,4 +1,4 @@
-import { ValidationError, NotFoundError } from '@coffer-org/mcp/client';
+import { ValidationError, NotFoundError } from "./mcp-contract/client.js";
 import { recordList, recordListPage, recordGet, recordCreate, recordUpdate, recordDelete, UnknownShelfError, recordTrashList, recordRestore, recordPurge, SingleShelfError, FilterError, } from "./records-api.js";
 import { ValidationError as ServerValidationError } from "./mutate.js";
 import { buildClientSchema } from "./schema-api.js";

package/dist/mcp-tools.d.ts

@@ -1,6 +1,6 @@
 import type { EntityManager } from '@mikro-orm/core';
 import { z } from 'zod';
-import { type ToolResult } from '@coffer-org/mcp';
+import { type ToolResult } from './mcp-contract/tools.ts';
 import { type AuthRole, type PluginHooks } from './plugin-hooks.ts';
 import { type Condition } from '@coffer-org/sdk/condition';
 import { type RagHit } from './rag-search.ts';
@@ -68,6 +68,18 @@ export declare function collectLibraryPurposes(reg?: {
         }[];
     }[];
 }): LibraryPurpose[];
+export declare function siteSection(siteUrl: string): Promise<string | null>;
 export declare function buildDomainSections(): Promise<string[]>;
+export declare function collectStarterHints(hooks?: Record<string, PluginHooks>, emFactory?: () => EntityManager, reg?: {
+    libraries: {
+        meta: {
+            id: string;
+            starterHint?: string;
+        };
+    }[];
+}): Promise<{
+    combined: string;
+    hash: string;
+}>;
 export declare function buildMcpInstructions(sections: string[]): string;
 export {};