semiotic 3.7.1 → 3.7.3

package/README.md

@@ -12,6 +12,17 @@ Simple charts in 5 lines. Network graphs, streaming data, and coordinated
 dashboards when you need them. Structured schemas and an MCP server so
 AI coding assistants generate correct chart code on the first try.
 
+## What's New in 3.7.3
+
+3.7.3 is a hosted ChatGPT Apps patch release:
+
+- `semiotic-mcp --http` can now serve the OpenAI Apps domain verification challenge from
+  `/.well-known/openai-apps-challenge` when `OPENAI_APPS_CHALLENGE_TOKEN` is configured.
+- The Cloud Run wrapper docs now include the exact Challenge Base URL, token environment variable,
+  and `curl` check for ChatGPT Apps verification.
+- MCP HTTP tests now cover the Apps challenge route while preserving the unauthenticated OAuth
+  discovery 404 behavior.
+
 ```jsx
 import { LineChart } from "semiotic/xy"
 
@@ -411,10 +422,16 @@ Add to your MCP client config (e.g. `claude_desktop_config.json` for Claude Desk
 }
 ```
 
-No API keys or authentication required. The server runs locally via stdio. HTTP mode is also available for inspectors, web clients, and ChatGPT Apps SDK experiments: `npx semiotic-mcp --http --port 3001`.
+No API keys or authentication required. The server runs locally via stdio. HTTP mode is also available for inspectors, web clients, and ChatGPT Apps SDK experiments: `npx semiotic-mcp --http --port 3001`. Since 3.7.2, HTTP mode is stateless: each request gets a fresh read-only MCP server + transport, so it can autoscale on serverless hosts without sticky sessions.
 
 For ChatGPT developer mode, expose the HTTP endpoint over HTTPS with a tunnel and create a connector that points at `https://<your-tunnel>/mcp`. The experimental Apps SDK surface is `renderInteractiveChart`, which returns a `text/html;profile=mcp-app` widget template plus a hidden SVG payload rendered by Semiotic on the MCP server.
 
+For a hosted deployment, see `deploy/cloud-run`. The wrapper runs the published `semiotic-mcp`
+binary, exposes `/mcp` plus health endpoints, and supports `MCP_ALLOWED_HOSTS` for production
+host-header allowlisting. For ChatGPT Apps domain verification, set
+`OPENAI_APPS_CHALLENGE_TOKEN` so HTTP mode serves the raw token from
+`/.well-known/openai-apps-challenge`.
+
 ### Tools
 
 | Tool | Description |

package/ai/behaviorContracts.cjs

@@ -15,13 +15,17 @@ const DOC_MARKER_START = "<!-- semiotic-behavior-contracts:start -->"
 const DOC_MARKER_END = "<!-- semiotic-behavior-contracts:end -->"
 
 // Components whose static config requires `data` are derived from
-// `ai/schema.json` rather than maintained as a hand-curated list. The schema
-// already declares which components require data — duplicating that here led
-// to drift (Heatmap, FunnelChart, MinimapChart, ScatterplotMatrix, and the
-// hierarchy charts were schema-required but missing from the local list,
-// which made `dataRequiredForUsageMode` incorrectly return `false` and
-// suppressed the "data is required" error in --doctor / MCP diagnoseConfig
-// even when usageMode wasn't `push`).
+// `ai/schema.json` rather than maintained as a hand-curated list.
+//
+// A component needs data in STATIC usage if its schema declares a `data` input
+// prop — NOT merely if `data` is in the `required` array. `required` lists the
+// semantic accessors a chart needs (highAccessor, subcategoryAccessor, series,
+// …), and several data-driven charts don't put `data` itself there:
+// CandlestickChart, MultiAxisLineChart, QuadrantChart, DifferenceChart,
+// LikertChart, and SwimlaneChart. Keying off `required.includes("data")` missed
+// exactly those — they'd render blank with no data yet passed --doctor / MCP
+// diagnoseConfig as "OK" in static mode. Keying off the presence of a `data`
+// property catches them (and still includes the charts that DO list `data`).
 //
 // `STATIC_DATA_COMPONENTS` stays exported as a Set for test/legacy callers
 // that probe the surface, and is rebuilt from disk at module load time.
