research-powerpack-mcp 3.5.0 → 3.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/README.md +674 -63
  2. package/dist/clients/reddit.d.ts +6 -1
  3. package/dist/clients/reddit.d.ts.map +1 -1
  4. package/dist/clients/reddit.js +60 -24
  5. package/dist/clients/reddit.js.map +1 -1
  6. package/dist/clients/scraper.d.ts +6 -1
  7. package/dist/clients/scraper.d.ts.map +1 -1
  8. package/dist/clients/scraper.js +77 -38
  9. package/dist/clients/scraper.js.map +1 -1
  10. package/dist/clients/search.d.ts +2 -2
  11. package/dist/clients/search.d.ts.map +1 -1
  12. package/dist/clients/search.js +11 -6
  13. package/dist/clients/search.js.map +1 -1
  14. package/dist/config/index.d.ts.map +1 -1
  15. package/dist/config/index.js +5 -1
  16. package/dist/config/index.js.map +1 -1
  17. package/dist/config/loader.d.ts.map +1 -1
  18. package/dist/config/loader.js +6 -1
  19. package/dist/config/loader.js.map +1 -1
  20. package/dist/index.js +28 -86
  21. package/dist/index.js.map +1 -1
  22. package/dist/schemas/web-search.js +1 -1
  23. package/dist/schemas/web-search.js.map +1 -1
  24. package/dist/services/file-attachment.d.ts.map +1 -1
  25. package/dist/services/file-attachment.js +25 -22
  26. package/dist/services/file-attachment.js.map +1 -1
  27. package/dist/tools/reddit.d.ts.map +1 -1
  28. package/dist/tools/reddit.js +43 -55
  29. package/dist/tools/reddit.js.map +1 -1
  30. package/dist/tools/registry.js +2 -2
  31. package/dist/tools/registry.js.map +1 -1
  32. package/dist/tools/research.d.ts +1 -2
  33. package/dist/tools/research.d.ts.map +1 -1
  34. package/dist/tools/research.js +69 -59
  35. package/dist/tools/research.js.map +1 -1
  36. package/dist/tools/scrape.d.ts +1 -2
  37. package/dist/tools/scrape.d.ts.map +1 -1
  38. package/dist/tools/scrape.js +74 -96
  39. package/dist/tools/scrape.js.map +1 -1
  40. package/dist/tools/search.d.ts +1 -2
  41. package/dist/tools/search.d.ts.map +1 -1
  42. package/dist/tools/search.js +19 -21
  43. package/dist/tools/search.js.map +1 -1
  44. package/dist/tools/utils.d.ts +68 -16
  45. package/dist/tools/utils.d.ts.map +1 -1
  46. package/dist/tools/utils.js +75 -22
  47. package/dist/tools/utils.js.map +1 -1
  48. package/dist/utils/concurrency.d.ts +29 -0
  49. package/dist/utils/concurrency.d.ts.map +1 -0
  50. package/dist/utils/concurrency.js +73 -0
  51. package/dist/utils/concurrency.js.map +1 -0
  52. package/dist/utils/logger.d.ts +26 -23
  53. package/dist/utils/logger.d.ts.map +1 -1
  54. package/dist/utils/logger.js +41 -24
  55. package/dist/utils/logger.js.map +1 -1
  56. package/dist/utils/response.d.ts +49 -62
  57. package/dist/utils/response.d.ts.map +1 -1
  58. package/dist/utils/response.js +102 -134
  59. package/dist/utils/response.js.map +1 -1
  60. package/dist/utils/url-aggregator.d.ts.map +1 -1
  61. package/dist/utils/url-aggregator.js +6 -4
  62. package/dist/utils/url-aggregator.js.map +1 -1
  63. package/package.json +2 -8
  64. package/dist/config/env.d.ts +0 -75
  65. package/dist/config/env.d.ts.map +0 -1
  66. package/dist/config/env.js +0 -87
  67. package/dist/config/env.js.map +0 -1
  68. package/dist/config/yaml/tools-enhanced.yaml +0 -0
