semantic-js-mcp 0.8.0

package/protocol.mjs

@@ -0,0 +1,356 @@
+export const TOOL = Object.freeze({
+  DOCUMENT_SYMBOLS: "lsp_document_symbols",
+  WORKSPACE_SYMBOLS: "lsp_workspace_symbols",
+  DEFINITION: "lsp_definition",
+  HOVER: "lsp_hover",
+  DIAGNOSTICS: "lsp_diagnostics",
+  COUNT_TEXT_MATCHES: "lsp_count_text_matches",
+  COUNT_NAMED_SYMBOL: "lsp_count_named_symbol",
+  COUNT_REFERENCES: "lsp_count_references",
+  AUDIT_NAMED_SYMBOL: "lsp_audit_named_symbol",
+  AUDIT_SYMBOL: "lsp_audit_symbol",
+  REFERENCES: "lsp_references",
+  REFERENCE_PAGE: "lsp_reference_page",
+  UNRESOLVED_REFERENCE_PAGE: "lsp_unresolved_reference_page",
+});
+
+export const TOOL_ORDER = Object.freeze(Object.values(TOOL));
+export const PRODUCT = Object.freeze({
+  NAME: "semantic-js-mcp",
+  DISPLAY_NAME: "Semantic JS MCP",
+});
+
+export const CLI_COMMAND = Object.freeze({
+  SERVE: "serve",
+  DOCTOR: "doctor",
+  HELP: "help",
+  VERSION: "version",
+});
+
+export const CLI_ARGUMENT = Object.freeze({
+  HELP: "--help",
+  HELP_SHORT: "-h",
+  VERSION: "--version",
+  VERSION_SHORT: "-v",
+  YAML: "--yaml",
+});
+
+export const CLI_MESSAGE = Object.freeze({
+  UNKNOWN_COMMAND: "Unknown command",
+  UNKNOWN_ARGUMENT: "Unknown argument",
+  UNKNOWN_OPTION: "Unknown option",
+});
+
+export const DOCTOR_CHECK = Object.freeze({
+  NODE_RUNTIME: "node-runtime",
+  RUNTIME_COMPONENTS: "runtime-components",
+  RIPGREP: "ripgrep",
+  MCP_STARTUP: "mcp-startup",
+  TOOL_DISCOVERY: "tool-discovery",
+  TYPESCRIPT_SYMBOLS: "typescript-symbols",
+  TYPESCRIPT_REFERENCES: "typescript-references",
+  DIAGNOSTIC_FRESHNESS: "diagnostic-freshness",
+  VUE_SYMBOLS: "vue-symbols",
+  VUE_TEMPLATE_DEFINITION: "vue-template-definition",
+});
+
+export const DOCTOR_REASON = Object.freeze({
+  CHECK_COMPLETED: "check-completed",
+  UNSUPPORTED_NODE_RUNTIME: "unsupported-node-runtime",
+  RUNTIME_COMPONENT_MISSING: "runtime-component-missing",
+  RIPGREP_UNAVAILABLE: "ripgrep-unavailable",
+  MCP_STARTUP_FAILED: "mcp-startup-failed",
+  TOOL_SET_DIFFERENT: "tool-set-different-from-protocol",
+  TYPESCRIPT_SYMBOL_NOT_FOUND: "typescript-symbol-not-found",
+  TYPESCRIPT_REFERENCE_ACCOUNTING_INCOMPLETE: "typescript-reference-accounting-incomplete",
+  DIAGNOSTICS_NOT_CONFIRMED: "diagnostics-not-confirmed-for-current-document",
+  VUE_SYMBOL_NOT_FOUND: "vue-symbol-not-found",
+  VUE_TEMPLATE_DEFINITION_UNRESOLVED: "vue-template-definition-unresolved",
+  CHECK_FAILED: "check-failed",
+});
+
+export const RUNTIME_COMMAND = Object.freeze({
+  RIPGREP: "rg",
+});
+
+export const RUNTIME_REQUIREMENT = Object.freeze({
+  MINIMUM_NODE_MAJOR: 22,
+});
+
+export const PACKAGE_PATH = Object.freeze({
+  SERVER: "server.mjs",
+  CLI: "cli.mjs",
+});
+
+export const ENVIRONMENT_VARIABLE = Object.freeze({
+  PROCESS_CWD: "SEMANTIC_JS_MCP_PROCESS_CWD",
+  CLIENT_IDLE_TIMEOUT_MS: "SEMANTIC_JS_MCP_CLIENT_IDLE_TIMEOUT_MS",
+  CLIENT_MINIMUM_EVICTION_AGE_MS: "SEMANTIC_JS_MCP_CLIENT_MINIMUM_EVICTION_AGE_MS",
+  MAXIMUM_ACTIVE_CLIENTS: "SEMANTIC_JS_MCP_MAXIMUM_ACTIVE_CLIENTS",
+  REFERENCE_SET_TTL_MS: "SEMANTIC_JS_MCP_REFERENCE_SET_TTL_MS",
+  MAXIMUM_REFERENCE_SETS: "SEMANTIC_JS_MCP_MAXIMUM_REFERENCE_SETS",
+  MAXIMUM_CHANGED_REFERENCE_SET_MARKERS: "SEMANTIC_JS_MCP_MAXIMUM_CHANGED_REFERENCE_SET_MARKERS",
+  MAXIMUM_CACHED_REFERENCE_LOCATIONS: "SEMANTIC_JS_MCP_MAXIMUM_CACHED_REFERENCE_LOCATIONS",
+  DEFAULT_REFERENCE_PAGE_SIZE: "SEMANTIC_JS_MCP_DEFAULT_REFERENCE_PAGE_SIZE",
+  CROSS_WORKSPACE_CONCURRENCY: "SEMANTIC_JS_MCP_CROSS_WORKSPACE_CONCURRENCY",
+  BENCHMARK_COUNTS: "SEMANTIC_JS_MCP_BENCHMARK_COUNTS",
+});
+
+export const CONFIGURATION_FILE = Object.freeze({
+  PACKAGE: "package.json",
+  TYPESCRIPT: "tsconfig.json",
+  JAVASCRIPT: "jsconfig.json",
+});
+export const WORKSPACE_CONFIGURATION_FILE_NAMES = Object.freeze(Object.values(CONFIGURATION_FILE));
+export const WORKSPACE_ROOT_MARKER_FILE_NAMES = Object.freeze([CONFIGURATION_FILE.PACKAGE, CONFIGURATION_FILE.TYPESCRIPT]);
+export const SOURCE_EXTENSION = Object.freeze({
+  TYPESCRIPT: ".ts",
+  TYPESCRIPT_REACT: ".tsx",
+  TYPESCRIPT_MODULE: ".mts",
+  TYPESCRIPT_COMMONJS: ".cts",
+  JAVASCRIPT: ".js",
+  JAVASCRIPT_REACT: ".jsx",
+  JAVASCRIPT_MODULE: ".mjs",
+  JAVASCRIPT_COMMONJS: ".cjs",
+  VUE: ".vue",
+});
+export const SOURCE_FILE_GLOBS = Object.freeze(Object.values(SOURCE_EXTENSION).map((extension) => `*${extension}`));
+export const SOURCE_EXCLUDED_GLOBS = Object.freeze(["!**/node_modules/**", "!**/dist/**", "!**/coverage/**"]);
+
+export const LANGUAGE_ID = Object.freeze({
+  TYPESCRIPT: "typescript",
+  TYPESCRIPT_REACT: "typescriptreact",
+  JAVASCRIPT: "javascript",
+  JAVASCRIPT_REACT: "javascriptreact",
+  VUE: "vue",
+});
+
+export const VUE_SCRIPT_LANGUAGE = Object.freeze({
+  JAVASCRIPT: "js",
+  JAVASCRIPT_REACT: "jsx",
+});
+
+export const FORBIDDEN_PUBLIC_FIELD = Object.freeze([
+  "confidence",
+  "exhaustive",
+  "rejectedCandidateCount",
+  "rejectedCandidates",
+  "rejectedCandidatesByReason",
+  "semanticIdentity",
+  "truncated",
+]);
+
+export const COLLECTION_STATUS = Object.freeze({
+  COMPLETE: "complete",
+  LIMITED: "limited",
+  PARTIAL: "partial",
+  FAILED: "failed",
+});
+
+export const PRESENTATION_MODE = Object.freeze({
+  ALL_ITEMS: "all-items",
+  SUBSET: "subset",
+  COUNT_ONLY: "count-only",
+  SUMMARY_BY_FILE: "summary-by-file",
+  PAGE: "page",
+});
+
+export const LIMIT_MODE = Object.freeze({
+  UNLIMITED: "unlimited",
+  MAXIMUM: "maximum",
+});
+
+export const ACCOUNTING_STATUS = Object.freeze({
+  COMPLETE: "complete",
+  INCOMPLETE: "incomplete",
+});
+
+export const DEFINITION_MATCH = Object.freeze({
+  RESOLVED: "resolved",
+  UNRESOLVED: "unresolved",
+});
+
+export const SIGNATURE_SOURCE = Object.freeze({
+  QUERY_POSITION_HOVER: "query-position-hover",
+  RESOLVED_DEFINITION_HOVER: "resolved-definition-hover",
+  NOT_REPORTED: "not-reported",
+});
+
+export const DIAGNOSTIC_FRESHNESS = Object.freeze({
+  CURRENT: "current-document-version",
+  VERSION_NOT_REPORTED: "version-not-reported-by-language-server",
+  DIFFERENT_VERSION: "different-document-version",
+  NOT_REPORTED_FOR_CURRENT_DOCUMENT: "not-reported-for-current-document",
+});
+
+export const DIAGNOSTIC_SEVERITY = Object.freeze({
+  ERROR: "error",
+  WARNING: "warning",
+  INFORMATION: "information",
+  HINT: "hint",
+  NOT_REPORTED: "not-reported",
+});
+
+export const EVIDENCE_STATUS = Object.freeze({
+  VERIFIED: "verified",
+  UNTRUSTED: "untrusted",
+});
+
+export const DIAGNOSTIC_EVIDENCE_REASON = Object.freeze({
+  CURRENT_DOCUMENT_VERSION_CONFIRMED: "current-document-version-confirmed",
+  LANGUAGE_SERVER_VERSION_NOT_REPORTED: "language-server-version-not-reported",
+  LANGUAGE_SERVER_REPORTED_DIFFERENT_VERSION: "language-server-reported-different-version",
+  LANGUAGE_SERVER_DID_NOT_REPORT_CURRENT_DOCUMENT: "language-server-did-not-report-current-document",
+});
+
+export const CONTENT_FRESHNESS = Object.freeze({
+  VERIFIED_CURRENT: "verified-current-file-content",
+  VERIFIED_REPOSITORY_SOURCE_INVENTORY: "verified-current-repository-source-inventory",
+});
+
+export const REFERENCE_SET_CHANGE_TYPE = Object.freeze({
+  EVIDENCE_FILE_CONTENT_CHANGED: "evidence-file-content-changed",
+  REPOSITORY_SOURCE_INVENTORY_CHANGED: "repository-source-inventory-changed",
+});
+
+export const ERROR_CODE = Object.freeze({
+  TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED",
+  REFERENCE_SET_CONTENT_CHANGED: "REFERENCE_SET_CONTENT_CHANGED",
+  REFERENCE_SET_NOT_FOUND_OR_EXPIRED: "REFERENCE_SET_NOT_FOUND_OR_EXPIRED",
+  REPOSITORY_CHANGED_DURING_COLLECTION: "REPOSITORY_CHANGED_DURING_COLLECTION",
+  RUNTIME_DEPENDENCY_MISSING: "RUNTIME_DEPENDENCY_MISSING",
+  RUNTIME_REQUIREMENT_UNMET: "RUNTIME_REQUIREMENT_UNMET",
+});
+
+export const EVIDENCE_TYPE = Object.freeze({
+  EXACT_IDENTIFIER_TEXT_MATCH: "exact-identifier-text-match",
+});
+
+export const FINGERPRINT_ALGORITHM = Object.freeze({
+  SHA_256: "sha256",
+});
+
+export const REFERENCE_DISCOVERY_METHOD = Object.freeze({
+  OWNING_WORKSPACE_LANGUAGE_SERVER: "owning-workspace-language-server",
+  DEFINITION_MATCH_FROM_ANOTHER_WORKSPACE: "definition-match-from-another-workspace",
+});
+
+export const DEFINITION_RESOLUTION_METHOD = Object.freeze({
+  LANGUAGE_SERVER: "language-server-definition",
+  TYPESCRIPT_SERVER: "typescript-server-definition",
+  VUE_TEMPLATE_IMPORT_BINDING: "vue-template-import-binding-definition",
+  UNRESOLVED: "unresolved",
+});
+
+export const UNRESOLVED_REFERENCE_REASON = Object.freeze({
+  DEFINITION_TOOLS_RETURNED_NO_LOCATION: "definition-tools-returned-no-location",
+  TYPESCRIPT_SERVER_REQUEST_FAILED: "typescript-server-request-failed-after-language-server-returned-no-location",
+  CANDIDATE_ANALYSIS_FAILED: "candidate-analysis-failed",
+  CANDIDATE_OPENED_IN_INFERRED_TYPESCRIPT_PROJECT: "candidate-opened-in-inferred-typescript-project",
+});
+
+export const TYPESCRIPT_PROJECT_KIND = Object.freeze({
+  CONFIGURED: "configured-typescript-project",
+  INFERRED: "inferred-typescript-project",
+  UNKNOWN: "typescript-project-kind-not-reported",
+});
+
+export const CI_STATUS = Object.freeze({
+  PASS: "pass",
+  FAIL: "fail",
+  UNTRUSTED: "untrusted",
+  BLOCKED: "blocked",
+});
+
+export const CI_EXIT_CODE = Object.freeze({
+  PASS: 0,
+  FAIL: 1,
+  UNTRUSTED: 2,
+  BLOCKED: 3,
+});
+
+export const DOCTOR_DISTRIBUTION_ACCEPTED_STATUS = Object.freeze([CI_STATUS.PASS, CI_STATUS.UNTRUSTED]);
+
+export const DOCTOR_STATUS_PRIORITY = Object.freeze({
+  [CI_STATUS.PASS]: 0,
+  [CI_STATUS.UNTRUSTED]: 1,
+  [CI_STATUS.FAIL]: 2,
+  [CI_STATUS.BLOCKED]: 3,
+});
+
+export const RUNTIME_REQUIREMENT_KIND = Object.freeze({
+  NODE: "node",
+  RUNTIME_COMPONENT: "runtime-component",
+});
+
+export const CI_REASON = Object.freeze({
+  COMPLETE_EVIDENCE: "complete-evidence",
+  VERIFIED_DIAGNOSTIC_ERRORS: "verified-current-document-has-error-diagnostics",
+  INCOMPLETE_EVIDENCE: "collection-is-limited-or-partial",
+  UNTRUSTED_DIAGNOSTICS: "diagnostics-for-current-document-are-untrusted",
+  TOOL_EXECUTION_FAILED: "tool-execution-failed",
+  INVALID_INPUT: "input-is-not-a-semantic-js-mcp-result",
+});
+
+export const INTERNAL_RESOLUTION_SOURCE = Object.freeze({
+  NATIVE_LSP: "native-lsp",
+  TYPESCRIPT_SERVER_FALLBACK: "tsserver-fallback",
+  CROSS_WORKSPACE_DEFINITION: "cross-workspace-definition",
+  VUE_TEMPLATE_IMPORT_BINDING: "vue-template-import-binding",
+  UNRESOLVED: "unresolved",
+});
+
+export const RESULT_SCHEMA = Object.freeze({
+  NAME: PRODUCT.NAME,
+  VERSION: 5,
+});
+
+export const SERVER_VERSION = "0.8.0";
+
+export const REQUIRED_RUNTIME_COMPONENT = Object.freeze({
+  TYPESCRIPT_LANGUAGE_SERVER: "typescript-language-server/lib/cli.mjs",
+  VUE_LANGUAGE_SERVER: "@vue/language-server/bin/vue-language-server.js",
+  TYPESCRIPT_SERVER: "typescript/lib/tsserver.js",
+  VUE_SFC_COMPILER: "@vue/compiler-sfc/dist/compiler-sfc.cjs.js",
+  VUE_TYPESCRIPT_PLUGIN: "@vue/typescript-plugin/package.json",
+});
+
+export const RUNTIME_STATUS = Object.freeze({
+  READY: "ready",
+  BLOCKED: "blocked",
+});
+
+export const PROCESS_EXIT_CODE = Object.freeze({
+  SUCCESS: 0,
+  FAILURE: 1,
+});
+
+export const NODE_EVENT = Object.freeze({
+  ERROR: "error",
+  CLOSE: "close",
+});
+
+export const DEFAULT = Object.freeze({
+  REQUEST_TIMEOUT_MS: 30_000,
+  DIAGNOSTIC_WAIT_MS: 2_000,
+  CLIENT_IDLE_TIMEOUT_MS: 60_000,
+  CLIENT_MINIMUM_EVICTION_AGE_MS: 15_000,
+  MAXIMUM_ACTIVE_CLIENTS: 4,
+  REFERENCE_SET_TTL_MS: 300_000,
+  MAXIMUM_REFERENCE_SETS: 12,
+  MAXIMUM_CHANGED_REFERENCE_SET_MARKERS: 24,
+  MAXIMUM_CACHED_REFERENCE_LOCATIONS: 50_000,
+  REFERENCE_PAGE_SIZE: 100,
+  CROSS_WORKSPACE_CONCURRENCY: 6,
+  FILE_FINGERPRINT_CONCURRENCY: 8,
+  NAMED_DEFINITION_CONCURRENCY: 2,
+  WORKSPACE_FILE_CONCURRENCY: 5,
+  FILE_SUGGESTION_COUNT: 8,
+  MILLISECONDS_PER_SECOND: 1_000,
+  BENCHMARK_COUNTS: Object.freeze([10, 100, 1_000]),
+  MCP_STARTUP_TIMEOUT_SECONDS: 30,
+  MCP_TOOL_TIMEOUT_SECONDS: 300,
+  INVENTORY_STAT_CONCURRENCY: 32,
+  COLLECTION_STABILITY_ATTEMPTS: 2,
+  PROCESS_ARGUMENT_OFFSET: 2,
+});

