research-powerpack-mcp 3.4.7 → 3.5.0

package/dist/utils/response.js

@@ -0,0 +1,183 @@
+/**
+ * Standardized Response Formatting for MCP Tools
+ * Implements the 70/20/10 pattern for agent-optimized responses
+ *
+ * 70% Summary - Key insights, status, metrics
+ * 20% Data - Structured results
+ * 10% Next Steps - Actionable follow-ups
+ */
+// ============================================================================
+// Success Response Formatting
+// ============================================================================
+/**
+ * Format a successful tool response using the 70/20/10 pattern
+ *
+ * @example
+ * formatSuccess({
+ *   title: 'Web Search Results',
+ *   summary: '**Found 45 unique URLs** across 5 queries\n• 12 consensus results (appeared 3+ times)\n• Top domains: github.com, stackoverflow.com',
+ *   data: '## Top Results\n1. [Title](url) - snippet\n2. ...',
+ *   nextSteps: ['Scrape top URLs: scrape_links({urls: [...]})', 'Deep dive: deep_research({...})']
+ * })
+ */
+export function formatSuccess(options) {
+    const sections = [];
+    // Title
+    sections.push(`# ✅ ${options.title}`);
+    // Summary (70%)
+    sections.push('');
+    sections.push(options.summary);
+    // Data (20%)
+    if (options.data) {
+        sections.push('');
+        sections.push('---');
+        sections.push('');
+        sections.push(options.data);
+    }
+    // Metadata
+    if (options.metadata && Object.keys(options.metadata).length > 0) {
+        sections.push('');
+        sections.push('---');
+        sections.push('');
+        sections.push('**Metadata:**');
+        for (const [key, value] of Object.entries(options.metadata)) {
+            sections.push(`- ${key}: ${value}`);
+        }
+    }
+    // Next Steps (10%)
+    if (options.nextSteps && options.nextSteps.length > 0) {
+        sections.push('');
+        sections.push('---');
+        sections.push('');
+        sections.push('**→ Next Steps:**');
+        for (const step of options.nextSteps) {
+            sections.push(`- ${step}`);
+        }
+    }
+    return sections.join('\n');
+}
+// ============================================================================
+// Error Response Formatting
+// ============================================================================
+/**
+ * Format an error response with recovery guidance
+ *
+ * @example
+ * formatError({
+ *   code: 'RATE_LIMITED',
+ *   message: 'API rate limit exceeded',
+ *   retryable: true,
+ *   howToFix: ['Wait 60 seconds', 'Reduce batch size'],
+ *   alternatives: ['Use cached results', 'Try different API']
+ * })
+ */
+export function formatError(options) {
+    const sections = [];
+    // Title with tool name if provided
+    const titlePrefix = options.toolName ? `${options.toolName}: ` : '';
+    sections.push(`# ❌ ${titlePrefix}${options.code}`);
+    // Message
+    sections.push('');
+    sections.push(options.message);
+    // Retry hint
+    if (options.retryable !== undefined) {
+        sections.push('');
+        if (options.retryable) {
+            sections.push('💡 **This error may be temporary.** Try again in a moment.');
+        }
+        else {
+            sections.push('⚠️ **This error requires manual intervention.**');
+        }
+    }
+    // How to fix
+    if (options.howToFix && options.howToFix.length > 0) {
+        sections.push('');
+        sections.push('**How to Fix:**');
+        options.howToFix.forEach((step, i) => {
+            sections.push(`${i + 1}. ${step}`);
+        });
+    }
+    // Alternatives
+    if (options.alternatives && options.alternatives.length > 0) {
+        sections.push('');
+        sections.push('**Alternative Actions:**');
+        for (const alt of options.alternatives) {
+            sections.push(`• ${alt}`);
+        }
+    }
+    return sections.join('\n');
+}
+// ============================================================================
+// Batch Result Formatting
+// ============================================================================
+/**
+ * Format batch operation header with status
+ */
+export function formatBatchHeader(options) {
+    const sections = [];
+    // Title with count
+    sections.push(`# ${options.title} (${options.totalItems} items)`);
+    // Token allocation if provided
+    if (options.tokensPerItem && options.totalBudget) {
+        sections.push('');
+        sections.push(`**Token Allocation:** ${options.tokensPerItem.toLocaleString()} tokens/item (${options.totalItems} items, ${options.totalBudget.toLocaleString()} total budget)`);
+    }
+    // Status line
+    sections.push('');
+    let status = `**Status:** ✅ ${options.successful} successful | ❌ ${options.failed} failed`;
+    if (options.batches !== undefined) {
+        status += ` | 📦 ${options.batches} batch(es)`;
+    }
+    if (options.extras && options.extras.length > 0) {
+        status += ` | ${options.extras.join(' | ')}`;
+    }
+    sections.push(status);
+    return sections.join('\n');
+}
+// ============================================================================
+// Utility Formatters
+// ============================================================================
+/**
+ * Format a list of items with optional truncation
+ */
+export function formatList(items, options) {
+    const maxItems = options?.maxItems ?? items.length;
+    const ordered = options?.ordered ?? false;
+    const truncated = items.length > maxItems;
+    const displayItems = items.slice(0, maxItems);
+    const formatted = displayItems.map((item, i) => {
+        return ordered ? `${i + 1}. ${item}` : `• ${item}`;
+    });
+    if (truncated) {
+        formatted.push(`... and ${items.length - maxItems} more`);
+    }
+    return formatted.join('\n');
+}
+/**
+ * Format key-value pairs as a compact list
+ */
+export function formatKeyValues(data) {
+    return Object.entries(data)
+        .filter(([, v]) => v !== undefined && v !== null)
+        .map(([k, v]) => `• **${k}:** ${v}`)
+        .join('\n');
+}
+/**
+ * Format execution time
+ */
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    return `${(ms / 60000).toFixed(1)}m`;
+}
+/**
+ * Truncate text with ellipsis
+ */
+export function truncateText(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    return text.slice(0, maxLength - 3) + '...';
+}
+//# sourceMappingURL=response.js.map

package/dist/utils/response.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "research-powerpack-mcp",
-  "version": "3.4.7",
+  "version": "3.5.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",
@@ -21,10 +21,14 @@
     "test:scrape-links": "tsx tests/test-scrape-links.ts",
     "test:deep-research": "tsx tests/test-deep-research.ts",
     "test:all": "npm run test:web-search && npm run test:reddit-search && npm run test:scrape-links && npm run test:deep-research",
-    "test:check": "tsx tests/check-setup.ts"
+    "test:check": "tsx tests/check-setup.ts",
+    "install:claude-desktop": "npx install-mcp research-powerpack-mcp --client claude-desktop",
+    "install:cursor": "npx install-mcp research-powerpack-mcp --client cursor"
   },
   "keywords": [
     "mcp",
+    "mcp-server",
+    "install-mcp",
     "research",
     "reddit",
     "serper",
@@ -48,6 +52,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.18.1",
     "openai": "^4.77.0",
+    "p-limit": "^7.2.0",
     "turndown": "^7.2.2",
     "yaml": "^2.7.0",
     "zod": "^3.24.1",
@@ -57,6 +62,7 @@
     "@types/node": "^22.0.0",
     "@types/turndown": "^5.0.6",
     "dotenv": "^17.2.3",
+    "install-mcp": "^1.10.2",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0"
   },