@jshookmcp/jshook 0.2.5 → 0.2.6

package/dist/src/server/domains/shared-state-board/definitions.js

@@ -0,0 +1,78 @@
+import { tool } from '../../registry/tool-builder.js';
+export const sharedStateBoardTools = [
+    tool('state_board_set')
+        .desc('Set a value in the shared state board. Supports string, number, boolean, object, and array values.')
+        .string('key', 'The key to store the value under')
+        .prop('value', {
+        type: 'object',
+        description: 'The value to store (any JSON-serializable type)',
+    })
+        .string('namespace', 'Optional namespace for key isolation (default: "default")')
+        .number('ttlSeconds', 'Optional TTL in seconds (value expires after this duration)')
+        .required('key', 'value')
+        .build(),
+    tool('state_board_get')
+        .desc('Get a value from the shared state board by key.')
+        .string('key', 'The key to retrieve')
+        .string('namespace', 'Optional namespace (default: "default")')
+        .readOnly()
+        .idempotent()
+        .required('key')
+        .build(),
+    tool('state_board_delete')
+        .desc('Delete a value from the shared state board by key.')
+        .string('key', 'The key to delete')
+        .string('namespace', 'Optional namespace (default: "default")')
+        .required('key')
+        .build(),
+    tool('state_board_list')
+        .desc('List all keys in the shared state board, optionally filtered by namespace.')
+        .string('namespace', 'Optional namespace filter (default: all namespaces)')
+        .boolean('includeValues', 'Include current values in the response (default: false)')
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('state_board_watch')
+        .desc('Watch a key or pattern for changes. Returns a watch ID that can be used to poll for updates.')
+        .string('key', 'The key to watch (supports * wildcard for pattern matching)')
+        .string('namespace', 'Optional namespace (default: "default")')
+        .number('pollIntervalMs', 'Polling interval in milliseconds (default: 1000)')
+        .required('key')
+        .build(),
+    tool('state_board_unwatch')
+        .desc('Stop watching a key or pattern.')
+        .string('watchId', 'The watch ID returned by state_board_watch')
+        .required('watchId')
+        .build(),
+    tool('state_board_history')
+        .desc('Get the change history for a key.')
+        .string('key', 'The key to get history for')
+        .string('namespace', 'Optional namespace (default: "default")')
+        .number('limit', 'Maximum number of history entries to return (default: 50)')
+        .readOnly()
+        .idempotent()
+        .required('key')
+        .build(),
+    tool('state_board_export')
+        .desc('Export all or filtered state board entries as JSON.')
+        .string('namespace', 'Optional namespace filter (default: all)')
+        .string('keyPattern', 'Optional key pattern filter (supports * wildcard)')
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('state_board_import')
+        .desc('Import state board entries from JSON. Merges with existing state.')
+        .prop('data', {
+        type: 'object',
+        description: 'Object with keys and values to import',
+    })
+        .string('namespace', 'Optional namespace (default: "default")')
+        .boolean('overwrite', 'Overwrite existing keys (default: false)')
+        .required('data')
+        .build(),
+    tool('state_board_clear')
+        .desc('Clear all or filtered state board entries.')
+        .string('namespace', 'Optional namespace to clear (default: all)')
+        .string('keyPattern', 'Optional key pattern to clear (supports * wildcard)')
+        .build(),
+];

package/dist/src/server/domains/shared-state-board/handlers.impl.d.ts