package/scripts/benchmark.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import {mkdtemp, mkdir, rm, writeFile} from "node:fs/promises";
+import {tmpdir} from "node:os";
+import {fileURLToPath} from "node:url";
+import {Client} from "@modelcontextprotocol/sdk/client/index.js";
+import {StdioClientTransport} from "@modelcontextprotocol/sdk/client/stdio.js";
+import {DEFAULT, ENVIRONMENT_VARIABLE, PRODUCT, TOOL} from "../protocol.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const counts = (process.env[ENVIRONMENT_VARIABLE.BENCHMARK_COUNTS] || DEFAULT.BENCHMARK_COUNTS.join(","))
+  .split(",")
+  .map((value) => Number(value.trim()))
+  .filter((value) => Number.isInteger(value) && value > 0);
+
+if (counts.length === 0) throw new Error(`${ENVIRONMENT_VARIABLE.BENCHMARK_COUNTS} must contain positive integers`);
+
+async function timedCall(client, name, argumentsValue) {
+  const startedAt = performance.now();
+  const response = await client.callTool({name, arguments: argumentsValue});
+  if (response.isError) throw new Error(response.content?.[0]?.text || `${name} failed`);
+  return {milliseconds: Math.round(performance.now() - startedAt), data: response.structuredContent};
+}
+
+const results = [];
+for (const count of counts) {
+  const workspace = await mkdtemp(path.join(tmpdir(), `${PRODUCT.NAME}-benchmark-${count}-`));
+  const src = path.join(workspace, "src");
+  await mkdir(src, {recursive: true});
+  await writeFile(path.join(workspace, "package.json"), JSON.stringify({private: true, type: "module"}));
+  await writeFile(
+    path.join(workspace, "tsconfig.json"),
+    JSON.stringify({
+      compilerOptions: {strict: true, target: "ES2022", module: "ESNext", moduleResolution: "Bundler"},
+      include: ["src/**/*.ts"],
+    }),
+  );
+  const symbol = `benchmarkTarget${count}`;
+  const target = path.join(src, "target.ts");
+  await writeFile(target, `export function ${symbol}(value: number): number { return value + 1; }\n`);
+  await writeFile(
+    path.join(src, "usage.ts"),
+    [
+      `import {${symbol}} from "./target.js";`,
+      "export const values = [",
+      ...Array.from({length: count}, (_, index) => `  ${symbol}(${index}),`),
+      "];",
+    ].join("\n"),
+  );
+
+  const client = new Client({name: `${PRODUCT.NAME}-benchmark`, version: "1.0.0"});
+  const transport = new StdioClientTransport({command: process.execPath, args: [path.join(root, "server.mjs")], cwd: root});
+  try {
+    await client.connect(transport);
+    const text = await timedCall(client, TOOL.COUNT_TEXT_MATCHES, {root: workspace, symbol});
+    const verified = await timedCall(client, TOOL.COUNT_REFERENCES, {
+      file: target,
+      root: workspace,
+      line: 1,
+      column: 17,
+    });
+    const freshness = await timedCall(client, TOOL.REFERENCE_PAGE, {
+      referenceSetId: verified.data.result.referenceSetId,
+      cursor: "0",
+      pageSize: 1,
+    });
+    results.push({
+      requestedCalls: count,
+      exactTextMatches: text.data.result.matchesFound,
+      textCountWallMilliseconds: text.milliseconds,
+      verifiedCollectionWallMilliseconds: verified.milliseconds,
+      freshnessValidationWallMilliseconds: freshness.milliseconds,
+      verifiedReferences: verified.data.result.references.verifiedTotal,
+      collectionStatus: verified.data.collection.status,
+      performance: verified.data.collection.performance,
+      freshness: {
+        repositorySourceFilesChecked: freshness.data.collection.repositorySourceFilesChecked,
+        freshnessCheckMilliseconds: freshness.data.collection.freshnessCheckMilliseconds,
+      },
+    });
+  } finally {
+    await client.close().catch(() => undefined);
+    await rm(workspace, {recursive: true, force: true});
+  }
+}
+
+console.log(JSON.stringify({counts, results}, null, 2));

