@jshookmcp/jshook 0.2.3 → 0.2.5

package/README.md

@@ -1,14 +1,14 @@
 # @jshookmcp/jshook
 
 [![License: AGPLv3](https://img.shields.io/badge/License-AGPLv3-red.svg)](LICENSE)
-[![Node.js >= 22](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
+[![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg)](https://www.typescriptlang.org/)
 [![MCP](https://img.shields.io/badge/MCP-current-8A2BE2.svg)](https://modelcontextprotocol.io/)
 [![pnpm](https://img.shields.io/badge/pnpm-10.x-F69220.svg)](https://pnpm.io/)
 
 English | [中文](./README.zh.md)
 
-An MCP (Model Context Protocol) server providing **290+ built-in tools** across **17+ domains** (including core meta-tools) — with runtime extension loading from `plugins/` and `workflows/` for AI-assisted JavaScript analysis and security analysis. Combines browser automation, Chrome DevTools Protocol debugging, network monitoring, intelligent JavaScript hooks, LLM-powered code analysis, process/memory inspection, WASM toolchain, binary encoding, anti-anti-debug, GraphQL discovery, source map reconstruction, AST transforms, crypto reconstruction, platform package analysis, Burp Suite / native analysis tool bridges, human behavior simulation, CAPTCHA solving, batch account workflows, and high-level composite workflow orchestration in a single server.
+An MCP (Model Context Protocol) server with a runtime-registry-driven catalog of built-in tools for AI-assisted JavaScript analysis and security analysis. It combines browser automation, Chrome DevTools Protocol debugging, network monitoring, intelligent JavaScript hooks, LLM-powered code analysis, process and memory inspection, WASM tooling, source-map reconstruction, AST transforms, and composite workflows in a single server.
 
 ## Documentation / Quick Links
 
@@ -42,11 +42,20 @@ Provides a comprehensive suite of tools for AI-assisted JavaScript analysis, bro
 - **Lazy Domain Initialization**: Handler classes instantiated via Proxy on first invocation, not during startup
 - **Domain Self-Discovery**: Runtime manifest scanning (`domains/*/manifest.ts`) replaces hardcoded imports; add new domains by creating a single manifest file
 - **B-Skeleton Contracts**: Extensibility contracts for plugins (`PluginContract`), workflows (`WorkflowContract`), and observability (`InstrumentationContract`)
-- **Context Efficiency Benchmark**: Built-in tool-schema init delta (Claude server-side count): `search` ≈ 3,000 tokens vs `full` ≈ 40,000+ tokens (10+ vs 290+ built-in tools; values change as tools/descriptions evolve)
+- **MCP ToolAnnotations**: Every tool carries semantic annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) enabling AI orchestrators to reason about tool safety and side-effects before invocation
+- **Context Efficiency Benchmark**: Built-in tool-schema init delta (Claude server-side count): `search` ≈ 3K tokens vs `full` ≈ 40K+ tokens; values change as tools/descriptions evolve
 
-## Tool Domains
+## Registry Snapshot
 
-The server provides **290+ built-in tools** across **17+ domains** (`antidebug`, `browser`, `coordination`, `core`, `debugger`, `encoding`, `graphql`, `hooks`, `maintenance`, `network`, `platform`, `process`, `sourcemap`, `streaming`, `transform`, `wasm`, and `workflow`).
+The built-in surface below is generated from the runtime registry and checked in CI.
+
+<!-- metadata-sync:start -->
+- Package version: `0.2.5`
+- Built-in domains: `23`
+- Built-in tools: `327`
+- Domains: `antidebug`, `browser`, `coordination`, `core`, `debugger`, `encoding`, `evidence`, `graphql`, `hooks`, `instrumentation`, `macro`, `maintenance`, `memory`, `network`, `platform`, `process`, `sandbox`, `sourcemap`, `streaming`, `trace`, `transform`, `wasm`, `workflow`
+- Note: this snapshot is generated from the runtime registry; do not edit the counts by hand.
+<!-- metadata-sync:end -->
 
 > **[View the complete Tool Reference ↗](https://vmoranv.github.io/jshookmcp/reference/)**
 

package/README.zh.md

@@ -1,14 +1,14 @@
 # @jshookmcp/jshook
 
 [![License: AGPLv3](https://img.shields.io/badge/License-AGPLv3-red.svg)](LICENSE)
-[![Node.js >= 22](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
+[![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg)](https://www.typescriptlang.org/)
 [![MCP](https://img.shields.io/badge/MCP-current-8A2BE2.svg)](https://modelcontextprotocol.io/)
 [![pnpm](https://img.shields.io/badge/pnpm-10.x-F69220.svg)](https://pnpm.io/)
 
 [English](./README.md) | 中文
 
-面向 AI 辅助 JavaScript 分析与安全分析的 MCP（模型上下文协议）服务器，提供 **290+ 个内置工具**——跨越 **17+ 个工具域**（包含核心元工具）——并支持从 `plugins/` 与 `workflows/` 目录运行时动态扩展。集成浏览器自动化、Chrome DevTools Protocol 调试、网络监控、智能 JavaScript Hook、LLM 驱动代码分析、进程/内存操作、WASM 工具链、二进制编码、反反调试、GraphQL 发现、Source Map 重建、AST 变换、加密重构、平台包分析、Burp Suite / Native 分析工具桥接及高层复合工作流编排。
+面向 AI 辅助 JavaScript 分析与安全分析的 MCP（模型上下文协议）服务器，内置工具面来自运行时 registry，而不是手写清单。它将浏览器自动化、Chrome DevTools Protocol 调试、网络监控、JavaScript Hook、LLM 驱动代码分析、进程与内存检查、WASM 工具链、Source Map 重建、AST 变换与复合工作流整合到同一服务中。
 
 ## 文档与快速导航
 
@@ -42,7 +42,22 @@
 - **域延迟初始化**：处理器类通过 Proxy 在首次调用时实例化，而非启动时预加载
 - **域自发现架构**：运行时扫描 `domains/*/manifest.ts` 替代硬编码导入；新增域只需创建一个 manifest 文件
 - **B-Skeleton 契约**：插件（`PluginContract`）、工作流（`WorkflowContract`）、可观测性（`InstrumentationContract`）的扩展性契约
-- **上下文效率基准**：基于 Claude 服务端对当前内置工具 schema 的实测计数，`search` 档 ≈ 3,000 tokens，`full` 档 ≈ 40,000+ tokens（当前分别为 10+ 与 290+ 个 built-in tools；数值会随工具与描述变更而变化）
+- **MCP ToolAnnotations**：每个工具均带有语义标注（`readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`），使 AI 协调器能在调用前推理工具安全性与副作用
+- **上下文效率基准**：基于 Claude 服务端实测，`search` 档 ≈ 3K tokens，`full` 档 ≈ 40K+ tokens；数值会随工具与描述变更而变化
+
+## 注册表快照
+
+下面的内置能力快照由运行时 registry 动态生成，并在 CI 中校验。
+
+<!-- metadata-sync:start -->
+- 包版本：`0.2.5`
+- 内置工具域：`23`
+- 内置工具数：`327`
+- 域列表：`antidebug`, `browser`, `coordination`, `core`, `debugger`, `encoding`, `evidence`, `graphql`, `hooks`, `instrumentation`, `macro`, `maintenance`, `memory`, `network`, `platform`, `process`, `sandbox`, `sourcemap`, `streaming`, `trace`, `transform`, `wasm`, `workflow`
+- 说明：以上数据由运行时 registry 动态生成，不要手改计数。
+<!-- metadata-sync:end -->
+
+> **[查看完整工具参考 ↗](https://vmoranv.github.io/jshookmcp/reference/)**
 
 ## 项目统计
 

package/dist/packages/extension-sdk/src/bridges/shared.js

@@ -52,7 +52,7 @@ export async function checkExternalCommand(command, versionArgs, label, installH
         const { stdout, stderr } = await execFileAsync(command, versionArgs, {
             timeout: 10_000,
         });
-        const version = (stdout || stderr).trim().split('\n')[0] ?? '';
+        const version = (stdout || stderr).trim().split('\n')[0];
         return toTextResponse({
             success: true,
             tool: label,
@@ -179,7 +179,7 @@ export async function requestJson(url, method = 'GET', bodyObj, timeoutMs = 15_0
             Accept: 'application/json',
             ...(body ? { 'Content-Type': 'application/json' } : {}),
         },
-        body,
+        ...(body === undefined ? {} : { body }),
         signal: AbortSignal.timeout(timeoutMs),
     });
     const text = await response.text();

package/dist/packages/extension-sdk/src/plugin.d.ts

@@ -1,4 +1,5 @@
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { WorkflowContract } from './workflow.js';
 export type ToolProfileId = 'search' | 'workflow' | 'full';
 export type ToolArgs = Record<string, unknown>;
 export type ToolResponse = CallToolResult;
@@ -23,6 +24,7 @@ export interface ExtensionToolDefinition {
     handler: ExtensionToolHandler;
     profiles?: ToolProfileId[];
 }
+export type ExtensionWorkflowDefinition = WorkflowContract;
 export declare const jsonResponse: (payload: Record<string, unknown>) => ToolResponse;
 export declare const errorResponse: (tool: string, error: unknown, extra?: Record<string, unknown>) => ToolResponse;
 export declare class ExtensionBuilder {
@@ -35,6 +37,7 @@ export declare class ExtensionBuilder {
     private _compatibleCore;
     private _profiles;
     private _tools;
+    private _workflows;
     private _allowCommands;
     private _allowHosts;
     private _allowTools;
@@ -54,6 +57,7 @@ export declare class ExtensionBuilder {
     get compatibleCoreRange(): string;
     get profiles(): ToolProfileId[];
     get tools(): ExtensionToolDefinition[];
+    get workflows(): ExtensionWorkflowDefinition[];
     get allowedCommands(): string[];
     get allowedHosts(): string[];
     get allowedTools(): string[];
@@ -87,6 +91,7 @@ export declare class ExtensionBuilder {
     metric(m: string | string[]): this;
     configDefault(key: string, value: unknown): this;
     tool(name: string, desc: string, schema: Record<string, unknown>, handler: ExtensionToolHandler, profiles?: ToolProfileId[]): this;
+    workflow(workflow: ExtensionWorkflowDefinition | ExtensionWorkflowDefinition[]): this;
     onLoad(h: (ctx: PluginLifecycleContext) => Promise<void> | void): this;
     onValidate(h: (ctx: PluginLifecycleContext) => Promise<{
         valid: boolean;

package/dist/packages/extension-sdk/src/plugin.js

@@ -1,4 +1,4 @@
-import { toTextResponse, toErrorResponse, } from './bridges/shared.js';
+import { toTextResponse, toErrorResponse } from './bridges/shared.js';
 export const jsonResponse = toTextResponse;
 export const errorResponse = toErrorResponse;
 export class ExtensionBuilder {
@@ -11,6 +11,7 @@ export class ExtensionBuilder {
     _compatibleCore = '>=0.1.0';
     _profiles = ['full'];
     _tools = [];
+    _workflows = [];
     _allowCommands = [];
     _allowHosts = [];
     _allowTools = [];
@@ -24,29 +25,83 @@ export class ExtensionBuilder {
         this._id = id;
         this._version = version;
     }
-    get id() { return this._id; }
-    get version() { return this._version; }
-    get pluginName() { return this._name; }
-    get pluginDescription() { return this._description; }
-    get pluginAuthor() { return this._author; }
-    get pluginSourceRepo() { return this._sourceRepo; }
-    get compatibleCoreRange() { return this._compatibleCore; }
-    get profiles() { return this._profiles; }
-    get tools() { return this._tools; }
-    get allowedCommands() { return this._allowCommands; }
-    get allowedHosts() { return this._allowHosts; }
-    get allowedTools() { return this._allowTools; }
-    get declaredMetrics() { return this._metrics; }
-    get configDefaults() { return this._configDefaults; }
-    get onLoadHandler() { return this._onLoadHandler; }
-    get onValidateHandler() { return this._onValidateHandler; }
-    get onActivateHandler() { return this._onActivateHandler; }
-    get onDeactivateHandler() { return this._onDeactivateHandler; }
-    name(n) { this._name = n; return this; }
-    description(desc) { this._description = desc; return this; }
-    author(a) { this._author = a; return this; }
-    sourceRepo(url) { this._sourceRepo = url; return this; }
-    compatibleCore(range) { this._compatibleCore = range; return this; }
+    get id() {
+        return this._id;
+    }
+    get version() {
+        return this._version;
+    }
+    get pluginName() {
+        return this._name;
+    }
+    get pluginDescription() {
+        return this._description;
+    }
+    get pluginAuthor() {
+        return this._author;
+    }
+    get pluginSourceRepo() {
+        return this._sourceRepo;
+    }
+    get compatibleCoreRange() {
+        return this._compatibleCore;
+    }
+    get profiles() {
+        return this._profiles;
+    }
+    get tools() {
+        return this._tools;
+    }
+    get workflows() {
+        return this._workflows;
+    }
+    get allowedCommands() {
+        return this._allowCommands;
+    }
+    get allowedHosts() {
+        return this._allowHosts;
+    }
+    get allowedTools() {
+        return this._allowTools;
+    }
+    get declaredMetrics() {
+        return this._metrics;
+    }
+    get configDefaults() {
+        return this._configDefaults;
+    }
+    get onLoadHandler() {
+        return this._onLoadHandler;
+    }
+    get onValidateHandler() {
+        return this._onValidateHandler;
+    }
+    get onActivateHandler() {
+        return this._onActivateHandler;
+    }
+    get onDeactivateHandler() {
+        return this._onDeactivateHandler;
+    }
+    name(n) {
+        this._name = n;
+        return this;
+    }
+    description(desc) {
+        this._description = desc;
+        return this;
+    }
+    author(a) {
+        this._author = a;
+        return this;
+    }
+    sourceRepo(url) {
+        this._sourceRepo = url;
+        return this;
+    }
+    compatibleCore(range) {
+        this._compatibleCore = range;
+        return this;
+    }
     mergeMetadata(meta) {
         if (!this._name && meta.name)
             this._name = meta.name;
@@ -62,11 +117,26 @@ export class ExtensionBuilder {
         this._profiles = Array.isArray(p) ? p : [p];
         return this;
     }
-    allowCommand(cmd) { this._allowCommands.push(...(Array.isArray(cmd) ? cmd : [cmd])); return this; }
-    allowHost(host) { this._allowHosts.push(...(Array.isArray(host) ? host : [host])); return this; }
-    allowTool(tool) { this._allowTools.push(...(Array.isArray(tool) ? tool : [tool])); return this; }
-    metric(m) { this._metrics.push(...(Array.isArray(m) ? m : [m])); return this; }
-    configDefault(key, value) { this._configDefaults[key] = value; return this; }
+    allowCommand(cmd) {
+        this._allowCommands.push(...(Array.isArray(cmd) ? cmd : [cmd]));
+        return this;
+    }
+    allowHost(host) {
+        this._allowHosts.push(...(Array.isArray(host) ? host : [host]));
+        return this;
+    }
+    allowTool(tool) {
+        this._allowTools.push(...(Array.isArray(tool) ? tool : [tool]));
+        return this;
+    }
+    metric(m) {
+        this._metrics.push(...(Array.isArray(m) ? m : [m]));
+        return this;
+    }
+    configDefault(key, value) {
+        this._configDefaults[key] = value;
+        return this;
+    }
     tool(name, desc, schema, handler, profiles) {
         this._tools.push({
             name,
@@ -77,10 +147,26 @@ export class ExtensionBuilder {
         });
         return this;
     }
-    onLoad(h) { this._onLoadHandler = h; return this; }
-    onValidate(h) { this._onValidateHandler = h; return this; }
-    onActivate(h) { this._onActivateHandler = h; return this; }
-    onDeactivate(h) { this._onDeactivateHandler = h; return this; }
+    workflow(workflow) {
+        this._workflows.push(...(Array.isArray(workflow) ? workflow : [workflow]));
+        return this;
+    }
+    onLoad(h) {
+        this._onLoadHandler = h;
+        return this;
+    }
+    onValidate(h) {
+        this._onValidateHandler = h;
+        return this;
+    }
+    onActivate(h) {
+        this._onActivateHandler = h;
+        return this;
+    }
+    onDeactivate(h) {
+        this._onDeactivateHandler = h;
+        return this;
+    }
 }
 export function createExtension(id, version) {
     return new ExtensionBuilder(id, version);

package/dist/packages/extension-sdk/src/workflow.d.ts

@@ -0,0 +1,156 @@
+export interface RetryPolicy {
+    maxAttempts: number;
+    backoffMs: number;
+    multiplier?: number;
+}
+export type WorkflowNodeType = 'tool' | 'sequence' | 'parallel' | 'branch';
+export interface ToolNode {
+    readonly kind: 'tool';
+    readonly id: string;
+    readonly toolName: string;
+    readonly input?: Record<string, unknown>;
+    readonly timeoutMs?: number;
+    readonly retry?: RetryPolicy;
+}
+export interface SequenceNode {
+    readonly kind: 'sequence';
+    readonly id: string;
+    readonly steps: WorkflowNode[];
+}
+export interface ParallelNode {
+    readonly kind: 'parallel';
+    readonly id: string;
+    readonly steps: WorkflowNode[];
+    readonly maxConcurrency?: number;
+    readonly failFast?: boolean;
+}
+export interface BranchNode {
+    readonly kind: 'branch';
+    readonly id: string;
+    readonly predicateId: string;
+    readonly predicateFn?: (ctx: WorkflowExecutionContext) => boolean | Promise<boolean>;
+    readonly whenTrue: WorkflowNode;
+    readonly whenFalse?: WorkflowNode;
+}
+export type WorkflowNode = ToolNode | SequenceNode | ParallelNode | BranchNode;
+export interface ToolNodeOptions {
+    input?: Record<string, unknown>;
+    retry?: RetryPolicy;
+    timeoutMs?: number;
+}
+export interface WorkflowExecutionContext {
+    readonly workflowRunId: string;
+    readonly profile: string;
+    invokeTool(toolName: string, args: Record<string, unknown>): Promise<unknown>;
+    emitSpan(name: string, attrs?: Record<string, unknown>): void;
+    emitMetric(name: string, value: number, type: 'counter' | 'gauge' | 'histogram', attrs?: Record<string, unknown>): void;
+    getConfig<T = unknown>(path: string, fallback?: T): T;
+}
+export interface WorkflowRouteStep {
+    readonly id: string;
+    readonly toolName: string;
+    readonly description: string;
+    readonly prerequisites: string[];
+    readonly parallel?: boolean;
+    readonly expectedInputs?: Record<string, string>;
+    readonly evidenceNodeType?: string;
+}
+export type WorkflowRouteKind = 'preset' | 'workflow';
+export interface WorkflowRouteMetadata {
+    readonly kind: WorkflowRouteKind;
+    readonly triggerPatterns: RegExp[];
+    readonly steps: WorkflowRouteStep[];
+    readonly requiredDomains: string[];
+    readonly priority: number;
+}
+export interface WorkflowContract {
+    readonly kind: 'workflow-contract';
+    readonly version: 1;
+    readonly id: string;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly tags?: string[];
+    readonly timeoutMs?: number;
+    readonly defaultMaxConcurrency?: number;
+    readonly route?: WorkflowRouteMetadata;
+    build(ctx: WorkflowExecutionContext): WorkflowNode;
+    onStart?(ctx: WorkflowExecutionContext): Promise<void> | void;
+    onFinish?(ctx: WorkflowExecutionContext, result: unknown): Promise<void> | void;
+    onError?(ctx: WorkflowExecutionContext, error: Error): Promise<void> | void;
+}
+export declare abstract class WorkflowNodeBuilder<T extends WorkflowNode> {
+    protected id: string;
+    constructor(id: string);
+    abstract build(): T;
+}
+type AnyWorkflowNodeBuilder = WorkflowNodeBuilder<WorkflowNode>;
+export declare class ToolNodeBuilder extends WorkflowNodeBuilder<ToolNode> {
+    private toolName;
+    private _input?;
+    private _retry?;
+    private _timeoutMs?;
+    constructor(id: string, toolName: string);
+    input(input: Record<string, unknown>): this;
+    retry(policy: RetryPolicy): this;
+    timeout(ms: number): this;
+    build(): ToolNode;
+}
+declare abstract class CompositeNodeBuilder<T extends WorkflowNode> extends WorkflowNodeBuilder<T> {
+    protected _steps: AnyWorkflowNodeBuilder[];
+    step(nodeBuilder: AnyWorkflowNodeBuilder): this;
+    tool(id: string, toolName: string, config?: ToolNodeOptions | ((b: ToolNodeBuilder) => void)): this;
+    sequence(id: string, config?: (b: SequenceNodeBuilder) => void): this;
+    parallel(id: string, config?: (b: ParallelNodeBuilder) => void): this;
+    branch(id: string, predicateId: string, config?: (b: BranchNodeBuilder) => void): this;
+}
+export declare class SequenceNodeBuilder extends CompositeNodeBuilder<SequenceNode> {
+    build(): SequenceNode;
+}
+export declare class ParallelNodeBuilder extends CompositeNodeBuilder<ParallelNode> {
+    private _maxConcurrency?;
+    private _failFast?;
+    maxConcurrency(concurrency: number): this;
+    failFast(ff: boolean): this;
+    build(): ParallelNode;
+}
+export declare class BranchNodeBuilder extends WorkflowNodeBuilder<BranchNode> {
+    private predicateId;
+    private _predicateFn?;
+    private _whenTrue?;
+    private _whenFalse?;
+    constructor(id: string, predicateId: string);
+    predicateFn(fn: (ctx: WorkflowExecutionContext) => boolean | Promise<boolean>): this;
+    whenTrue(nodeBuilder: AnyWorkflowNodeBuilder): this;
+    whenFalse(nodeBuilder: AnyWorkflowNodeBuilder): this;
+    build(): BranchNode;
+}
+export declare class WorkflowBuilder {
+    private _id;
+    private _displayName;
+    private _description?;
+    private _tags?;
+    private _timeoutMs?;
+    private _defaultMaxConcurrency?;
+    private _route?;
+    private _buildFn;
+    private _onStart?;
+    private _onFinish?;
+    private _onError?;
+    constructor(id: string, displayName: string);
+    description(desc: string): this;
+    tags(tags: string[]): this;
+    timeoutMs(timeout: number): this;
+    defaultMaxConcurrency(max: number): this;
+    route(route: WorkflowRouteMetadata): this;
+    buildGraph(fn: (ctx: WorkflowExecutionContext) => AnyWorkflowNodeBuilder): this;
+    onStart(fn: (ctx: WorkflowExecutionContext) => Promise<void> | void): this;
+    onFinish(fn: (ctx: WorkflowExecutionContext, result: unknown) => Promise<void> | void): this;
+    onError(fn: (ctx: WorkflowExecutionContext, error: Error) => Promise<void> | void): this;
+    build(): WorkflowContract;
+}
+export declare function createWorkflow(id: string, displayName: string): WorkflowBuilder;
+export declare function toolNode(id: string, toolName: string): ToolNodeBuilder;
+export declare function sequenceNode(id: string): SequenceNodeBuilder;
+export declare function parallelNode(id: string): ParallelNodeBuilder;
+export declare function branchNode(id: string, predicateId: string): BranchNodeBuilder;
+export {};