research-powerpack-mcp 3.3.2 → 3.4.0

package/dist/tools/registry.js

@@ -0,0 +1,238 @@
+/**
+ * Handler Registry - Central tool registration and execution
+ * Eliminates repetitive if/else routing with declarative registration
+ */
+import { z, ZodError } from 'zod';
+import { McpError, ErrorCode as McpErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { parseEnv, getCapabilities, getMissingEnvMessage } from '../config/index.js';
+import { classifyError, createToolErrorFromStructured } from '../utils/errors.js';
+// Import schemas
+import { deepResearchParamsSchema } from '../schemas/deep-research.js';
+import { scrapeLinksParamsSchema } from '../schemas/scrape-links.js';
+import { webSearchParamsSchema } from '../schemas/web-search.js';
+// Import handlers
+import { handleSearchReddit, handleGetRedditPosts } from './reddit.js';
+import { handleDeepResearch } from './research.js';
+import { handleScrapeLinks } from './scrape.js';
+import { handleWebSearch } from './search.js';
+// ============================================================================
+// Schemas for Simple Tools (inline definitions)
+// ============================================================================
+const searchRedditParamsSchema = z.object({
+    queries: z.array(z.string()).min(10).max(50),
+    date_after: z.string().optional(),
+});
+const getRedditPostParamsSchema = z.object({
+    urls: z.array(z.string()).min(2).max(50),
+    fetch_comments: z.boolean().default(true),
+    max_comments: z.number().default(100),
+});
+// ============================================================================
+// Handler Wrappers
+// ============================================================================
+const env = parseEnv();
+/**
+ * Wrapper for search_reddit handler
+ */
+async function searchRedditHandler(params) {
+    const p = params;
+    return handleSearchReddit(p.queries, env.SEARCH_API_KEY, p.date_after);
+}
+/**
+ * Wrapper for get_reddit_post handler
+ */
+async function getRedditPostHandler(params) {
+    const p = params;
+    return handleGetRedditPosts(p.urls, env.REDDIT_CLIENT_ID, env.REDDIT_CLIENT_SECRET, p.max_comments, {
+        fetchComments: p.fetch_comments,
+        maxCommentsOverride: p.max_comments !== 100 ? p.max_comments : undefined,
+    });
+}
+/**
+ * Wrapper for deep_research handler
+ */
+async function deepResearchHandler(params) {
+    const { content } = await handleDeepResearch(params);
+    return content;
+}
+/**
+ * Wrapper for scrape_links handler
+ */
+async function scrapeLinksHandler(params) {
+    const { content } = await handleScrapeLinks(params);
+    return content;
+}
+/**
+ * Wrapper for web_search handler
+ */
+async function webSearchHandler(params) {
+    const { content } = await handleWebSearch(params);
+    return content;
+}
+// ============================================================================
+// Tool Registry
+// ============================================================================
+/**
+ * Central registry of all MCP tools
+ */
+export const toolRegistry = {
+    search_reddit: {
+        name: 'search_reddit',
+        capability: 'search',
+        schema: searchRedditParamsSchema,
+        handler: searchRedditHandler,
+    },
+    get_reddit_post: {
+        name: 'get_reddit_post',
+        capability: 'reddit',
+        schema: getRedditPostParamsSchema,
+        handler: getRedditPostHandler,
+    },
+    deep_research: {
+        name: 'deep_research',
+        capability: 'deepResearch',
+        schema: deepResearchParamsSchema,
+        handler: deepResearchHandler,
+        transformResponse: (result) => ({
+            content: result,
+            isError: result.includes('# ❌ Error'),
+        }),
+    },
+    scrape_links: {
+        name: 'scrape_links',
+        capability: 'scraping',
+        schema: scrapeLinksParamsSchema,
+        handler: scrapeLinksHandler,
+        transformResponse: (result) => ({
+            content: result,
+            isError: result.includes('# ❌ Scraping Failed'),
+        }),
+    },
+    web_search: {
+        name: 'web_search',
+        capability: 'search',
+        schema: webSearchParamsSchema,
+        handler: webSearchHandler,
+        transformResponse: (result) => ({
+            content: result,
+            isError: result.includes('# ❌ web_search'),
+        }),
+    },
+};
+// ============================================================================
+// Execute Tool (Main Entry Point)
+// ============================================================================
+/**
+ * Execute a tool by name with full middleware chain
+ *
+ * Middleware steps:
+ * 1. Lookup tool in registry (throw McpError if not found)
+ * 2. Check capability (return error response if missing)
+ * 3. Validate params with Zod (return error response if invalid)
+ * 4. Execute handler (catch and format any errors)
+ * 5. Transform response if needed
+ *
+ * @param name - Tool name from request
+ * @param args - Raw arguments from request
+ * @param capabilities - Current capabilities from getCapabilities()
+ * @returns MCP-compliant tool result
+ */
+export async function executeTool(name, args, capabilities) {
+    // Step 1: Lookup tool
+    const tool = toolRegistry[name];
+    if (!tool) {
+        throw new McpError(McpErrorCode.MethodNotFound, `Method not found: ${name}. Available tools: ${Object.keys(toolRegistry).join(', ')}`);
+    }
+    // Step 2: Check capability
+    if (tool.capability && !capabilities[tool.capability]) {
+        return {
+            content: [{ type: 'text', text: getMissingEnvMessage(tool.capability) }],
+            isError: true,
+        };
+    }
+    // Step 3: Validate params with Zod
+    let validatedParams;
+    try {
+        validatedParams = tool.schema.parse(args);
+    }
+    catch (error) {
+        if (error instanceof ZodError) {
+            const issues = error.issues
+                .map((i) => `- **${i.path.join('.') || 'root'}**: ${i.message}`)
+                .join('\n');
+            return {
+                content: [{ type: 'text', text: `# ❌ Validation Error\n\n${issues}` }],
+                isError: true,
+            };
+        }
+        // Non-Zod validation error
+        const structured = classifyError(error);
+        return createToolErrorFromStructured(structured);
+    }
+    // Step 3.5: Optional post-validation
+    if (tool.postValidate) {
+        const postError = tool.postValidate(validatedParams);
+        if (postError) {
+            return {
+                content: [{ type: 'text', text: `# ❌ Validation Error\n\n${postError}` }],
+                isError: true,
+            };
+        }
+    }
+    // Step 4: Execute handler
+    let result;
+    try {
+        result = await tool.handler(validatedParams);
+    }
+    catch (error) {
+        // Handler threw (shouldn't happen if handlers follow "never throw" pattern)
+        const structured = classifyError(error);
+        return createToolErrorFromStructured(structured);
+    }
+    // Step 5: Transform response
+    if (tool.transformResponse) {
+        const transformed = tool.transformResponse(result);
+        return {
+            content: [{ type: 'text', text: transformed.content }],
+            isError: transformed.isError,
+        };
+    }
+    // Default: success response
+    return {
+        content: [{ type: 'text', text: result }],
+    };
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Get list of all registered tool names
+ */
+export function getRegisteredToolNames() {
+    return Object.keys(toolRegistry);
+}
+/**
+ * Check if a tool is registered
+ */
+export function isToolRegistered(name) {
+    return name in toolRegistry;
+}
+/**
+ * Get tool capabilities for logging
+ */
+export function getToolCapabilities() {
+    const caps = getCapabilities();
+    const enabled = [];
+    const disabled = [];
+    for (const [name, tool] of Object.entries(toolRegistry)) {
+        const capKey = tool.capability;
+        if (!capKey || caps[capKey]) {
+            enabled.push(name);
+        }
+        else {
+            disabled.push(name);
+        }
+    }
+    return { enabled, disabled };
+}
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"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"}

package/dist/tools/utils.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared Tool Utilities
+ * Extracted from individual handlers to eliminate duplication
+ */
+/**
+ * Logger function type used by tools
+ */
+export type ToolLogger = (level: 'info' | 'error' | 'debug', message: string, sessionId: string) => Promise<void>;
+/**
+ * Standard tool options passed to handlers
+ */
+export interface ToolOptions {
+    sessionId?: string;
+    logger?: ToolLogger;
+}
+/**
+ * Safe logger wrapper - NEVER throws
+ * Logs to provided logger or falls back to console.error
+ *
+ * @param logger - Optional logger function
+ * @param sessionId - Session ID for logging context
+ * @param level - Log level
+ * @param message - Message to log
+ * @param toolName - Name of the tool for prefixing
+ */
+export declare function safeLog(logger: ToolLogger | undefined, sessionId: string | undefined, level: 'info' | 'error' | 'debug', message: string, toolName: string): Promise<void>;
+/**
+ * Calculate token allocation for batch operations
+ * Distributes a fixed budget across multiple items
+ *
+ * @param count - Number of items to distribute budget across
+ * @param budget - Total token budget
+ * @returns Tokens per item
+ */
+export declare function calculateTokenAllocation(count: number, budget: number): number;
+/**
+ * Format retry hint based on error retryability
+ *
+ * @param retryable - Whether the error is retryable
+ * @returns Hint string or empty string
+ */
+export declare function formatRetryHint(retryable: boolean): string;
+/**
+ * Create a standard error markdown response
+ *
+ * @param toolName - Name of the tool that errored
+ * @param errorCode - Error code
+ * @param message - Error message
+ * @param retryable - Whether error is retryable
+ * @param tip - Optional tip for resolution
+ * @returns Formatted markdown error string
+ */
+export declare function formatToolError(toolName: string, errorCode: string, message: string, retryable: boolean, tip?: string): string;
+/**
+ * Validate that a value is a non-empty array
+ *
+ * @param value - Value to check
+ * @param fieldName - Field name for error message
+ * @returns Error message or undefined if valid
+ */
+export declare function validateNonEmptyArray(value: unknown, fieldName: string): string | undefined;
+/**
+ * Validate array length is within bounds
+ *
+ * @param arr - Array to check
+ * @param min - Minimum length
+ * @param max - Maximum length
+ * @param fieldName - Field name for error message
+ * @returns Error message or undefined if valid
+ */
+export declare function validateArrayBounds(arr: unknown[], min: number, max: number, fieldName: string): string | undefined;
+/**
+ * Build standard header for batch operation results
+ *
+ * @param title - Title of the results section
+ * @param count - Number of items processed
+ * @param tokensPerItem - Tokens allocated per item
+ * @param totalBudget - Total token budget
+ * @returns Formatted header string
+ */
+export declare function buildBatchHeader(title: string, count: number, tokensPerItem: number, totalBudget: number): string;
+/**
+ * Build status line for batch results
+ *
+ * @param successful - Number of successful items
+ * @param failed - Number of failed items
+ * @param batches - Number of batches processed
+ * @param extras - Optional extra status items
+ * @returns Formatted status line
+ */
+export declare function buildStatusLine(successful: number, failed: number, batches: number, extras?: string[]): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/tools/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/tools/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,EACjC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,KACd,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAMD;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,EACjC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAQf;AAMD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG9E;AAMD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAI1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,OAAO,EAClB,GAAG,CAAC,EAAE,MAAM,GACX,MAAM,CAIR;AAMD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,OAAO,EAAE,EACd,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAQpB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,GAClB,MAAM,CAER;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,EAAE,GAChB,MAAM,CAMR"}

package/dist/tools/utils.js

@@ -0,0 +1,142 @@
+/**
+ * Shared Tool Utilities
+ * Extracted from individual handlers to eliminate duplication
+ */
+// ============================================================================
+// Logging Utilities
+// ============================================================================
+/**
+ * Safe logger wrapper - NEVER throws
+ * Logs to provided logger or falls back to console.error
+ *
+ * @param logger - Optional logger function
+ * @param sessionId - Session ID for logging context
+ * @param level - Log level
+ * @param message - Message to log
+ * @param toolName - Name of the tool for prefixing
+ */
+export async function safeLog(logger, sessionId, level, message, toolName) {
+    if (!logger || !sessionId)
+        return;
+    try {
+        await logger(level, `[${toolName}] ${message}`, sessionId);
+    }
+    catch {
+        // Silently ignore logger errors - they should never crash the tool
+        console.error(`[${toolName}] Logger failed: ${message}`);
+    }
+}
+// ============================================================================
+// Token Allocation
+// ============================================================================
+/**
+ * Calculate token allocation for batch operations
+ * Distributes a fixed budget across multiple items
+ *
+ * @param count - Number of items to distribute budget across
+ * @param budget - Total token budget
+ * @returns Tokens per item
+ */
+export function calculateTokenAllocation(count, budget) {
+    if (count <= 0)
+        return budget;
+    return Math.floor(budget / count);
+}
+// ============================================================================
+// Error Formatting
+// ============================================================================
+/**
+ * Format retry hint based on error retryability
+ *
+ * @param retryable - Whether the error is retryable
+ * @returns Hint string or empty string
+ */
+export function formatRetryHint(retryable) {
+    return retryable
+        ? '\n\n💡 This error may be temporary. Try again in a moment.'
+        : '';
+}
+/**
+ * Create a standard error markdown response
+ *
+ * @param toolName - Name of the tool that errored
+ * @param errorCode - Error code
+ * @param message - Error message
+ * @param retryable - Whether error is retryable
+ * @param tip - Optional tip for resolution
+ * @returns Formatted markdown error string
+ */
+export function formatToolError(toolName, errorCode, message, retryable, tip) {
+    const retryHint = formatRetryHint(retryable);
+    const tipSection = tip ? `\n\n**Tip:** ${tip}` : '';
+    return `# ❌ ${toolName}: Operation Failed\n\n**${errorCode}:** ${message}${retryHint}${tipSection}`;
+}
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+/**
+ * Validate that a value is a non-empty array
+ *
+ * @param value - Value to check
+ * @param fieldName - Field name for error message
+ * @returns Error message or undefined if valid
+ */
+export function validateNonEmptyArray(value, fieldName) {
+    if (!Array.isArray(value)) {
+        return `${fieldName} must be an array`;
+    }
+    if (value.length === 0) {
+        return `${fieldName} must not be empty`;
+    }
+    return undefined;
+}
+/**
+ * Validate array length is within bounds
+ *
+ * @param arr - Array to check
+ * @param min - Minimum length
+ * @param max - Maximum length
+ * @param fieldName - Field name for error message
+ * @returns Error message or undefined if valid
+ */
+export function validateArrayBounds(arr, min, max, fieldName) {
+    if (arr.length < min) {
+        return `${fieldName} requires at least ${min} items. Received: ${arr.length}`;
+    }
+    if (arr.length > max) {
+        return `${fieldName} allows at most ${max} items. Received: ${arr.length}. Please remove ${arr.length - max} item(s).`;
+    }
+    return undefined;
+}
+// ============================================================================
+// Response Builders
+// ============================================================================
+/**
+ * Build standard header for batch operation results
+ *
+ * @param title - Title of the results section
+ * @param count - Number of items processed
+ * @param tokensPerItem - Tokens allocated per item
+ * @param totalBudget - Total token budget
+ * @returns Formatted header string
+ */
+export function buildBatchHeader(title, count, tokensPerItem, totalBudget) {
+    return `# ${title} (${count} items)\n\n**Token Allocation:** ${tokensPerItem.toLocaleString()} tokens/item (${count} items, ${totalBudget.toLocaleString()} total budget)`;
+}
+/**
+ * Build status line for batch results
+ *
+ * @param successful - Number of successful items
+ * @param failed - Number of failed items
+ * @param batches - Number of batches processed
+ * @param extras - Optional extra status items
+ * @returns Formatted status line
+ */
+export function buildStatusLine(successful, failed, batches, extras) {
+    let status = `**Status:** ✅ ${successful} successful | ❌ ${failed} failed | 📦 ${batches} batch(es)`;
+    if (extras && extras.length > 0) {
+        status += ` | ${extras.join(' | ')}`;
+    }
+    return status;
+}
+//# sourceMappingURL=utils.js.map

package/dist/tools/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/tools/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "research-powerpack-mcp",
-  "version": "3.3.2",
+  "version": "3.4.0",
   "description": "The ultimate research MCP toolkit: Reddit mining, web search with CTR aggregation, AI-powered deep research, and intelligent web scraping - all in one modular package",
   "type": "module",
   "main": "dist/index.js",
@@ -11,7 +11,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && cp -r src/config/yaml dist/config/",
     "prepublishOnly": "npm run build",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
@@ -49,6 +49,7 @@
     "@modelcontextprotocol/sdk": "^1.18.1",
     "openai": "^4.77.0",
     "turndown": "^7.2.2",
+    "yaml": "^2.7.0",
     "zod": "^3.24.1",
     "zod-to-json-schema": "^3.24.1"
   },