@vpalmisano/webrtcperf 4.6.1 → 4.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpalmisano/webrtcperf",
-  "version": "4.6.1",
+  "version": "4.7.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/vpalmisano/webrtcperf.git"
@@ -51,11 +51,12 @@
   },
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@google/genai": "^1.22.0",
-    "@puppeteer/browsers": "^2.10.10",
+    "@google/genai": "^1.40.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@puppeteer/browsers": "^2.12.0",
     "@vpalmisano/throttler": "0.0.14",
-    "@vpalmisano/webrtcperf-js": "^1.1.16",
-    "axios": "^1.12.2",
+    "@vpalmisano/webrtcperf-js": "^1.1.17",
+    "axios": "^1.13.5",
     "chalk-template": "^1.1.2",
     "change-case": "^4.1.2",
     "compression": "^1.8.1",
@@ -63,11 +64,11 @@
     "convict-format-with-validator": "^6.2.0",
     "debug-level": "^4.1.1",
     "dockerode": "^4.0.9",
-    "express": "^5.1.0",
+    "express": "^5.2.1",
     "express-basic-auth": "^1.2.1",
     "fast-stats": "^0.0.7",
     "form-data": "^4.0.4",
-    "googleapis": "^160.0.0",
+    "googleapis": "^164.1.0",
     "ipaddr.js": "^2.2.0",
     "json5": "^2.2.3",
     "lorem-ipsum": "^2.0.8",
@@ -78,16 +79,17 @@
     "pidtree": "^0.6.0",
     "pidusage": "^4.0.1",
     "prom-client": "^15.1.3",
-    "puppeteer": "^24.23.0",
-    "puppeteer-core": "^24.23.0",
+    "puppeteer": "^24.37.2",
+    "puppeteer-core": "^24.37.2",
     "puppeteer-extra": "^3.3.6",
     "puppeteer-extra-plugin-stealth": "^2.11.2",
     "puppeteer-intercept-and-modify-requests": "^1.3.1",
     "sprintf-js": "^1.1.3",
     "tar-fs": "^3.1.1",
     "toml": "^3.0.0",
