@mcp-shark/mcp-shark 1.5.4 → 1.5.5

package/core/libraries/LoggerLibrary.js

@@ -0,0 +1,91 @@
+import { consola } from 'consola';
+
+/**
+ * Library for logging utilities
+ * Pure utility - no dependencies on services or repositories
+ * Uses consola with a consistent API supporting both Pino-style and consola-style
+ */
+export class LoggerLibrary {
+  constructor() {
+    this._consola = consola;
+  }
+
+  _formatArgs(args) {
+    if (args.length === 0) {
+      return null;
+    }
+    if (
+      args.length === 2 &&
+      typeof args[0] === 'object' &&
+      args[0] !== null &&
+      typeof args[1] === 'string'
+    ) {
+      return { style: 'pino', message: args[1] || '', metadata: args[0] };
+    }
+    return { style: 'consola', args };
+  }
+
+  info(...args) {
+    const formatted = this._formatArgs(args);
+    if (!formatted) {
+      return;
+    }
+    if (formatted.style === 'pino') {
+      consola.info(formatted.message, formatted.metadata);
+    } else {
+      consola.info(...formatted.args);
+    }
+  }
+
+  error(...args) {
+    const formatted = this._formatArgs(args);
+    if (!formatted) {
+      return;
+    }
+    if (formatted.style === 'pino') {
+      consola.error(formatted.message, formatted.metadata);
+    } else {
+      consola.error(...formatted.args);
+    }
+  }
+
+  warn(...args) {
+    const formatted = this._formatArgs(args);
+    if (!formatted) {
+      return;
+    }
+    if (formatted.style === 'pino') {
+      consola.warn(formatted.message, formatted.metadata);
+    } else {
+      consola.warn(...formatted.args);
+    }
+  }
+
+  debug(...args) {
+    const formatted = this._formatArgs(args);
+    if (!formatted) {
+      return;
+    }
+    if (formatted.style === 'pino') {
+      consola.debug(formatted.message, formatted.metadata);
+    } else {
+      consola.debug(...formatted.args);
+    }
+  }
+
+  log(...args) {
+    const formatted = this._formatArgs(args);
+    if (!formatted) {
+      return;
+    }
+    if (formatted.style === 'pino') {
+      consola.log(formatted.message, formatted.metadata);
+    } else {
+      consola.log(...formatted.args);
+    }
+  }
+
+  get consola() {
+    return this._consola;
+  }
+}

package/core/libraries/SerializationLibrary.js

@@ -0,0 +1,32 @@
+/**
+ * Library for serialization utilities
+ * Pure utility functions - no dependencies on services or repositories
+ */
+export class SerializationLibrary {
+  /**
+   * Serialize BigInt values to strings for JSON compatibility
+   */
+  serializeBigInt(data) {
+    if (data === null || data === undefined) {
+      return data;
+    }
+
+    if (typeof data === 'bigint') {
+      return data.toString();
+    }
+
+    if (Array.isArray(data)) {
+      return data.map((item) => this.serializeBigInt(item));
+    }
+
+    if (typeof data === 'object') {
+      const serialized = {};
+      for (const [key, value] of Object.entries(data)) {
+        serialized[key] = this.serializeBigInt(value);
+      }
+      return serialized;
+    }
+
+    return data;
+  }
+}

package/core/libraries/bootstrap-logger.js

@@ -0,0 +1,19 @@
+import { LoggerLibrary } from './LoggerLibrary.js';
+
+/**
+ * Bootstrap logger instance for use before DI container is available
+ * Re-exports LoggerLibrary instance for backward compatibility
+ * In core architecture, use LoggerLibrary via DependencyContainer
+ */
+const loggerInstance = new LoggerLibrary();
+
+const logger = {
+  info: (...args) => loggerInstance.info(...args),
+  error: (...args) => loggerInstance.error(...args),
+  warn: (...args) => loggerInstance.warn(...args),
+  debug: (...args) => loggerInstance.debug(...args),
+  log: (...args) => loggerInstance.log(...args),
+  consola: loggerInstance.consola,
+};
+
+export default logger;

