@jrpool/kilotest 48.0.0 → 50.0.0

package/index.ts

@@ -11,6 +11,7 @@ import {
   createLock,
   deleteTestRequests,
   errorMessage,
+  getExclusionCookieValue,
   getJobNames,
   getJSON,
   getObject,
@@ -22,8 +23,12 @@ import {
   isReportAvailable,
   isTimeStamp,
   isJobID,
+  isURL,
   isUsableReport,
+  isValidAuthCode,
   jobsPath,
+  metricsExclusionCookieName,
+  recordMetric,
   reportsPath
 } from './util.ts';
 import {sendAlert} from './alerts.ts';
@@ -49,6 +54,7 @@ import {answer as listRules} from './web/listRules/index.ts';
 import {answer as listTopIssues} from './web/listTopIssues/index.ts';
 import {answer as listViolatorsPage} from './web/listViolators/index.ts';
 import {answer as manage} from './web/manage/index.ts';
+import {answer as metrics} from './web/metrics/index.ts';
 import {answer as pruneReportsForm} from './web/pruneReportsForm/index.ts';
 import {answer as reannotate} from './web/reannotate/index.ts';
 import {answer as reannotateForm} from './web/reannotateForm/index.ts';
@@ -59,6 +65,7 @@ import {answer as requestRetestForm} from './web/requestRetestForm/index.ts';
 import {answer as requestTestPage} from './web/requestTest/index.ts';
 import {answer as requestTestForm} from './web/requestTestForm/index.ts';
 import {answer as rewindReportsForm} from './web/rewindReportsForm/index.ts';
+import {answer as showHiddenReportsForm} from './web/showHiddenReportsForm/index.ts';
 import {answer as unhideReportForm} from './web/unhideReportForm/index.ts';
 import {response as getReportAPI} from './api/getReport.ts';
 import {response as listDiagnosesAPI} from './api/listDiagnoses.ts';
@@ -76,7 +83,15 @@ dotenv.config({quiet: true});
 // CONSTANTS
 
 // The data returned by a page-answering handler.
-type AnswerData = {status: string; message?: string; answerPage?: string};
+type AnswerData = {
+  status: string;
+  message?: string;
+  answerPage?: string;
+  // A cookie an answer() handler wants set on the response. Generic, not metrics-specific:
+  // handlers return data and never touch the response object directly, so this is how one
+  // asks index.ts, which owns the response, to set a cookie on its behalf.
+  setCookie?: {name: string; value: string; maxAgeSeconds: number};
+};
 // A page-answering handler, whose parameters vary by topic.
 type PageHandler = (...args: any[]) => Promise<AnswerData>;
 
@@ -93,6 +108,7 @@ const answer: {
   listTopIssues: PageHandler;
   listViolators: PageHandler;
   manage: PageHandler;
+  metrics: PageHandler;
   pruneReportsForm: PageHandler;
   tutorialWeb: PageHandler;
   tutorialAI: PageHandler;
@@ -105,6 +121,7 @@ const answer: {
   requestTest: PageHandler;
   requestTestForm: PageHandler;
   rewindReportsForm: PageHandler;
+  showHiddenReportsForm: PageHandler;
   unhideReportForm: PageHandler;
   [key: string]: PageHandler | undefined;
 } = {
@@ -120,6 +137,7 @@ const answer: {
   listTopIssues,
   listViolators: listViolatorsPage,
   manage,
+  metrics,
   pruneReportsForm,
   tutorialWeb,
   tutorialAI,
@@ -132,6 +150,7 @@ const answer: {
   requestTest: requestTestPage,
   requestTestForm,
   rewindReportsForm,
+  showHiddenReportsForm,
   unhideReportForm
 };
 // Response functions of the API services.
@@ -187,6 +206,13 @@ export const routes = {
   POST: [
     '/api/*',
     '/mcp',
+    '/ai0BalanceForm.html',
+    '/expungeReportsForm.html',
+    '/hideReportForm.html',
+    '/metrics.html',
+    '/pruneReportsForm.html',
+    '/rewindReportsForm.html',
+    '/showHiddenReportsForm.html',
     '/tutorialAIComment.html',
     '/reannotate.html',
     '/requestAction.html',
@@ -194,10 +220,59 @@ export const routes = {
     '/requestRetest.html/*',
     '/requestTest.html',
     '/tutorialWebComment.html',
+    '/unhideReportForm.html',
     '/worker/job',
     '/worker/report'
   ]
 };
+// The set of page topics (answer{} keys) that are manager-only pages, linked from
+// manage.html. Their views and submissions are recorded under the managerActivity
+// metrics category instead of pageViews, since they are the maintainer operating
+// Kilotest rather than the usage the observability plan's questions are about.
+const managerPages = new Set([
+  'enqueueForm',
+  'reannotateForm',
+  'pruneReportsForm',
+  'rewindReportsForm',
+  'expungeReportsForm',
+  'hideReportForm',
+  'showHiddenReportsForm',
+  'unhideReportForm',
+  'ai0BalanceForm',
+  'renewWCAGForm',
+  'metrics'
+]);
+// The set of manager pages (a subset of managerPages) whose single answer() function both
+// displays a form on GET and processes that form's own submission on POST, as opposed to
+// enqueueForm/reannotateForm, whose submissions post to a separate action page. This
+// governs POST dispatch for all of these pages, and GET dispatch for all except
+// unhideReportForm (see noDirectGetPages below).
+const selfSubmittingManagerPages = new Set([
+  'pruneReportsForm',
+  'rewindReportsForm',
+  'expungeReportsForm',
+  'hideReportForm',
+  'showHiddenReportsForm',
+  'unhideReportForm',
+  'ai0BalanceForm',
+  'metrics'
+]);
+// The subset of selfSubmittingManagerPages that must never be served on a direct GET
+// request, only as the response to another page's successful submission (here,
+// unhideReportForm is served only by showHiddenReportsForm, once a valid authorization code
+// has been submitted), so that the names of hidden reports are never disclosed without one.
+const noDirectGetPages = new Set(['unhideReportForm']);
+// Old page names, from before a 2026-08-31 rename (see GitHub issue #3), that search
+// engines and other crawlers are still requesting. Redirecting them lets crawlers update
+// their own indexes, rather than leaving them to repeat the same dead request indefinitely.
+// TEMPORARY: retire this redirect after 2027-04-01 once crawlers have re-indexed.
+const renamedPagePrefixes: Record<string, string> = {
+  diagnoses: 'listDiagnoses',
+  reportIssue: 'listViolators',
+  reportIssues: 'listIssues',
+  rules: 'listRules',
+  targets: 'listReports'
+};
 const jobLock = createLock();
 
 // FUNCTIONS
@@ -247,16 +322,22 @@ export const serveError = async (error: Record<string, unknown>, response: Serve
     console.log('Cannot send error response because the response has ended.');
   }
 };
+// Returns the IP address a request should be attributed to: the value of its
+// x-forwarded-for header (Caddy runs in front of Kilotest, so a real client's address
+// arrives this way, not as the socket's own remote address), else the socket's remote
+// address, else 'unknown' if neither is available.
+export const getRequestIP = (request: IncomingMessage): string | string[] => {
+  const forwardedFor = request.headers['x-forwarded-for'];
+  const remoteAddress = request.socket.remoteAddress;
+  return forwardedFor || remoteAddress || 'unknown';
+};
 // Creates an error object about a suspicious request.
 export const getAbuseError = (request: IncomingMessage, reason: string | undefined) => {
   const {method, url, headers} = request;
-  const forwardedFor = headers['x-forwarded-for'];
-  const remoteAddress = request.socket.remoteAddress;
-  const ip = forwardedFor || remoteAddress || 'unknown';
   return {
     message: 'Invalid request',
     reason,
-    'IP address': ip,
+    'IP address': getRequestIP(request),
     method,
     URL: url,
     'user agent': headers['user-agent'] || 'none',
@@ -264,6 +345,51 @@ export const getAbuseError = (request: IncomingMessage, reason: string | undefin
     time: new Date().toISOString()
   };
 };
+// Logs one line for every request, successful or not, once it finishes. Unlike
+// getAbuseError (logged only for rejected requests, as a rare, human-read-in-the-moment
+// dump), this is a terse, single-line-per-request JSON record, intended to be high-volume
+// and machine-parseable, so that any kind of suspicious traffic pattern (not only the
+// specific rejection reasons getAbuseError already covers) can be recognized later. It
+// deliberately does not consult isMetricsExcluded: that exclusion exists to keep the
+// maintainer's own manual testing out of usage counts, but abuse visibility should see
+// all traffic, including the maintainer's own, or it recreates the same kind of blind
+// spot this logging exists to close.
+const logRequestOnFinish = (request: IncomingMessage, response: ServerResponse): void => {
+  const {method, headers} = request;
+  const ip = getRequestIP(request);
+  const userAgent = headers['user-agent'] || 'none';
+  const path = new URL(request.url as string, 'https://localhost:3000').pathname;
+  const originalEnd = response.end.bind(response);
+  // Reassign response.end so that every path through handleRequest logs exactly once,
+  // right before the response is actually sent, rather than requiring every dispatch
+  // branch to remember to log itself (the same class of gap that left successful
+  // requests unlogged in the first place). No query string is logged, so that a
+  // parameter such as authCode is never written to a log file.
+  response.end = ((...args: Parameters<typeof originalEnd>) => {
+    console.log(JSON.stringify({
+      type: 'request',
+      time: new Date().toISOString(),
+      ip,
+      method,
+      path,
+      status: response.statusCode,
+      userAgent
+    }));
+    return originalEnd(...args);
+  }) as typeof response.end;
+};
+// Returns whether a request carries the metrics-exclusion cookie with the value that
+// proves it. A request without a valid AUTH_CODE configured can never match, since
+// getExclusionCookieValue then hashes an empty string, which no cookie should equal.
+const isMetricsExcluded = (request: IncomingMessage): boolean => {
+  const header = request.headers.cookie;
+  if (!header || !process.env.AUTH_CODE) {
+    return false;
+  }
+  const cookies = header.split(';').map(pair => pair.trim().split('='));
+  const cookieValue = cookies.find(([name]) => name === metricsExclusionCookieName)?.[1];
+  return cookieValue === getExclusionCookieValue();
+};
 // Gets the ID and secret from a request's HTTP Basic Authorization header, or null if the header
 // is absent or malformed.
 const getBasicAuth = (request: IncomingMessage) => {
@@ -311,7 +437,21 @@ const processJobRequest = async (request: IncomingMessage, response: ServerRespo
   const claimedJobNames = jobNames.claimed;
   // For each claimed job:
   for (const jobName of claimedJobNames) {
-    const job = await getObject(path.join(jobsPath(), 'claimed', jobName));
+    // A claimed-job file can disappear between the directory listing above and this
+    // read, because report submission (which deletes or reclassifies claimed jobs) is
+    // not serialized by jobLock. That race is a normal, recoverable condition, so the
+    // job is skipped rather than treated as defective; any other failure to read it
+    // should never occur and is left to propagate.
+    let job: unknown;
+    try {
+      job = await getObject(path.join(jobsPath(), 'claimed', jobName));
+    }
+    catch (error: unknown) {
+      if (error instanceof Error && (error.cause as NodeJS.ErrnoException | undefined)?.code === 'ENOENT') {
+        continue;
+      }
+      throw error;
+    }
     const {id, sources} = job as {id: string, sources: {worker: string}};
     const {worker} = sources;
     // If its assignee is the worker:
@@ -399,6 +539,24 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
     response.end('{}');
     return;
   }
+  // Log this request once it finishes, for general abuse/usage visibility (see GitHub
+  // issue #3). Placed after the smoke-test short-circuit above, so CI's own smoke-test
+  // traffic is excluded from this log exactly as it is already excluded from metrics.
+  logRequestOnFinish(request, response);
+  // Records a pageViews or apiOperations metric, unless this request's browser has proven,
+  // via a valid authCode submitted earlier on metrics.html, that it belongs to the
+  // maintainer testing Kilotest manually rather than to real usage.
+  const recordPageMetric = (category: 'pageViews' | 'apiOperations', name: string): Promise<void> =>
+    isMetricsExcluded(request) ? Promise.resolve() : recordMetric(category, name);
+  // Applies a cookie an answer() handler asked to have set on the response.
+  const applySetCookie = (answerData: AnswerData): void => {
+    if (answerData.setCookie) {
+      const {name, value, maxAgeSeconds} = answerData.setCookie;
+      response.setHeader(
+        'Set-Cookie', `${name}=${value}; Max-Age=${maxAgeSeconds}; Path=/; HttpOnly; SameSite=Strict`
+      );
+    }
+  };
   // If the request is a GET request:
   if (method === 'GET') {
     // If the path is not authorized for GET requests:
@@ -423,6 +581,7 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
     }
     // Otherwise, if it is for the home page:
     else if (['/', '/index.html'].includes(pathname)) {
+      await recordPageMetric('pageViews', 'index');
       // Get the home page.
       const homePage = await fs.readFile('index.html', 'utf8');
       // Serve it.
@@ -533,20 +692,46 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
     // Otherwise, if it is for an HTML page other than the home page:
     else if (pageName.endsWith('.html')) {
       const topic = pageName.slice(0, -5);
-      // If the page can be generated and is not POST-only (a POST-only path also
-      // matches the '*.html*' GET pattern, but its handler expects POST's argument
-      // list and performs no GET-appropriate rendering):
-      if (answer[topic] && !isPathAllowed('POST', pathname)) {
+      // If it is for a page's old, pre-rename name:
+      if (renamedPagePrefixes[topic]) {
+        // Redirect the client permanently to the current page name, preserving any
+        // further path segments and the query string.
+        const newLocation = `/${renamedPagePrefixes[topic]}.html${pathTail ? `/${pathTail}` : ''}${search}`;
+        response.writeHead(301, {Location: newLocation});
+        response.end();
+      }
+      // Otherwise, if the page can be generated and is not POST-only (a POST-only path also matches
+      // the '*.html*' GET pattern, but its handler expects POST's argument list and
+      // performs no GET-appropriate rendering; a self-submitting manager page is POST-allowed
+      // too, but its handler serves both methods the same way, so it is not excluded here,
+      // except for a page in noDirectGetPages, which stays excluded from GET even though
+      // it is self-submitting, since it must be reachable only via another page's POST):
+      else if (
+        answer[topic] &&
+        !noDirectGetPages.has(topic) &&
+        (!isPathAllowed('POST', pathname) || selfSubmittingManagerPages.has(topic))
+      ) {
         setHeaders('text/html', pathname, 'ultra');
-        // Get the answer data.
-        const answerData = await answer[topic](pathTail, search);
+        // Get the answer data. The method is passed so that a self-submitting manager
+        // page's handler can tell a form-display GET from its own submission POST.
+        const answerData = await answer[topic](pathTail, search, method);
         // If they are valid:
         if (answerData.status === 'ok') {
+          if (managerPages.has(topic)) {
+            await recordMetric('managerActivity', topic, 'ok');
+          }
+          else {
+            await recordPageMetric('pageViews', topic);
+          }
+          applySetCookie(answerData);
           // Serve the answer page.
           response.end(answerData.answerPage);
         }
         // Otherwise, i.e. if they are invalid:
         else {
+          if (managerPages.has(topic)) {
+            await recordMetric('managerActivity', topic, 'error');
+          }
           // Report the error as suspected abuse.
           await serveError(getAbuseError(request, answerData.message), response, true);
         }
@@ -564,6 +749,7 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
       if (service === 'listReports') {
         // Get the response body.
         const responseBody = await apiRespond.listReports([]);
+        await recordPageMetric('apiOperations', 'listReports');
         // Send it.
         setHeaders('application/json', null, 'ultra');
         response.end(JSON.stringify(responseBody));
@@ -572,6 +758,7 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
       else if (service === 'listIssues') {
         // Get the response body.
         const responseBody = await apiRespond.listIssues(specs);
+        await recordPageMetric('apiOperations', 'listIssues');
         // Send it.
         setHeaders('application/json', null, 'high');
         response.end(JSON.stringify(responseBody));
@@ -580,6 +767,7 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
       else if (service === 'listViolators') {
         // Get the response body.
         const responseBody = await apiRespond.listViolators(specs);
+        await recordPageMetric('apiOperations', 'listViolators');
         // Send it.
         setHeaders('application/json', null, 'high');
         response.end(JSON.stringify(responseBody));
@@ -588,6 +776,7 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
       else if (service === 'listDiagnoses') {
         // Get the response body.
         const responseBody = await apiRespond.listDiagnoses(specs);
+        await recordPageMetric('apiOperations', 'listDiagnoses');
         // Send it.
         setHeaders('application/json', null, 'high');
         response.end(JSON.stringify(responseBody));
@@ -596,6 +785,7 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
       else if (service === 'getReport') {
         // Get the response body.
         const responseBody = await apiRespond.getReport(specs);
+        await recordPageMetric('apiOperations', 'getReport');
         // Send it.
         setHeaders('application/json', null, 'low');
         response.end(JSON.stringify(responseBody));
@@ -689,7 +879,7 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
       else if (pageName === 'requestTest.html') {
         const {description, url, why} = postData as {description?: string; url: string; why?: string};
         // If the request is valid:
-        if (description && url.startsWith('https://') && why) {
+        if (description && isURL(url) && why) {
           // If a report on the page is already available:
           if (await isReportAvailable(description, url)) {
             // Report the error.
@@ -751,7 +941,7 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
         const {target, authCode} = postData as {target: string; authCode?: string};
         const [url, description] = target.split('\t') as [string, string];
         // If the request is valid:
-        if (url.startsWith('https://') && authCode === process.env.AUTH_CODE) {
+        if (isURL(url) && isValidAuthCode(authCode)) {
           // Set the non-location headers for a response.
           setHeaders('text/html', null, 'ultra');
           // If the request is an approval:
@@ -759,20 +949,14 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
             // Set a location header for a response.
             response.setHeader('content-location', pathname);
             // Process the approval and get the answer data about the remaining requests.
-            const answerData = await answer.enqueue(url, description, authCode);
-            // If the answer data are valid:
-            if (answerData.status === 'ok') {
-              // Serve the test-order page with the remaining recommendations.
-              response.end(answerData.answerPage);
-            }
-            // Otherwise, i.e. if they are invalid:
-            else {
-              // Report the error.
-              await serveError({message: answerData.message}, response, true);
-            }
+            const answerData = await answer.enqueue(url, description);
+            await recordMetric('managerActivity', 'requestAction.html', 'ok');
+            // Serve the test-order page with the remaining recommendations.
+            response.end(answerData.answerPage);
           }
           // Otherwise, i.e. if it is a rejection:
           else {
+            await recordMetric('managerActivity', 'requestAction.html', 'ok');
             // Delete the test requests for the URL.
             await deleteTestRequests(url);
             // Set a location header for a response.
@@ -785,8 +969,10 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
         }
         // Otherwise, i.e. if the request is invalid:
         else {
-          // Report the error.
-          await serveError({message: 'ERROR: Invalid test order'}, response, true);
+          await recordMetric('managerActivity', 'requestAction.html', 'error');
+          // Report the error, deliberately vague so as not to confirm to an attacker
+          // which part of the request (the URL, or the authorization code) was wrong.
+          await serveError({message: 'Invalid request'}, response, true);
         }
       }
       // Otherwise, if it is a reannotation order:
@@ -798,11 +984,13 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
         const answerData = await answer.reannotate(authCode);
         // If the answer data are valid:
         if (answerData.status === 'ok') {
+          await recordMetric('managerActivity', 'reannotate.html', 'ok');
           // Serve the answer page.
           response.end(answerData.answerPage);
         }
         // Otherwise, i.e. if they are invalid:
         else {
+          await recordMetric('managerActivity', 'reannotate.html', 'error');
           // Report the error.
           await serveError({message: answerData.message}, response, true);
         }
@@ -816,11 +1004,39 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
         const answerData = await answer.renewWCAG(authCode);
         // If the answer data are valid:
         if (answerData.status === 'ok') {
+          await recordMetric('managerActivity', 'renewWCAG.html', 'ok');
+          // Serve the answer page.
+          response.end(answerData.answerPage);
+        }
+        // Otherwise, i.e. if they are invalid:
+        else {
+          await recordMetric('managerActivity', 'renewWCAG.html', 'error');
+          // Report the error.
+          await serveError({message: answerData.message}, response, true);
+        }
+      }
+      // Otherwise, if it is a self-submitting manager page (one page serves the form on
+      // GET and processes its own submission on POST, unlike enqueueForm.html/reannotateForm.html,
+      // whose submissions go to a separate action page):
+      else if (pageName.endsWith('.html') && selfSubmittingManagerPages.has(pageName.slice(0, -5))) {
+        const topic = pageName.slice(0, -5);
+        setHeaders('text/html', pathname, 'ultra');
+        // Reconstruct a query string from the POST body, so the page's answer() function
+        // can read its submitted parameters the same way it reads a GET query string.
+        const search = `?${new URLSearchParams(postData as Record<string, string>).toString()}`;
+        // Get the answer data. The method is passed so the handler only processes a
+        // submission for POST, never for GET, regardless of what its query string contains.
+        const answerData = await answer[topic]!(pathTail, search, method);
+        // If they are valid:
+        if (answerData.status === 'ok') {
+          await recordMetric('managerActivity', topic, 'ok');
+          applySetCookie(answerData);
           // Serve the answer page.
           response.end(answerData.answerPage);
         }
         // Otherwise, i.e. if they are invalid:
         else {
+          await recordMetric('managerActivity', topic, 'error');
           // Report the error.
           await serveError({message: answerData.message}, response, true);
         }
@@ -938,6 +1154,7 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
           const {description, URL, reason} = postData as {description: string; URL: string; reason: string};
           // Get the response body.
           const responseBody = await apiRespond.requestTest([description, URL, reason]);
+          await recordPageMetric('apiOperations', 'requestTest');
           // Send it.
           setHeaders('application/json', null, 'ultra');
           response.end(JSON.stringify(responseBody));
@@ -947,6 +1164,7 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
           const {reason} = postData as {reason: string};
           // Get the response body.
           const responseBody = await apiRespond.requestRetest(segments.slice(1).concat(reason));
+          await recordPageMetric('apiOperations', 'requestRetest');
           // Send it.
           setHeaders('application/json', null, 'ultra');
           response.end(JSON.stringify(responseBody));
@@ -956,6 +1174,7 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
           const {feature} = postData as {feature: string};
           // Get the response body.
           const responseBody = await apiRespond.requestFeature([feature]);
+          await recordPageMetric('apiOperations', 'requestFeature');
           // Send it.
           setHeaders('application/json', null, 'ultra');
           response.end(JSON.stringify(responseBody));

package/linkValidation.test.ts

@@ -55,6 +55,7 @@ const htmlRoutes = [
   '/reannotate.html',
   '/reannotateForm.html',
   '/hideReportForm.html',
+  '/showHiddenReportsForm.html',
   '/unhideReportForm.html',
   '/expungeReportsForm.html',
   '/pruneReportsForm.html',

package/mcp.test.ts

@@ -9,12 +9,26 @@ import {test} from 'node:test';
 import assert from 'node:assert/strict';
 import http from 'node:http';
 import {mcpPath, createMCPServer, handleMCP} from './mcp.ts';
+import {metricsPath} from './util.ts';
+import fs from 'node:fs';
 
 // CONSTANTS
 
 // Set DB_DIR to the fixture database for all tests.
 process.env.DB_DIR = (await import('./test/dbFixture.ts')).fixtureDBDir;
 
+// FUNCTIONS
+
+// Returns the current count for an MCP tool in the metrics file, or 0 if the file or the
+// tool's entry is absent (the file does not exist until the first metric is recorded).
+const getToolCallCount = (toolName: string): number => {
+  if (!fs.existsSync(metricsPath())) {
+    return 0;
+  }
+  const metrics = JSON.parse(fs.readFileSync(metricsPath(), 'utf8'));
+  return metrics.mcpToolCalls[toolName] ?? 0;
+};
+
 // TESTS
 
 test('mcpPath is /mcp', () => {
@@ -48,14 +62,17 @@ test('each tool has a description and a handler function', () => {
 
 test('listReports handler returns content and structuredContent', async () => {
   const server = createMCPServer();
+  const countBefore = getToolCallCount('listReports');
   const result = await (server as any)._registeredTools.listReports.handler({});
   assert.ok(result.content);
   assert.equal(result.content[0].type, 'text');
   assert.ok(result.structuredContent);
+  assert.equal(getToolCallCount('listReports'), countBefore + 1);
 });
 
 test('listIssues handler returns content and structuredContent for a valid report', async () => {
   const server = createMCPServer();
+  const countBefore = getToolCallCount('listIssues');
   const result = await (server as any)._registeredTools.listIssues.handler({
     timeStamp: '260101T0000',
     jobID: 'mix'
@@ -63,10 +80,12 @@ test('listIssues handler returns content and structuredContent for a valid repor
   assert.ok(result.content);
   assert.equal(result.content[0].type, 'text');
   assert.ok(result.structuredContent);
+  assert.equal(getToolCallCount('listIssues'), countBefore + 1);
 });
 
 test('listViolators handler returns content and structuredContent for a valid issue', async () => {
   const server = createMCPServer();
+  const countBefore = getToolCallCount('listViolators');
   const result = await (server as any)._registeredTools.listViolators.handler({
     issueID: 'linkNoText',
     timeStamp: '260101T0000',
@@ -75,10 +94,12 @@ test('listViolators handler returns content and structuredContent for a valid is
   assert.ok(result.content);
   assert.equal(result.content[0].type, 'text');
   assert.ok(result.structuredContent);
+  assert.equal(getToolCallCount('listViolators'), countBefore + 1);
 });
 
 test('listDiagnoses handler returns content and structuredContent for a valid diagnosis', async () => {
   const server = createMCPServer();
+  const countBefore = getToolCallCount('listDiagnoses');
   const result = await (server as any)._registeredTools.listDiagnoses.handler({
     catalogIndex: '0',
     issueID: 'linkNoText',
@@ -88,10 +109,12 @@ test('listDiagnoses handler returns content and structuredContent for a valid di
   assert.ok(result.content);
   assert.equal(result.content[0].type, 'text');
   assert.ok(result.structuredContent);
+  assert.equal(getToolCallCount('listDiagnoses'), countBefore + 1);
 });
 
 test('getReport handler returns content and structuredContent for a valid report', async () => {
   const server = createMCPServer();
+  const countBefore = getToolCallCount('getReport');
   const result = await (server as any)._registeredTools.getReport.handler({
     timeStamp: '260101T0000',
     jobID: 'mix'
@@ -99,10 +122,12 @@ test('getReport handler returns content and structuredContent for a valid report
   assert.ok(result.content);
   assert.equal(result.content[0].type, 'text');
   assert.ok(result.structuredContent);
+  assert.equal(getToolCallCount('getReport'), countBefore + 1);
 });
 
 test('requestTest handler returns content and structuredContent', async () => {
   const server = createMCPServer();
+  const countBefore = getToolCallCount('requestTest');
   const result = await (server as any)._registeredTools.requestTest.handler({
     description: 'Test Page',
     URL: 'https://example.com/test',
@@ -111,10 +136,12 @@ test('requestTest handler returns content and structuredContent', async () => {
   assert.ok(result.content);
   assert.equal(result.content[0].type, 'text');
   assert.ok(result.structuredContent);
+  assert.equal(getToolCallCount('requestTest'), countBefore + 1);
 });
 
 test('requestRetest handler returns content and structuredContent for a valid report', async () => {
   const server = createMCPServer();
+  const countBefore = getToolCallCount('requestRetest');
   const result = await (server as any)._registeredTools.requestRetest.handler({
     timeStamp: '260101T0000',
     jobID: 'mix',
@@ -123,16 +150,19 @@ test('requestRetest handler returns content and structuredContent for a valid re
   assert.ok(result.content);
   assert.equal(result.content[0].type, 'text');
   assert.ok(result.structuredContent);
+  assert.equal(getToolCallCount('requestRetest'), countBefore + 1);
 });
 
 test('requestFeature handler returns content and structuredContent', async () => {
   const server = createMCPServer();
+  const countBefore = getToolCallCount('requestFeature');
   const result = await (server as any)._registeredTools.requestFeature.handler({
-    feature: 'A new feature idea'
+    feature: 'A new feature idea worth considering'
   });
   assert.ok(result.content);
   assert.equal(result.content[0].type, 'text');
   assert.ok(result.structuredContent);
+  assert.equal(getToolCallCount('requestFeature'), countBefore + 1);
 });
 
 test('listIssues handler returns an error for a nonexistent report', async () => {