-    "ws": "^8.18.3",
-    "yaml": "^2.8.1"
+    "ws": "^8.19.0",
+    "yaml": "^2.8.1",
+    "zod": "3"
   },
   "devDependencies": {
     "@eslint/js": "^9.37.0",
@@ -122,7 +124,7 @@
     "ts-loader": "^9.5.4",
     "typedoc": "^0.28.13",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.45.0",
+    "typescript-eslint": "^8.46.2",
     "webpack": "^5.102.0",
     "webpack-cli": "^6.0.1",
     "webpack-node-externals": "^3.0.0",

package/src/app.ts

@@ -26,6 +26,7 @@ import { markedTerminal } from 'marked-terminal'
 import { EventEmitter } from 'events'
 import { runWithDocker } from './docker'
 import { plotDetailedStatsDashboard } from './plot'
+import { mcpRunner } from './mcp'
 
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { marked } = require('marked')
@@ -243,6 +244,7 @@ async function main(): Promise<void> {
     process.exit(0)
   }
 
+  // Handle plot command.
   if (process.argv.includes('--plot')) {
     process.argv = process.argv.filter(s => s !== '--plot')
     try {
@@ -254,6 +256,13 @@ async function main(): Promise<void> {
     process.exit(0)
   }
 
+  // Handle MCP command.
+  if (process.argv.includes('--mcp')) {
+    process.argv = process.argv.filter(s => s !== '--mcp')
+    await mcpRunner()
+    return
+  }
+
   let configs: Config[]
 
   // Handle prompt.

package/src/config.ts

@@ -1,4 +1,5 @@
 import convict, { addFormats, SchemaObj } from 'convict'
+import { z } from 'zod'
 import { ipaddress, url } from 'convict-format-with-validator'
 import { existsSync } from 'fs'
 import os from 'os'
@@ -472,8 +473,9 @@ the following global variables will be attached to the \`webrtcperf\` global obj
 \`WEBRTC_PERF_SESSION\` the session number (0-indexed); \
 \`WEBRTC_PERF_TAB\` the tab number inside the same session (0-indexed); \
 \`WEBRTC_PERF_INDEX\` the page absolute index (0-indexed).
-Suggested values:
-- With meet.google.com: https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/google-meet.js
+Suggested values for automated testing:
+- meet.google.com: https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/google-meet.js
+- meet.livekit.io: https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/livekit.js
 `,
     format: String,
     default: '',
@@ -916,6 +918,40 @@ export function getConfigDocs(): ConfigDocs {
   return formatDocs({}, null, convict(configSchema).getSchema())
 }
 
+/**
+ * Returns a Zod schema for the config object, with all parameters optional and described.
+ * Uses the config default values when a field is omitted. Useful for MCP tools and other
+ * consumers that need validated partial config.
+ */
+export function getConfigZodSchema(): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  const schema = convict(configSchema).getSchema()
+  const shape: Record<string, z.ZodTypeAny> = {}
+  for (const [key, value] of Object.entries(schema._cvtProperties)) {
+    const prop = value as SchemaObj & { doc?: string; format?: unknown; default?: unknown }
+    const doc = prop.doc ?? key
+    const def = prop.default
+    const format = prop.format
+    let zodType: z.ZodTypeAny
+    if (format === String || format === 'string') {
+      zodType = z.string()
+    } else if (format === 'nat' || format === Number) {
+      zodType = z.number()
+    } else if (format === 'float') {
+      zodType = z.number()
+    } else if (format === 'Boolean' || format === 'boolean') {
+      zodType = z.boolean()
+    } else if (format === 'index') {
+      zodType = z.union([z.string(), z.number(), z.boolean()])
+    } else if (Array.isArray(format)) {
+      zodType = z.enum(format as [string, ...string[]])
+    } else {
+      zodType = z.union([z.string(), z.number(), z.boolean()])
+    }
+    shape[key] = def !== undefined ? zodType.default(def).describe(doc) : zodType.optional().describe(doc)
+  }
+  return z.object(shape)
+}
+
 const _schemaProperties = convict(configSchema).getProperties()
 
 /** [[include:config.md]] */

package/src/mcp.ts

@@ -0,0 +1,248 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { getSessionThrottleIndex, startThrottle } from '@vpalmisano/throttler'
+import { z } from 'zod'
+
+import { loadConfig } from './config'
+import type { Config } from './config'
+import { Session } from './session'
+import { Stats } from './stats'
+import { MediaPath, prepareFakeMedia } from './media'
+import { logger } from './utils'
+
+const log = logger('webrtcperf:mcp')
+
+const mcpServer = new McpServer({
+  name: 'webrtcperf',
+  version: '1.0.0',
+})
+
+let stats: Stats
+let statsReady: Promise<void>
+
+async function getStats(): Promise<Stats> {
+  if (!stats) {
+    const [defaultConfig] = await loadConfig(undefined, {
+      showStats: false,
+    })
+    if (!defaultConfig.startTimestamp) {
+      defaultConfig.startTimestamp = Date.now()
+    }
+    stats = new Stats(defaultConfig)
+    stats.on('stats', () => {
+      mcpServer.server.sendResourceUpdated({ uri: 'webrtcperf://stats' })
+    })
+    statsReady = stats.start()
+  }
+  await statsReady
+  return stats
+}
+
+async function startSessionHandler(args: {
+  config: Record<string, unknown>
+}): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
+  const { config } = args
+  log.debug('startSessionHandler', config)
+  const stats = await getStats()
+  const configs = await loadConfig(undefined, config as Partial<Config>)
+  const sessionConfig = configs[0]
+  const tabsPerSession = sessionConfig.tabsPerSession ?? 1
+  const id = stats.consumeSessionId(tabsPerSession)
+  const throttleIndex = getSessionThrottleIndex(id)
+  const spawnRate = (sessionConfig as Config & { spawnRate?: number }).spawnRate ?? 1
+  const spawnPeriod = 1000 / spawnRate
+  const throttleConfig = (sessionConfig as Config & { throttleConfig?: string }).throttleConfig
+  if (throttleConfig) {
+    await startThrottle(throttleConfig)
+  }
+  const mediaPaths: MediaPath[] = []
+  const videoPath = sessionConfig.videoPath
+  if (videoPath) {
+    for (const vp of videoPath.split(',')) {
+      const ret = await prepareFakeMedia({ ...sessionConfig, videoPath: vp })
+      mediaPaths.push(ret)
+    }
+  }
+  const mediaPath = mediaPaths.length ? mediaPaths[id % mediaPaths.length] : undefined
+
+  if (sessionConfig.url.startsWith('https://meet.google.com')) {
+    if (!sessionConfig.scriptPath) {
+      sessionConfig.scriptPath =
+        'https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/google-meet.js'
+    }
+    if (!sessionConfig.scriptParams) {
+      sessionConfig.scriptParams = '{"enableMic": true, "enableCam": true}'
+    }
+    if (!sessionConfig.debuggingPort) {
+      sessionConfig.debuggingPort = 9000
+    }
+  } else if (sessionConfig.url.startsWith('https://meet.livekit.io')) {
+    if (!sessionConfig.scriptPath) {
+      sessionConfig.scriptPath =
+        'https://raw.githubusercontent.com/vpalmisano/webrtcperf/refs/heads/devel/examples/livekit.js'
+    }
+  }
+
+  const session = new Session({
+    ...sessionConfig,
+    throttleIndex,
+    spawnPeriod,
+    mediaPath,
+    id,
+  })
+  session.once('stop', () => {
+    setTimeout(() => startSessionHandler({ config }).catch(() => {}), spawnPeriod)
+  })
+  stats.addSession(session)
+  try {
+    await session.start()
+  } catch (err) {
+    stats.removeSession(session.id)
+    throw err
+  }
+  if (sessionConfig.runDuration) {
+    setTimeout(() => {
+      session.removeAllListeners()
+      session.stop()
+      stats.removeSession(session.id)
+    }, sessionConfig.runDuration * 1000)
+  }
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify({ message: 'Session created', id }, null, 2),
+      },
+    ],
+  }
+}
+
+async function stopSessionHandler(args: { id: number }): Promise<{
+  content: Array<{ type: 'text'; text: string }>
+}> {
+  const { id } = args
+  log.debug('stopSessionHandler', id)
+  const s = await getStats()
+  const session = s.sessions.get(id)
+  if (!session) {
+    return {
+      content: [
+        {
+          type: 'text' as const,
+          text: JSON.stringify({ message: 'Session not found', id }, null, 2),
+        },
+      ],
+    }
+  }
+  session.removeAllListeners()
+  s.removeSession(id)
+  await session.stop()
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify({ message: 'Session deleted', id }),
+      },
+    ],
+  }
+}
+
+async function getSessionsHandler(): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
+  const s = await getStats()
+  const sessions = Array.from(s.sessions.entries()).map(([id, session]) => ({
+    id,
+    stats: session.stats,
+  }))
+  log.debug('getSessionsHandler', sessions)
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify({ sessions, count: sessions.length }),
+      },
+    ],
+  }
+}
+
+async function resetStatsHandler(): Promise<{ content: Array<{ type: 'text'; text: string }> }> {
+  const s = await getStats()
+  log.debug('resetStatsHandler')
+  s.resetStats()
+  await mcpServer.server.sendResourceUpdated({ uri: 'webrtcperf://stats' })
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify({ message: 'Stats reset' }),
+      },
+    ],
+  }
+}
+
+async function getStatsReadHandler(uri: URL): Promise<{
+  contents: Array<{ uri: string; mimeType: string; text: string }>
+}> {
+  const stats = await getStats()
+  log.debug('getStatsReadHandler', uri.href)
+  return {
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: 'application/json',
+        text: JSON.stringify(stats.collectedStats),
+      },
+    ],
+  }
+}
+
+mcpServer.registerTool(
+  'start_session',
+  {
+    description:
+      'Start a new webrtcperf session in-process. Config is the session config object (url, tabsPerSession, throttleConfig, etc.). Returns the created session id.',
+    inputSchema: { config: z.record(z.string(), z.unknown()) },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  } as any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  startSessionHandler as any,
+)
+
+mcpServer.registerTool(
+  'stop_session',
+  {
+    description: 'Stop a webrtcperf session by id.',
+    inputSchema: { id: z.number().int().nonnegative() },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  } as any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  stopSessionHandler as any,
+)
+
+mcpServer.registerTool(
+  'get_sessions',
+  {
+    description: 'List current webrtcperf sessions (id and stats for each running session).',
+  },
+  getSessionsHandler,
+)
+
+mcpServer.registerTool(
+  'reset_stats',
+  {
+    description: 'Reset the collected webrtcperf stats.',
+  },
+  resetStatsHandler,
+)
+
+mcpServer.registerResource(
+  'stats',
+  'webrtcperf://stats',
+  { description: 'Get the current webrtcperf stats.' },
+  getStatsReadHandler,
+)
+
+export async function mcpRunner(): Promise<void> {
+  log.debug('mcpRunner')
+  const transport = new StdioServerTransport()
+  await mcpServer.connect(transport)
+}