@@ -0,0 +1,58 @@
+export * from './definitions.js';
+export interface StateEntry {
+    key: string;
+    value: unknown;
+    namespace: string;
+    createdAt: number;
+    updatedAt: number;
+    ttlSeconds?: number;
+    expiresAt?: number;
+    version: number;
+}
+export interface StateChangeRecord {
+    id: string;
+    key: string;
+    namespace: string;
+    action: 'set' | 'delete' | 'expire';
+    oldValue?: unknown;
+    newValue?: unknown;
+    timestamp: number;
+    source?: string;
+}
+export interface StateWatch {
+    id: string;
+    key: string;
+    namespace: string;
+    pattern: boolean;
+    pollIntervalMs: number;
+    lastChecked: number;
+    lastVersion: Record<string, number>;
+    createdAt: number;
+}
+export interface StateBoardStats {
+    totalEntries: number;
+    entriesByNamespace: Record<string, number>;
+    expiredEntries: number;
+    totalWatches: number;
+    historySize: number;
+}
+export declare class SharedStateBoardHandlers {
+    private readonly state;
+    private readonly history;
+    private readonly watches;
+    private readonly maxHistoryPerKey;
+    handleSet(args: Record<string, unknown>): Promise<unknown>;
+    handleGet(args: Record<string, unknown>): Promise<unknown>;
+    handleDelete(args: Record<string, unknown>): Promise<unknown>;
+    handleList(args: Record<string, unknown>): Promise<unknown>;
+    handleWatch(args: Record<string, unknown>): Promise<unknown>;
+    handleUnwatch(args: Record<string, unknown>): Promise<unknown>;
+    handlePoll(args: Record<string, unknown>): Promise<unknown>;
+    handleHistory(args: Record<string, unknown>): Promise<unknown>;
+    handleExport(args: Record<string, unknown>): Promise<unknown>;
+    handleImport(args: Record<string, unknown>): Promise<unknown>;
+    handleClear(args: Record<string, unknown>): Promise<unknown>;
+    handleStats(): Promise<unknown>;
+    private recordChange;
+    cleanupExpired(): number;
+}

package/dist/src/server/domains/shared-state-board/handlers.impl.js