@@ -41,8 +45,10 @@ function loadStaticDataComponentsFromSchema() {
       const schema = JSON.parse(fs.readFileSync(schemaPath, "utf8"))
       const out = new Set()
       for (const tool of schema.tools || []) {
-        const required = tool.function?.parameters?.required || []
-        if (required.includes("data")) out.add(tool.function.name)
+        const properties = tool.function?.parameters?.properties || {}
+        // Data-driven if the schema declares a `data` input prop, regardless of
+        // whether `data` appears in `required` (see note above).
+        if ("data" in properties) out.add(tool.function.name)
       }
       if (out.size > 0) return out
     } catch {
@@ -114,6 +120,10 @@ const PUSH_MODE_COMPONENTS = [
   "Scatterplot",
   "BubbleChart",
   "ConnectedScatterplot",
+  "CandlestickChart",
+  "MultiAxisLineChart",
+  "QuadrantChart",
+  "DifferenceChart",
   "BarChart",
   "StackedBarChart",
   "GroupedBarChart",

package/ai/cli.js

@@ -163,6 +163,21 @@ function validatePropsWithSchema(componentName, props, usageMode = "static") {
     }
   }
 
+  // Array-shape charts that declare a `data` schema prop need it in static
+  // usage even when "data" isn't in `required` (those lists hold semantic
+  // accessors). Without this, --doctor passed dataless static CandlestickChart /
+  // MultiAxisLineChart / QuadrantChart / DifferenceChart / SwimlaneChart /
+  // LikertChart configs that render blank. dataRequiredForUsageMode is true for
+  // them in static and false in push, mirroring the MCP diagnoseConfig path.
+  if (
+    "data" in properties &&
+    !required.includes("data") &&
+    dataRequiredForUsageMode(component.name, usageMode) &&
+    (props.data === undefined || props.data === null)
+  ) {
+    errors.push(`"data" is required for ${component.name}.`)
+  }
+
   for (const [propName, value] of Object.entries(props)) {
     if (value === undefined || value === null) continue
     const propSchema = properties[propName]

package/ai/dist/mcp-server.js

@@ -7,7 +7,11 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -7030,7 +7034,7 @@ var require_chartSuggestions = __commonJS({
   "ai/chartSuggestions.cjs"(exports2, module2) {
     "use strict";
     var path2 = require("path");
-    var VALID_INTENTS = [
+    var VALID_INTENTS2 = [
       "comparison",
       "trend",
       "distribution",
@@ -7163,10 +7167,10 @@ var require_chartSuggestions = __commonJS({
       const data = args.data;
       const intent = args.intent;
       const capabilities = args.capabilities;
-      if (intent && !VALID_INTENTS.includes(intent)) {
+      if (intent && !VALID_INTENTS2.includes(intent)) {
         return {
           ok: false,
-          error: `Unknown intent "${intent}". Expected one of: ${VALID_INTENTS.join(", ")}.`
+          error: `Unknown intent "${intent}". Expected one of: ${VALID_INTENTS2.join(", ")}.`
         };
       }
       if (capabilities) {
@@ -7384,7 +7388,7 @@ ${result.filteredOut.map((s) => `- ${s.component}: ${s.reason}`).join("\n")}
 
 Relax the capability constraints, or use getSchema to browse alternatives.` : `
 
-Try providing intent ('${VALID_INTENTS.join("', '")}') to narrow recommendations, or use getSchema to browse available components.`;
+Try providing intent ('${VALID_INTENTS2.join("', '")}') to narrow recommendations, or use getSchema to browse available components.`;
         return `Could not confidently recommend a chart type.
 
 ${result.fieldSummary}${tail}`;
@@ -7423,7 +7427,7 @@ For accessibility, use \`colorScheme={COLOR_BLIND_SAFE_CATEGORICAL}\` (import fr
       return Object.entries(capabilities).filter(([, v]) => v != null).map(([k, v]) => `${k}=${v}`).join(", ");
     }
     module2.exports = {
-      VALID_INTENTS,
+      VALID_INTENTS: VALID_INTENTS2,
       VALID_CAPABILITY_KEYS,
       formatSuggestionReport: formatSuggestionReport2,
       suggestCharts: suggestCharts2,
@@ -7453,8 +7457,8 @@ var require_behaviorContracts = __commonJS({
           const schema2 = JSON.parse(fs2.readFileSync(schemaPath2, "utf8"));
           const out = /* @__PURE__ */ new Set();
           for (const tool of schema2.tools || []) {
-            const required2 = tool.function?.parameters?.required || [];
-            if (required2.includes("data")) out.add(tool.function.name);
+            const properties = tool.function?.parameters?.properties || {};
+            if ("data" in properties) out.add(tool.function.name);
           }
           if (out.size > 0) return out;
         } catch {
@@ -7520,6 +7524,10 @@ var require_behaviorContracts = __commonJS({
       "Scatterplot",
       "BubbleChart",
       "ConnectedScatterplot",
+      "CandlestickChart",
+      "MultiAxisLineChart",
+      "QuadrantChart",
+      "DifferenceChart",
       "BarChart",
       "StackedBarChart",
       "GroupedBarChart",
@@ -32435,21 +32443,25 @@ ${errors.join("\n")}`
 // ai/mcp-server.ts
 var import_server2 = require("semiotic/server");
 var import_ai3 = require("semiotic/ai");
+var import_componentMetadata = __toESM(require_componentMetadata());
+var import_chartSuggestions = __toESM(require_chartSuggestions());
+var import_behaviorContracts = __toESM(require_behaviorContracts());
 var {
   componentIndexFromSchema,
   metadataForComponent
-} = require_componentMetadata();
+} = import_componentMetadata.default;
 var {
   formatSuggestionReport,
-  suggestCharts
-} = require_chartSuggestions();
+  suggestCharts,
+  VALID_INTENTS
+} = import_chartSuggestions.default;
 var {
   BEHAVIOR_CONTRACTS,
   behaviorContractsFor,
   dataRequiredForUsageMode,
   formatDoctorBehaviorContracts,
   normalizeUsageMode
-} = require_behaviorContracts();
+} = import_behaviorContracts.default;
 var schemaPath = path.resolve(__dirname, "../schema.json");
 var schema = JSON.parse(fs.readFileSync(schemaPath, "utf-8"));
 var schemaByComponent = {};
@@ -32824,8 +32836,23 @@ ${JSON.stringify(contracts, null, 2)}` : "";
 ${JSON.stringify(entry, null, 2)}${contractText}` }]
   };
 }
+var SUGGEST_INTENT_ALIASES = {
+  "compare-series": "comparison",
+  "compare-categories": "comparison",
+  "rank": "comparison",
+  "part-to-whole": "composition",
+  "composition-over-time": "composition",
+  "correlation": "relationship",
+  "flow": "network",
+  "geo": "geographic",
+  "outlier-detection": "distribution",
+  "change-detection": "trend"
+};
 async function suggestChartHandler(args) {
-  const result = suggestCharts(args);
+  let intent = args.intent;
+  if (intent && SUGGEST_INTENT_ALIASES[intent]) intent = SUGGEST_INTENT_ALIASES[intent];
+  if (intent && !VALID_INTENTS.includes(intent)) intent = void 0;
+  const result = suggestCharts({ ...args, intent });
   const content = [{ type: "text", text: formatSuggestionReport(result) }];
   if (!result.ok) {
     return { content, isError: true, structuredContent: result };
@@ -32873,6 +32900,10 @@ async function renderChartHandler(args) {
 ${JSON.stringify(evidence, null, 2)}`
     };
   } catch {
+    evidenceBlock = {
+      type: "text",
+      text: `Render evidence: unavailable for ${component} (no server render config). The SVG above is the validated React render; mark-count / domain evidence is only produced for components with a server render path.`
+    };
   }
   if (theme && Object.keys(theme).length > 0) {
     const validVars = Object.entries(theme).filter(([k]) => k.startsWith("--semiotic-")).map(([k, v]) => `${k}: ${v}`).join("; ");
@@ -33046,23 +33077,26 @@ async function reportIssueHandler(args) {
 ${url2}` }]
   };
 }
-var THEME_PRESET_NAMES = [
-  "light",
-  "dark",
-  "high-contrast",
-  "pastels",
-  "pastels-dark",
-  "bi-tool",
-  "bi-tool-dark",
-  "italian",
-  "italian-dark",
-  "tufte",
-  "tufte-dark",
-  "journalist",
-  "journalist-dark",
-  "playful",
-  "playful-dark"
-];
+var THEME_PRESETS = {
+  "light": "LIGHT_THEME",
+  "dark": "DARK_THEME",
+  "high-contrast": "HIGH_CONTRAST_THEME",
+  "pastels": "PASTELS_LIGHT",
+  "pastels-dark": "PASTELS_DARK",
+  "bi-tool": "BI_TOOL_LIGHT",
+  "bi-tool-dark": "BI_TOOL_DARK",
+  "italian": "ITALIAN_LIGHT",
+  "italian-dark": "ITALIAN_DARK",
+  "tufte": "TUFTE_LIGHT",
+  "tufte-dark": "TUFTE_DARK",
+  "journalist": "JOURNALIST_LIGHT",
+  "journalist-dark": "JOURNALIST_DARK",
+  "playful": "PLAYFUL_LIGHT",
+  "playful-dark": "PLAYFUL_DARK",
+  "carbon": "CARBON_LIGHT",
+  "carbon-dark": "CARBON_DARK"
+};
+var THEME_PRESET_NAMES = Object.keys(THEME_PRESETS);
 async function applyThemeHandler(args) {
   const name = args.name;
   if (!name) {
@@ -33082,6 +33116,7 @@ Dark-mode presets: ${THEME_PRESET_NAMES.filter((n) => n.includes("dark")).join("
       isError: true
     };
   }
+  const exportName = THEME_PRESETS[name];
   const usage = [
     `## Theme: "${name}"`,
     "",
@@ -33095,24 +33130,23 @@ Dark-mode presets: ${THEME_PRESET_NAMES.filter((n) => n.includes("dark")).join("
     "",
     "### Option 2: Import the theme object",
     "```jsx",
-    `import { ${name.replace(/-./g, (c) => c[1].toUpperCase()).replace(/^./, (c) => c.toUpperCase()).replace(/Dark$/, "_DARK").replace(/([a-z])([A-Z])/g, "$1_$2").toUpperCase()} } from "semiotic/themes"`,
-    `<ThemeProvider theme={themeObject}>`,
+    `import { ${exportName} } from "semiotic/themes"`,
+    `<ThemeProvider theme={${exportName}}>`,
     `  <BarChart ... />`,
     `</ThemeProvider>`,
     "```",
     "",
     "### Option 3: CSS custom properties (no React required)",
     "```jsx",
-    `import { themeToCSS } from "semiotic/themes"`,
-    `import { ${name.replace(/-./g, (c) => c[1].toUpperCase()).replace(/^./, (c) => c.toUpperCase()).replace(/Dark$/, "_DARK").replace(/([a-z])([A-Z])/g, "$1_$2").toUpperCase()} } from "semiotic/themes"`,
-    `const css = themeToCSS(themeObject, ".my-charts")`,
+    `import { themeToCSS, ${exportName} } from "semiotic/themes"`,
+    `const css = themeToCSS(${exportName}, ".my-charts")`,
     "// Outputs CSS custom properties string for embedding in a stylesheet",
     "```",
     "",
     "### Option 4: Design tokens JSON",
     "```jsx",
-    `import { themeToTokens } from "semiotic/themes"`,
-    `const tokens = themeToTokens(themeObject)`,
+    `import { themeToTokens, ${exportName} } from "semiotic/themes"`,
+    `const tokens = themeToTokens(${exportName})`,
     "// Style Dictionary / DTCG-compatible token format",
     "```",
     "",
@@ -33403,6 +33437,12 @@ async function groundChartHandler(args) {
     structuredContent: grounding
   };
 }
+var READ_ONLY_TOOL_ANNOTATIONS = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
 function createServer2() {
   const srv = new McpServer({
     name: "semiotic",
@@ -33547,14 +33587,15 @@ function createServer2() {
     "getSchema",
     `Return the prop schema for a Semiotic chart component. Pass { component: '<name>' } to get its props, or omit component to list all available components. Components marked [renderable] can be passed to renderChart for static SVG output.`,
     { component: external_exports3.string().optional().describe("Component name, e.g. 'LineChart'. Omit to list all.") },
+    READ_ONLY_TOOL_ANNOTATIONS,
     getSchemaHandler
   );
   srv.tool(
     "suggestChart",
-    "Recommend Semiotic chart types for a given data sample. Pass { data: [...] } with 1-5 sample objects. Optionally pass intent to narrow suggestions, or capabilities to require/forbid features (push API, linked hover, SSR, selection, legend). Returns ranked recommendations with example props; charts that don't satisfy the capability constraints are dropped.",
+    "Lightweight heuristic chart recommender for a small data sample (1-5 rows) with capability filtering (push API, linked hover, SSR, selection, legend). Returns ranked recommendations with example props. For richer capability-descriptor ranking (scores, reasons, caveats) and the full 13-intent taxonomy, prefer `suggestCharts` (plural).",
     {
       data: external_exports3.array(external_exports3.record(external_exports3.string(), external_exports3.unknown())).min(1).max(5).describe("1-5 sample data objects"),
-      intent: external_exports3.enum(["comparison", "trend", "distribution", "relationship", "composition", "geographic", "network", "hierarchy"]).optional().describe("Visualization intent to narrow suggestions"),
+      intent: external_exports3.string().optional().describe("Visualization intent. Accepts this engine's intents (comparison, trend, distribution, relationship, composition, geographic, network, hierarchy) AND the richer suggestCharts taxonomy (compare-categories, part-to-whole, correlation, flow, geo, rank, \u2026), which is translated automatically; an unrecognized intent is ignored rather than rejected."),
       capabilities: external_exports3.object({
         push: external_exports3.boolean().optional().describe("Require ref-based push API (live streaming via ref.current.push())"),
         linkedHover: external_exports3.boolean().optional().describe("Require cross-chart linked hover support"),
@@ -33567,6 +33608,7 @@ function createServer2() {
         // validation from being unreachable from MCP callers.
       }).strict().optional().describe("Capability constraints \u2014 set a key to true to require, false to forbid. Unset keys are ignored.")
     },
+    READ_ONLY_TOOL_ANNOTATIONS,
     suggestChartHandler
   );
   srv.tool(
@@ -33578,6 +33620,7 @@ function createServer2() {
       theme: external_exports3.record(external_exports3.string(), external_exports3.string()).optional().describe("CSS custom properties for theming, e.g. { '--semiotic-bg': '#1a1a2e', '--semiotic-text': '#ededed' }. Only --semiotic-* variables are applied."),
       format: external_exports3.enum(["svg", "png"]).optional().describe("Output format: 'svg' (default) returns SVG markup, 'png' returns a Base64-encoded PNG image. PNG requires the 'sharp' package.")
     },
+    READ_ONLY_TOOL_ANNOTATIONS,
     renderChartHandler
   );
   srv.registerTool(
@@ -33620,6 +33663,7 @@ function createServer2() {
       props: external_exports3.record(external_exports3.string(), external_exports3.unknown()).optional().describe("Chart props object, e.g. { data: [...], xAccessor: 'x' }."),
       usageMode: external_exports3.enum(["static", "push", "renderChart", "server"]).optional().describe("Validation mode. Use 'push' for ref-based React HOCs that omit data; use 'static' or omit for renderChart/MCP/static data configs.")
     },
+    READ_ONLY_TOOL_ANNOTATIONS,
     diagnoseConfigHandler
   );
   srv.tool(
@@ -33632,6 +33676,7 @@ function createServer2() {
       describe: external_exports3.boolean().optional().describe("True if ChartContainer's describe option (auto-generated L1\u2013L3 description via describeChart) is enabled \u2014 passes the 'features described' heuristic."),
       navigable: external_exports3.boolean().optional().describe("True if ChartContainer's navigable option (structured navigation tree via buildNavigationTree) is enabled \u2014 passes the 'navigable structure' heuristic.")
     },
+    READ_ONLY_TOOL_ANNOTATIONS,
     auditAccessibilityHandler
   );
   srv.tool(
@@ -33642,6 +33687,7 @@ function createServer2() {
       body: external_exports3.string().optional().describe("Issue body with details, reproduction steps, diagnoseConfig output"),
       labels: external_exports3.union([external_exports3.array(external_exports3.string()), external_exports3.string()]).optional().describe("GitHub labels, e.g. ['bug'] or 'bug'")
     },
+    READ_ONLY_TOOL_ANNOTATIONS,
     reportIssueHandler
   );
   srv.tool(
@@ -33650,6 +33696,7 @@ function createServer2() {
     {
       name: external_exports3.string().optional().describe("Theme preset name, e.g. 'tufte', 'pastels-dark', 'bi-tool'. Omit to list all available themes.")
     },
+    READ_ONLY_TOOL_ANNOTATIONS,
     applyThemeHandler
   );
   srv.tool(
@@ -33660,6 +33707,7 @@ function createServer2() {
       props: external_exports3.record(external_exports3.string(), external_exports3.unknown()).describe("The full chart props including data"),
       query: external_exports3.string().optional().describe("A natural language question about the chart data")
     },
+    READ_ONLY_TOOL_ANNOTATIONS,
     interrogateChartHandler
   );
   srv.tool(
@@ -33669,6 +33717,7 @@ function createServer2() {
       component: external_exports3.string().describe("Chart component name, e.g. 'LineChart'"),
       props: external_exports3.record(external_exports3.string(), external_exports3.unknown()).describe("The full chart props including data")
     },
+    READ_ONLY_TOOL_ANNOTATIONS,
     groundChartHandler
   );
   srv.tool(
@@ -33689,6 +33738,7 @@ function createServer2() {
       intent: external_exports3.union([external_exports3.string(), external_exports3.array(external_exports3.string())]).optional().describe("Ranking intent."),
       maxResults: external_exports3.number().int().min(1).max(20).optional()
     },
+    READ_ONLY_TOOL_ANNOTATIONS,
     suggestStreamChartsHandler
   );
   srv.tool(
@@ -33700,6 +33750,7 @@ function createServer2() {
       maxPanels: external_exports3.number().int().min(1).max(12).optional().describe("Maximum panels (default 6)."),
       diversifyByFamily: external_exports3.boolean().optional().describe("Prefer not to repeat chart families across panels (default true).")
     },
+    READ_ONLY_TOOL_ANNOTATIONS,
     suggestDashboardHandler
   );
   srv.tool(
@@ -33724,6 +33775,7 @@ function createServer2() {
       intent: external_exports3.union([external_exports3.string(), external_exports3.array(external_exports3.string())]).optional(),
       maxResults: external_exports3.number().int().min(1).max(20).optional()
     },
+    READ_ONLY_TOOL_ANNOTATIONS,
     suggestStretchChartsHandler
   );
   srv.tool(
@@ -33735,6 +33787,7 @@ function createServer2() {
       intent: external_exports3.union([external_exports3.string(), external_exports3.array(external_exports3.string())]).optional().describe("User intent \u2014 informs ranking of alternatives when the chart doesn't fit."),
       maxAlternatives: external_exports3.number().int().min(1).max(10).optional().describe("Cap on alternatives returned (default 3).")
     },
+    READ_ONLY_TOOL_ANNOTATIONS,
     repairChartConfigHandler
   );
   srv.tool(
@@ -33761,6 +33814,7 @@ function createServer2() {
         receptionModality: external_exports3.enum(["visual", "screen-reader", "sonified", "agent"]).optional().describe("Reception channel \u2014 see suggestCharts.")
       }).optional().describe("Audience profile \u2014 familiarity, adoption targets, exposure level, and reception modality.")
     },
+    READ_ONLY_TOOL_ANNOTATIONS,
     proposeChartVariantsHandler
   );
   srv.tool(
@@ -33787,6 +33841,7 @@ function createServer2() {
         receptionModality: external_exports3.enum(["visual", "screen-reader", "sonified", "agent"]).optional().describe("Reception channel. A non-visual value down-ranks charts the audience can't receive in that channel (e.g. a many-slice pie for a screen reader) and adds receivability caveats.")
       }).optional().describe("Audience profile \u2014 familiarity, adoption targets, exposure level, and reception modality.")
     },
+    READ_ONLY_TOOL_ANNOTATIONS,
     suggestChartsHandler
   );
   return srv;
@@ -33798,39 +33853,98 @@ var parsedPort = portFlagIndex !== -1 && cliArgs[portFlagIndex + 1] != null ? pa
 var port = Number.isFinite(parsedPort) ? parsedPort : 3001;
 async function main() {
   if (httpMode) {
-    const sessions = /* @__PURE__ */ new Map();
+    const allowedHosts = (process.env.MCP_ALLOWED_HOSTS || "").split(",").map((h) => h.trim().toLowerCase()).filter(Boolean);
+    const openaiAppsChallengeToken = (process.env.OPENAI_APPS_CHALLENGE_TOKEN || "").trim();
+    const healthBody = () => JSON.stringify({
+      status: "ok",
+      name: "semiotic-mcp",
+      version: schema.version || "3.0.0",
+      transport: "streamable-http",
+      mode: "stateless"
+    });
     const httpServer = http.createServer(async (req, res) => {
       res.setHeader("Access-Control-Allow-Origin", "*");
-      res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
-      res.setHeader("Access-Control-Allow-Headers", "Content-Type, mcp-session-id");
-      res.setHeader("Access-Control-Expose-Headers", "mcp-session-id");
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+      res.setHeader(
+        "Access-Control-Allow-Headers",
+        "Content-Type, Accept, Authorization, mcp-session-id, MCP-Protocol-Version, Last-Event-ID"
+      );
+      res.setHeader("Access-Control-Expose-Headers", "MCP-Protocol-Version");
       if (req.method === "OPTIONS") {
         res.writeHead(204);
         res.end();
         return;
       }
-      const sessionId = req.headers["mcp-session-id"];
-      if (sessionId && sessions.has(sessionId)) {
-        const session = sessions.get(sessionId);
-        await session.transport.handleRequest(req, res);
-      } else if (!sessionId) {
-        const transport = new StreamableHTTPServerTransport({
-          sessionIdGenerator: () => `semiotic-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+      const pathname = (() => {
+        try {
+          return new URL(req.url || "/", "http://localhost").pathname;
+        } catch {
+          return "/";
+        }
+      })();
+      if (allowedHosts.length > 0) {
+        const rawHost = String(req.headers.host || "").trim().toLowerCase();
+        const normalizedHost = rawHost.startsWith("[") ? rawHost.replace(/^\[([^\]]+)\](?::\d+)?$/, "$1") : rawHost.split(":")[0];
+        if (!allowedHosts.includes(rawHost) && !allowedHosts.includes(normalizedHost)) {
+          res.writeHead(403, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32e3, message: "Forbidden host" }, id: null }));
+          return;
+        }
+      }
+      if (req.method === "GET" && (pathname === "/healthz" || pathname === "/health")) {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(healthBody());
+        return;
+      }
+      if (req.method === "GET" && pathname === "/.well-known/openai-apps-challenge" && openaiAppsChallengeToken) {
+        res.writeHead(200, {
+          "Content-Type": "text/plain; charset=utf-8",
+          "Cache-Control": "no-store"
         });
-        const srv = createServer2();
+        res.end(openaiAppsChallengeToken);
+        return;
+      }
+      if (pathname !== "/" && pathname !== "/mcp") {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Not found" }));
+        return;
+      }
+      if (req.method === "GET") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(healthBody());
+        return;
+      }
+      if (req.method !== "POST") {
+        res.writeHead(405, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32e3, message: "Method not allowed" }, id: null }));
+        return;
+      }
+      const srv = createServer2();
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: void 0,
+        enableJsonResponse: true
+      });
+      let torndown = false;
+      const teardown = () => {
+        if (torndown) return;
+        torndown = true;
+        Promise.resolve(transport.close()).catch(() => {
+        });
+        Promise.resolve(srv.close()).catch(() => {
+        });
+      };
+      res.on("close", teardown);
+      try {
         await srv.connect(transport);
-        transport.onclose = () => {
-          const sid2 = transport.sessionId;
-          if (sid2) sessions.delete(sid2);
-        };
         await transport.handleRequest(req, res);
-        const sid = transport.sessionId;
-        if (sid) {
-          sessions.set(sid, { server: srv, transport });
+      } catch (err) {
+        console.error("Request handling error:", err);
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32603, message: "Internal server error" }, id: null }));
         }
-      } else {
-        res.writeHead(400, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32e3, message: "Unknown session. Send a request without mcp-session-id to start a new session." }, id: null }));
+      } finally {
+        teardown();
       }
     });
     httpServer.listen(port, () => {

package/ai/schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "semiotic",
-  "version": "3.7.1",
+  "version": "3.7.3",
   "description": "React data visualization library for charts, networks, and beyond",
   "tools": [
     {

package/dist/components/stream/NetworkCanvasHitTester.d.ts

@@ -1,4 +1,5 @@
-import type { NetworkSceneNode, NetworkSceneEdge } from "./networkTypes";
+import type { NetworkSceneNode, NetworkSceneEdge, NetworkCircleNode } from "./networkTypes";
+import type { Quadtree } from "d3-quadtree";
 export interface NetworkHitResult {
     type: "node" | "edge";
     datum: any;
@@ -11,4 +12,4 @@ export interface NetworkHitResult {
  *
  * Checks nodes first (they're on top), then edges.
  */
-export declare function findNearestNetworkNode(sceneNodes: NetworkSceneNode[], sceneEdges: NetworkSceneEdge[], px: number, py: number, maxDistance?: number): NetworkHitResult | null;
+export declare function findNearestNetworkNode(sceneNodes: NetworkSceneNode[], sceneEdges: NetworkSceneEdge[], px: number, py: number, maxDistance?: number, nodeQuadtree?: Quadtree<NetworkCircleNode> | null, maxNodeRadius?: number): NetworkHitResult | null;