package/core/libraries/errors/ApplicationError.js

@@ -0,0 +1,97 @@
+import { CompositeError } from '../ErrorLibrary.js';
+
+/**
+ * Base application error class
+ * All custom errors should extend this
+ */
+export class ApplicationError extends CompositeError {
+  constructor(name, message, statusCode = 500, error = null) {
+    super(name, message, error);
+    this.statusCode = statusCode;
+    this.name = name;
+  }
+
+  /**
+   * Convert error to HTTP response format
+   * @returns {{error: string, message: string, details?: string}}
+   */
+  toResponse() {
+    return {
+      error: this.name,
+      message: this.message,
+      ...(this.error && { details: this.error.message || String(this.error) }),
+    };
+  }
+}
+
+/**
+ * Validation error (400 Bad Request)
+ */
+export class ValidationError extends ApplicationError {
+  constructor(message, error = null) {
+    super('ValidationError', message, 400, error);
+  }
+}
+
+/**
+ * Not found error (404 Not Found)
+ */
+export class NotFoundError extends ApplicationError {
+  constructor(message, error = null) {
+    super('NotFoundError', message, 404, error);
+  }
+}
+
+/**
+ * Service unavailable error (503 Service Unavailable)
+ */
+export class ServiceUnavailableError extends ApplicationError {
+  constructor(message, error = null) {
+    super('ServiceUnavailableError', message, 503, error);
+  }
+}
+
+/**
+ * Internal server error (500 Internal Server Error)
+ */
+export class InternalServerError extends ApplicationError {
+  constructor(message, error = null) {
+    super('InternalServerError', message, 500, error);
+  }
+}
+
+/**
+ * Check if error is an ApplicationError
+ * @param {*} error
+ * @returns {boolean}
+ */
+export function isApplicationError(error) {
+  return error instanceof ApplicationError;
+}
+
+/**
+ * Convert any error to ApplicationError
+ * @param {Error|ApplicationError} error
+ * @param {string} defaultMessage
+ * @returns {ApplicationError}
+ */
+export function toApplicationError(error, defaultMessage = 'An unexpected error occurred') {
+  if (isApplicationError(error)) {
+    return error;
+  }
+
+  // Check for common error patterns
+  if (error?.message?.includes('ECONNREFUSED') || error?.message?.includes('connect')) {
+    return new ServiceUnavailableError('Service unavailable', error);
+  }
+
+  if (error?.message?.includes('required')) {
+    return new ValidationError(error.message, error);
+  }
+
+  if (error?.message?.includes('not found') || error?.code === 'ENOENT') {
+    return new NotFoundError(error.message || 'Resource not found', error);
+  }
+
+  return new InternalServerError(defaultMessage, error);
+}

package/core/libraries/index.js

@@ -0,0 +1,17 @@
+/**
+ * Library layer exports
+ * Libraries are pure utilities with no dependencies on services or repositories
+ */
+export { SerializationLibrary } from './SerializationLibrary.js';
+export { LoggerLibrary } from './LoggerLibrary.js';
+export { CompositeError, isError, getErrors } from './ErrorLibrary.js';
+export {
+  ApplicationError,
+  ValidationError,
+  NotFoundError,
+  ServiceUnavailableError,
+  InternalServerError,
+  isApplicationError,
+  toApplicationError,
+} from './errors/ApplicationError.js';
+export { default as bootstrapLogger } from './bootstrap-logger.js';

package/{mcp-server/lib → core/mcp-server}/auditor/audit.js

@@ -2,11 +2,6 @@ import { Readable } from 'node:stream';
 import { parse as parseJsonRpc } from 'jsonrpc-lite';
 import { getSessionFromRequest } from '../server/internal/handlers/common.js';
 
