@jshookmcp/jshook 0.1.8 → 0.1.9

package/dist/src/server/MCPServer.search.js

@@ -0,0 +1,137 @@
+import { z } from 'zod';
+import { logger } from '../utils/logger.js';
+import { asErrorResponse } from './domains/shared/response.js';
+import { ALL_DOMAINS } from './registry/index.js';
+export { buildSearchSignature, getSearchEngine } from './MCPServer.search.helpers.js';
+export { buildDomainDescription } from './MCPServer.search.helpers.js';
+import { buildDomainDescription } from './MCPServer.search.helpers.js';
+import { handleSearchTools } from './MCPServer.search.handlers.search.js';
+import { handleActivateTools, handleDeactivateTools } from './MCPServer.search.handlers.activate.js';
+import { handleActivateDomain } from './MCPServer.search.handlers.domain.js';
+import { handleRouteTool, handleDescribeTool } from './MCPServer.search.handlers.route.js';
+import { handleExtensionsReload, handleExtensionsList } from './MCPServer.search.handlers.extensions.js';
+export function registerSearchMetaTools(ctx) {
+    ctx.server.registerTool('search_tools', {
+        description: buildDomainDescription(ctx),
+        inputSchema: {
+            query: z.string().describe('Search query: keywords, tool name, domain name, or description fragment'),
+            top_k: z.number().optional().describe('Max results to return (default: 10, max: 30)'),
+        },
+    }, async (args) => {
+        try {
+            return await handleSearchTools(ctx, args);
+        }
+        catch (error) {
+            logger.error('search_tools failed', error);
+            return asErrorResponse(error);
+        }
+    });
+    ctx.server.registerTool('route_tool', {
+        description: 'One-stop tool router: accepts a natural language task description, returns recommended tools and next actions. ' +
+            'Automatically detects workflow patterns, recommends activation order, and provides example arguments. ' +
+            'Use this instead of search_tools when you want guided tool discovery with actionable next steps.',
+        inputSchema: {
+            task: z.string().describe('Natural language description of the task you want to accomplish'),
+            context: z.object({
+                preferredDomain: z.string().optional().describe('Domain preference (e.g., "browser", "network")'),
+                autoActivate: z.boolean().optional().describe('Whether to auto-activate recommended tools (default: true)'),
+                maxRecommendations: z.number().optional().describe('Maximum number of recommendations (default: 5)'),
+            }).optional().describe('Optional context hints for routing'),
+        },
+    }, async (args) => {
+        try {
+            return await handleRouteTool(ctx, args);
+        }
+        catch (error) {
+            logger.error('route_tool failed', error);
+            return asErrorResponse(error);
+        }
+    });
+    ctx.server.registerTool('describe_tool', {
+        description: 'Get detailed information about a specific tool, including its input schema. ' +
+            'Use this to see the exact parameters a tool expects before calling it.',
+        inputSchema: {
+            name: z.string().describe('Tool name to describe'),
+        },
+    }, async (args) => {
+        try {
+            return await handleDescribeTool(ctx, args);
+        }
+        catch (error) {
+            logger.error('describe_tool failed', error);
+            return asErrorResponse(error);
+        }
+    });
+    ctx.server.registerTool('activate_tools', {
+        description: 'Dynamically register specific tools by name, regardless of current base tier. ' +
+            'Use after search_tools to enable exactly the tools you need. ' +
+            'In search-tier sessions this is usually enough; you do not need boost_profile just to use a few exact tools. ' +
+            'Activated tools appear in the tool list immediately.',
+        inputSchema: {
+            names: z.array(z.string()).describe('Array of tool names to activate (from search_tools results)'),
+        },
+    }, async (args) => {
+        try {
+            return await handleActivateTools(ctx, args);
+        }
+        catch (error) {
+            logger.error('activate_tools failed', error);
+            return asErrorResponse(error);
+        }
+    });
+    ctx.server.registerTool('deactivate_tools', {
+        description: 'Remove previously activated tools to free context. ' +
+            'Only affects tools added via activate_tools, not base profile tools.',
+        inputSchema: {
+            names: z.array(z.string()).describe('Array of tool names to deactivate'),
+        },
+    }, async (args) => {
+        try {
+            return await handleDeactivateTools(ctx, args);
+        }
+        catch (error) {
+            logger.error('deactivate_tools failed', error);
+            return asErrorResponse(error);
+        }
+    });
+    ctx.server.registerTool('activate_domain', {
+        description: `Activate all tools in a domain at once. ` +
+            `Domains: ${[...ALL_DOMAINS].join(', ')}. ` +
+            `Use extensions_reload first to include external plugin/workflow domains.`,
+        inputSchema: {
+            domain: z.string().describe('Domain name to activate (e.g. "debugger", "network")'),
+        },
+    }, async (args) => {
+        try {
+            return await handleActivateDomain(ctx, args);
+        }
+        catch (error) {
+            logger.error('activate_domain failed', error);
+            return asErrorResponse(error);
+        }
+    });
+    ctx.server.registerTool('extensions_list', {
+        description: 'List dynamically loaded extensions from plugins/workflows directories. ' +
+            'Shows loaded plugins, extension workflows, extension tools, and active roots.',
+    }, async () => {
+        try {
+            return await handleExtensionsList(ctx);
+        }
+        catch (error) {
+            logger.error('extensions_list failed', error);
+            return asErrorResponse(error);
+        }
+    });
+    ctx.server.registerTool('extensions_reload', {
+        description: 'Reload external extensions from plugins/ and workflows/ (or MCP_PLUGIN_ROOTS/MCP_WORKFLOW_ROOTS). ' +
+            'Dynamically registers extension tools and refreshes tool list.',
+    }, async () => {
+        try {
+            return await handleExtensionsReload(ctx);
+        }
+        catch (error) {
+            logger.error('extensions_reload failed', error);
+            return asErrorResponse(error);
+        }
+    });
+}