@@ -1,28 +1,49 @@
1
1
  /**
2
2
  * Shared Tool Utilities
3
- * Central module for common tool functionality
4
- * Re-exports from specialized utility modules for backwards compatibility
3
+ * Extracted from individual handlers to eliminate duplication
5
4
  */
6
- // Re-export logging utilities from centralized module
7
- export { safeLog, createToolLogger } from '../utils/logger.js';
8
- // Re-export response formatting utilities
9
- export { formatSuccess, formatError, formatBatchHeader, formatList, formatKeyValues, formatDuration, truncateText, } from '../utils/response.js';
5
+ // Re-export from centralized modules
6
+ export { mcpLog, safeLog as safeLogSimple, createToolLogger, } from '../utils/logger.js';
7
+ export { formatSuccess, formatError, formatBatchHeader, formatList, formatDuration, truncateText, } from '../utils/response.js';
10
8
  // ============================================================================
11
9
  // Token Budget Constants
12
10
  // ============================================================================
13
11
  /**
14
- * Token budgets for different tools
15
- * Centralized here to ensure consistency
12
+ * Centralized token budgets for all tools
16
13
  */
17
14
  export const TOKEN_BUDGETS = {
18
- /** Total token budget for deep research */
19
- RESEARCH: 32000,
20
- /** Total token budget for web scraping */
21
- SCRAPER: 32000,
22
- /** Total token budget for Reddit post fetching */
23
- REDDIT: 1000, // Comments budget
15
+ /** Deep research total budget */
16
+ RESEARCH: 32_000,
17
+ /** Web scraper total budget */
18
+ SCRAPER: 32_000,
19
+ /** Reddit comment budget per batch */
20
+ REDDIT_COMMENTS: 1_000,
24
21
  };
25
22
  // ============================================================================
23
+ // Logging Utilities
24
+ // ============================================================================
25
+ /**
26
+ * Safe logger wrapper - NEVER throws
27
+ * Logs to provided logger or falls back to console.error
28
+ *
29
+ * @param logger - Optional logger function
30
+ * @param sessionId - Session ID for logging context
31
+ * @param level - Log level
32
+ * @param message - Message to log
33
+ * @param toolName - Name of the tool for prefixing
34
+ */
35
+ export async function safeLog(logger, sessionId, level, message, toolName) {
36
+ if (!logger || !sessionId)
37
+ return;
38
+ try {
39
+ await logger(level, `[${toolName}] ${message}`, sessionId);
40
+ }
41
+ catch {
42
+ // Silently ignore logger errors - they should never crash the tool
43
+ console.error(`[${toolName}] Logger failed: ${message}`);
44
+ }
45
+ }
46
+ // ============================================================================
26
47
  // Token Allocation
27
48
  // ============================================================================
28
49
  /**
@@ -30,19 +51,22 @@ export const TOKEN_BUDGETS = {
30
51
  * Distributes a fixed budget across multiple items
31
52
  *
32
53
  * @param count - Number of items to distribute budget across
33
- * @param budget - Total token budget (defaults to RESEARCH budget)
54
+ * @param budget - Total token budget
34
55
  * @returns Tokens per item
35
56
  */