package/scripts/check-protocol-literals.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+import {readFile} from "node:fs/promises";
+import path from "node:path";
+import {fileURLToPath} from "node:url";
+import {
+  ACCOUNTING_STATUS,
+  COLLECTION_STATUS,
+  CI_REASON,
+  CI_STATUS,
+  CLI_ARGUMENT,
+  CLI_COMMAND,
+  CLI_MESSAGE,
+  CONFIGURATION_FILE,
+  CONTENT_FRESHNESS,
+  DEFAULT,
+  DEFINITION_MATCH,
+  DEFINITION_RESOLUTION_METHOD,
+  DIAGNOSTIC_EVIDENCE_REASON,
+  DIAGNOSTIC_FRESHNESS,
+  DIAGNOSTIC_SEVERITY,
+  DOCTOR_CHECK,
+  DOCTOR_DISTRIBUTION_ACCEPTED_STATUS,
+  DOCTOR_REASON,
+  DOCTOR_STATUS_PRIORITY,
+  EVIDENCE_STATUS,
+  ENVIRONMENT_VARIABLE,
+  ERROR_CODE,
+  EVIDENCE_TYPE,
+  FINGERPRINT_ALGORITHM,
+  INTERNAL_RESOLUTION_SOURCE,
+  LIMIT_MODE,
+  NODE_EVENT,
+  PRESENTATION_MODE,
+  PACKAGE_PATH,
+  PRODUCT,
+  REFERENCE_DISCOVERY_METHOD,
+  REFERENCE_SET_CHANGE_TYPE,
+  REQUIRED_RUNTIME_COMPONENT,
+  RUNTIME_COMMAND,
+  RUNTIME_REQUIREMENT,
+  RUNTIME_REQUIREMENT_KIND,
+  RESULT_SCHEMA,
+  TOOL,
+  TYPESCRIPT_PROJECT_KIND,
+  SOURCE_EXCLUDED_GLOBS,
+  SOURCE_FILE_GLOBS,
+  WORKSPACE_CONFIGURATION_FILE_NAMES,
+  WORKSPACE_ROOT_MARKER_FILE_NAMES,
+  RUNTIME_STATUS,
+  UNRESOLVED_REFERENCE_REASON,
+} from "../protocol.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const runtimeSourceFiles = ["server.mjs", "cli.mjs", "lib/runtime.mjs", "lib/doctor.mjs"];
+const runtimeSources = await Promise.all(
+  runtimeSourceFiles.map(async (file) => ({
+    file,
+    source: await readFile(path.join(root, file), "utf8"),
+  })),
+);
+const mcpConfig = JSON.parse(await readFile(path.join(root, ".mcp.json"), "utf8"));
+const semanticServer = mcpConfig.mcpServers?.[PRODUCT.NAME];
+if (semanticServer?.startup_timeout_sec !== DEFAULT.MCP_STARTUP_TIMEOUT_SECONDS) {
+  throw new Error(".mcp.json startup_timeout_sec differs from protocol.mjs");
+}
+if (semanticServer?.tool_timeout_sec !== DEFAULT.MCP_TOOL_TIMEOUT_SECONDS) {
+  throw new Error(".mcp.json tool_timeout_sec differs from protocol.mjs");
+}
+const groups = [
+  TOOL,
+  COLLECTION_STATUS,
+  PRESENTATION_MODE,
+  LIMIT_MODE,
+  ACCOUNTING_STATUS,
+  DEFINITION_MATCH,
+  DIAGNOSTIC_FRESHNESS,
+  DIAGNOSTIC_SEVERITY,
+  DIAGNOSTIC_EVIDENCE_REASON,
+  EVIDENCE_STATUS,
+  CONTENT_FRESHNESS,
+  ERROR_CODE,
+  EVIDENCE_TYPE,
+  FINGERPRINT_ALGORITHM,
+  REFERENCE_DISCOVERY_METHOD,
+  REFERENCE_SET_CHANGE_TYPE,
+  DEFINITION_RESOLUTION_METHOD,
+  INTERNAL_RESOLUTION_SOURCE,
+  UNRESOLVED_REFERENCE_REASON,
+  TYPESCRIPT_PROJECT_KIND,
+  CI_STATUS,
+  CI_REASON,
+  CLI_COMMAND,
+  CLI_ARGUMENT,
+  CLI_MESSAGE,
+  DOCTOR_CHECK,
+  DOCTOR_REASON,
+  Object.fromEntries(DOCTOR_DISTRIBUTION_ACCEPTED_STATUS.map((status) => [status, status])),
+  DOCTOR_STATUS_PRIORITY,
+  REQUIRED_RUNTIME_COMPONENT,
+  RUNTIME_COMMAND,
+  RUNTIME_REQUIREMENT,
+  RUNTIME_REQUIREMENT_KIND,
+  PACKAGE_PATH,
+  RUNTIME_STATUS,
+  NODE_EVENT,
+  PRODUCT,
+  ENVIRONMENT_VARIABLE,
+  RESULT_SCHEMA,
+  Object.fromEntries(WORKSPACE_CONFIGURATION_FILE_NAMES.map((name) => [name, name])),
+  Object.fromEntries(WORKSPACE_ROOT_MARKER_FILE_NAMES.map((name) => [name, name])),
+  Object.fromEntries(SOURCE_FILE_GLOBS.map((glob) => [glob, glob])),
+  Object.fromEntries(SOURCE_EXCLUDED_GLOBS.map((glob) => [glob, glob])),
+];
+const duplicated = [];
+for (const value of new Set(groups.flatMap((group) => Object.values(group)))) {
+  if (typeof value !== "string") continue;
+  const literal = JSON.stringify(value);
+  for (const runtimeSource of runtimeSources) {
+    if (runtimeSource.source.includes(literal)) duplicated.push(`${runtimeSource.file}: ${literal}`);
+  }
+}
+if (duplicated.length > 0) {
+  process.stderr.write(`Protocol string literals must come from protocol.mjs:\n${duplicated.join("\n")}\n`);
+  process.exitCode = 1;
+}