package/dist/src/server/MCPServer.search.validation.d.ts

@@ -0,0 +1,4 @@
+export declare function validateToolNameArray(args: Record<string, unknown>): {
+    names: string[];
+    error?: string;
+};

package/dist/src/server/MCPServer.search.validation.js

@@ -0,0 +1,14 @@
+export function validateToolNameArray(args) {
+    const raw = args.names;
+    if (!Array.isArray(raw)) {
+        return { names: [], error: 'names must be an array' };
+    }
+    const names = [];
+    for (const item of raw) {
+        if (typeof item !== 'string' || item.length === 0) {
+            return { names: [], error: 'invalid tool name: expected non-empty string' };
+        }
+        names.push(item);
+    }
+    return { names };
+}

package/dist/src/server/MCPServer.tools.js

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { logger } from '../utils/logger.js';
+import { asErrorResponse, toolErrorToResponse } from './domains/shared/response.js';
+import { ToolError } from '../errors/ToolError.js';
+import { getToolsForProfile } from './ToolCatalog.js';
+import { buildZodShape } from './MCPServer.schema.js';
+function handleToolError(toolName, error) {
+    if (error instanceof ToolError) {
+        return toolErrorToResponse(error);
+    }
+    logger.error(`Tool execution failed: ${toolName}`, error);
+    return asErrorResponse(error);
+}
+export function registerSingleTool(ctx, toolDef) {
+    const shape = buildZodShape(toolDef.inputSchema);
+    const description = toolDef.description ?? toolDef.name;
+    if (Object.keys(shape).length > 0) {
+        return ctx.server.registerTool(toolDef.name, { description, inputSchema: shape }, async (args) => {
+            try {
+                return await ctx.executeToolWithTracking(toolDef.name, args);
+            }
+            catch (error) {
+                return handleToolError(toolDef.name, error);
+            }
+        });
+    }
+    return ctx.server.registerTool(toolDef.name, { description }, async () => {
+        try {
+            return await ctx.executeToolWithTracking(toolDef.name, {});
+        }
+        catch (error) {
+            return handleToolError(toolDef.name, error);
+        }
+    });
+}
+export function registerMetaTools(ctx) {
+    const searchCount = getToolsForProfile('search').length;
+    const workflowCount = getToolsForProfile('workflow').length;
+    const fullCount = getToolsForProfile('full').length;
+    ctx.server.registerTool('boost_profile', {
+        description: 'Optionally upgrade the active tool tier. Three tiers: search → workflow → full. ' +
+            `search: maintenance only (${searchCount} tools) — use search_tools to discover and activate_tools to enable. ` +
+            `workflow: + browser, core analysis, debugger, network, streaming, encoding, graphql, workflows (${workflowCount} tools) and higher ranking for workflow search results. ` +
+            `full: + hooks, process, wasm, antidebug, platform, sourcemap, transform (${fullCount} tools). ` +
+            'Not required after search_tools for single-tool activation, because activate_tools can register exact matches directly across tiers. ' +
+            'Workflow-domain search ranking is configurable via SEARCH_WORKFLOW_BOOST_TIERS / SEARCH_WORKFLOW_DOMAIN_BOOST_MULTIPLIER. ' +
+            'Auto-expires after TTL (default per-tier: workflow=60min, full=30min). Call unboost_profile to downgrade.',
+        inputSchema: {
+            target: z.string().optional().describe('Target tier: "workflow" or "full" (default: next tier up)'),
+            ttlMinutes: z
+                .number()
+                .optional()
+                .describe('Auto-downgrade after N minutes (default: per-tier, set 0 to disable)'),
+        },
+    }, async (args) => {
+        try {
+            const target = args.target ?? undefined;
+            const ttlMinutes = args.ttlMinutes;
+            const result = await ctx.boostProfile(target, ttlMinutes);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('boost_profile failed', error);
+            return asErrorResponse(error);
+        }
+    });
+    ctx.server.registerTool('unboost_profile', {
+        description: 'Downgrade to the previous tool tier (full → workflow → search). ' +
+            'Removes tools added by the last boost. Set target to drop directly to a specific tier.',
+        inputSchema: {
+            target: z
+                .string()
+                .optional()
+                .describe('Drop directly to this tier ("search" or "workflow"). Default: previous tier.'),
+        },
+    }, async (args) => {
+        try {
+            const target = args.target ?? undefined;
+            const result = await ctx.unboostProfile(target);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('unboost_profile failed', error);
+            return asErrorResponse(error);
+        }
+    });
+}