@@ -0,0 +1,419 @@
+import { randomUUID } from 'node:crypto';
+export * from './definitions.js';
+export class SharedStateBoardHandlers {
+    state = new Map();
+    history = new Map();
+    watches = new Map();
+    maxHistoryPerKey = 100;
+    async handleSet(args) {
+        const key = args.key;
+        const value = args.value;
+        const namespace = args.namespace ?? 'default';
+        const ttlSeconds = args.ttlSeconds;
+        if (!key || typeof key !== 'string') {
+            throw new Error('key must be a non-empty string');
+        }
+        const fullKey = `${namespace}:${key}`;
+        const now = Date.now();
+        const existing = this.state.get(fullKey);
+        const oldVersion = existing?.version ?? 0;
+        const oldValue = existing?.value;
+        const entry = {
+            key,
+            value,
+            namespace,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+            ttlSeconds,
+            expiresAt: ttlSeconds ? now + ttlSeconds * 1000 : undefined,
+            version: oldVersion + 1,
+        };
+        this.state.set(fullKey, entry);
+        this.recordChange(fullKey, {
+            id: randomUUID().slice(0, 8),
+            key,
+            namespace,
+            action: 'set',
+            oldValue,
+            newValue: value,
+            timestamp: now,
+        });
+        return {
+            success: true,
+            key,
+            namespace,
+            version: entry.version,
+            expiresAt: entry.expiresAt ? new Date(entry.expiresAt).toISOString() : undefined,
+        };
+    }
+    async handleGet(args) {
+        const key = args.key;
+        const namespace = args.namespace ?? 'default';
+        if (!key || typeof key !== 'string') {
+            throw new Error('key must be a non-empty string');
+        }
+        const fullKey = `${namespace}:${key}`;
+        const entry = this.state.get(fullKey);
+        if (!entry) {
+            return { found: false, key, namespace };
+        }
+        if (entry.expiresAt && Date.now() > entry.expiresAt) {
+            this.handleDelete({ key, namespace });
+            return { found: false, key, namespace, expired: true };
+        }
+        return {
+            found: true,
+            key,
+            namespace,
+            value: entry.value,
+            version: entry.version,
+            createdAt: new Date(entry.createdAt).toISOString(),
+            updatedAt: new Date(entry.updatedAt).toISOString(),
+            ttlSeconds: entry.ttlSeconds,
+            expiresAt: entry.expiresAt ? new Date(entry.expiresAt).toISOString() : undefined,
+        };
+    }
+    async handleDelete(args) {
+        const key = args.key;
+        const namespace = args.namespace ?? 'default';
+        const fullKey = `${namespace}:${key}`;
+        const existing = this.state.get(fullKey);
+        if (!existing) {
+            return { deleted: false, key, namespace, reason: 'not_found' };
+        }
+        this.state.delete(fullKey);
+        this.recordChange(fullKey, {
+            id: randomUUID().slice(0, 8),
+            key,
+            namespace,
+            action: 'delete',
+            oldValue: existing.value,
+            timestamp: Date.now(),
+        });
+        return { deleted: true, key, namespace };
+    }
+    async handleList(args) {
+        const namespace = args.namespace;
+        const includeValues = args.includeValues ?? false;
+        const now = Date.now();
+        const entries = [];
+        for (const entry of this.state.values()) {
+            if (namespace && entry.namespace !== namespace) {
+                continue;
+            }
+            const expired = !!(entry.expiresAt && now > entry.expiresAt);
+            if (expired) {
+                this.handleDelete({ key: entry.key, namespace: entry.namespace });
+                continue;
+            }
+            entries.push({
+                key: entry.key,
+                namespace: entry.namespace,
+                version: entry.version,
+                updatedAt: new Date(entry.updatedAt).toISOString(),
+                ...(includeValues ? { value: entry.value } : {}),
+            });
+        }
+        entries.sort((a, b) => {
+            if (a.namespace !== b.namespace) {
+                return a.namespace.localeCompare(b.namespace);
+            }
+            return a.key.localeCompare(b.key);
+        });
+        return {
+            entries,
+            total: entries.length,
+            namespaces: [...new Set(entries.map((e) => e.namespace))],
+        };
+    }
+    async handleWatch(args) {
+        const key = args.key;
+        const namespace = args.namespace ?? 'default';
+        const pollIntervalMs = args.pollIntervalMs ?? 1000;
+        if (!key || typeof key !== 'string') {
+            throw new Error('key must be a non-empty string');
+        }
+        const watchId = `watch_${randomUUID().slice(0, 8)}`;
+        const isPattern = key.includes('*');
+        const watch = {
+            id: watchId,
+            key,
+            namespace,
+            pattern: isPattern,
+            pollIntervalMs,
+            lastChecked: Date.now(),
+            lastVersion: {},
+            createdAt: Date.now(),
+        };
+        const prefix = `${namespace}:`;
+        for (const [fullKey, entry] of this.state.entries()) {
+            if (fullKey.startsWith(prefix)) {
+                if (isPattern) {
+                    const regex = new RegExp(`^${prefix}${key.replace(/\*/g, '.*')}$`);
+                    if (regex.test(fullKey)) {
+                        watch.lastVersion[fullKey] = entry.version;
+                    }
+                }
+                else {
+                    watch.lastVersion[fullKey] = entry.version;
+                }
+            }
+        }
+        this.watches.set(watchId, watch);
+        return {
+            watchId,
+            key,
+            namespace,
+            pattern: isPattern,
+            pollIntervalMs,
+            initialKeys: Object.keys(watch.lastVersion),
+        };
+    }
+    async handleUnwatch(args) {
+        const watchId = args.watchId;
+        const watch = this.watches.get(watchId);
+        if (!watch) {
+            return { removed: false, watchId, reason: 'not_found' };
+        }
+        this.watches.delete(watchId);
+        return { removed: true, watchId, wasWatching: watch.key };
+    }
+    async handlePoll(args) {
+        const watchId = args.watchId;
+        const watch = this.watches.get(watchId);
+        if (!watch) {
+            throw new Error(`Watch "${watchId}" not found`);
+        }
+        const now = Date.now();
+        const changes = [];
+        const prefix = `${watch.namespace}:`;
+        if (watch.pattern) {
+            const regex = new RegExp(`^${prefix}${watch.key.replace(/\*/g, '.*')}$`);
+            for (const [fullKey, entry] of this.state.entries()) {
+                if (regex.test(fullKey)) {
+                    const lastVer = watch.lastVersion[fullKey];
+                    if (lastVer === undefined) {
+                        changes.push({ key: entry.key, namespace: entry.namespace, action: 'created' });
+                    }
+                    else if (entry.version > lastVer) {
+                        changes.push({ key: entry.key, namespace: entry.namespace, action: 'changed' });
+                    }
+                    watch.lastVersion[fullKey] = entry.version;
+                }
+            }
+            for (const watchedKey of Object.keys(watch.lastVersion)) {
+                if (!this.state.has(watchedKey) && regex.test(watchedKey)) {
+                    const idx = watchedKey.indexOf(':');
+                    const key = idx >= 0 ? watchedKey.substring(idx + 1) : watchedKey;
+                    changes.push({
+                        key,
+                        namespace: watch.namespace,
+                        action: 'deleted',
+                    });
+                    delete watch.lastVersion[watchedKey];
+                }
+            }
+        }
+        else {
+            const fullKey = `${watch.namespace}:${watch.key}`;
+            const entry = this.state.get(fullKey);
+            const lastVer = watch.lastVersion[fullKey];
+            if (!entry && lastVer !== undefined) {
+                changes.push({ key: watch.key, namespace: watch.namespace, action: 'deleted' });
+                delete watch.lastVersion[fullKey];
+            }
+            else if (entry) {
+                if (lastVer === undefined) {
+                    changes.push({ key: entry.key, namespace: entry.namespace, action: 'created' });
+                }
+                else if (entry.version > lastVer) {
+                    changes.push({ key: entry.key, namespace: entry.namespace, action: 'changed' });
+                }
+                watch.lastVersion[fullKey] = entry.version;
+            }
+        }
+        watch.lastChecked = now;
+        return {
+            watchId,
+            changes,
+            hasChanges: changes.length > 0,
+            checkedAt: new Date(now).toISOString(),
+        };
+    }
+    async handleHistory(args) {
+        const key = args.key;
+        const namespace = args.namespace ?? 'default';
+        const limit = args.limit ?? 50;
+        const fullKey = `${namespace}:${key}`;
+        const records = this.history.get(fullKey) ?? [];
+        const sorted = [...records].toSorted((a, b) => b.timestamp - a.timestamp);
+        const limited = sorted.slice(0, limit);
+        return {
+            key,
+            namespace,
+            history: limited.map((r) => ({
+                ...r,
+                timestamp: new Date(r.timestamp).toISOString(),
+            })),
+            total: records.length,
+            returned: limited.length,
+        };
+    }
+    async handleExport(args) {
+        const namespace = args.namespace;
+        const keyPattern = args.keyPattern;
+        const now = Date.now();
+        const data = {};
+        for (const [_fullKey, entry] of this.state.entries()) {
+            if (namespace && entry.namespace !== namespace) {
+                continue;
+            }
+            if (keyPattern) {
+                const regex = new RegExp(`^${keyPattern.replace(/\*/g, '.*')}$`);
+                if (!regex.test(entry.key)) {
+                    continue;
+                }
+            }
+            if (entry.expiresAt && now > entry.expiresAt) {
+                continue;
+            }
+            data[entry.key] = entry.value;
+        }
+        return {
+            data,
+            count: Object.keys(data).length,
+            namespace: namespace ?? 'all',
+            exportedAt: new Date(now).toISOString(),
+        };
+    }
+    async handleImport(args) {
+        const data = args.data;
+        const namespace = args.namespace ?? 'default';
+        const overwrite = args.overwrite ?? false;
+        if (!data || typeof data !== 'object') {
+            throw new Error('data must be an object');
+        }
+        const imported = [];
+        const skipped = [];
+        const overwritten = [];
+        for (const [key, value] of Object.entries(data)) {
+            const fullKey = `${namespace}:${key}`;
+            const existing = this.state.get(fullKey);
+            if (existing && !overwrite) {
+                skipped.push(key);
+                continue;
+            }
+            if (existing && overwrite) {
+                overwritten.push(key);
+            }
+            const now = Date.now();
+            const entry = {
+                key,
+                value,
+                namespace,
+                createdAt: existing?.createdAt ?? now,
+                updatedAt: now,
+                version: (existing?.version ?? 0) + 1,
+            };
+            this.state.set(fullKey, entry);
+            imported.push(key);
+        }
+        return {
+            imported: imported.length,
+            skipped: skipped.length,
+            overwritten: overwritten.length,
+            total: Object.keys(data).length,
+            keys: imported,
+        };
+    }
+    async handleClear(args) {
+        const namespace = args.namespace;
+        const keyPattern = args.keyPattern;
+        const toDelete = [];
+        for (const [fullKey, entry] of this.state.entries()) {
+            if (namespace && entry.namespace !== namespace) {
+                continue;
+            }
+            if (keyPattern) {
+                const regex = new RegExp(`^${keyPattern.replace(/\*/g, '.*')}$`);
+                if (!regex.test(entry.key)) {
+                    continue;
+                }
+            }
+            toDelete.push(fullKey);
+        }
+        for (const fullKey of toDelete) {
+            const entry = this.state.get(fullKey);
+            if (entry) {
+                this.state.delete(fullKey);
+                this.recordChange(fullKey, {
+                    id: randomUUID().slice(0, 8),
+                    key: entry.key,
+                    namespace: entry.namespace,
+                    action: 'delete',
+                    oldValue: entry.value,
+                    timestamp: Date.now(),
+                });
+            }
+        }
+        return {
+            cleared: toDelete.length,
+            namespace: namespace ?? 'all',
+            pattern: keyPattern,
+        };
+    }
+    async handleStats() {
+        const now = Date.now();
+        const entriesByNamespace = {};
+        let expiredCount = 0;
+        for (const [, entry] of this.state.entries()) {
+            if (entry.expiresAt && now > entry.expiresAt) {
+                expiredCount++;
+                continue;
+            }
+            entriesByNamespace[entry.namespace] = (entriesByNamespace[entry.namespace] ?? 0) + 1;
+        }
+        let historySize = 0;
+        for (const records of this.history.values()) {
+            historySize += records.length;
+        }
+        const stats = {
+            totalEntries: Object.values(entriesByNamespace).reduce((a, b) => a + b, 0),
+            entriesByNamespace,
+            expiredEntries: expiredCount,
+            totalWatches: this.watches.size,
+            historySize,
+        };
+        return stats;
+    }
+    recordChange(fullKey, record) {
+        let history = this.history.get(fullKey);
+        if (!history) {
+            history = [];
+            this.history.set(fullKey, history);
+        }
+        history.push(record);
+        if (history.length > this.maxHistoryPerKey) {
+            history.splice(0, history.length - this.maxHistoryPerKey);
+        }
+    }
+    cleanupExpired() {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [fullKey, entry] of this.state.entries()) {
+            if (entry.expiresAt && now > entry.expiresAt) {
+                this.state.delete(fullKey);
+                this.recordChange(fullKey, {
+                    id: randomUUID().slice(0, 8),
+                    key: entry.key,
+                    namespace: entry.namespace,
+                    action: 'expire',
+                    oldValue: entry.value,
+                    timestamp: now,
+                });
+                cleaned++;
+            }
+        }
+        return cleaned;
+    }
+}

