@jrpool/kilotest 38.1.0 → 39.0.1

package/llms.txt

@@ -8,20 +8,25 @@ There is a [detailed explanation of Kilotest and its capabilities for LLMs](http
 
 ## API
 
-- [Get summaries of reports about a specified web page](/api/target)
-- [List all available reports](/api/reportList)
-- Summarize one report: `/api/reportSummary/{timeStamp}/{jobID}`
-- Get details about one issue from one report: `/api/reportIssue/{issueID}/{timeStamp}/{jobID}`
-- Recommend testing of a web page: `/api/testRecForm` (requires `POST` request)
+- [List all available reports](/api/listReports)
+- List all issues in one report: `/api/listIssues/{timeStamp}/{jobID}`
+- List all elements exhibiting one issue in one report: `/api/listViolators/{issueID}/{timeStamp}/{jobID}`
+- List all diagnoses of one element exhibiting one issue in one report: `/api/listDiagnoses/{catalogIndex}/{issueID}/{timeStamp}/{jobID}`
+- Get one full report in JSON: `/api/getReport/{timeStamp}/{jobID}`
+- Request testing of a web page: `/api/requestTest` (requires `POST` request)
+- Request retesting of a web page: `/api/requestRetest/{timeStamp}/{jobID}` (requires `POST` request)
+- Request adding or improving a feature: `/api/requestFeature` (requires `POST` request)
 - [OpenAPI specification for Kilotest](https://kilotest.com/openapi.yaml)
 
 ## Web UI
 
-- [Summarize test results for all tested pages](https://kilotest.com/targets.html)
-- Provide statistics about issues reported in one job: `https://kilotest.com/reportIssues.html/{timeStamp}/{jobID}`
-- Provide details about one issue reported in one job: `https://kilotest.com/reportIssue.html/{issueID}/{timeStamp}/{jobID}`
-- Provide diagnoses about one issue exhibited by one HTML element in one job: `https://kilotest.com/diagnoses.html/{issueID}/{timeStamp}/{jobID}/{catalogIndex}`
-- [Provide statistics about frequently reported issues across all pages](https://kilotest.com/issues.html)
-- [Recommend testing of a web page](https://kilotest.com/testRecForm.html)
+- [List all available reports](https://kilotest.com/targets.html)
+- List all issues in one report: `https://kilotest.com/reportIssues.html/{timeStamp}/{jobID}`
+- List all elements exhibiting one issue in one report: `https://kilotest.com/reportIssue.html/{issueID}/{timeStamp}/{jobID}`
+- List all diagnoses of one element exhibiting one issue in one report: `https://kilotest.com/diagnoses.html/{issueID}/{timeStamp}/{jobID}/{catalogIndex}`
+- Get one full report in JSON: `https://kilotest.com/fullReport.json/{timeStamp}/{jobID}`
+- [Request testing of a web page](https://kilotest.com/testRecForm.html)
+- Request retesting of a web page: `https://kilotest.com/retestRecForm.html/{timeStamp}/{jobID}`
 - [List the operations that Kilotest managers are authorized to request](https://kilotest.com/manage.html)
+- [Provide statistics about frequently reported issues across all pages](https://kilotest.com/issues.html)
 - [Tutorial, “Accessibility testing strategies”](https://kilotest.com/tutorial.html)

package/mcp.js

@@ -9,13 +9,32 @@ const {McpServer} = require('@modelcontextprotocol/sdk/server/mcp.js');
 const {StreamableHTTPServerTransport} = require(
   '@modelcontextprotocol/sdk/server/streamableHttp.js'
 );
-const {z} = require('zod');
-const {isReportAvailable, isURL} = require('./util');
-const targetAPI = require('./target/api');
-const reportListAPI = require('./api/reportList');
-const reportSummaryAPI = require('./api/reportSummary');
-const reportIssueAPI = require('./reportIssue/api');
-const testRecFormAPI = require('./testRecForm/api');
+const getReportAPI = require('./api/getReport');
+const listReportsAPI = require('./api/listReports');
+const listIssuesAPI = require('./api/listIssues');
+const listViolatorsAPI = require('./api/listViolators');
+const listDiagnosesAPI = require('./api/listDiagnoses');
+const requestTestAPI = require('./api/requestTest');
+const requestRetestAPI = require('./api/requestRetest');
+const requestFeatureAPI = require('./api/requestFeature');
+
+const {
+  getReportSchema,
+  listIssuesSchema,
+  listViolatorsSchema,
+  listDiagnosesSchema,
+  requestTestSchema,
+  requestRetestSchema,
+  requestFeatureSchema,
+  listReportsResponseSchema,
+  listIssuesResponseSchema,
+  listViolatorsResponseSchema,
+  listDiagnosesResponseSchema,
+  getReportResponseSchema,
+  requestTestResponseSchema,
+  requestRetestResponseSchema,
+  requestFeatureResponseSchema
+} = require('./api/schemas');
 
 // CONSTANTS
 
@@ -25,119 +44,164 @@ exports.mcpPath = '/mcp';
 
 // Creates and returns an McpServer with Kilotest tools registered.
 const createMCPServer = () => {
-  const server = new McpServer({name: 'Kilotest', version: '1.0.0'});
+  const server = new McpServer({
+    name: 'Kilotest',
+    version: '2.0.0',
+    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.'
+  });
   server.registerTool(
-    'summarizeQualityOfMatchingWebPages',
+    'listReports',
     {
-      description: 'Returns summary data from every available Kilotest report about the front-end quality (i.e. accessibility, usability, and standards conformity) of web pages that match the description or hostname fragment of a web page that you have provided. Matching is case-insensitive and succeeds if the page property either is included by or includes the specified fragment.',
-      inputSchema: {
-        description: z.string().describe('All or part of a description of the web page.'),
-        hostname: z.string().describe('All or part of the hostname of the URL of the web page.')
-      },
+      description: 'Provide basics about all available reports.',
+      inputSchema: {},
+      outputSchema: listReportsResponseSchema,
       annotations: {
-        title: 'Summarize the quality of matching web pages',
+        title: 'Provide basics about all available reports.',
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
         openWorldHint: false
       }
     },
-    async ({description, hostname}) => {
-      const result = await targetAPI.response([description, hostname]);
-      return {content: [{type: 'text', text: JSON.stringify(result)}]};
+    async () => {
+      const result = await listReportsAPI.response();
+      return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
   server.registerTool(
-    'listAllAvailableReports',
+    'listIssues',
     {
-      description: 'Returns a list of all available Kilotest reports; each report describes the results of a job that tested one web page for front-end quality (i.e. accessibility, usability, and standards conformity).',
-      inputSchema: {},
+      description: 'Provide details about one report, including basics about the issues reported in it.',
+      inputSchema: listIssuesSchema,
+      outputSchema: listIssuesResponseSchema,
       annotations: {
-        title: 'List all available reports',
+        title: 'Provide details about one report, including basics about the issues reported in it.',
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
         openWorldHint: false
       }
     },
-    async () => {
-      const result = await reportListAPI.response();
-      return {content: [{type: 'text', text: JSON.stringify(result)}]};
+    async ({timeStamp, jobID}) => {
+      const result = await listIssuesAPI.response([timeStamp, jobID]);
+      return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
   server.registerTool(
-    'summarizeOneReport',
+    'listViolators',
     {
-      description: 'Returns a summary of a specified Kilotest report about the front-end quality (i.e. accessibility, usability, and standards conformity) of a web page. The required timeStamp and jobID parameters identify the report and are obtained from a listAllAvailableReports response.',
-      inputSchema: {
-        timeStamp: z.string().describe('Timestamp of the report in YYMMDDTHHMM format, e.g. 260503T0432'),
-        jobID: z.string().describe('Job identifier, e.g. x9z')
-      },
+      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.',
+      inputSchema: listViolatorsSchema,
+      outputSchema: listViolatorsResponseSchema,
       annotations: {
-        title: 'Summarize one report',
+        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.',
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
         openWorldHint: false
       }
     },
-    async ({timeStamp, jobID}) => {
-      const result = await reportSummaryAPI.response([timeStamp, jobID]);
-      return {content: [{type: 'text', text: JSON.stringify(result)}]};
+    async ({issueID, timeStamp, jobID}) => {
+      const result = await listViolatorsAPI.response([issueID, timeStamp, jobID]);
+      return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
   server.registerTool(
-    'describeOneIssueFromOneReport',
+    'listDiagnoses',
     {
-      description: 'Returns data from a specified Kilotest report about one of the issues for the front-end quality (i.e. accessibility, usability, and standards conformity) of a web page. The required issueID, timeStamp, and jobID parameters identify the issue and the report and are obtained from a summarizeOneReport response.',
-      inputSchema: {
-        issueID: z.string().describe('Issue identifier, e.g. contrastPoor'),
-        timeStamp: z.string().describe('Report timestamp in YYMMDDTHHMM format, e.g. 260503T0432'),
-        jobID: z.string().describe('Job identifier, e.g. x9z')
-      },
+      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.',
+      inputSchema: listDiagnosesSchema,
+      outputSchema: listDiagnosesResponseSchema,
       annotations: {
-        title: 'Describe one issue from one report',
+        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.',
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
         openWorldHint: false
       }
     },
-    async ({issueID, timeStamp, jobID}) => {
-      const result = await reportIssueAPI.response([issueID, timeStamp, jobID]);
-      return {content: [{type: 'text', text: JSON.stringify(result)}]};
+    async ({catalogIndex, issueID, timeStamp, jobID}) => {
+      const result = await listDiagnosesAPI.response([catalogIndex, issueID, timeStamp, jobID]);
+      return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
+    }
+  );
+  server.registerTool(
+    'getReport',
+    {
+      description: 'Get one full report in JSON.',
+      inputSchema: getReportSchema,
+      outputSchema: getReportResponseSchema,
+      annotations: {
+        title: 'Get one full report in JSON.',
+        readOnlyHint: true,
+        idempotentHint: true,
+        destructiveHint: false,
+        openWorldHint: false
+      }
+    },
+    async ({timeStamp, jobID}) => {
+      const result = await getReportAPI.response([timeStamp, jobID]);
+      return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
   server.registerTool(
-    'recommendQualityTestingOfOneWebPage',
+    'requestTest',
     {
-      description: 'Recommends a web page for Kilotest to test for front-end quality (i.e. accessibility, usability, and standards conformity). Do not call this tool until after you call listAllAvailableReports to check whether a report about the page, or a related page that satisfies your requirements, is available and to understand the naming conventions for pages.',
-      inputSchema: {
-        'description of the web page': z.string().describe('Short description of the page, following the naming conventions visible in the listAllAvailableReports response'),
-        'URL of the web page': z.string().describe('Full HTTPS URL of the page to test'),
-        'reason for testing the web page': z.string().describe('Reason for recommending this page for testing')
-      },
+      description: 'Process my request to test a page about which no report is available yet.',
+      inputSchema: requestTestSchema,
+      outputSchema: requestTestResponseSchema,
       annotations: {
-        title: 'Recommend quality testing of one web page',
+        title: 'Process my request to test a page about which no report is available yet.',
         readOnlyHint: false,
         idempotentHint: false,
         destructiveHint: false,
         openWorldHint: false
       }
     },
-    async ({
-      'description of the web page': what,
-      'URL of the web page': url,
-      'reason for testing the web page': why
-    }) => {
-      if (!isURL(url)) {
-        return {content: [{type: 'text', text: JSON.stringify({error: 'Invalid URL'})}], isError: true};
+    async ({description, URL, reason}) => {
+      const result = await requestTestAPI.response([description, URL, reason]);
+      return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
+    }
+  );
+  server.registerTool(
+    'requestRetest',
+    {
+      description: '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.',
+        readOnlyHint: false,
+        idempotentHint: false,
+        destructiveHint: false,
+        openWorldHint: false
       }
-      if (await isReportAvailable(what, url)) {
-        return {content: [{type: 'text', text: JSON.stringify({error: 'A report about the page is already available'})}], isError: true};
+    },
+    async ({timeStamp, jobID, reason}) => {
+      const result = await requestRetestAPI.response([timeStamp, jobID, reason]);
+      return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
+    }
+  );
+  server.registerTool(
+    'requestFeature',
+    {
+      description: 'Process my request to add or improve a feature.',
+      inputSchema: requestFeatureSchema,
+      outputSchema: requestFeatureResponseSchema,
+      annotations: {
+        title: 'Process my request to add or improve a feature.',
+        readOnlyHint: false,
+        idempotentHint: false,
+        destructiveHint: false,
+        openWorldHint: false
       }
-      const result = await testRecFormAPI.response(what, url, why);
-      return {content: [{type: 'text', text: JSON.stringify(result)}]};
+    },
+    async ({request}) => {
+      const result = await requestFeatureAPI.response([request]);
+      return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
   return server;