@jrpool/kilotest 51.1.0 → 55.0.0

package/index.test.ts

@@ -19,6 +19,10 @@ process.env.FEATURE_REQUESTS_PATH = path.join(testCommentsDir, 'featureRequests.
 process.env.TESTARO_WORKERS = JSON.stringify({
   worker1: {secret: 'secret1', name: 'Worker One'}
 });
+// Allow internal targets by default, so tests that submit an ordinary https://example.com/...
+// URL do not depend on real DNS/network access to pass the resolution check that
+// isAllowedTarget performs. Tests of the check itself (below) override this per test.
+process.env.ALLOW_INTERNAL_TARGETS = 'true';
 // Blank the alert configuration unconditionally, so this file sends no real alert
 // emails (e.g. from the requestTest/requestRetest/tutorial-comment tests below) even
 // when run directly (e.g. `npx tsx --test index.test.ts`) rather than via `npm test`,
@@ -905,6 +909,21 @@ test('POST /requestTest.html with non-https URL returns an error', async () => {
   assert.ok(res.body.includes('Invalid test request'));
 });
 
+test('POST /requestTest.html with a private-address URL returns an error unless internal targets are allowed', async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  try {
+    const res = await formRequest('POST', '/requestTest.html', {
+      description: 'Internal Page',
+      url: 'https://192.168.1.1/page',
+      why: 'Because accessibility matters'
+    });
+    assert.equal(res.statusCode, 400);
+    assert.ok(res.body.includes('Invalid test request'));
+  } finally {
+    process.env.ALLOW_INTERNAL_TARGETS = 'true';
+  }
+});
+
 test('POST /requestRetest.html/260202T0000/new with missing why returns an error', async () => {
   const res = await formRequest('POST', '/requestRetest.html/260202T0000/new', {
     why: ''
@@ -1147,6 +1166,57 @@ test('POST /worker/job with a queued job assigns it to the worker', {timeout: 50
   await fs.unlink(path.join(claimedDir, jobFile)).catch(() => {});
 });
 
+test('POST /worker/job with a queued job whose host now redirects to a disallowed target rejects it without assigning it', {timeout: 500}, async (t) => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  // Clean up claimed, queue, and failed directories.
+  const claimedDir = path.join(fixtureDBDir, 'jobs', 'claimed');
+  const queueDir = path.join(fixtureDBDir, 'jobs', 'queue');
+  const failedDir = path.join(fixtureDBDir, 'jobs', 'failed');
+  for (const dir of [claimedDir, queueDir]) {
+    await fs.mkdir(dir, {recursive: true});
+    const files = await fs.readdir(dir).catch(() => []);
+    for (const file of files) {
+      await fs.unlink(path.join(dir, file)).catch(() => {});
+    }
+  }
+  const jobFile = '260101T0000-mix.json';
+  const failedJobPath = path.join(failedDir, jobFile);
+  await fs.unlink(failedJobPath).catch(() => {});
+  // The job's host still resolves publicly, but by the time it is dequeued for
+  // assignment it has been reconfigured (e.g. by an attacker) to redirect to a
+  // private address, which only a fetch-based check, not a DNS-only one, can see.
+  t.mock.method(globalThis, 'fetch', async () => ({url: 'https://192.168.1.1/test'}) as Response);
+  try {
+    await fs.writeFile(path.join(queueDir, jobFile), JSON.stringify({
+      id: '260101T0000-mix',
+      target: {what: 'Test Page', url: 'https://example.com/test'},
+      sources: {}
+    }));
+    const auth = Buffer.from('worker1:secret1').toString('base64');
+    const res = await request('POST', '/worker/job', {}, {
+      authorization: `Basic ${auth}`
+    });
+    // The worker should be told there is no job, not given the disallowed job.
+    assert.equal(res.statusCode, 200);
+    const body = jsonBody(res);
+    assert.equal(body.id, undefined);
+    // Wait for the async rename to complete.
+    await new Promise<void>(resolve => setTimeout(resolve, 100));
+    // The job should have been moved from queue to failed, never to claimed.
+    const queueExists = await fs.access(path.join(queueDir, jobFile)).then(() => true).catch(() => false);
+    assert.equal(queueExists, false, 'Job should be removed from queue');
+    const claimedExists = await fs.access(path.join(claimedDir, jobFile)).then(() => true).catch(() => false);
+    assert.equal(claimedExists, false, 'Job should not be moved to claimed directory');
+    const failedExists = await fs.access(failedJobPath).then(() => true).catch(() => false);
+    assert.ok(failedExists, 'Job should be moved to the failed directory');
+  } finally {
+    t.mock.reset();
+    process.env.ALLOW_INTERNAL_TARGETS = 'true';
+    // Clean up.
+    await fs.unlink(failedJobPath).catch(() => {});
+  }
+});
+
 // TESTS: worker/report valid submission
 
 test('POST /worker/report with valid authentication and valid claimed job processes the report', {timeout: 500}, async () => {
@@ -1227,6 +1297,62 @@ test('POST /worker/report with a claimed job but an unusable report returns an e
   await fs.unlink(failedJobPath).catch(() => {});
 });
 
+test('POST /worker/report with a report on a disallowed target rejects it and reclassifies the job', {timeout: 500}, async () => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  // Use a unique job ID that does not conflict with existing fixtures.
+  const jobID = '990101T0002-ssr';
+  const reportPath = path.join(fixtureDBDir, 'reports', `${jobID}.json`);
+  const claimedDir = path.join(fixtureDBDir, 'jobs', 'claimed');
+  const failedDir = path.join(fixtureDBDir, 'jobs', 'failed');
+  const jobFile = `${jobID}.json`;
+  const claimedJobPath = path.join(claimedDir, jobFile);
+  const failedJobPath = path.join(failedDir, jobFile);
+  try {
+    // Clean up any leftover files.
+    await fs.unlink(reportPath).catch(() => {});
+    await fs.unlink(failedJobPath).catch(() => {});
+    // Create a claimed job assigned to Worker One.
+    await fs.writeFile(claimedJobPath, JSON.stringify({
+      id: jobID,
+      target: {what: 'Test', url: 'https://example.com/test'},
+      sources: {worker: 'Worker One'}
+    }));
+    const auth = Buffer.from('worker1:secret1').toString('base64');
+    // A report that is otherwise usable, but whose test act was redirected (actualURL)
+    // to a private address that this deployment does not allow as a testing target.
+    const report = {
+      id: jobID,
+      target: {what: 'Test', url: 'https://example.com/test'},
+      acts: [{
+        type: 'test', which: 'axe', actualURL: 'https://192.168.1.1/test',
+        result: {standardResult: {instances: []}}
+      }],
+      jobData: {endTime: '26-01-01T00:00'},
+      catalog: {}
+    };
+    const res = await request('POST', '/worker/report', {report}, {
+      authorization: `Basic ${auth}`
+    });
+    assert.equal(res.statusCode, 400);
+    const body = jsonBody(res);
+    assert.ok(body.error.message.includes('disallowed target'));
+    // The report should not have been recorded.
+    const reportExists = await fs.access(reportPath).then(() => true).catch(() => false);
+    assert.equal(reportExists, false, 'Report on a disallowed target should not be saved');
+    // Wait for the async rename to complete.
+    await new Promise<void>(resolve => setTimeout(resolve, 100));
+    // The job should have been reclassified as failed rather than left claimed.
+    const failedExists = await fs.access(failedJobPath).then(() => true).catch(() => false);
+    assert.ok(failedExists, 'Job should be moved to the failed directory');
+    const claimedExists = await fs.access(claimedJobPath).then(() => true).catch(() => false);
+    assert.equal(claimedExists, false, 'Job should be removed from the claimed directory');
+  } finally {
+    process.env.ALLOW_INTERNAL_TARGETS = 'true';
+    // Clean up.
+    await fs.unlink(failedJobPath).catch(() => {});
+  }
+});
+
 // TESTS: remaining error branches and web pages
 
 test('GET /style.css with a read error returns an error page', async () => {

package/index.ts

@@ -17,6 +17,9 @@ import {
   getObject,
   getPOSTData,
   getReport,
+  isAllowedRedirectTarget,
+  isAllowedReport,
+  isAllowedTarget,
   isReportError,
   getReportPath,
   hiddenReportsPath,
@@ -482,26 +485,54 @@ const processJobRequest = async (request: IncomingMessage, response: ServerRespo
     if (queuedJobNames.length) {
       const oldestJobName = queuedJobNames[0]!;
       // Get the first one.
-      const firstJob = await getObject(path.join(queuePath(), oldestJobName)) as {id: string, sources: {worker: string}, target: {what: string}};
-      // Add the public worker name to the job, in a property Testaro does not read or alter.
-      firstJob.sources.worker = workerName;
-      console.log(
-        `Job ${firstJob.id} (${firstJob.target.what}) is being sent to the worker.`
-      );
-      // Assign the job to the worker.
-      response.writeHead(200, {
-        'content-type': 'application/json; charset=utf-8'
-      });
-      response.end(JSON.stringify(firstJob));
-      const messageEnd
-      = `and job ${firstJob.id} (${firstJob.target.what}) was assigned to the worker`;
-      console.log(`${messageStart}${messageEnd}`);
-      // Save the job in the claimed-jobs directory.
-      await fs.writeFile(
-        path.join(claimedPath(), oldestJobName), getJSON(firstJob)
-      );
-      // Delete it from the queue.
-      await fs.unlink(path.join(queuePath(), oldestJobName));
+      const firstJob = await getObject(path.join(queuePath(), oldestJobName)) as {id: string, sources: {worker: string}, target: {what: string, url: string}};
+      // If the job's target is no longer allowed, whether because its host now resolves
+      // to a disallowed address or, more likely, because the host now redirects to one
+      // (both possible if the target host was reconfigured, e.g. by an attacker, after
+      // the request was accepted; a fetch-based check is used, rather than the cheaper
+      // DNS-only isAllowedTarget, because this runs only when a job is actually queued,
+      // which is rare, and a redirect introduced after acceptance is the likelier attack):
+      if (!(await isAllowedRedirectTarget(firstJob.target.url))) {
+        console.error(`ERROR: Queued job ${firstJob.id} is on a target this deployment does not allow`);
+        // Alert a manager, since this indicates an attempted or accidental SSRF
+        // rather than an ordinary usability problem with the target.
+        await sendAlert(
+          'Kilotest: queued job on disallowed target rejected',
+          `Job ${firstJob.id} (${firstJob.target.what}) was never assigned to a worker because its target no longer resolves, directly or via a redirect, to an address this deployment allows (e.g. a private, loopback, or link-local address). The job was reclassified as failed.`
+        );
+        // Reclassify the job as failed, instead of assigning it or leaving it queued.
+        await fs.rename(
+          path.join(queuePath(), oldestJobName), path.join(failedPath(), oldestJobName)
+        );
+        // Respond as if no job were queued, rather than revealing anything about the rejected job.
+        response.writeHead(200, {
+          'content-type': 'application/json; charset=utf-8'
+        });
+        response.end(JSON.stringify({}));
+        console.log(`${messageStart}but the queued job was on a disallowed target`);
+      }
+      // Otherwise, i.e. if the job's target is still allowed:
+      else {
+        // Add the public worker name to the job, in a property Testaro does not read or alter.
+        firstJob.sources.worker = workerName;
+        console.log(
+          `Job ${firstJob.id} (${firstJob.target.what}) is being sent to the worker.`
+        );
+        // Assign the job to the worker.
+        response.writeHead(200, {
+          'content-type': 'application/json; charset=utf-8'
+        });
+        response.end(JSON.stringify(firstJob));
+        const messageEnd
+        = `and job ${firstJob.id} (${firstJob.target.what}) was assigned to the worker`;
+        console.log(`${messageStart}${messageEnd}`);
+        // Save the job in the claimed-jobs directory.
+        await fs.writeFile(
+          path.join(claimedPath(), oldestJobName), getJSON(firstJob)
+        );
+        // Delete it from the queue.
+        await fs.unlink(path.join(queuePath(), oldestJobName));
+      }
     }
     // Otherwise, i.e. if no jobs are queued:
     else {
@@ -899,7 +930,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 && isURL(url) && why) {
+        if (description && isURL(url) && why && await isAllowedTarget(url)) {
           // If a report on the page is already available:
           if (await isReportAvailable(description, url)) {
             // Report the error.
@@ -1103,8 +1134,28 @@ const handleRequest = async (request: IncomingMessage, response: ServerResponse)
               }
               // If the job was actually assigned to this worker:
               if (typeof claimedJob === 'object' && claimedJob !== null && (claimedJob as {sources?: {worker?: string}}).sources?.worker === workerName) {
-                // If the report is usable by Kilotest (as any report of an assigned job should be):
-                if (isUsableReport(reportObj)) {
+                // If the report is on a target this deployment allows (a redirect during
+                // navigation, possibly via DNS rebinding, can take a worker to a target that
+                // was disallowed even though the originally submitted URL passed that check
+                // at submission time):
+                if (!(await isAllowedReport(reportObj))) {
+                  console.error(`ERROR: Report ${id} from worker ${workerName} is on a disallowed target`);
+                  // Alert a manager, since this indicates an attempted or accidental SSRF
+                  // rather than an ordinary usability problem with the report.
+                  await sendAlert(
+                    'Kilotest: report on disallowed target rejected',
+                    `Job ${id} from worker ${workerName} resulted in a visit to a target this deployment does not allow (e.g. a private, loopback, or link-local address), possibly via a redirect. The report was discarded and the job was reclassified as failed.`
+                  );
+                  // Reclassify the job as failed, instead of recording the disallowed report or
+                  // leaving the job claimed indefinitely.
+                  await fs.rename(
+                    path.join(claimedPath(), `${id}.json`), path.join(failedPath(), `${id}.json`)
+                  );
+                  // Report the error.
+                  await serveError({message: `ERROR: Report ${id} is on a disallowed target`}, response, false);
+                }
+                // Otherwise, if the report is usable by Kilotest (as any report of an assigned job should be):
+                else if (isUsableReport(reportObj)) {
                   console.log(`Testaro report ${id} was received from worker ${workerName}`);
                   // Add the public worker name to the report.
                   report!.sources = {...report!.sources, worker: workerName};

package/llms-full.txt

@@ -6,7 +6,7 @@ Kilotest is an application that performs ensemble testing of web pages for front
 
 ## What Kilotest does for language models
 
-Kilotest is deployed on the public Internet as a service at `https://kilotest.com`. Kilotest can test only web pages that can be accessed from the public Internet and that are not protected by authentication or other access controls. Kilotest has not implemented any mechanism for testing private, internal, password-protected, or otherwise restricted pages.
+Kilotest is deployed on the public Internet as a service at `https://kilotest.com`. That deployment of Kilotest can test only web pages that can be accessed by its Testaro worker with a URL. Generally those are pages on the public Internet that are not protected by authentication or other access controls.
 
 Without calling any tool, an LLM can, under some conditions, load web pages and use its knowledge to assess successes and failures of front-end quality. But such an assessment is almost always:
 

package/llms.txt

@@ -1,6 +1,6 @@
 # Kilotest
 
-Kilotest helps language models and AI platforms to give thorough, accurate and truthful answers when users ask about the front-end quality (i.e. accessibility, usability, and standards conformity) of web pages. Kilotest integrates an ensemble of twelve independent rule engines to test any public web page. Kilotest creates a structured report of the results and saves the report for future reference. Kilotest API endpoints and MCP tools can provide multipage, single-page, and element-level test results.
+Kilotest helps language models and AI platforms to give thorough, accurate and truthful answers when users ask about the front-end quality (i.e. accessibility, usability, and standards conformity) of web pages. Kilotest integrates an ensemble of twelve independent rule engines to test a web page. Kilotest creates a structured report of the results and saves the report for future reference. Kilotest API endpoints and MCP tools can provide multipage, single-page, and element-level test results.
 
 ## API
 

package/mcp.test.ts

@@ -11,6 +11,8 @@ import http from 'node:http';
 import {mcpPath, createMCPServer, handleMCP} from './mcp.ts';
 import {metricsPath} from './util.ts';
 import fs from 'node:fs';
+import {Client} from '@modelcontextprotocol/sdk/client/index.js';
+import {InMemoryTransport} from '@modelcontextprotocol/sdk/inMemory.js';
 
 // CONSTANTS
 
@@ -35,11 +37,12 @@ test('mcpPath is /mcp', () => {
   assert.equal(mcpPath, '/mcp');
 });
 
-test('createMCPServer registers all 8 tools', () => {
+test('createMCPServer registers all 9 tools', () => {
   const server = createMCPServer();
   const toolNames = Object.keys((server as any)._registeredTools);
-  assert.equal(toolNames.length, 8);
+  assert.equal(toolNames.length, 9);
   assert.deepEqual(toolNames, [
+    'getKilotestOverview',
     'listReports',
     'listIssues',
     'listViolators',
@@ -56,10 +59,41 @@ test('each tool has a description and a handler function', () => {
   const tools = (server as any)._registeredTools;
   for (const [name, tool] of Object.entries(tools) as [string, any][]) {
     assert.ok(tool.description, `${name} has a description`);
+    assert.ok(
+      tool.description.includes('front-end quality'),
+      `${name} description includes the shared domain context`
+    );
     assert.equal(typeof tool.handler, 'function', `${name} has a handler function`);
   }
 });
 
+test('getKilotestOverview handler returns overview text and records a metric', async () => {
+  const server = createMCPServer();
+  const countBefore = getToolCallCount('getKilotestOverview');
+  const result = await (server as any)._registeredTools.getKilotestOverview.handler({});
+  assert.ok(result.content);
+  assert.equal(result.content[0].type, 'text');
+  assert.ok(result.content[0].text.includes('front-end quality'));
+  assert.equal(getToolCallCount('getKilotestOverview'), countBefore + 1);
+});
+
+test('client receives instructions, server description, and the overview resource', async () => {
+  const server = createMCPServer();
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await server.connect(serverTransport);
+  const client = new Client({name: 'test-client', version: '1.0.0'});
+  await client.connect(clientTransport);
+  assert.ok(client.getInstructions()?.includes('front-end quality'));
+  assert.ok(client.getServerVersion()?.description?.includes('front-end quality'));
+  const resources = await client.listResources();
+  assert.deepEqual(resources.resources.map((r: any) => r.uri), ['docs://kilotest/overview']);
+  const read = await client.readResource({uri: 'docs://kilotest/overview'});
+  assert.equal(read.contents[0]?.mimeType, 'text/plain');
+  assert.ok((read.contents[0] as any).text.includes('front-end quality'));
+  await client.close();
+  await server.close();
+});
+
 test('listReports handler returns content and structuredContent', async () => {
   const server = createMCPServer();
   const countBefore = getToolCallCount('listReports');
@@ -258,6 +292,8 @@ test('handleMCP responds to initialize with server info', async () => {
     assert.equal(res.statusCode, 200);
     const result = parseSSEResult(res.body);
     assert.equal(result.result.serverInfo.name, 'Kilotest');
+    assert.ok(result.result.serverInfo.description.includes('front-end quality'));
+    assert.ok(result.result.instructions.includes('front-end quality'));
     assert.equal(result.result.protocolVersion, '2025-06-18');
   }
   finally {
@@ -265,7 +301,7 @@ test('handleMCP responds to initialize with server info', async () => {
   }
 });
 
-test('handleMCP lists all 8 tools via tools/list', async () => {
+test('handleMCP lists all 9 tools via tools/list', async () => {
   const server = await startMCPServer();
   try {
     const port = server.address().port;
@@ -273,8 +309,9 @@ test('handleMCP lists all 8 tools via tools/list', async () => {
     assert.equal(res.statusCode, 200);
     const result = parseSSEResult(res.body);
     const toolNames = result.result.tools.map((t: any) => t.name);
-    assert.equal(toolNames.length, 8);
+    assert.equal(toolNames.length, 9);
     assert.deepEqual(toolNames, [
+      'getKilotestOverview',
       'listReports',
       'listIssues',
       'listViolators',

package/mcp.ts

@@ -41,8 +41,28 @@ import {
 
 export const mcpPath = '/mcp';
 
+// Shared statement of the Kilotest domain and data hierarchy, repeated in every tool
+// description, in the server instructions, and in the getKilotestOverview tool description,
+// because some MCP clients do not propagate server-level instructions or the server
+// description to their models.
+const sharedContext = 'Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as report, then issue, then violator element, then diagnosis.';
+
+// Detailed overview of the Kilotest domain, data hierarchy, and tool workflow, returned by
+// the getKilotestOverview tool and served as the docs://kilotest/overview resource.
+const kilotestOverview = [
+  'Kilotest tests web pages for front-end quality: accessibility, usability, and standards conformity.',
+  'Kilotest integrates an ensemble of twelve independent rule engines to test a web page and stores the results as a structured report.',
+  'Results are organized as a hierarchy. A report contains issues. An issue has violators: elements of the tested page reported as exhibiting the issue. A violator has diagnoses: explanations from rule engines of how the element exhibited the issue.',
+  'Typical workflow: call the listReports tool to learn whether a report about the page already exists. If it does, drill down with the listIssues, listViolators, and listDiagnoses tools, or retrieve the entire report with the getReport tool. If no report exists, request a test with the requestTest tool. If the latest report is obsolete, request a retest with the requestRetest tool.',
+  'More documentation is available at https://kilotest.com/llms.txt and https://kilotest.com/llms-full.txt.'
+].join('\n\n');
+
 // FUNCTIONS
 
+// Returns a tool description consisting of the tool-specific summary followed by the shared
+// Kilotest domain context.
+const toolDoc = (summary: string): string => `${summary} ${sharedContext}`;
+
 // Creates and returns an McpServer with Kilotest tools registered.
 export const createMCPServer = (): McpServer => {
   const server = new McpServer({
@@ -51,16 +71,34 @@ export const createMCPServer = (): McpServer => {
     description: 'Tools that test web pages for front-end quality (accessibility, usability, and standards conformity) and make test results available'
   },
   {
-    instructions: 'Use the listReports tool to start. If it shows that there is a report available about the page you want facts about, drill down with the listIssues, listViolators, and listDiagnoses tools. If not, use the requestTest tool to request that the page be tested. If the latest report about the page is obsolete, use the requestRetest tool to request that the page be retested.'
+    instructions: `${sharedContext} Use the listReports tool to start. If it shows that there is a report available about the page you want facts about, drill down with the listIssues, listViolators, and listDiagnoses tools. If not, use the requestTest tool to request that the page be tested. If the latest report about the page is obsolete, use the requestRetest tool to request that the page be retested. For detailed documentation, call the getKilotestOverview tool.`
   });
+  server.registerTool(
+    'getKilotestOverview',
+    {
+      description: toolDoc('Explain what Kilotest is, what its tools do, and how its results are structured.'),
+      inputSchema: {},
+      annotations: {
+        title: toolDoc('Explain what Kilotest is, what its tools do, and how its results are structured.'),
+        readOnlyHint: true,
+        idempotentHint: true,
+        destructiveHint: false,
+        openWorldHint: false
+      }
+    },
+    async () => {
+      await recordMetric('mcpToolCalls', 'getKilotestOverview');
+      return {content: [{type: 'text', text: kilotestOverview}]};
+    }
+  );
   server.registerTool(
     'listReports',
     {
-      description: 'Provide basics about all available reports.',
+      description: toolDoc('Provide basics about all available reports.'),
       inputSchema: {},
       outputSchema: listReportsResponseSchema,
       annotations: {
-        title: 'Provide basics about all available reports.',
+        title: toolDoc('Provide basics about all available reports.'),
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
@@ -76,11 +114,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'listIssues',
     {
-      description: 'Provide details about one report, including basics about the issues reported in it.',
+      description: toolDoc('Provide details about one report, including basics about the issues reported in it.'),
       inputSchema: listIssuesSchema,
       outputSchema: listIssuesResponseSchema,
       annotations: {
-        title: 'Provide details about one report, including basics about the issues reported in it.',
+        title: toolDoc('Provide details about one report, including basics about the issues reported in it.'),
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
@@ -96,11 +134,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'listViolators',
     {
-      description: 'Provide details about one issue in one report, including basics about the elements of the tested page that were reported as exhibiting the issue.',
+      description: toolDoc('Provide details about one issue in one report, including basics about the elements of the tested page that were reported as exhibiting the issue.'),
       inputSchema: listViolatorsSchema,
       outputSchema: listViolatorsResponseSchema,
       annotations: {
-        title: 'Provide details about one issue in one report, including basics about the elements of the tested page that were reported as exhibiting the issue.',
+        title: toolDoc('Provide details about one issue in one report, including basics about the elements of the tested page that were reported as exhibiting the issue.'),
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
@@ -116,11 +154,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'listDiagnoses',
     {
-      description: 'Provide details about one element reported as exhibiting one issue in one report, including the diagnoses provided by rule engines about how the element exhibited the issue.',
+      description: toolDoc('Provide details about one element reported as exhibiting one issue in one report, including the diagnoses provided by rule engines about how the element exhibited the issue.'),
       inputSchema: listDiagnosesSchema,
       outputSchema: listDiagnosesResponseSchema,
       annotations: {
-        title: 'Provide details about one element reported as exhibiting one issue in one report, including the diagnoses provided by rule engines about how the element exhibited the issue.',
+        title: toolDoc('Provide details about one element reported as exhibiting one issue in one report, including the diagnoses provided by rule engines about how the element exhibited the issue.'),
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
@@ -136,11 +174,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'getReport',
     {
-      description: 'Get one full report in JSON.',
+      description: toolDoc('Get one full report in JSON.'),
       inputSchema: getReportSchema,
       outputSchema: getReportResponseSchema,
       annotations: {
-        title: 'Get one full report in JSON.',
+        title: toolDoc('Get one full report in JSON.'),
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
@@ -156,11 +194,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'requestTest',
     {
-      description: 'Process my request to test a page about which no report is available yet.',
+      description: toolDoc('Process my request to test a page about which no report is available yet.'),
       inputSchema: requestTestSchema,
       outputSchema: requestTestResponseSchema,
       annotations: {
-        title: 'Process my request to test a page about which no report is available yet.',
+        title: toolDoc('Process my request to test a page about which no report is available yet.'),
         readOnlyHint: false,
         idempotentHint: false,
         destructiveHint: false,
@@ -176,11 +214,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'requestRetest',
     {
-      description: 'Process my request to retest a page about which a report is available.',
+      description: toolDoc('Process my request to retest a page about which a report is available.'),
       inputSchema: requestRetestSchema,
       outputSchema: requestRetestResponseSchema,
       annotations: {
-        title: 'Process my request to retest a page about which a report is available.',
+        title: toolDoc('Process my request to retest a page about which a report is available.'),
         readOnlyHint: false,
         idempotentHint: false,
         destructiveHint: false,
@@ -196,11 +234,11 @@ export const createMCPServer = (): McpServer => {
   server.registerTool(
     'requestFeature',
     {
-      description: 'Process my request to add or improve a feature.',
+      description: toolDoc('Process my request to add or improve a feature.'),
       inputSchema: requestFeatureSchema,
       outputSchema: requestFeatureResponseSchema,
       annotations: {
-        title: 'Process my request to add or improve a feature.',
+        title: toolDoc('Process my request to add or improve a feature.'),
         readOnlyHint: false,
         idempotentHint: false,
         destructiveHint: false,
@@ -213,6 +251,18 @@ export const createMCPServer = (): McpServer => {
       return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
+  server.registerResource(
+    'kilotest-overview',
+    'docs://kilotest/overview',
+    {
+      title: 'Kilotest overview',
+      description: `What Kilotest is and how its tools and results are organized. ${sharedContext}`,
+      mimeType: 'text/plain'
+    },
+    async () => ({
+      contents: [{uri: 'docs://kilotest/overview', mimeType: 'text/plain', text: kilotestOverview}]
+    })
+  );
   return server;
 };
 // Handles an MCP request.

package/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Kilotest API
-  description: 'Kilotest is an ensemble testing and reporting service for front-end web quality. It uses an ensemble of 12 rule engines to test public web pages for front-end quality (accessibility, usability, and standards conformity). Kilotest acts as a web server for human users, an MCP server for AI platforms, and an API for programmatic access. With this API you can request that a page be tested or retested, discover available reports, incrementally retrieve facts from a report: from what reports are available, to what issues were reported in one report, to what elements violated one issue, to what diagnoses rule engines gave for one violation.'
+  description: 'Kilotest is an ensemble testing and reporting service for front-end web quality. It uses an ensemble of 12 rule engines to test web pages for front-end quality (accessibility, usability, and standards conformity). Kilotest acts as a web server for human users, an MCP server for AI platforms, and an API for programmatic access. With this API you can request that a page be tested or retested, discover available reports, incrementally retrieve facts from a report: from what reports are available, to what issues were reported in one report, to what elements violated one issue, to what diagnoses rule engines gave for one violation.'
   version: 2.1.0
   license:
     name: MIT
@@ -822,7 +822,7 @@ paths:
               properties:
                 description:
                   type: string
-                  description: 10- to 100-character description of the page conforming to the naming convention used in the listReports output
+                  description: 1- to 100-character description of the page conforming to the naming convention used in the listReports output
                 URL:
                   type: string
                   description: 12- to 300-character URL of the page, including the https:// scheme and any query
@@ -860,7 +860,7 @@ paths:
                         properties:
                           description:
                             type: string
-                            description: 10- to 100-character description of the page conforming to the naming convention used in the listReports output
+                            description: 1- to 100-character description of the page conforming to the naming convention used in the listReports output
                           URL:
                             type: string
                             description: 12- to 300-character URL of the page, including the https:// scheme and any query
@@ -1099,7 +1099,7 @@ paths:
               properties:
                 feature:
                   type: string
-                  description: description of requested feature improvement or new feature
+                  description: 20- to 1000-character description of requested feature improvement or new feature
               required:
                 - feature
       responses:
@@ -1129,7 +1129,7 @@ paths:
                         properties:
                           feature:
                             type: string
-                            description: description of requested feature improvement or new feature
+                            description: 20- to 1000-character description of requested feature improvement or new feature
                         required:
                           - feature
                         additionalProperties: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "51.1.0",
+  "version": "55.0.0",
   "description": "Ensemble testing for front-end web quality",
   "type": "module",
   "main": "index.ts",
@@ -38,6 +38,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "*",
     "dotenv": "*",
+    "ipaddr.js": "*",
     "testaro-issues": "*",
     "zod": "*"
   },

package/scripts/generate-openapi.ts

@@ -58,7 +58,7 @@ const generate = () => {
     openapi: '3.1.0',
     info: {
       title: 'Kilotest API',
-      description: 'Kilotest is an ensemble testing and reporting service for front-end web quality. It uses an ensemble of 12 rule engines to test public web pages for front-end quality (accessibility, usability, and standards conformity). Kilotest acts as a web server for human users, an MCP server for AI platforms, and an API for programmatic access. With this API you can request that a page be tested or retested, discover available reports, incrementally retrieve facts from a report: from what reports are available, to what issues were reported in one report, to what elements violated one issue, to what diagnoses rule engines gave for one violation.',
+      description: 'Kilotest is an ensemble testing and reporting service for front-end web quality. It uses an ensemble of 12 rule engines to test web pages for front-end quality (accessibility, usability, and standards conformity). Kilotest acts as a web server for human users, an MCP server for AI platforms, and an API for programmatic access. With this API you can request that a page be tested or retested, discover available reports, incrementally retrieve facts from a report: from what reports are available, to what issues were reported in one report, to what elements violated one issue, to what diagnoses rule engines gave for one violation.',
       version,
       license: {
         name: license,