@jrpool/kilotest 63.1.7 → 63.2.0

package/content.ts

@@ -0,0 +1,12 @@
+/*
+  content.ts
+  Canonical prose describing what Kilotest is and does, reused verbatim by mcp.ts, scripts/generate-openapi.ts, and scripts/generate-lhm.ts, so the sentences are written once instead of being hand-copied into mcp.ts, lhm.plugin.json, llms.txt, and openapi.yaml.
+*/
+
+// CONSTANTS
+
+// Brief description of the Kilotest tool collection. Used as the MCP server description and as lhm.plugin.json’s top-level description. No length limit.
+export const collectionDescription = 'Tools that test web pages with an ensemble of 12 rule engines for front-end quality (accessibility, usability, and W3C web standards, including HTML, CSS, ARIA, and WCAG)';
+
+// Description of the Kilotest domain and data hierarchy. Used as (1) the server instructions, (2) the opening paragraph of llms.txt, (3) the start of the openapi.yaml info.description, and (4) the getKilotestOverview tool description (but not part of the other tool descriptions, to avoid diluting how models read each tool), because some MCP clients do not propagate server-level instructions or the server description to their models.
+export const sharedContext = 'Kilotest integrates an ensemble of 12 rule engines, with about 1,300 rules, to test web pages for front-end quality (accessibility, usability, and W3C web standards, including HTML, CSS, ARIA, and WCAG). Each test job generates a standardized report describing which elements violated which rules and grouping the violations into about 380 issues. Kilotest can list the tested pages, the reports about each page, the issues in each report, the violators of each issue, and the diagnoses of each violation. Kilotest also accepts requests to test pages not yet tested and to retest already tested pages.';

package/docs/AI-TOOLS.md

@@ -40,6 +40,8 @@ The internal features that make Kilotest a collection of tools for language mode
 
 The external features that support the use of Kilotest as a collection of AI tools are:
 