package/dist/src/server/ToolCallContextGuard.js

@@ -0,0 +1,78 @@
+import { logger } from '../utils/logger.js';
+const CONTEXT_SENSITIVE_PREFIXES = [
+    'page_',
+    'console_',
+    'debugger_',
+    'network_',
+    'dom_',
+    'stealth_',
+    'framework_',
+    'indexeddb_',
+    'js_heap_',
+    'script_',
+    'captcha_',
+];
+export class ToolCallContextGuard {
+    getProvider;
+    contextSensitiveCache = new Map();
+    constructor(getProvider) {
+        this.getProvider = getProvider;
+    }
+    isContextSensitive(toolName) {
+        const cached = this.contextSensitiveCache.get(toolName);
+        if (cached !== undefined)
+            return cached;
+        const result = CONTEXT_SENSITIVE_PREFIXES.some((p) => toolName.startsWith(p));
+        this.contextSensitiveCache.set(toolName, result);
+        return result;
+    }
+    enrichResponse(toolName, response) {
+        if (!this.isContextSensitive(toolName))
+            return response;
+        if (response.isError)
+            return response;
+        const provider = this.getProvider();
+        if (!provider)
+            return response;
+        const meta = provider.getContextMeta();
+        if (!meta.pageId && meta.tabIndex === null)
+            return response;
+        const content = response.content;
+        if (!Array.isArray(content))
+            return response;
+        const firstText = content.find((c) => typeof c === 'object' &&
+            c !== null &&
+            c.type === 'text' &&
+            typeof c.text === 'string');
+        if (!firstText)
+            return response;
+        const raw = firstText.text;
+        const trimmedStart = raw.trimStart();
+        if (trimmedStart.startsWith('{') && trimmedStart.trimEnd().endsWith('}')) {
+            try {
+                const parsed = JSON.parse(raw);
+                if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+                    firstText.text = this.spliceTabContext(raw, meta);
+                    return response;
+                }
+            }
+            catch {
+                logger.debug(`[ContextGuard] Skipped non-JSON response enrichment for ${toolName}`);
+                return response;
+            }
+        }
+        return response;
+    }
+    spliceTabContext(raw, meta) {
+        const tabContext = { url: meta.url, title: meta.title, tabIndex: meta.tabIndex, pageId: meta.pageId };
+        if (/\n\}\s*$/.test(raw)) {
+            const prettyJson = JSON.stringify(tabContext, null, 2).replace(/\n/g, '\n  ');
+            return raw.replace(/\n\}\s*$/, `,\n  "_tabContext": ${prettyJson}\n}`);
+        }
+        const compactJson = JSON.stringify(tabContext);
+        if (/^\{\s*\}\s*$/.test(raw)) {
+            return raw.replace(/\{\s*\}\s*$/, `{"_tabContext":${compactJson}}`);
+        }
+        return raw.replace(/\}\s*$/, `,"_tabContext":${compactJson}}`);
+    }
+}

package/dist/src/server/ToolCatalog.d.ts

@@ -0,0 +1,15 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolProfileId } from './registry/contracts.js';
+export type ToolDomain = string;
+export type ToolProfile = ToolProfileId;
+export declare const allTools: Tool[];
+export declare const TIER_ORDER: readonly ToolProfile[];
+export declare const TIER_DEFAULT_TTL: Readonly<Record<ToolProfile, number>>;
+export declare function getTierIndex(profile: ToolProfile): number;
+export declare function parseToolDomains(raw: string | undefined): string[] | null;
+export declare function getToolsByDomains(domains: string[]): Tool[];
+export declare function getToolsForProfile(profile: ToolProfile): Tool[];
+export declare function getToolDomain(toolName: string): string | null;
+export declare function getProfileDomains(profile: ToolProfile): string[];
+export declare function getToolMinimalTier(toolName: string): ToolProfile | null;
+export declare function getMinSatisfyingTier(toolNames: string[]): ToolProfile | null;