package/scripts/check-runtime.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+import {ERROR_CODE, PROCESS_EXIT_CODE, RUNTIME_COMMAND, RUNTIME_REQUIREMENT_KIND, RUNTIME_STATUS, SERVER_VERSION} from "../protocol.mjs";
+import {PACKAGE_ROOT, inspectExternalCommand, inspectNodeRuntime, inspectRuntimeComponents} from "../lib/runtime.mjs";
+
+const node = inspectNodeRuntime();
+const components = inspectRuntimeComponents();
+const ripgrep = await inspectExternalCommand(RUNTIME_COMMAND.RIPGREP, ["--version"]);
+const missingComponents = components.filter((component) => !component.available);
+const blocked = !node.supported || missingComponents.length > 0 || !ripgrep.available;
+const unmetRequirements = [
+  ...(!node.supported ? [{requirement: RUNTIME_REQUIREMENT_KIND.NODE, details: node}] : []),
+  ...missingComponents.map((component) => ({requirement: RUNTIME_REQUIREMENT_KIND.RUNTIME_COMPONENT, details: component})),
+  ...(!ripgrep.available ? [{requirement: RUNTIME_COMMAND.RIPGREP, details: ripgrep}] : []),
+];
+const result = {
+  serverVersion: SERVER_VERSION,
+  installationRoot: PACKAGE_ROOT,
+  status: blocked ? RUNTIME_STATUS.BLOCKED : RUNTIME_STATUS.READY,
+  node,
+  components,
+  externalCommands: [ripgrep],
+  error: blocked
+    ? {
+        code: ERROR_CODE.RUNTIME_REQUIREMENT_UNMET,
+        unmetRequirements,
+      }
+    : undefined,
+};
+
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+process.exitCode = blocked ? PROCESS_EXIT_CODE.FAILURE : PROCESS_EXIT_CODE.SUCCESS;