@jshookmcp/jshook 0.1.9 → 0.2.1

package/dist/src/server/domains/maintenance/definitions.js

@@ -1,36 +1,9 @@
 export const tokenBudgetTools = [
     {
         name: 'get_token_budget_stats',
-        description: `Get current token budget usage statistics.
-
-Returns:
-- Current token consumption estimate
-- Tool call counts and top token consumers
-- Active warnings and optimization suggestions
-
-When to use:
-- After sessions with many large scripts (>10K tokens each)
-- When responses feel slow or context seems full
-- Before running AI analysis tools
-- When approaching MCP context limits
-
-Tip: Use manual_token_cleanup when usage exceeds 20-30%.
-
-Response fields:
-- currentUsage: estimated token count (approximate)
-- maxTokens: context limit (200K)
-- usagePercentage: utilization ratio
-- toolCallCount: number of tool invocations
-- topTools: highest token-consuming tools
-- warnings: active threshold alerts
-- recentCalls: recent tool activity
-- suggestions: recommended actions
-
-Example:
-\`\`\`
-get_token_budget_stats()
--> Returns current token budget report
-\`\`\``,
+        description: 'Get current token budget usage statistics.\n\n' +
+            'Returns current consumption, tool call counts, top consumers, warnings, and optimization suggestions. ' +
+            'Use manual_token_cleanup when usage exceeds 20-30%.',
         inputSchema: {
             type: 'object',
             properties: {},
@@ -38,33 +11,9 @@ get_token_budget_stats()
     },
     {
         name: 'manual_token_cleanup',
-        description: `Manually trigger token budget cleanup to free context space.
-
-Actions performed:
-- Clears DetailedDataManager stale entries
-- Removes entries older than 5 minutes
-- Resets internal token counters
-
-When to use:
-- Token usage exceeds 90%
-- Context feels sluggish or slow
-- Before a long analysis session
-
-Effect:
-- Frees 10-30% of token budget
-- Preserves recent data
-- Does not affect page state
-
-Response fields:
-- before: usage before cleanup
-- after: usage after cleanup
-- freed: tokens freed
-
-Example:
-\`\`\`
-manual_token_cleanup()
--> Triggers cleanup, frees token budget
-\`\`\``,
+        description: 'Trigger token budget cleanup to free context space. ' +
+            'Clears stale entries older than 5 minutes and resets counters. ' +
+            'Frees 10-30% of token budget while preserving recent data.',
         inputSchema: {
             type: 'object',
             properties: {},
@@ -72,30 +21,8 @@ manual_token_cleanup()
     },
     {
         name: 'reset_token_budget',
-        description: `Reset all token budget counters to zero (hard reset).
-
-Actions performed:
-- Resets token counter to 0
-- Clears all tool call history
-- Resets all warning thresholds
-
-Warning:
-- This is a destructive operation
-- All token tracking history will be lost
-- Running analysis tasks will be interrupted
-
-When to use:
-- Starting a completely new analysis session
-- After a token budget anomaly
-- Periodic maintenance reset
-
-Prefer manual_token_cleanup for routine cleanup. Only use reset_token_budget when MCP session state is corrupted.
-
-Example:
-\`\`\`
-reset_token_budget()
--> Resets all token budget counters
-\`\`\``,
+        description: 'Hard-reset all token budget counters to zero. Destructive: clears all tracking history. ' +
+            'Only use when MCP session state is corrupted. Prefer manual_token_cleanup for routine cleanup.',
         inputSchema: {
             type: 'object',
             properties: {},
@@ -105,24 +32,7 @@ reset_token_budget()
 export const extensionTools = [
     {
         name: 'list_extensions',
-        description: `List all locally loaded plugins, workflows, and extension tools.
-
-Returns:
-- Plugin roots and workflow roots being scanned
-- Loaded plugin count, workflow count, tool count
-- Per-plugin details (id, name, source, contributed domains/tools)
-- Per-workflow details (id, display name, source)
-
-When to use:
-- Check which extensions are currently active
-- Verify a plugin loaded successfully after reload
-- Inspect which tools an extension contributed
-
-Example:
-\`\`\`
-list_extensions()
--> Returns loaded plugins, workflows, and their tools
-\`\`\``,
+        description: 'List all locally loaded plugins, workflows, and extension tools with their details.',
         inputSchema: {
             type: 'object',
             properties: {},
@@ -130,30 +40,8 @@ list_extensions()
     },
     {
         name: 'reload_extensions',
-        description: `Reload all plugins and workflows from configured directories.
-
-Actions performed:
-- Unloads all currently loaded extension tools
-- Re-scans plugin roots (MCP_PLUGIN_ROOTS or <jshook-install>/plugins)
-- Re-scans workflow roots (MCP_WORKFLOW_ROOTS or <jshook-install>/workflows)
-- Validates, loads, and activates discovered plugins
-- Registers contributed tools and workflows
-
-Returns:
-- Added/removed tool counts
-- Loaded plugins and workflows list
-- Any warnings or errors encountered
-
-When to use:
-- After installing a new extension
-- After modifying a plugin's manifest
-- To hot-reload plugins without restarting the server
-
-Example:
-\`\`\`
-reload_extensions()
--> Reloads all extensions, returns summary
-\`\`\``,
+        description: 'Reload all plugins and workflows from configured directories. ' +
+            'Dynamically registers extension tools and refreshes tool list.',
         inputSchema: {
             type: 'object',
             properties: {},
@@ -161,28 +49,7 @@ reload_extensions()
     },
     {
         name: 'browse_extension_registry',
-        description: `Browse the remote jshookmcp extension registry to discover available plugins and workflows.
-
-Fetches the latest plugin and workflow indices from the official registry (github.com/vmoranv/jshookmcpextension).
-
-Parameters:
-- kind: Filter by "plugin", "workflow", or "all" (default: "all")
-
-Returns:
-- Available plugins with id, name, description, author, repo URL
-- Available workflows with id, name, description, author, repo URL
-- Source commit hash for reproducible installs
-
-When to use:
-- Discover what extensions are available
-- Find a plugin for a specific integration (Burp, Frida, IDA, etc.)
-- Check if a newer version of an extension exists
-
-Example:
-\`\`\`
-browse_extension_registry({ kind: "plugin" })
--> Returns all available plugins from the registry
-\`\`\``,
+        description: 'Browse the remote jshookmcp extension registry to discover available plugins and workflows.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -196,33 +63,8 @@ browse_extension_registry({ kind: "plugin" })
     },
     {
         name: 'install_extension',
-        description: `Install an extension from the remote registry into the jshook installation extension directories.
-
-Clones the extension repository and checks out the pinned commit from the registry.
-
-Parameters:
-- slug: Extension slug from the registry (e.g. "ida-bridge", "frida-bridge")
-- targetDir: Target directory override (optional). By default:
-  - plugin -> <jshook-install>/plugins/<slug>
-  - workflow -> <jshook-install>/workflows/<slug>
-
-Actions performed:
-1. Fetches the registry index to resolve the extension
-2. Clones the extension repo to the target directory
-3. Checks out the pinned commit for reproducibility
-4. Runs reload_extensions to activate the new plugin
-
-Requires: git available in PATH.
-
-When to use:
-- Install a new plugin from the registry
-- Set up a bridge integration (Burp, Frida, IDA, Ghidra, Jadx, ZAP)
-
-Example:
-\`\`\`
-install_extension({ slug: "ida-bridge" })
--> Clones and installs the IDA bridge plugin
-\`\`\``,
+        description: 'Install an extension from the remote registry. Clones the repo, checks out the pinned commit, ' +
+            'and runs reload_extensions to activate. Requires git in PATH.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -242,64 +84,8 @@ install_extension({ slug: "ida-bridge" })
 export const cacheTools = [
     {
         name: 'get_cache_stats',
-        description: `Get cache statistics for all internal caches.
-
-Returns information about:
-- Total entries and size across all caches
-- Per-cache hit rates and TTL configuration
-- Actionable cleanup recommendations
-
-Response fields:
-- totalEntries: total cached items
-- totalSize: total size in bytes
-- totalSizeMB: total size in MB
-- hitRate: overall cache hit ratio
-- caches: per-cache breakdown
-  - name: cache name
-  - entries: item count
-  - size: size in bytes
-  - sizeMB: size in MB
-  - hitRate: hit ratio
-  - ttl: time-to-live in ms
-- recommendations: suggested actions
-
-Example:
-\`\`\`typescript
-get_cache_stats()
-{
-  "totalEntries": 150,
-  "totalSize": 52428800,
-  "totalSizeMB": "50.00",
-  "hitRate": 0.75,
-  "caches": [
-    {
-      "name": "DetailedDataManager",
-      "entries": 50,
-      "size": 2621440,
-      "sizeMB": "2.50",
-      "hitRate": 0.8,
-      "ttl": 600000
-    },
-    {
-      "name": "CodeCache",
-      "entries": 80,
-      "size": 41943040,
-      "sizeMB": "40.00",
-      "hitRate": 0.7
-    },
-    {
-      "name": "CodeCompressor",
-      "entries": 20,
-      "size": 7864320,
-      "sizeMB": "7.50",
-      "hitRate": 0.75
-    }
-  ],
-  "recommendations": [
-    "Cache health is good. No action needed."
-  ]
-}
-\`\`\``,
+        description: 'Get cache statistics for all internal caches. ' +
+            'Returns total entries, sizes, per-cache hit rates, TTL config, and cleanup recommendations.',
         inputSchema: {
             type: 'object',
             properties: {},
@@ -307,39 +93,8 @@ get_cache_stats()
     },
     {
         name: 'smart_cache_cleanup',
-        description: `Intelligently clean caches to free memory while preserving hot data.
-
-Cleanup strategy:
-1. Evicts least-recently-used entries first
-2. Removes entries below hit threshold (< average * 30%)
-3. Clears entries older than 2 hours
-
-Parameter:
-- targetSize: target size in bytes (optional)
-  - Default: 70% of maximum (350MB)
-  - Automatic: triggered when usage > 70%
-
-Response fields:
-- before: size before cleanup (bytes)
-- after: size after cleanup (bytes)
-- freed: bytes freed
-- freedPercentage: percentage reduction
-
-When to use:
-- Cache usage > 70%
-- Token usage > 80%
-- Before a memory-intensive analysis
-
-Example:
-\`\`\`typescript
-smart_cache_cleanup()
-{
-  "before": 419430400,
-  "after": 314572800,
-  "freed": 104857600,
-  "freedPercentage": 21
-}
-\`\`\``,
+        description: 'Intelligently clean caches to free memory while preserving hot data. ' +
+            'Evicts LRU entries, removes low-hit entries, and clears entries older than 2 hours.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -352,34 +107,8 @@ smart_cache_cleanup()
     },
     {
         name: 'clear_all_caches',
-        description: `Clear all internal caches completely.
-
-Actions performed:
-- Clears all cached code scripts
-- Resets all hit rate counters
-- Frees all allocated cache memory
-
-Warning: This is a destructive operation. All cached data will be lost:
-- DetailedDataManager (hook capture data)
-- CodeCache (collected scripts)
-- CodeCompressor (compressed code)
-
-When to use:
-- Starting a completely fresh session
-- After cache corruption
-- When memory usage is critically high
-- Periodic maintenance
-
-Prefer smart_cache_cleanup for routine maintenance to preserve hot data.
-
-Example:
-\`\`\`typescript
-clear_all_caches()
-{
-  "success": true,
-  "message": "All caches cleared"
-}
-\`\`\``,
+        description: 'Clear all internal caches completely. Destructive: all cached data will be lost. ' +
+            'Prefer smart_cache_cleanup for routine maintenance.',
         inputSchema: {
             type: 'object',
             properties: {},
@@ -389,28 +118,8 @@ clear_all_caches()
 export const artifactTools = [
     {
         name: 'cleanup_artifacts',
-        description: `Clean generated artifacts, screenshots, and debugger sessions using retention rules.
-
-Supports:
-- Age-based removal via retentionDays
-- Size-based trimming via maxTotalBytes
-- Dry-run mode for safe preview
-
-Default directories:
-- artifacts/
-- screenshots/
-- debugger-sessions/
-
-Environment defaults:
-- MCP_ARTIFACT_RETENTION_DAYS
-- MCP_ARTIFACT_MAX_TOTAL_MB
-- MCP_ARTIFACT_CLEANUP_ON_START
-- MCP_ARTIFACT_CLEANUP_INTERVAL_MINUTES
-
-Example:
-\`\`\`typescript
-cleanup_artifacts({ retentionDays: 7, dryRun: true })
-\`\`\``,
+        description: 'Clean generated artifacts, screenshots, and debugger sessions using retention rules. ' +
+            'Supports age-based removal, size-based trimming, and dry-run preview.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -425,35 +134,20 @@ cleanup_artifacts({ retentionDays: 7, dryRun: true })
                 dryRun: {
                     type: 'boolean',
                     description: 'Preview removals without deleting files.',
-                    default: false,
                 },
             },
         },
     },
     {
         name: 'doctor_environment',
-        description: `Run an environment doctor for optional dependencies, bridge endpoints, and platform limitations.
-
-Checks:
-- Installed optional packages (camoufox-js, playwright-core)
-- External toolchain availability (wabt, binaryen, jadx, etc.)
-- Native bridge health (Ghidra / IDA / Burp)
-- Active security and artifact-retention configuration
-- Platform limitations for Windows-only memory tooling
-
-Use this before debugging dependency issues or after installing external integrations.
-
-Example:
-\`\`\`typescript
-doctor_environment({ includeBridgeHealth: true })
-\`\`\``,
+        description: 'Run an environment doctor for optional dependencies, bridge endpoints, and platform limitations. ' +
+            'Use before debugging dependency issues or after installing external integrations.',
         inputSchema: {
             type: 'object',
             properties: {
                 includeBridgeHealth: {
                     type: 'boolean',
                     description: 'When true, probe local native-bridge / Burp endpoints as part of the report.',
-                    default: true,
                 },
             },
         },

package/dist/src/server/domains/maintenance/handlers.extensions.js

@@ -40,7 +40,10 @@ function getRegistryBaseUrl() {
 }
 const LOCAL_EXTENSION_SDK_PACKAGE = '@jshookmcp/extension-sdk';
 const LOCAL_EXTENSION_SDK_ROOT = resolve(getJshookInstallRoot(), 'packages', 'extension-sdk');
-const REGISTRY_FETCH_TIMEOUT_MS = 10_000;
+var RegistryLimit;
+(function (RegistryLimit) {
+    RegistryLimit[RegistryLimit["FETCH_TIMEOUT_MS"] = 10000] = "FETCH_TIMEOUT_MS";
+})(RegistryLimit || (RegistryLimit = {}));
 const REGISTRY_CACHE_DIR = resolve(homedir(), '.jshookmcp', 'cache');
 class RegistryFetchError extends Error {
     code;
@@ -122,7 +125,7 @@ function classifyRegistryFetchError(url, error, cachePath) {
         return error;
     }
     if (error instanceof DOMException && error.name === 'AbortError') {
-        return new RegistryFetchError('timeout', url, `Registry fetch timed out after ${REGISTRY_FETCH_TIMEOUT_MS}ms: ${url}`, cachePath);
+        return new RegistryFetchError('timeout', url, `Registry fetch timed out after ${RegistryLimit.FETCH_TIMEOUT_MS}ms: ${url}`, cachePath);
     }
     const message = error instanceof Error ? error.message : String(error);
     if (message.includes('ENOTFOUND') || message.includes('getaddrinfo')) {
@@ -153,7 +156,7 @@ function serializeRegistryFetchError(error) {
 }
 async function fetchJson(url, options) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), REGISTRY_FETCH_TIMEOUT_MS);
+    const timer = setTimeout(() => controller.abort(), RegistryLimit.FETCH_TIMEOUT_MS);
     const cachePath = options?.cacheKey ? getRegistryCachePath(options.cacheKey) : undefined;
     try {
         const res = await fetch(url, { signal: controller.signal });

package/dist/src/server/domains/maintenance/manifest.d.ts

@@ -1,7 +1,102 @@
-import type { DomainManifest } from '../../domains/shared/registry.js';
+import type { MCPServerContext } from '../../domains/shared/registry.js';
 import { CoreMaintenanceHandlers } from '../../domains/maintenance/index.js';
-declare const DOMAIN: "maintenance";
-declare const DEP_KEY: "coreMaintenanceHandlers";
 type H = CoreMaintenanceHandlers;
-declare const manifest: DomainManifest<typeof DEP_KEY, H, typeof DOMAIN>;
+declare function ensure(ctx: MCPServerContext): H;
+declare const manifest: {
+    kind: "domain-manifest";
+    version: 1;
+    domain: "maintenance";
+    depKey: "coreMaintenanceHandlers";
+    profiles: ("workflow" | "full" | "search")[];
+    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: "maintenance";
+        bind: (deps: import("../../domains/shared/registry.js").ToolHandlerDeps) => (args: import("../../types.js").ToolArgs) => Promise<unknown>;
+        profiles?: undefined;
+    } | {
+        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: "maintenance";
+        bind: (deps: import("../../domains/shared/registry.js").ToolHandlerDeps) => (args: import("../../types.js").ToolArgs) => Promise<unknown>;
+        profiles: ("workflow" | "full")[];
+    })[];
+};
 export default manifest;

package/dist/src/server/domains/maintenance/manifest.js

@@ -29,16 +29,16 @@ const manifest = {
     registrations: [
         { tool: t('get_token_budget_stats'), domain: DOMAIN, bind: b((h) => h.handleGetTokenBudgetStats()) },
         { tool: t('manual_token_cleanup'), domain: DOMAIN, bind: b((h) => h.handleManualTokenCleanup()) },
-        { tool: t('reset_token_budget'), domain: DOMAIN, bind: b((h) => h.handleResetTokenBudget()) },
+        { tool: t('reset_token_budget'), domain: DOMAIN, bind: b((h) => h.handleResetTokenBudget()), profiles: ['workflow', 'full'] },
         { tool: t('get_cache_stats'), domain: DOMAIN, bind: b((h) => h.handleGetCacheStats()) },
         { tool: t('smart_cache_cleanup'), domain: DOMAIN, bind: b((h, a) => h.handleSmartCacheCleanup(a.targetSize)) },
-        { tool: t('clear_all_caches'), domain: DOMAIN, bind: b((h) => h.handleClearAllCaches()) },
-        { tool: t('cleanup_artifacts'), domain: DOMAIN, bind: b((h, a) => h.handleCleanupArtifacts({ retentionDays: a.retentionDays, maxTotalBytes: a.maxTotalBytes, dryRun: a.dryRun })) },
-        { tool: t('doctor_environment'), domain: DOMAIN, bind: b((h, a) => h.handleEnvironmentDoctor({ includeBridgeHealth: a.includeBridgeHealth })) },
+        { tool: t('clear_all_caches'), domain: DOMAIN, bind: b((h) => h.handleClearAllCaches()), profiles: ['workflow', 'full'] },
+        { tool: t('cleanup_artifacts'), domain: DOMAIN, bind: b((h, a) => h.handleCleanupArtifacts({ retentionDays: a.retentionDays, maxTotalBytes: a.maxTotalBytes, dryRun: a.dryRun })), profiles: ['workflow', 'full'] },
+        { tool: t('doctor_environment'), domain: DOMAIN, bind: b((h, a) => h.handleEnvironmentDoctor({ includeBridgeHealth: a.includeBridgeHealth })), profiles: ['workflow', 'full'] },
         { tool: t('list_extensions'), domain: DOMAIN, bind: be((h) => h.handleListExtensions()) },
         { tool: t('reload_extensions'), domain: DOMAIN, bind: be((h) => h.handleReloadExtensions()) },
-        { tool: t('browse_extension_registry'), domain: DOMAIN, bind: be((h, a) => h.handleBrowseExtensionRegistry(a.kind ?? 'all')) },
-        { tool: t('install_extension'), domain: DOMAIN, bind: be((h, a) => h.handleInstallExtension(a.slug, a.targetDir)) },
+        { tool: t('browse_extension_registry'), domain: DOMAIN, bind: be((h, a) => h.handleBrowseExtensionRegistry(a.kind ?? 'all')), profiles: ['workflow', 'full'] },
+        { tool: t('install_extension'), domain: DOMAIN, bind: be((h, a) => h.handleInstallExtension(a.slug, a.targetDir)), profiles: ['workflow', 'full'] },
     ],
 };
 export default manifest;