-/* ---------- helpers ---------- */
-
-/**
- * Safely parse JSON string, returning null if parsing fails
- */
 function parseJsonSafely(jsonString) {
   try {
     return JSON.parse(jsonString);
@@ -53,40 +48,66 @@ async function readBody(req) {
   return Buffer.concat(chunks);
 }
 
+function writeHandlerFunction(chunks, target, chunk, ...args) {
+  if (chunk) {
+    const buf = toBuffer(chunk);
+    chunks.push(buf);
+  }
+  return target.write(chunk, ...args);
+}
+
+function createWriteHandler(chunks, target) {
+  return (chunk, ...args) => {
+    return writeHandlerFunction(chunks, target, chunk, ...args);
+  };
+}
+
+function endHandlerFunction(chunks, target, chunk, ...args) {
+  if (chunk) {
+    const buf = toBuffer(chunk);
+    chunks.push(buf);
+  }
+  return target.end(chunk, ...args);
+}
+
+function createEndHandler(chunks, target) {
+  return (chunk, ...args) => {
+    return endHandlerFunction(chunks, target, chunk, ...args);
+  };
+}
+
+function proxyGetHandlerFunction(chunks, target, prop, receiver) {
+  if (prop === 'write') {
+    return createWriteHandler(chunks, target);
+  }
+
+  if (prop === 'end') {
+    return createEndHandler(chunks, target);
+  }
+
+  return Reflect.get(target, prop, receiver);
+}
+
+function createProxyGetHandler(chunks) {
+  return (target, prop, receiver) => {
+    return proxyGetHandlerFunction(chunks, target, prop, receiver);
+  };
+}
+
+function getResponseBody(chunks) {
+  return Buffer.concat(chunks);
+}
+
 function captureResponse(res) {
   const chunks = [];
 
   const wrapped = new Proxy(res, {
-    get(target, prop, receiver) {
-      if (prop === 'write') {
-        return (chunk, ...args) => {
-          if (chunk) {
-            const buf = toBuffer(chunk);
-            chunks.push(buf);
-          }
-          return target.write(chunk, ...args);
-        };
-      }
-
-      if (prop === 'end') {
-        return (chunk, ...args) => {
-          if (chunk) {
-            const buf = toBuffer(chunk);
-            chunks.push(buf);
-          }
-          return target.end(chunk, ...args);
-        };
-      }
-
-      return Reflect.get(target, prop, receiver);
-    },
+    get: createProxyGetHandler(chunks),
   });
 
   return {
     res: wrapped,
-    getBody: () => {
-      return Buffer.concat(chunks);
-    },
+    getBody: () => getResponseBody(chunks),
   };
 }
 
@@ -105,12 +126,16 @@ function tryParseJsonRpc(buf) {
   }
 }
 
+function createReadableRead(buf) {
+  return function read() {
+    this.push(buf);
+    this.push(null);
+  };
+}
+
 function rebuildReq(req, buf) {
   const r = new Readable({
-    read() {
-      this.push(buf);
-      this.push(null);
-    },
+    read: createReadableRead(buf),
   });
 
   r.headers = req.headers;
@@ -120,24 +145,30 @@ function rebuildReq(req, buf) {
   return r;
 }
 
+function finishOnce(state, resolve) {
+  if (!state.done) {
+    state.done = true;
+    resolve();
+  }
+}
+
+function handleResponseFinish(state, resolve) {
+  finishOnce(state, resolve);
+}
+
+function handleResponseClose(state, resolve) {
+  finishOnce(state, resolve);
+}
+
 function waitForResponseFinish(res) {
   return new Promise((resolve) => {
     const state = { done: false };
 
-    function finishOnce() {
-      if (!state.done) {
-        state.done = true;
-        resolve();
-      }
-    }
-
-    res.on('finish', finishOnce);
-    res.on('close', finishOnce);
+    res.on('finish', () => handleResponseFinish(state, resolve));
+    res.on('close', () => handleResponseClose(state, resolve));
   });
 }
 
-/* ---------- main handler ---------- */
-
 export async function withAuditRequestResponseHandler(
   transport,
   req,
@@ -149,8 +180,6 @@ export async function withAuditRequestResponseHandler(
   const reqBuf = await readBody(req);
   const reqJsonRpc = tryParseJsonRpc(reqBuf);
 
-  // Extract session ID from request
-  // If no session ID exists, it's an initiation request
   const sessionIdFromRequest = getSessionFromRequest(req);
   const sessionId =
     sessionIdFromRequest === null ||
@@ -180,14 +209,12 @@ export async function withAuditRequestResponseHandler(
 
   const parsedForTransport = reqJsonRpc ? parseJsonSafely(reqBuf.toString('utf8')) : undefined;
 
-  // hand over to transport
   if (!transport || typeof transport.handleRequest !== 'function') {
     res.status(500).json({ error: 'Transport not available' });
     return;
   }
   await transport.handleRequest(replayReq, wrappedRes, parsedForTransport);
 
-  // wait until response fully finished (important for SSE / streaming)
   await waitForResponseFinish(wrappedRes);
 
   const resBuf = getBody();
@@ -201,11 +228,8 @@ export async function withAuditRequestResponseHandler(
   const resBodyStr = resBuf.toString('utf8');
   const resBodyJson = parseJsonSafely(resBodyStr);
 
-  // Extract JSON-RPC ID from request for correlation
   const jsonrpcId = reqJsonRpc?.payload?.id !== undefined ? String(reqJsonRpc.payload.id) : null;
 
-  // Log response packet to database
-  // Use the same session ID from the request
   auditLogger.logResponsePacket({
     statusCode: wrappedRes.statusCode || 200,
     headers: resHeaders,

package/core/mcp-server/index.js

@@ -0,0 +1,192 @@
+import { createServer } from 'node:http';
+
+import { isError } from '#core/libraries/ErrorLibrary.js';
+import { bootstrapLogger as serverLogger } from '#core/libraries/index.js';
+import { runAllExternalServers } from './server/external/all.js';
+
+import { DependencyContainer } from '#core';
+import {
+  Environment,
+  getDatabaseFile,
+  getMcpConfigPath,
+  prepareAppDataSpaces,
+} from '#core/configs/index.js';
+import { initDb } from '#core/db/init.js';
+import { withAuditRequestResponseHandler } from './auditor/audit.js';
+import { getInternalServer } from './server/internal/run.js';
+import { createInternalServerFactory } from './server/internal/server.js';
+
+/**
+ * Initialize audit logger
+ * @param {Object} serverLogger - Logger instance
+ * @returns {Object} Audit logger instance
+ */
+export function initAuditLogger(serverLogger) {
+  serverLogger.info({ path: getDatabaseFile() }, 'Initializing audit logger at');
+  const db = initDb(getDatabaseFile());
+  const container = new DependencyContainer(db);
+  return container.getAuditLogger();
+}
+
+function createCloseCallback(serverLogger, resolve) {
+  return () => {
+    serverLogger.info('MCP Shark server stopped');
+    resolve();
+  };
+}
+
+async function performStop(server, externalServers, serverLogger) {
+  // Close all external server clients
+  for (const serverInfo of externalServers) {
+    if (serverInfo?.client && !isError(serverInfo)) {
+      try {
+        await serverInfo.client.close();
+      } catch (error) {
+        serverLogger.warn(
+          { error, message: error.message },
+          'Error closing external server client'
+        );
+      }
+    }
+  }
+
+  // Close all connections forcefully
+  if (server.closeAllConnections) {
+    server.closeAllConnections();
+  }
+
+  // Close the server
+  return new Promise((resolve) => {
+    const closeCallback = createCloseCallback(serverLogger, resolve);
+    server.close(closeCallback);
+  });
+}
+
+function stopFunctionWrapper(server, externalServers, serverLogger) {
+  return performStop(server, externalServers, serverLogger);
+}
+
+async function stopServerWrapper(server, externalServers, serverLogger) {
+  return stopFunctionWrapper(server, externalServers, serverLogger);
+}
+
+function createStopFunction(server, externalServers, serverLogger) {
+  return async () => {
+    return stopServerWrapper(server, externalServers, serverLogger);
+  };
+}
+
+function handleServerError(error, serverLogger, onError, reject) {
+  serverLogger.error(
+    { error, message: error.message, stack: error.stack },
+    `[MCP-Shark] ${error.message}`
+  );
+  if (onError) {
+    onError(error);
+  }
+  reject(error);
+}
+
+function handleServerReady(httpServer, port, serverLogger, onReady, resolve) {
+  serverLogger.info(`MCP proxy HTTP server listening on http://localhost:${port}/mcp`);
+  if (onReady) {
+    onReady();
+  }
+  resolve(httpServer);
+}
+
+function createServerPromise(httpServer, port, serverLogger, onError, onReady) {
+  return new Promise((resolve, reject) => {
+    httpServer.on('error', (error) => {
+      handleServerError(error, serverLogger, onError, reject);
+    });
+
+    httpServer.listen(port, '0.0.0.0', () => {
+      handleServerReady(httpServer, port, serverLogger, onReady, resolve);
+    });
+  });
+}
+
+/**
+ * Start the MCP Shark server
+ * @param {Object} options - Configuration options
+ * @param {string} [options.configPath] - Path to MCP config file (defaults to getMcpConfigPath())
+ * @param {number} [options.port=9851] - Port to listen on
+ * @param {Function} [options.onError] - Error callback
+ * @param {Function} [options.onReady] - Ready callback
+ * @param {Object} options.auditLogger - Required audit logger instance (use initAuditLogger() to create)
+ * @returns {Promise<{app: Express, server: http.Server, stop: Function}>} Server instance
+ */
+export async function startMcpSharkServer(options = {}) {
+  const {
+    configPath = getMcpConfigPath(),
+    port = 9851,
+    onError,
+    onReady,
+    auditLogger: providedAuditLogger,
+  } = options;
+
+  prepareAppDataSpaces();
+
+  serverLogger.info('[MCP-Shark] Starting MCP server...');
+  serverLogger.info(`[MCP-Shark] Config path: ${configPath}`);
+  serverLogger.info(`[MCP-Shark] Database path: ${getDatabaseFile()}`);
+  serverLogger.info(`[MCP-Shark] Working directory: ${process.cwd()}`);
+  serverLogger.info({ path: Environment.getPath() }, '[MCP-Shark] PATH');
+
+  try {
+    if (!providedAuditLogger) {
+      throw new Error('auditLogger is required. Call initAuditLogger() and pass it in options.');
+    }
+    const auditLogger = providedAuditLogger;
+    const externalServersResult = await runAllExternalServers(serverLogger, configPath);
+
+    if (isError(externalServersResult)) {
+      serverLogger.error(
+        {
+          error: externalServersResult,
+          message: externalServersResult.message,
+          stack: externalServersResult.stack,
+        },
+        `[MCP-Shark] ${externalServersResult.message}`
+      );
+      const error = new Error(JSON.stringify(externalServersResult));
+      if (onError) {
+        onError(error);
+      }
+      throw error;
+    }
+
+    const { kv, servers: externalServers } = externalServersResult;
+
+    const internalServerFactory = createInternalServerFactory(serverLogger, kv);
+    const app = getInternalServer(
+      internalServerFactory,
+      auditLogger,
+      withAuditRequestResponseHandler
+    );
+
+    const httpServer = createServer(app);
+
+    const server = await createServerPromise(httpServer, port, serverLogger, onError, onReady);
+
+    const stop = createStopFunction(server, externalServers, serverLogger);
+
+    return {
+      app,
+      server,
+      stop,
+      auditLogger,
+    };
+  } catch (error) {
+    const errorMsg = 'Error starting MCP server';
+    serverLogger.error(
+      { error, message: error.message, stack: error.stack },
+      `[MCP-Shark] ${errorMsg}`
+    );
+    if (onError) {
+      onError(error);
+    }
+    throw error;
+  }
+}

package/{mcp-server/lib → core/mcp-server}/server/external/all.js

@@ -1,4 +1,4 @@
-import { CompositeError, getErrors } from '../../common/error.js';
+import { CompositeError, getErrors } from '#core/libraries/ErrorLibrary.js';
 import { normalizeConfig } from './config.js';
 import { buildKv } from './kv.js';
 import { runExternalServer } from './single/run.js';