package/dist/src/server/ToolCatalog.js

@@ -0,0 +1,100 @@
+import { buildToolGroups, buildToolDomainMap, buildAllTools, buildProfileDomains, ALL_DOMAINS, } from './registry/index.js';
+let _toolGroups = null;
+let _toolDomainByName = null;
+let _profileDomains = null;
+let _allTools = null;
+function getToolGroups() {
+    if (!_toolGroups)
+        _toolGroups = buildToolGroups();
+    return _toolGroups;
+}
+function getToolDomainByName() {
+    if (!_toolDomainByName)
+        _toolDomainByName = buildToolDomainMap();
+    return _toolDomainByName;
+}
+function getProfileDomainsMap() {
+    if (!_profileDomains)
+        _profileDomains = buildProfileDomains();
+    return _profileDomains;
+}
+export const allTools = new Proxy([], {
+    get(_t, p) {
+        if (!_allTools)
+            _allTools = buildAllTools();
+        const real = _allTools;
+        const v = real[p];
+        return typeof v === 'function' ? v.bind(real) : v;
+    },
+});
+export const TIER_ORDER = ['search', 'workflow', 'full'];
+export const TIER_DEFAULT_TTL = {
+    search: 0,
+    workflow: 60,
+    full: 30,
+};
+export function getTierIndex(profile) {
+    return TIER_ORDER.indexOf(profile);
+}
+function dedupeTools(tools) {
+    const map = new Map();
+    for (const tool of tools) {
+        map.set(tool.name, tool);
+    }
+    return Array.from(map.values());
+}
+export function parseToolDomains(raw) {
+    if (!raw?.trim()) {
+        return null;
+    }
+    const validDomains = ALL_DOMAINS;
+    const parsed = raw
+        .split(',')
+        .map((item) => item.trim().toLowerCase())
+        .filter(Boolean)
+        .filter((item) => validDomains.has(item));
+    return parsed.length > 0 ? (Array.from(new Set(parsed))) : null;
+}
+export function getToolsByDomains(domains) {
+    const tools = domains.flatMap((domain) => getToolGroups()[domain] ?? []);
+    return dedupeTools(tools);
+}
+export function getToolsForProfile(profile) {
+    const domains = getProfileDomainsMap()[profile];
+    if (!domains)
+        return [];
+    return getToolsByDomains(domains);
+}
+export function getToolDomain(toolName) {
+    return getToolDomainByName().get(toolName) ?? null;
+}
+export function getProfileDomains(profile) {
+    return getProfileDomainsMap()[profile] ?? [];
+}
+export function getToolMinimalTier(toolName) {
+    const domain = getToolDomain(toolName);
+    if (!domain)
+        return null;
+    for (const tier of TIER_ORDER) {
+        const domains = getProfileDomains(tier);
+        if (domains.includes(domain)) {
+            return tier;
+        }
+    }
+    return null;
+}
+export function getMinSatisfyingTier(toolNames) {
+    if (toolNames.length === 0)
+        return null;
+    let maxTierIndex = -1;
+    for (const name of toolNames) {
+        const tier = getToolMinimalTier(name);
+        if (!tier)
+            continue;
+        const idx = getTierIndex(tier);
+        if (idx > maxTierIndex) {
+            maxTierIndex = idx;
+        }
+    }
+    return maxTierIndex >= 0 ? TIER_ORDER[maxTierIndex] : null;
+}

package/dist/src/server/ToolRouter.d.ts

@@ -0,0 +1,38 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { MCPServerContext } from './MCPServer.context.js';
+import { ToolSearchEngine } from './ToolSearch.js';
+export interface RouterRequest {
+    task: string;
+    context?: {
+        preferredDomain?: string;
+        autoActivate?: boolean;
+        maxRecommendations?: number;
+    };
+}
+export interface RouterResponse {
+    recommendations: Array<{
+        name: string;
+        domain: string | null;
+        description: string;
+        inputSchema: Tool['inputSchema'];
+        score: number;
+        isActive: boolean;
+        activationCommand?: string;
+    }>;
+    nextActions: Array<{
+        step: number;
+        action: 'activate' | 'call';
+        toolName?: string;
+        command: string;
+        exampleArgs?: Record<string, unknown>;
+        description: string;
+    }>;
+    workflowHint?: string;
+    autoActivated?: boolean;
+}
+export declare function routeToolRequest(request: RouterRequest, ctx: MCPServerContext, searchEngine: ToolSearchEngine): Promise<RouterResponse>;
+export declare function describeTool(toolName: string, ctx: MCPServerContext): {
+    name: string;
+    description: string;
+    inputSchema: Tool['inputSchema'];
+} | null;