package/dist/src/server/domains/shared-state-board/index.d.ts

@@ -0,0 +1,2 @@
+export * from './definitions.js';
+export * from './handlers.impl.js';

package/dist/src/server/domains/shared-state-board/index.js

@@ -0,0 +1,2 @@
+export * from './definitions.js';
+export * from './handlers.impl.js';

package/dist/src/server/domains/shared-state-board/manifest.d.ts

@@ -0,0 +1,57 @@
+import type { MCPServerContext } from '../../domains/shared/registry.js';
+import { SharedStateBoardHandlers } from '../../domains/shared-state-board/index.js';
+type H = SharedStateBoardHandlers;
+declare function ensure(ctx: MCPServerContext): H;
+declare const manifest: {
+    kind: "domain-manifest";
+    version: 1;
+    domain: "shared-state-board";
+    depKey: "sharedStateBoardHandlers";
+    profiles: ("workflow" | "full")[];
+    ensure: typeof ensure;
+    registrations: {
+        tool: {
+            inputSchema: {
+                [x: string]: unknown;
+                type: "object";
+                properties?: {
+                    [x: string]: object;
+                } | undefined;
+                required?: string[] | undefined;
+            };
+            name: string;
+            description?: string | undefined;
+            outputSchema?: {
+                [x: string]: unknown;
+                type: "object";
+                properties?: {
+                    [x: string]: object;
+                } | undefined;
+                required?: string[] | undefined;
+            } | undefined;
+            annotations?: {
+                title?: string | undefined;
+                readOnlyHint?: boolean | undefined;
+                destructiveHint?: boolean | undefined;
+                idempotentHint?: boolean | undefined;
+                openWorldHint?: boolean | undefined;
+            } | undefined;
+            execution?: {
+                taskSupport?: "optional" | "required" | "forbidden" | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        };
+        domain: "shared-state-board";
+        bind: (deps: import("../../domains/shared/registry.js").ToolHandlerDeps) => (args: import("../../types.js").ToolArgs) => Promise<unknown>;
+    }[];
+};
+export default manifest;

package/dist/src/server/domains/shared-state-board/manifest.js

@@ -0,0 +1,74 @@
+import { bindByDepKey, toolLookup } from '../../domains/shared/registry.js';
+import { sharedStateBoardTools } from '../../domains/shared-state-board/definitions.js';
+import { SharedStateBoardHandlers } from '../../domains/shared-state-board/index.js';
+const DOMAIN = 'shared-state-board';
+const DEP_KEY = 'sharedStateBoardHandlers';
+const t = toolLookup(sharedStateBoardTools);
+const b = (invoke) => bindByDepKey(DEP_KEY, invoke);
+function ensure(ctx) {
+    if (!ctx.sharedStateBoardHandlers) {
+        ctx.sharedStateBoardHandlers = new SharedStateBoardHandlers();
+    }
+    return ctx.sharedStateBoardHandlers;
+}
+const manifest = {
+    kind: 'domain-manifest',
+    version: 1,
+    domain: DOMAIN,
+    depKey: DEP_KEY,
+    profiles: ['workflow', 'full'],
+    ensure,
+    registrations: [
+        {
+            tool: t('state_board_set'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleSet(a)),
+        },
+        {
+            tool: t('state_board_get'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleGet(a)),
+        },
+        {
+            tool: t('state_board_delete'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleDelete(a)),
+        },
+        {
+            tool: t('state_board_list'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleList(a)),
+        },
+        {
+            tool: t('state_board_watch'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleWatch(a)),
+        },
+        {
+            tool: t('state_board_unwatch'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleUnwatch(a)),
+        },
+        {
+            tool: t('state_board_history'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleHistory(a)),
+        },
+        {
+            tool: t('state_board_export'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleExport(a)),
+        },
+        {
+            tool: t('state_board_import'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleImport(a)),
+        },
+        {
+            tool: t('state_board_clear'),
+            domain: DOMAIN,
+            bind: b((h, a) => h.handleClear(a)),
+        },
+    ],
+};
+export default manifest;