36
- export function calculateTokenAllocation(count, budget = TOKEN_BUDGETS.RESEARCH) {
57
+ export function calculateTokenAllocation(count, budget) {
37
58
  if (count <= 0)
38
59
  return budget;
39
60
  return Math.floor(budget / count);
40
61
  }
41
62
  // ============================================================================
42
- // Legacy Error Formatting (deprecated - use response.ts instead)
63
+ // Error Formatting
43
64
  // ============================================================================
44
65
  /**
45
- * @deprecated Use formatError from response.ts instead
66
+ * Format retry hint based on error retryability
67
+ *
68
+ * @param retryable - Whether the error is retryable
69
+ * @returns Hint string or empty string
46
70
  */
47
71
  export function formatRetryHint(retryable) {
48
72
  return retryable
@@ -50,7 +74,14 @@ export function formatRetryHint(retryable) {
50
74
  : '';
51
75
  }
52
76
  /**
53
- * @deprecated Use formatError from response.ts instead
77
+ * Create a standard error markdown response
78
+ *
79
+ * @param toolName - Name of the tool that errored
80
+ * @param errorCode - Error code
81
+ * @param message - Error message
82
+ * @param retryable - Whether error is retryable
83
+ * @param tip - Optional tip for resolution
84
+ * @returns Formatted markdown error string
54
85
  */
55
86
  export function formatToolError(toolName, errorCode, message, retryable, tip) {
56
87
  const retryHint = formatRetryHint(retryable);
@@ -62,6 +93,10 @@ export function formatToolError(toolName, errorCode, message, retryable, tip) {
62
93
  // ============================================================================
63
94
  /**
64
95
  * Validate that a value is a non-empty array
96
+ *
97
+ * @param value - Value to check
98
+ * @param fieldName - Field name for error message
99
+ * @returns Error message or undefined if valid
65
100
  */
66
101
  export function validateNonEmptyArray(value, fieldName) {
67
102
  if (!Array.isArray(value)) {
@@ -74,6 +109,12 @@ export function validateNonEmptyArray(value, fieldName) {
74
109
  }
75
110
  /**
76
111
  * Validate array length is within bounds
112
+ *
113
+ * @param arr - Array to check
114
+ * @param min - Minimum length
115
+ * @param max - Maximum length
116
+ * @param fieldName - Field name for error message
117
+ * @returns Error message or undefined if valid
77
118
  */
78
119
  export function validateArrayBounds(arr, min, max, fieldName) {
79
120
  if (arr.length < min) {
@@ -85,16 +126,28 @@ export function validateArrayBounds(arr, min, max, fieldName) {
85
126
  return undefined;
86
127
  }
87
128
  // ============================================================================
88
- // Legacy Response Builders (deprecated - use response.ts instead)
129
+ // Response Builders
89
130
  // ============================================================================
90
131
  /**
91
- * @deprecated Use formatBatchHeader from response.ts instead
132
+ * Build standard header for batch operation results
133
+ *
134
+ * @param title - Title of the results section
135
+ * @param count - Number of items processed
136
+ * @param tokensPerItem - Tokens allocated per item
137
+ * @param totalBudget - Total token budget
138
+ * @returns Formatted header string
92
139
  */
93
140
  export function buildBatchHeader(title, count, tokensPerItem, totalBudget) {
94
141
  return `# ${title} (${count} items)\n\n**Token Allocation:** ${tokensPerItem.toLocaleString()} tokens/item (${count} items, ${totalBudget.toLocaleString()} total budget)`;
95
142
  }
96
143
  /**
97
- * @deprecated Use formatBatchHeader from response.ts instead
144
+ * Build status line for batch results
145
+ *
146
+ * @param successful - Number of successful items
147
+ * @param failed - Number of failed items
148
+ * @param batches - Number of batches processed
149
+ * @param extras - Optional extra status items
150
+ * @returns Formatted status line
98
151
  */
99
152
  export function buildStatusLine(successful, failed, batches, extras) {
100
153
  let status = `**Status:** ✅ ${successful} successful | ❌ ${failed} failed | 📦 ${batches} batch(es)`;
@@ -1 +1 @@
1
- {"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/tools/utils.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/tools/utils.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Concurrency utilities for bounded parallel execution
3
+ * Prevents CPU spikes and API rate limiting from unbounded Promise.all
4
+ */
5
+ /**
6
+ * Execute async tasks with a concurrency limit (like p-map).
7
+ * Processes items from the input array through the mapper function,
8
+ * running at most `concurrency` tasks simultaneously.
9
+ *
10
+ * NEVER throws - if the mapper throws, the error propagates per-item
11
+ * (caller should handle via try/catch in mapper or use Promise.allSettled pattern).
12
+ *
13
+ * @param items - Array of items to process
14
+ * @param mapper - Async function to apply to each item
15
+ * @param concurrency - Maximum number of concurrent tasks (default: 6)
16
+ * @returns Array of results in the same order as input items
17
+ */
18
+ export declare function pMap<T, R>(items: T[], mapper: (item: T, index: number) => Promise<R>, concurrency?: number): Promise<R[]>;
19
+ /**
20
+ * Like pMap but uses Promise.allSettled semantics — never rejects,
21
+ * returns PromiseSettledResult for each item.
22
+ *
23
+ * @param items - Array of items to process
24
+ * @param mapper - Async function to apply to each item
25
+ * @param concurrency - Maximum number of concurrent tasks (default: 6)
26
+ * @returns Array of PromiseSettledResult in the same order as input items
27
+ */
28
+ export declare function pMapSettled<T, R>(items: T[], mapper: (item: T, index: number) => Promise<R>, concurrency?: number): Promise<PromiseSettledResult<R>[]>;
29
+ //# sourceMappingURL=concurrency.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../src/utils/concurrency.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAsB,IAAI,CAAC,CAAC,EAAE,CAAC,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9C,WAAW,GAAE,MAAU,GACtB,OAAO,CAAC,CAAC,EAAE,CAAC,CAwBd;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,CAAC,EACpC,KAAK,EAAE,CAAC,EAAE,EACV,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9C,WAAW,GAAE,MAAU,GACtB,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC,CA2BpC"}
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Concurrency utilities for bounded parallel execution
3
+ * Prevents CPU spikes and API rate limiting from unbounded Promise.all
4
+ */
5
+ /**
6
+ * Execute async tasks with a concurrency limit (like p-map).
7
+ * Processes items from the input array through the mapper function,
8
+ * running at most `concurrency` tasks simultaneously.
9
+ *
10
+ * NEVER throws - if the mapper throws, the error propagates per-item
11
+ * (caller should handle via try/catch in mapper or use Promise.allSettled pattern).
12
+ *
13
+ * @param items - Array of items to process
14
+ * @param mapper - Async function to apply to each item
15
+ * @param concurrency - Maximum number of concurrent tasks (default: 6)
16
+ * @returns Array of results in the same order as input items
17
+ */
18
+ export async function pMap(items, mapper, concurrency = 6) {
19
+ if (items.length === 0)
20
+ return [];
21
+ // Clamp concurrency to reasonable bounds
22
+ const limit = Math.max(1, Math.min(concurrency, items.length));
23
+ const results = new Array(items.length);
24
+ let nextIndex = 0;
25
+ async function worker() {
26
+ while (nextIndex < items.length) {
27
+ const index = nextIndex++;
28
+ results[index] = await mapper(items[index], index);
29
+ }
30
+ }
31
+ // Spawn `limit` workers that pull from the shared index
32
+ const workers = [];
33
+ for (let i = 0; i < limit; i++) {
34
+ workers.push(worker());
35
+ }
36
+ await Promise.all(workers);
37
+ return results;
38
+ }
39
+ /**
40
+ * Like pMap but uses Promise.allSettled semantics — never rejects,
41
+ * returns PromiseSettledResult for each item.
42
+ *
43
+ * @param items - Array of items to process
44
+ * @param mapper - Async function to apply to each item
45
+ * @param concurrency - Maximum number of concurrent tasks (default: 6)
46
+ * @returns Array of PromiseSettledResult in the same order as input items
47
+ */
48
+ export async function pMapSettled(items, mapper, concurrency = 6) {
49
+ if (items.length === 0)
50
+ return [];
51
+ const limit = Math.max(1, Math.min(concurrency, items.length));
52
+ const results = new Array(items.length);
53
+ let nextIndex = 0;
54
+ async function worker() {
55
+ while (nextIndex < items.length) {
56
+ const index = nextIndex++;
57
+ try {
58
+ const value = await mapper(items[index], index);
59
+ results[index] = { status: 'fulfilled', value };
60
+ }
61
+ catch (reason) {
62
+ results[index] = { status: 'rejected', reason };
63
+ }
64
+ }
65
+ }
66
+ const workers = [];
67
+ for (let i = 0; i < limit; i++) {
68
+ workers.push(worker());
69
+ }
70
+ await Promise.all(workers);
71
+ return results;
72
+ }
73
+ //# sourceMappingURL=concurrency.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../../src/utils/concurrency.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,KAAU,EACV,MAA8C,EAC9C,cAAsB,CAAC;IAEvB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAElC,yCAAyC;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAE/D,MAAM,OAAO,GAAQ,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,KAAK,UAAU,MAAM;QACnB,OAAO,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;YAC1B,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,wDAAwD;IACxD,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACzB,CAAC;IAED,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAU,EACV,MAA8C,EAC9C,cAAsB,CAAC;IAEvB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAElC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAE/D,MAAM,OAAO,GAA8B,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACnE,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,KAAK,UAAU,MAAM;QACnB,OAAO,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;gBAChD,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;YAClD,CAAC;YAAC,OAAO,MAAM,EAAE,CAAC;gBAChB,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;YAClD,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACzB,CAAC;IAED,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC"}
@@ -1,36 +1,39 @@
1
1
  /**
2
- * Centralized Logger Utilities
3
- * Provides safe logging that NEVER throws - extracted from tool handlers
2
+ * MCP SDK Structured Logging Utility
3
+ *
4
+ * Sends log messages to MCP clients via server.sendLoggingMessage().
5
+ * Falls back to stderr before the server is initialized.
4
6
  */
7
+ import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
8
+ export type LogLevel = 'debug' | 'info' | 'warning' | 'error';
5
9
  /**
6
- * Logger function type used across all tools
10
+ * Initialize the logger with an MCP server reference.
11
+ * Must be called after server creation and before any tool execution.
7
12
  */
8
- export type ToolLogger = (level: 'info' | 'error' | 'debug', message: string, sessionId: string) => Promise<void>;
13
+ export declare function initLogger(server: Server): void;
9
14
  /**
10
- * Standard options passed to tool handlers
15
+ * Log message via MCP SDK structured logging.
16
+ * Falls back to stderr if the server isn't initialized yet.
17
+ * @param level - Log level
18
+ * @param message - Message to log
19
+ * @param tool - Tool/logger name for context
11
20
  */
12
- export interface ToolOptions {
13
- sessionId?: string;
14
- logger?: ToolLogger;
15
- }
21
+ export declare function mcpLog(level: LogLevel, message: string, tool?: string): void;
16
22
  /**
17
- * Safe logger wrapper - NEVER throws
18
- * Logs to provided logger or falls back to console.error
19
- *
20
- * @param logger - Optional logger function
21
- * @param sessionId - Session ID for logging context
22
- * @param level - Log level ('info' | 'error' | 'debug')
23
+ * Safe log that catches any errors (never crashes)
24
+ * @param level - Log level
23
25
  * @param message - Message to log
24
- * @param toolName - Name of the tool for prefixing (optional)
26
+ * @param tool - Tool name for context
25
27
  */
26
- export declare function safeLog(logger: ToolLogger | undefined, sessionId: string | undefined, level: 'info' | 'error' | 'debug', message: string, toolName?: string): Promise<void>;
28
+ export declare function safeLog(level: LogLevel, message: string, tool?: string): void;
27
29
  /**
28
30
  * Create a bound logger for a specific tool
29
- * Returns a simpler function that only needs level and message
30
- *
31
- * @param options - Tool options containing logger and sessionId
32
- * @param toolName - Name of the tool for log prefixing
33
- * @returns Bound log function
34
31
  */
35
- export declare function createToolLogger(options: ToolOptions, toolName: string): (level: 'info' | 'error' | 'debug', message: string) => Promise<void>;
32
+ export declare function createToolLogger(tool: string): {
33
+ debug: (msg: string) => void;
34
+ info: (msg: string) => void;
35
+ warning: (msg: string) => void;
36
+ error: (msg: string) => void;
37
+ };
38
+ export type ToolLogger = ReturnType<typeof createToolLogger>;
36
39
  //# sourceMappingURL=logger.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;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;AAED;;;;;;;;;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,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,MAAM,GACf,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAIvE"}
1
+ {"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAExE,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAI9D;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE/C;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAQ5E;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAM7E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM;iBAE5B,MAAM;gBACP,MAAM;mBACH,MAAM;iBACR,MAAM;EAEtB;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC"}
@@ -1,40 +1,57 @@
1
1
  /**
2
- * Centralized Logger Utilities
3
- * Provides safe logging that NEVER throws - extracted from tool handlers
2
+ * MCP SDK Structured Logging Utility
3
+ *
4
+ * Sends log messages to MCP clients via server.sendLoggingMessage().
5
+ * Falls back to stderr before the server is initialized.
4
6
  */
7
+ let serverRef = null;
5
8
  /**
6
- * Safe logger wrapper - NEVER throws
7
- * Logs to provided logger or falls back to console.error
8
- *
9
- * @param logger - Optional logger function
10
- * @param sessionId - Session ID for logging context
11
- * @param level - Log level ('info' | 'error' | 'debug')
9
+ * Initialize the logger with an MCP server reference.
10
+ * Must be called after server creation and before any tool execution.
11
+ */
12
+ export function initLogger(server) {
13
+ serverRef = server;
14
+ }
15
+ /**
16
+ * Log message via MCP SDK structured logging.
17
+ * Falls back to stderr if the server isn't initialized yet.
18
+ * @param level - Log level
19
+ * @param message - Message to log
20
+ * @param tool - Tool/logger name for context
21
+ */
22
+ export function mcpLog(level, message, tool) {
23
+ const logger = tool ?? 'research-powerpack';
24
+ if (serverRef) {
25
+ serverRef.sendLoggingMessage({ level, data: message, logger }).catch(() => { });
26
+ }
27
+ else {
28
+ // Fallback to stderr before MCP transport is connected
29
+ console.error(`[${logger}] ${message}`);
30
+ }
31
+ }
32
+ /**
33
+ * Safe log that catches any errors (never crashes)
34
+ * @param level - Log level
12
35
  * @param message - Message to log
13
- * @param toolName - Name of the tool for prefixing (optional)
36
+ * @param tool - Tool name for context
14
37
  */
15
- export async function safeLog(logger, sessionId, level, message, toolName) {
16
- if (!logger || !sessionId)
17
- return;
18
- const prefix = toolName ? `[${toolName}] ` : '';
38
+ export function safeLog(level, message, tool) {
19
39
  try {
20
- await logger(level, `${prefix}${message}`, sessionId);
40
+ mcpLog(level, message, tool);
21
41
  }
22
42
  catch {
23
- // Silently ignore logger errors - they should never crash the tool
24
- console.error(`${prefix}Logger failed: ${message}`);
43
+ // Swallow logging errors - never crash
25
44
  }
26
45
  }
27
46
  /**
28
47
  * Create a bound logger for a specific tool
29
- * Returns a simpler function that only needs level and message
30
- *
31
- * @param options - Tool options containing logger and sessionId
32
- * @param toolName - Name of the tool for log prefixing
33
- * @returns Bound log function
34
48
  */
35
- export function createToolLogger(options, toolName) {
36
- return async (level, message) => {
37
- await safeLog(options.logger, options.sessionId, level, message, toolName);
49
+ export function createToolLogger(tool) {
50
+ return {
51
+ debug: (msg) => safeLog('debug', msg, tool),
52
+ info: (msg) => safeLog('info', msg, tool),
53
+ warning: (msg) => safeLog('warning', msg, tool),
54
+ error: (msg) => safeLog('error', msg, tool),
38
55
  };
39
56
  }
40
57
  //# sourceMappingURL=logger.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAmBH;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,MAA8B,EAC9B,SAA6B,EAC7B,KAAiC,EACjC,OAAe,EACf,QAAiB;IAEjB,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS;QAAE,OAAO;IAElC,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,QAAQ,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAEhD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,KAAK,EAAE,GAAG,MAAM,GAAG,OAAO,EAAE,EAAE,SAAS,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;QACnE,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,kBAAkB,OAAO,EAAE,CAAC,CAAC;IACtD,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAoB,EACpB,QAAgB;IAEhB,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAC9B,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC7E,CAAC,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,IAAI,SAAS,GAAkB,IAAI,CAAC;AAEpC;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,SAAS,GAAG,MAAM,CAAC;AACrB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,KAAe,EAAE,OAAe,EAAE,IAAa;IACpE,MAAM,MAAM,GAAG,IAAI,IAAI,oBAAoB,CAAC;IAC5C,IAAI,SAAS,EAAE,CAAC;QACd,SAAS,CAAC,kBAAkB,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACjF,CAAC;SAAM,CAAC;QACN,uDAAuD;QACvD,OAAO,CAAC,KAAK,CAAC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,KAAe,EAAE,OAAe,EAAE,IAAa;IACrE,IAAI,CAAC;QACH,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,uCAAuC;IACzC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO;QACL,KAAK,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;QACnD,IAAI,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;QACjD,OAAO,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC;QACvD,KAAK,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;KACpD,CAAC;AACJ,CAAC"}
@@ -1,101 +1,88 @@
1
1
  /**
2
- * Standardized Response Formatting for MCP Tools
3
- * Implements the 70/20/10 pattern for agent-optimized responses
2
+ * MCP Response Formatters - 70/20/10 Pattern
4
3
  *
5
- * 70% Summary - Key insights, status, metrics
6
- * 20% Data - Structured results
7
- * 10% Next Steps - Actionable follow-ups
4
+ * All tool responses should follow this structure:
5
+ * - 70% Summary: Key insights, status, metrics
6
+ * - 20% Data: Structured results (lists, tables)
7
+ * - 10% Next Steps: Actionable follow-up commands
8
8
  */
9
- export interface SuccessResponseOptions {
10
- /** Main title for the response */
9
+ export interface SuccessOptions {
10
+ /** Title/header for the response */
11
11
  title: string;
12
- /** Summary section (70% of response) */
12
+ /** Summary section (70% of content) */
13
13
  summary: string;
14
- /** Optional data section (20% of response) */
14
+ /** Optional data section (20% of content) */
15
15
  data?: string;
16
- /** Optional next steps (10% of response) */
16
+ /** Optional next steps (10% of content) */
17
17
  nextSteps?: string[];
18
- /** Optional metadata to append */
18
+ /** Optional metadata footer */
19
19
  metadata?: Record<string, string | number>;
20
20
  }
21
- export interface ErrorResponseOptions {
21
+ /**
22
+ * Format a successful response using 70/20/10 pattern
23
+ */
24
+ export declare function formatSuccess(opts: SuccessOptions): string;
25
+ export interface ErrorOptions {
22
26
  /** Error code (e.g., RATE_LIMITED, TIMEOUT) */
23
27
  code: string;
24
28
  /** Human-readable error message */
25
29
  message: string;
26
- /** Whether the error is retryable */
30
+ /** Is this error retryable? */
27
31
  retryable?: boolean;
28
- /** Steps to fix the error */
32
+ /** How to fix the error */
29
33
  howToFix?: string[];
30
- /** Alternative actions to try */
34
+ /** Alternative actions */
31
35
  alternatives?: string[];
32
36
  /** Tool name for context */
33
37
  toolName?: string;
34
38
  }
35
- export interface BatchResultOptions {
36
- /** Title for the batch results */
39
+ /**
40
+ * Format an error response with recovery guidance
41
+ */
42
+ export declare function formatError(opts: ErrorOptions): string;
43
+ export interface BatchHeaderOptions {
44
+ /** Batch operation title */
37
45
  title: string;
38
- /** Number of items processed */
46
+ /** Total items attempted */
39
47
  totalItems: number;
40
- /** Number of successful items */
48
+ /** Successfully processed count */
41
49
  successful: number;
42
- /** Number of failed items */
50
+ /** Failed count */
43
51
  failed: number;
44
- /** Tokens allocated per item */
52
+ /** Optional tokens per item */
45
53
  tokensPerItem?: number;
46
- /** Total token budget */
47
- totalBudget?: number;
48
- /** Number of batches processed */
54
+ /** Optional batch count */
49
55
  batches?: number;
50
- /** Additional status items */
51
- extras?: string[];
56
+ /** Extra stats to include */
57
+ extras?: Record<string, string | number>;
52
58
  }
53
59
  /**
54
- * Format a successful tool response using the 70/20/10 pattern
55
- *
56
- * @example
57
- * formatSuccess({
58
- * title: 'Web Search Results',
59
- * summary: '**Found 45 unique URLs** across 5 queries\n• 12 consensus results (appeared 3+ times)\n• Top domains: github.com, stackoverflow.com',
60
- * data: '## Top Results\n1. [Title](url) - snippet\n2. ...',
61
- * nextSteps: ['Scrape top URLs: scrape_links({urls: [...]})', 'Deep dive: deep_research({...})']
62
- * })
63
- */
64
- export declare function formatSuccess(options: SuccessResponseOptions): string;
65
- /**
66
- * Format an error response with recovery guidance
67
- *
68
- * @example
69
- * formatError({
70
- * code: 'RATE_LIMITED',
71
- * message: 'API rate limit exceeded',
72
- * retryable: true,
73
- * howToFix: ['Wait 60 seconds', 'Reduce batch size'],
74
- * alternatives: ['Use cached results', 'Try different API']
75
- * })
76
- */
77
- export declare function formatError(options: ErrorResponseOptions): string;
78
- /**
79
- * Format batch operation header with status
60
+ * Format a batch operation header with stats
80
61
  */
81
- export declare function formatBatchHeader(options: BatchResultOptions): string;
62
+ export declare function formatBatchHeader(opts: BatchHeaderOptions): string;
63
+ export interface ListItem {
64
+ /** Item title/name */
65
+ title: string;
66
+ /** Optional description */
67
+ description?: string;
68
+ /** Optional metadata */
69
+ meta?: string;
70
+ /** Optional URL */
71
+ url?: string;
72
+ }
82
73
  /**
83
- * Format a list of items with optional truncation
74
+ * Format a numbered list with optional metadata
84
75
  */
85
- export declare function formatList(items: string[], options?: {
76
+ export declare function formatList(items: ListItem[], options?: {
86
77
  maxItems?: number;
87
- ordered?: boolean;
78
+ numbered?: boolean;
88
79
  }): string;
89
80
  /**
90
- * Format key-value pairs as a compact list
91
- */
92
- export declare function formatKeyValues(data: Record<string, unknown>): string;
93
- /**
94
- * Format execution time
81
+ * Format duration in human-readable form
95
82
  */
96
83
  export declare function formatDuration(ms: number): string;
97
84
  /**
98
- * Truncate text with ellipsis
85
+ * Truncate text to max length with ellipsis
99
86
  */
100
87
  export declare function truncateText(text: string, maxLength: number): string;
101
88
  //# sourceMappingURL=response.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/utils/response.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,sBAAsB;IACrC,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,iCAAiC;IACjC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yBAAyB;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAyCrE;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAwCjE;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAwBrE;AAMD;;GAEG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACjD,MAAM,CAeR;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAKrE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAIjD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGpE"}
1
+ {"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/utils/response.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAoC1D;AAMD,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,0BAA0B;IAC1B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CA4BtD;AAMD,MAAM,WAAW,kBAAkB;IACjC,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CAC1C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CA8BlE;AAMD,MAAM,WAAW,QAAQ;IACvB,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CA0BzG;AAMD;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAIjD;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGpE"}