package/src/scenarios.ts

@@ -259,7 +259,7 @@ export async function plotStatsSummary(stats: StatsSummary[]) {
 export async function twoParticipantsWithRateLossDelay(
   id: string,
   { rate, loss, delay, direction }: { rate: number; loss: number; delay: number; direction: ThrottleDirection },
-  repeat: 1,
+  repeat = 1,
 ) {
   const throttle: ThrottleConfig = {}
   const queue = 25

package/src/server.ts

@@ -241,7 +241,7 @@ export class Server {
         throw new Error(`Session not found: "${sessionId}"`)
       }
       const filePath = await session.pageScreenshot(pageId, format)
-      res.sendFile(path.resolve(filePath))
+      res.sendFile(path.resolve(filePath), { dotfiles: 'allow' })
     } catch (err) {
       next(err)
     }
@@ -365,7 +365,7 @@ export class Server {
     if (req.query.range && !req.headers.range) {
       req.headers.range = `bytes=${req.query.range}`
     }
-    res.sendFile(path.resolve(this.pageLogPath))
+    res.sendFile(path.resolve(this.pageLogPath), { dotfiles: 'allow' })
   }
 
   /**
@@ -386,7 +386,7 @@ export class Server {
       if (req.query.range && !req.headers.range) {
         req.headers.range = `bytes=${req.query.range}`
       }
-      res.sendFile(path.resolve(logPath))
+      res.sendFile(path.resolve(logPath), { dotfiles: 'allow' })
     } catch (err) {
       next(err)
     }
@@ -441,7 +441,7 @@ export class Server {
     if (req.query.range && !req.headers.range) {
       req.headers.range = `bytes=${req.query.range}`
     }
-    res.sendFile(fpath)
+    res.sendFile(fpath, { dotfiles: 'allow' })
   }
 
   private getDataArchive(req: express.Request, res: express.Response, next: express.NextFunction): void {
@@ -465,7 +465,7 @@ export class Server {
     if (req.query.range && !req.headers.range) {
       req.headers.range = `bytes=${req.query.range}`
     }
-    res.sendFile(fpath)
+    res.sendFile(fpath, { dotfiles: 'allow' })
   }
 
   /**

package/src/stats.ts

@@ -1682,6 +1682,15 @@ export class Stats extends events.EventEmitter {
     }
   }
 
+  /**
+   * Reset the stats.
+   */
+  resetStats(): void {
+    log.debug('resetStats')
+    this.collectedStats = this.initCollectedStats()
+    this.externalCollectedStats.clear()
+  }
+
   async stop() {
     if (!this.running) return
     this.running = false
@@ -1716,7 +1725,6 @@ export class Stats extends events.EventEmitter {
       this.metrics = {}
     }
 
-    this.collectedStats = this.initCollectedStats()
-    this.externalCollectedStats.clear()
+    this.resetStats()
   }
 }