+### Registrations
+
 - A [pull request](https://github.com/public-apis/public-apis/pull/6346/changes) to add Kilotest to the list of public APIs in the `public-apis` repository.
 - An [issue](https://github.com/APIs-guru/openapi-directory/issues/2677) to add Kilotest to `openapi-directory`.
 - A [pull request](https://github.com/w3c/wai-evaluation-tools-list/pull/1153) to add Kilotest to the WAI evaluation tools list.
@@ -51,17 +53,27 @@ The external features that support the use of Kilotest as a collection of AI too
 - Registration of Kilotest with the [RapidAPI](https://rapidapi.com/jrpool/api/kilotest/playground/apiendpoint_0f03577a-ff9a-472a-a0ed-533bd198981a) Hub.
 - Registration of Kilotest with the [LobeHub MCP Market](https://lobehub.com/mcp) (identifier: `jrpool-kilotest`), enabled with an `lhm.plugin.json` file.
 - Registration of Kilotest with [MCPTry](https://mcptry.com/servers/io.github.jrpool/kilotest).
+- Registration of the MCP server as a community connector in the [Claude directory of plugins and connectors](https://claude.ai/directory/kilotest).
+- Registration of Kilotest and its sitemap at [Google Search Console](https://search.google.com/search-console?resource_id=sc-domain:kilotest.com) and [Bing Webmaster Tools](https://www.bing.com/webmasters/home?siteUrl=https://kilotest.com/).
+- Submission of the MCP server to `mcp.directory`.
+- Submission of the MCP server to [MCP.so](https://mcp.so/). The submission is in review.
+
+### Deployment
+
 - Deployment of an MCP server in HTTP mode on the Kilotest service host.
-- Submission of the MCP server to the [Claude directory of plugins and connectors](https://claude.ai/directory/manage).
+
+### Local configuration
+
 - Configuration of Claude Desktop on the local development host and the `claude.ai` web application to connect Claude Desktop models to the Kilotest MCP server. The configuration was performed in the UI of each platform with the addition of Kilotest as a _connector_. The user used the `Customize/Connectors/Add connector/Add custom connector` interface, providing these data before activating the `Add` button:
 
   - Name: Kilotest
   - Remote MCP server URL: `https://kilotest.com/mcp`
 
+### Documentation
+
 - MCP-related topics added to the [repository details](https://github.com/jrpool/kilotest).
-- An [MCP Registry badge](https://registry.modelcontextprotocol.io/v0/servers?search=kilotest) added to the `README.md` file.
+- Registry badges added to the `README.md` file.
 - A link to the MCP server on the `README.md` page of the [`testaro-issues`](https://github.com/jrpool/testaro-issues) repository.
-- Registration of Kilotest and its sitemap at [Google Search Console](https://search.google.com/search-console?resource_id=sc-domain:kilotest.com) and [Bing Webmaster Tools](https://www.bing.com/webmasters/home?siteUrl=https://kilotest.com/).
 
 ## Required maintenance
 
@@ -69,7 +81,7 @@ The maintenance routine is prescribed in the [README.md](../README.md) file.
 
 Releasing a new version is a two-script procedure:
 
-- On a feature branch, commit all substantive changes, then execute `npm run prePR -- <level>` (`major`, `minor`, or `patch`). The script bumps `package.json` and `package-lock.json`, regenerates `openapi.yaml`, `openapi-3.0.yaml`, and the versions of `server.json` and `lhm.plugin.json` by explicitly running `npm run generate`, commits and pushes the result, and records the branch name for the next step.
+- On a feature branch, commit all substantive changes, then execute `npm run prePR -- <level>` (`major`, `minor`, or `patch`). The script bumps `package.json` and `package-lock.json`, regenerates `openapi.yaml`, `openapi-3.0.yaml`, and the descriptions, schemas, and versions of `server.json` and `lhm.plugin.json` by explicitly running `npm run generate`, commits and pushes the result, and records the branch name for the next step.
 - Submit a pull request and merge it to `main` (triggers `publish-mcp.yml`, which publishes `server.json` to the MCP Registry).
 - Execute `npm run postPR`. The script checks out and pulls `main`, verifies that the merge landed, publishes to npm, updates the LobeHub listing via `npm run publish:lhm`, deletes the feature branch, and prunes remote-tracking branches. If the LobeHub update fails, retry it alone with `npm run publish:lhm`.
 
@@ -84,8 +96,9 @@ A change to the tool or API contract (tool names, parameter names, schemas, resp
 - `openapi.yaml`: regenerated automatically by the `version` hook during `npm run prePR`; never edit it by hand.
 - `openapi-3.0.yaml`: an OpenAPI 3.0.3 conversion of `openapi.yaml`, regenerated by the same hook, for registries whose importers reject 3.1 documents; never edit it by hand.
 - `server.json`: contains only the server descriptor (name, description, repository, remotes, version), no tool schemas. Its version is synced by `update-versions.ts`; edit it manually only if the server description or remote URL changes.
-- `lhm.plugin.json`: embeds every tool’s input and output schema and its descriptions, in the LobeHub manifest format. It is hand-maintained, not generated, so transform it to match `api/schemas.ts` and `mcp.ts` whenever the contract changes.
-- `llms.txt`, `llms-full.txt`, `capability.md`, `README.md`: hand-maintained; search them for stale parameter and path names after a contract change.
+- `lhm.plugin.json`: embeds every tool’s input and output schema and its descriptions, in the LobeHub manifest format. Its `description` and every tool’s `description`, `inputSchema`, `outputSchema`, and `annotations` are regenerated from `mcp.ts`/`api/schemas.ts` by `scripts/generate-lhm.ts` (run by `npm run generate`, part of `npm run prePR`); never edit those fields by hand. The remaining fields (`author`, `cloudEndpoint`, `homepage`, `identifier`, `name`, `prompts`, `resources`, `tags`, `version`, and each tool’s `execution` block) have no canonical source elsewhere and are still edited manually. See `docs/decisions/010-content-generation.md`.
+- `content.ts`: canonical prose shared verbatim by `mcp.ts`, `scripts/generate-openapi.ts`, and `scripts/generate-lhm.ts`. Also hand-check `llms.txt`’s opening paragraph, which is supposed to match `content.ts`’s `sharedContext` verbatim but is not generated.
+- `llms-full.txt`, `capability.md`, `README.md`, `docs/openai-plugin/skills/kilotest-overview/SKILL.md`: hand-maintained, intentionally paraphrased rather than copied verbatim; search them for stale parameter and path names after a contract change.
 
 #### External registries that update themselves, needing no maintainer action
 
@@ -123,7 +136,7 @@ To-dos recommended by Claude Sonnet 5 Medium on Devin:
 
 - **No content/backlink outreach.** Registrations are passive listings; there's no blog post, Show HN, or subreddit post (r/modelcontextprotocol, r/accessibility, r/webdev) building external backlinks and social-discovery signal, which the doc's own "difficult problem…lack of standardization" framing suggests is exactly the gap left for the **human**-driven parts of discoverability.
 
-- **Other directories not yet targeted.** The [mcp.so](https://mcp.so/submit) directory offers a free tier but steers submitters toward a $39 paid listing; deferred as a commercial decision. The Docker MCP Catalog is not a fit because it requires stdio transport and a Dockerfile, and Kilotest is streamable-http.
+- **Other directories not yet targeted.** The Docker MCP Catalog is not a fit because it requires stdio transport and a Dockerfile, and Kilotest is streamable-http.
 
 - **Client-onboarding friction isn't documented.** Some MCP clients need the `mcp-remote` npx bridge to use a remote streamable-HTTP server like Kilotest's. Ready-made Claude Desktop/Cursor/Windsurf config instructions added to the AI tutorial would convert "discovered" into "used" faster, since case 3 of your use cases assumes a technically savvy discoverer but not all users are.
 

package/docs/decisions/010-content-generation.md

@@ -0,0 +1,32 @@
+---
+date: 2026-11-04
+status: accepted
+---
+
+# Generating duplicated prose and schemas instead of hand-copying them
+
+## Context and problem
+
+`mcp.ts`, `lhm.plugin.json`, `llms.txt`, and `scripts/generate-openapi.ts` each carried their own hand-typed copy of the same sentence describing what Kilotest is (“Kilotest integrates an ensemble of 12 rule engines…”). The four copies had already drifted: `llms.txt` had an accidentally duplicated clause and said “test job” where `lhm.plugin.json` said “test session”, and `generate-openapi.ts`’s `info.description` was a fourth, independently worded variant. Separately, `lhm.plugin.json` hand-transcribes every MCP tool’s `inputSchema`, `outputSchema`, `description`, and `annotations` from `mcp.ts`/`api/schemas.ts`, a step `docs/AI-TOOLS.md` already flagged as “hand-maintained, not generated…transform it…whenever the contract changes.” Regenerating `lhm.plugin.json` from the live registrations in `mcp.ts` found that this hand-transcription had already gone stale: several tool descriptions no longer matched `mcp.ts`, and `listDiagnoses`’s output schema was missing two fields (`identifier of the rule engine` and `how to report that you disagree with this diagnosis`) that the real tool returns.
+
+## Considered options
+
+- Status quo: keep hand-copying prose and schemas into each surface, relying on the `docs/AI-TOOLS.md` “Contract changes” checklist to remind a maintainer to update every copy.
+- Add a lint/test check that only flags byte-for-byte differences between the copies, without removing the duplication itself.
+- Generate the duplicated surfaces from canonical sources, extending the pattern the project already uses for `package.json`’s `version` (copied into `server.json`/`lhm.plugin.json` by `scripts/update-versions.ts`) and for `api/schemas.ts`/`api/routes.ts` (rendered into `openapi.yaml`/`openapi-3.0.yaml` by `scripts/generate-openapi.ts`).
+
+## Decision
+
+Generate, rather than hand-copy, wherever the same sentence or schema is supposed to appear verbatim in more than one file, extending the project's existing generate-from-canonical-source pattern:
+
+- `content.ts` is the new single source of truth for prose that must be identical across surfaces (`collectionDescription`, the one-line tool-collection description; `sharedContext`, the domain/data-hierarchy paragraph). `mcp.ts` and `scripts/generate-openapi.ts` import it instead of defining their own copies.
+- `scripts/generate-lhm.ts` regenerates `lhm.plugin.json`’s top-level `description` and every tool’s `description`, `inputSchema`, `outputSchema`, and `annotations` from `content.ts` and the same tool registrations `mcp.ts` creates at runtime (via `createMCPServer()`) and the same Zod schemas `api/schemas.ts` exports, using `z.toJSONSchema`. Fields with no canonical source elsewhere in the repository (`author`, `cloudEndpoint`, `homepage`, `identifier`, `name`, `prompts`, `resources`, `tags`, `version`, and each tool’s `execution` block) are left untouched by the generator.
+- `scripts/generate-lhm.ts` is wired into `npm run generate`, alongside `generate-openapi.ts` and `update-versions.ts`, so `prePR.ts` regenerates it before every release the same way it already regenerates `openapi.yaml`.
+- `llms.txt`’s opening paragraph is hand-corrected to match `content.ts`’s `sharedContext` verbatim; it is not generated, because the rest of the file (and `llms-full.txt`, `capability.md`, `README.md`, and the OpenAI-plugin `SKILL.md`) intentionally paraphrase for their audience rather than repeating the same sentence, so forcing byte-identical text there would reduce documentation quality for no benefit. These remain on the existing hand-maintained checklist in `docs/AI-TOOLS.md`.
+- Publishing remains separate from generation, as it already was for `openapi.yaml`/`server.json`: `npm run generate` produces correct file content locally, and `npm run publish:lhm` still performs the manual, OAuth-gated push to LobeHub.
+
+The byte-for-byte lint-check option was rejected as a primary strategy because it would still require a maintainer to hand-edit three or four files in sync on every contract change; it only catches drift after the fact rather than removing the duplication that causes it.
+
+### Confirmation
+
+To confirm the correctness of the implementation, run `npm run generate`, verify `lhm.plugin.json`, `openapi.yaml`, and `openapi-3.0.yaml` are unchanged (a clean `git diff`), and run `npm test` and `npm run lint` to confirm nothing else regressed.

package/lhm.plugin.json

@@ -1,7 +1,7 @@
 {
   "author": "Jonathan Robert Pool",
   "cloudEndpoint": "https://kilotest.com/mcp",
-  "description": "Tools that test web pages for front-end quality (accessibility, usability, and web standards, including HTML, CSS, ARIA, and WCAG) and make test results available",
+  "description": "Tools that test web pages with an ensemble of 12 rule engines for front-end quality (accessibility, usability, and W3C web standards, including HTML, CSS, ARIA, and WCAG)",
   "homepage": "https://github.com/jrpool/kilotest",
   "identifier": "jrpool-kilotest",
   "name": "Kilotest",
@@ -21,7 +21,7 @@
   "tools": [
     {
       "name": "getKilotestOverview",
-      "description": "Explains what Kilotest is, what its tools do, and how its results are structured. Use this before any other tool when the available tools or workflow are unclear. Returns a prose overview of the Kilotest domain, the tool workflow, and links to further documentation. Kilotest integrates an ensemble of 12 rule engines, with about 1,300 rules, to test web pages for front-end quality (accessibility, usability, and web standards, including HTML, CSS, ARIA, and WCAG). Each test session generates a standardized report describing which elements violated which rules and grouping the violations into about 380 issues. Kilotest can list the tested pages, the reports about each page, the issues in each report, the violators of each issue, and the diagnoses of each violation. Kilotest also accepts requests to test pages not yet tested and to retest already tested pages.",
+      "description": "Explains what Kilotest is, what its tools do, and how its results are structured. Use this before any other tool when the available tools or workflow are unclear. Returns a prose overview of the Kilotest domain, the tool workflow, and links to further documentation. Kilotest integrates an ensemble of 12 rule engines, with about 1,300 rules, to test web pages for front-end quality (accessibility, usability, and W3C web standards, including HTML, CSS, ARIA, and WCAG). Each test job generates a standardized report describing which elements violated which rules and grouping the violations into about 380 issues. Kilotest can list the tested pages, the reports about each page, the issues in each report, the violators of each issue, and the diagnoses of each violation. Kilotest also accepts requests to test pages not yet tested and to retest already tested pages.",
       "inputSchema": {
         "type": "object",
         "properties": {},
@@ -30,8 +30,8 @@
       "annotations": {
         "title": "Explain Kilotest and its tools",
         "readOnlyHint": true,
-        "destructiveHint": false,
         "idempotentHint": true,
+        "destructiveHint": false,
         "openWorldHint": false
       },
       "execution": {
@@ -40,7 +40,7 @@
     },
     {
       "name": "listPages",
-      "description": "Lists all pages Kilotest has tested. Use this first to discover whether a page already has a report before requesting a test. Returns, for each tested page, its description, URL, and the timestamp and job identifier of its latest report.",
+      "description": "Lists all pages Kilotest has tested. Use this first to discover whether a page already has any reports before requesting a test. Returns, for each tested page, its description, URL, and the identifier of its latest available report.",
       "inputSchema": {
         "type": "object",
         "properties": {},
@@ -382,8 +382,8 @@
       "annotations": {
         "title": "List tested pages",
         "readOnlyHint": true,
-        "destructiveHint": false,
         "idempotentHint": true,
+        "destructiveHint": false,
         "openWorldHint": false
       },
       "execution": {
@@ -392,7 +392,7 @@
     },
     {
       "name": "listIssues",
-      "description": "Lists the issues reported in one report, along with the history of all reports about the same page. Use this after listPages to drill into a specific report, identified by its timestamp and job identifier. Returns basics about the report’s issues and a list of every report about the same page, from oldest to latest.",
+      "description": "Lists the issues reported in one report, along with the history of all reports about the same page. Use this after listPages to switch to an earlier or later report or to begin examining this report. Returns the history and the basics about this report’s issues.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1124,8 +1124,8 @@
       "annotations": {
         "title": "List issues in a report",
         "readOnlyHint": true,
-        "destructiveHint": false,
         "idempotentHint": true,
+        "destructiveHint": false,
         "openWorldHint": false
       },
       "execution": {
@@ -1134,7 +1134,7 @@
     },
     {
       "name": "listViolators",
-      "description": "Lists the elements of a tested page that were reported as exhibiting one issue in one report. Use this after listIssues to drill from an issue down to the elements it affects. Returns basics about each violating element, including its identifier in the page’s element catalog.",
+      "description": "Lists the elements of a tested page that were reported as exhibiting one issue in one report. Use this after listIssues to drill down from an issue to the elements violating rules belonging to that issue. Returns basics about each violating element.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1633,8 +1633,8 @@
       "annotations": {
         "title": "List elements exhibiting an issue",
         "readOnlyHint": true,
-        "destructiveHint": false,
         "idempotentHint": true,
+        "destructiveHint": false,
         "openWorldHint": false
       },
       "execution": {
@@ -1643,7 +1643,7 @@
     },
     {
       "name": "listDiagnoses",
-      "description": "Lists the diagnoses that rule engines gave for how one element exhibited one issue in one report. Use this after listViolators to drill from an element down to the rule-engine explanations of why it was flagged. Returns, for each rule engine that reported the issue on that element, its diagnosis.",
+      "description": "Lists the diagnoses that rule engines gave for how one element exhibited one issue in one report. Use this after listViolators to get details about the element as a violator of the issue. Returns, for each rule engine that reported a violation by the element of a rule belonging to the issue, the diagnosis given by the rule engine.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -1802,6 +1802,9 @@
                         "items": {
                           "type": "object",
                           "properties": {
+                            "identifier of the rule engine": {
+                              "description": "Copied from the report act (which); type not guaranteed."
+                            },
                             "identifier of the violated rule": {
                               "description": "Copied from the report instance (ruleID); type not guaranteed."
                             },
@@ -1813,13 +1816,53 @@
                             },
                             "count of violations of the rule by the element": {
                               "type": "number"
+                            },
+                            "how to report that you disagree with this diagnosis": {
+                              "type": "object",
+                              "properties": {
+                                "method": {
+                                  "type": "string",
+                                  "const": "POST"
+                                },
+                                "URL": {
+                                  "type": "string"
+                                },
+                                "request body": {
+                                  "type": "object",
+                                  "properties": {
+                                    "engineID": {
+                                      "type": "string"
+                                    },
+                                    "ruleID": {
+                                      "type": "string"
+                                    },
+                                    "reason": {
+                                      "type": "string"
+                                    }
+                                  },
+                                  "required": [
+                                    "engineID",
+                                    "ruleID",
+                                    "reason"
+                                  ],
+                                  "additionalProperties": false
+                                }
+                              },
+                              "required": [
+                                "method",
+                                "URL",
+                                "request body"
+                              ],
+                              "additionalProperties": false
                             }
                           },
                           "required": [
+                            "identifier of the rule engine",
                             "identifier of the violated rule",
                             "description of the violation",
                             "severity of the violation on a 0-to-3 scale",
-                            "count of violations of the rule by the element"
+                            "count of violations of the rule by the element",
+                            "how to report that you disagree with this diagnosis"
                           ],
                           "additionalProperties": false
                         }
@@ -2160,8 +2203,8 @@
       "annotations": {
         "title": "List diagnoses of a violation",
         "readOnlyHint": true,
-        "destructiveHint": false,
         "idempotentHint": true,
+        "destructiveHint": false,
         "openWorldHint": false
       },
       "execution": {
@@ -2170,7 +2213,7 @@
     },
     {
       "name": "getReport",
-      "description": "Retrieves one entire report as JSON, with all of its issues, violators, and diagnoses. Use this instead of drilling down through listIssues, listViolators, and listDiagnoses when the full report is needed in one call. Returns the complete report data for the specified timestamp and job identifier.",
+      "description": "Retrieves one entire report as JSON, with all of its issues, violators, and diagnoses. Use this instead of drilling down through listIssues, listViolators, and listDiagnoses when the full report is needed in one call. Returns the complete report data for the specified report identifier. The size of the report is disclosed by the listIssues tool.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -2426,8 +2469,8 @@
       "annotations": {
         "title": "Get a full report",
         "readOnlyHint": true,
-        "destructiveHint": false,
         "idempotentHint": true,
+        "destructiveHint": false,
         "openWorldHint": false
       },
       "execution": {
@@ -2436,7 +2479,7 @@
     },
     {
       "name": "requestNewTest",
-      "description": "Submits a request to test a page that has no report yet; queued for manual approval. Use orderNewTest instead for immediate, automatically approved testing. Returns a request confirmation with disposition details.",
+      "description": "Submits a request to test a page that has no report yet; queued for manager approval. Use orderNewTest instead for immediate, automatically approved testing. Returns a request confirmation with disposition details.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -2793,8 +2836,8 @@
       "annotations": {
         "title": "Request testing of a new page",
         "readOnlyHint": false,
-        "destructiveHint": false,
         "idempotentHint": false,
+        "destructiveHint": false,
         "openWorldHint": true
       },
       "execution": {
@@ -2803,7 +2846,7 @@
     },
     {
       "name": "requestRetest",
-      "description": "Submits a request to retest a page whose existing report is obsolete; queued for manual approval. Use orderRetest instead for immediate, automatically approved retesting. Returns a request confirmation with disposition details.",
+      "description": "Submits a request to retest a page whose existing report is considered obsolete; queued for manager approval. Use orderRetest instead for immediate, automatically approved retesting. Returns a request confirmation with disposition details.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -3145,8 +3188,8 @@
       "annotations": {
         "title": "Request a retest",
         "readOnlyHint": false,
-        "destructiveHint": false,
         "idempotentHint": false,
+        "destructiveHint": false,
         "openWorldHint": true
       },
       "execution": {
@@ -3155,7 +3198,7 @@
     },
     {
       "name": "requestFeature",
-      "description": "Submits a request to add a new feature or improve an existing one; queued for manual review. There is no immediate-approval alternative for feature requests. Returns a request confirmation with disposition details.",
+      "description": "Submits a request to add a new feature or improve an existing one; queued for manager review. There is no immediate-approval alternative for feature requests. Returns a request confirmation with disposition details.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -3427,8 +3470,8 @@
       "annotations": {
         "title": "Request a feature",
         "readOnlyHint": false,
-        "destructiveHint": false,
         "idempotentHint": false,
+        "destructiveHint": false,
         "openWorldHint": false
       },
       "execution": {
@@ -3765,8 +3808,8 @@
       "annotations": {
         "title": "Report disagreement with a diagnosis",
         "readOnlyHint": false,
-        "destructiveHint": false,
         "idempotentHint": false,
+        "destructiveHint": false,
         "openWorldHint": false
       },
       "execution": {
@@ -3775,7 +3818,7 @@
     },
     {
       "name": "orderNewTest",
-      "description": "Orders testing of a page that has no report yet, with automated approval or rejection and immediate enqueueing if approved. Use this instead of requestNewTest when immediate testing is wanted; testing typically takes 2 to 4 minutes. Returns an order confirmation and disposition details, including, if approved, a report identifier (timestamp and job identifier) and a question about whether to wait for completion with the awaitTest tool.",
+      "description": "Orders testing of a page that has no report yet, with automated approval or rejection and immediate enqueueing if approved. Use this instead of requestNewTest when immediate testing is wanted; testing typically takes 2 to 4 minutes. Returns an order confirmation and disposition details, including, if approved, a report identifier and a question about whether to wait for completion with the awaitTest tool.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -4140,8 +4183,8 @@
       "annotations": {
         "title": "Order immediate testing of a new page",
         "readOnlyHint": false,
-        "destructiveHint": false,
         "idempotentHint": false,
+        "destructiveHint": false,
         "openWorldHint": true
       },
       "execution": {
@@ -4150,7 +4193,7 @@
     },
     {
       "name": "orderRetest",
-      "description": "Orders a retest of a page whose existing report is considered obsolete, with automated approval or rejection and immediate enqueuing if approved. Use this instead of requestRetest when immediate retesting is wanted; testing typically takes 2 to 4 minutes. Returns an order confirmation and disposition details, including, if approved, a report identifier (timestamp and job identifier) and a question about whether to wait for completion with the awaitTest tool.",
+      "description": "Orders a retest of a page whose existing report is considered obsolete, with automated approval or rejection and immediate enqueuing if approved. Use this instead of requestRetest when immediate retesting is wanted; testing typically takes 2 to 4 minutes. Returns an order confirmation and disposition details, including, if approved, a report identifier and a question about whether to wait for completion with the awaitTest tool.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -4500,8 +4543,8 @@
       "annotations": {
         "title": "Order an immediate retest",
         "readOnlyHint": false,
-        "destructiveHint": false,
         "idempotentHint": false,
+        "destructiveHint": false,
         "openWorldHint": true
       },
       "execution": {
@@ -4809,8 +4852,8 @@
       "annotations": {
         "title": "Wait for an ordered job to finish",
         "readOnlyHint": true,
-        "destructiveHint": false,
         "idempotentHint": false,
+        "destructiveHint": false,
         "openWorldHint": false
       },
       "execution": {
@@ -4818,5 +4861,5 @@
       }
     }
   ],
-  "version": "63.1.7"
+  "version": "63.2.0"
 }

package/llms.txt

@@ -1,6 +1,6 @@
 # Kilotest
 
-Kilotest integrates an ensemble of 12 rule engines, with about 1,300 rules, to test web pages for front-end quality (accessibility, usability, and web standards, including HTML, CSS, ARIA, and WCAG, including HTML, CSS, ARIA, and WCAG). Each test job generates a standardized report describing which elements violated which rules and grouping the violations into about 380 issues. Kilotest can list the tested pages, the reports about each page, the issues in each report, the violators of each issue, and the diagnoses of each violation. Kilotest also accepts requests to test pages not yet tested and to retest already tested pages. Kilotest features are available via a web UI, an API, and an MCP server with streamable HTTP and no authentication.
+Kilotest integrates an ensemble of 12 rule engines, with about 1,300 rules, to test web pages for front-end quality (accessibility, usability, and web standards, including HTML, CSS, ARIA, and WCAG). Each test job generates a standardized report describing which elements violated which rules and grouping the violations into about 380 issues. Kilotest can list the tested pages, the reports about each page, the issues in each report, the violators of each issue, and the diagnoses of each violation. Kilotest also accepts requests to test pages not yet tested and to retest already tested pages. Kilotest features are available via a web UI, an API, and an MCP server with streamable HTTP and no authentication.
 
 ## API
 

package/mcp.ts

@@ -22,6 +22,7 @@ import * as awaitTestAPI from './api/awaitTest.ts';
 import * as reportDisagreementAPI from './api/reportDisagreement.ts';
 import {version} from './api/version.ts';
 import {recordMetric} from './util.ts';
+import {collectionDescription, sharedContext} from './content.ts';
 
 import {
   getReportSchema,
@@ -53,12 +54,6 @@ import {
 
 export const mcpPath = '/mcp';
 
-// Shared statement of the Kilotest domain and data hierarchy, repeated in the server
-// instructions and in the getKilotestOverview tool description (but not in the other tool
-// descriptions, to avoid diluting how models read each tool), because some MCP clients do
-// not propagate server-level instructions or the server description to their models.
-const sharedContext = 'Kilotest integrates an ensemble of 12 rule engines, with about 1,300 rules, to test web pages for front-end quality (accessibility, usability, and web standards, including HTML, CSS, ARIA, and WCAG). Each test job generates a standardized report describing which elements violated which rules and grouping the violations into about 380 issues. Kilotest can list the tested pages, the reports about each page, the issues in each report, the violators of each issue, and the diagnoses of each violation. Kilotest also accepts requests to test pages not yet tested and to retest already tested pages.';
-
 // 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 = [
@@ -77,7 +72,7 @@ export const createMCPServer = (): McpServer => {
   const server = new McpServer({
     name: 'Kilotest',
     version,
-    description: 'Tools that test web pages for front-end quality (accessibility, usability, and web standards, including HTML, CSS, ARIA, and WCAG) and make test results available'
+    description: collectionDescription
   },
   {
     instructions: `${sharedContext} Use the listPages tool to start. If it shows that the page you want facts about has been tested, drill down from its latest report with the listIssues, listViolators, and listDiagnoses tools. If not, use the requestNewTest tool to request that the page be tested, or the orderNewTest tool for immediate, automatically approved testing. If the latest report about the page is obsolete, use the requestRetest tool to request that the page be retested, or the orderRetest tool for immediate, automatically approved retesting. For detailed documentation, call the getKilotestOverview tool.`

package/openapi-3.0.yaml

@@ -1,8 +1,8 @@
 openapi: 3.0.3
 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 web pages for front-end quality (accessibility, usability, and web standards, including HTML, CSS, ARIA, and WCAG). 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: 63.1.7
+  description: 'Kilotest integrates an ensemble of 12 rule engines, with about 1,300 rules, to test web pages for front-end quality (accessibility, usability, and W3C web standards, including HTML, CSS, ARIA, and WCAG). Each test job generates a standardized report describing which elements violated which rules and grouping the violations into about 380 issues. Kilotest can list the tested pages, the reports about each page, the issues in each report, the violators of each issue, and the diagnoses of each violation. Kilotest also accepts requests to test pages not yet tested and to retest already tested pages. 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, and 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: 63.2.0
   license:
     name: MIT
     url: https://github.com/jrpool/kilotest/blob/main/LICENSE

package/openapi.yaml

@@ -1,8 +1,8 @@
 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 web pages for front-end quality (accessibility, usability, and web standards, including HTML, CSS, ARIA, and WCAG). 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: 63.1.7
+  description: 'Kilotest integrates an ensemble of 12 rule engines, with about 1,300 rules, to test web pages for front-end quality (accessibility, usability, and W3C web standards, including HTML, CSS, ARIA, and WCAG). Each test job generates a standardized report describing which elements violated which rules and grouping the violations into about 380 issues. Kilotest can list the tested pages, the reports about each page, the issues in each report, the violators of each issue, and the diagnoses of each violation. Kilotest also accepts requests to test pages not yet tested and to retest already tested pages. 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, and 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: 63.2.0
   license:
     name: MIT
     identifier: MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "63.1.7",
+  "version": "63.2.0",
   "description": "Ensemble testing for front-end web quality",
   "type": "module",
   "main": "index.ts",
@@ -14,7 +14,7 @@
     "test": "c8 node --require ./test/setup.ts --experimental-test-module-mocks --test --test-concurrency=1 --test-randomize '**/*.test.ts'",
     "test:smoke": "node smokeTest.ts",
     "checkinfo": "node checkinfo.ts",
-    "generate": "node scripts/generate-openapi.ts && node scripts/update-versions.ts",
+    "generate": "node scripts/generate-openapi.ts && node scripts/generate-lhm.ts && node scripts/update-versions.ts",
     "build:media": "node scripts/buildDemoVideo.ts",
     "publish:lhm": "npx -y @lobehub/market-cli plugin update --dir .",
     "prePR": "node scripts/prePR.ts",
@@ -58,7 +58,7 @@
     "globals": "*",
     "htmlhint": "^1.9.2",
     "js-yaml": "*",
-    "markdownlint-cli2": "^0.23.2",
+    "markdownlint-cli2": "*",
     "node-html-parser": "*",
     "testaro": "*",
     "typescript": "*",
@@ -108,6 +108,7 @@
     "branches": 100
   },
   "overrides": {
-    "smol-toml": "^1.8.0"
+    "smol-toml": "^1.8.0",
+    "re2js": "^2.9.1"
   }
 }

package/scripts/generate-lhm.ts

@@ -0,0 +1,118 @@
+/*
+  generate-lhm.ts
+  Regenerates the description and tool entries (description, inputSchema, outputSchema,
+  annotations) of lhm.plugin.json from the single sources of truth: content.ts for prose and
+  api/schemas.ts (via the same registrations mcp.ts makes) for schemas. Everything else in
+  lhm.plugin.json (author, cloudEndpoint, homepage, identifier, name, prompts, resources,
+  tags, version, and each tool's execution block) is left untouched, because it has no
+  canonical source elsewhere in the repository; version is kept in sync separately by
+  update-versions.ts.
+*/
+
+// IMPORTS
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {z} from 'zod';
+import {createMCPServer} from '../mcp.ts';
+import {collectionDescription} from '../content.ts';
+import {
+  listIssuesSchema,
+  listViolatorsSchema,
+  listDiagnosesSchema,
+  getReportSchema,
+  requestNewTestSchema,
+  requestRetestSchema,
+  requestFeatureSchema,
+  orderNewTestSchema,
+  orderRetestSchema,
+  awaitTestSchema,
+  reportDisagreementSchema,
+  listPagesResponseSchema,
+  listIssuesResponseSchema,
+  listViolatorsResponseSchema,
+  listDiagnosesResponseSchema,
+  getReportResponseSchema,
+  requestNewTestResponseSchema,
+  requestRetestResponseSchema,
+  requestFeatureResponseSchema,
+  orderNewTestResponseSchema,
+  orderRetestResponseSchema,
+  awaitTestResponseSchema,
+  reportDisagreementResponseSchema
+} from '../api/schemas.ts';
+
+// TYPES
+
+type ZodRawShape = Record<string, z.ZodTypeAny>;
+
+// CONSTANTS
+
+const outputPath = path.join(import.meta.dirname, '..', 'lhm.plugin.json');
+const jsonSchemaOptions = {target: 'draft-7' as const, unrepresentable: 'any' as const};
+
+// The input and output schemas mcp.ts passes to registerTool for each tool, keyed by tool
+// name, matching mcp.ts's own registerTool calls exactly (mcp.ts remains the source for
+// descriptions and annotations, read at runtime below via createMCPServer).
+const toolSchemas: Record<string, {input: ZodRawShape; output?: z.ZodTypeAny}> = {
+  getKilotestOverview: {input: {}},
+  listPages: {input: {}, output: listPagesResponseSchema},
+  listIssues: {input: listIssuesSchema, output: listIssuesResponseSchema},
+  listViolators: {input: listViolatorsSchema, output: listViolatorsResponseSchema},
+  listDiagnoses: {input: listDiagnosesSchema, output: listDiagnosesResponseSchema},
+  getReport: {input: getReportSchema, output: getReportResponseSchema},
+  requestNewTest: {input: requestNewTestSchema, output: requestNewTestResponseSchema},
+  requestRetest: {input: requestRetestSchema, output: requestRetestResponseSchema},
+  requestFeature: {input: requestFeatureSchema, output: requestFeatureResponseSchema},
+  reportDisagreement: {input: reportDisagreementSchema, output: reportDisagreementResponseSchema},
+  orderNewTest: {input: orderNewTestSchema, output: orderNewTestResponseSchema},
+  orderRetest: {input: orderRetestSchema, output: orderRetestResponseSchema},
+  awaitTest: {input: awaitTestSchema, output: awaitTestResponseSchema}
+};
+
+// FUNCTIONS
+
+// Builds the lhm.plugin.json inputSchema for a tool: like outputSchema below, but LobeHub's
+// existing input schemas never carry additionalProperties, so that key is dropped.
+const buildInputSchema = (shape: ZodRawShape): Record<string, unknown> => {
+  const generated = z.toJSONSchema(z.object(shape), jsonSchemaOptions) as Record<string, unknown>;
+  delete generated.additionalProperties;
+  const {$schema, ...withoutSchemaKeyword} = generated;
+  return {...withoutSchemaKeyword, $schema};
+};
+// Builds the lhm.plugin.json outputSchema for a tool, reordering keys to match the file's
+// existing convention ($schema placed just before additionalProperties and definitions).
+const buildOutputSchema = (schema: z.ZodTypeAny): Record<string, unknown> => {
+  const generated = z.toJSONSchema(schema, jsonSchemaOptions) as Record<string, unknown>;
+  const {$schema, additionalProperties, definitions, ...rest} = generated;
+  return {
+    ...rest,
+    ...($schema !== undefined ? {$schema} : {}),
+    ...(additionalProperties !== undefined ? {additionalProperties} : {}),
+    ...(definitions !== undefined ? {definitions} : {})
+  };
+};
+
+// EXECUTION
+
+const server = createMCPServer();
+const registeredTools = (server as unknown as {_registeredTools: Record<string, {description: string; annotations: unknown}>})._registeredTools;
+const manifest = JSON.parse(fs.readFileSync(outputPath, 'utf8'));
+manifest.description = collectionDescription;
+manifest.tools = manifest.tools.map((tool: {name: string; execution: unknown}) => {
+  const registered = registeredTools[tool.name];
+  const schemas = toolSchemas[tool.name];
+  if (!registered || !schemas) {
+    throw new Error(`No registration or schema mapping found for lhm.plugin.json tool "${tool.name}"`);
+  }
+  return {
+    name: tool.name,
+    description: registered.description,
+    inputSchema: buildInputSchema(schemas.input),
+    ...(schemas.output ? {outputSchema: buildOutputSchema(schemas.output)} : {}),
+    annotations: registered.annotations,
+    execution: tool.execution
+  };
+});
+fs.writeFileSync(outputPath, `${JSON.stringify(manifest, null, 2)}\n`);
+console.log(`Wrote ${outputPath}`);

package/scripts/generate-openapi.ts

@@ -12,6 +12,7 @@ import {createDocument} from 'zod-openapi';
 import pkg from '../package.json' with {type: 'json'};
 import {routes} from '../api/routes.ts';
 import {version} from '../api/version.ts';
+import {sharedContext} from '../content.ts';
 
 // CONSTANTS
 
@@ -137,7 +138,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 web pages for front-end quality (accessibility, usability, and web standards, including HTML, CSS, ARIA, and WCAG). 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: `${sharedContext} 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, and 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,

package/server.json

@@ -6,7 +6,7 @@
     "url": "https://github.com/jrpool/kilotest",
     "source": "github"
   },
-  "version": "63.1.7",
+  "version": "63.2.0",
   "remotes": [
     {
       "type": "streamable-http",