@amcharts/amcharts5-mcp 1.9.0 → 1.9.2

package/extended/reference/xychart.md

@@ -2,7 +2,7 @@
 title: "XYChart"
 type: "class"
 source: "https://www.amcharts.com/docs/v5/reference/xychart/"
-generatedFrom: "@amcharts/amcharts5@5.21.3"
+generatedFrom: "@amcharts/amcharts5@5.21.4"
 ---
 
 A chart with X and Y axes, for line, column, scatter and other XY series.

package/extended/reference/xychartdefaulttheme.md

@@ -2,7 +2,7 @@
 title: "XYChartDefaultTheme"
 type: "class"
 source: "https://www.amcharts.com/docs/v5/reference/xychartdefaulttheme/"
-generatedFrom: "@amcharts/amcharts5@5.21.3"
+generatedFrom: "@amcharts/amcharts5@5.21.4"
 ---
 
 Built-in theme rules: `StockChart` and `XYChart` add this theme to their default themes, so its rules apply to those elements and everything inside them.

package/extended/reference/xychartscrollbar.md

@@ -2,7 +2,7 @@
 title: "XYChartScrollbar"
 type: "class"
 source: "https://www.amcharts.com/docs/v5/reference/xychartscrollbar/"
-generatedFrom: "@amcharts/amcharts5@5.21.3"
+generatedFrom: "@amcharts/amcharts5@5.21.4"
 ---
 
 A scrollbar with a small preview chart in it. Add axes and series to its `chart` to draw the preview.

package/extended/reference/xycursor.md

@@ -2,7 +2,7 @@
 title: "XYCursor"
 type: "class"
 source: "https://www.amcharts.com/docs/v5/reference/xycursor/"
-generatedFrom: "@amcharts/amcharts5@5.21.3"
+generatedFrom: "@amcharts/amcharts5@5.21.4"
 ---
 
 Crosshair lines over an `XYChart` that follow the pointer and show the axis and series tooltips. Dragging can zoom or select (`behavior`).

package/extended/reference/xyseries.md

@@ -2,7 +2,7 @@
 title: "XYSeries"
 type: "class"
 source: "https://www.amcharts.com/docs/v5/reference/xyseries/"
-generatedFrom: "@amcharts/amcharts5@5.21.3"
+generatedFrom: "@amcharts/amcharts5@5.21.4"
 ---
 
 Base class for all XY chart series.

package/extended/reference/zigzag.md

@@ -2,7 +2,7 @@
 title: "ZigZag"
 type: "class"
 source: "https://www.amcharts.com/docs/v5/reference/zigzag/"
-generatedFrom: "@amcharts/amcharts5@5.21.3"
+generatedFrom: "@amcharts/amcharts5@5.21.4"
 ---
 
 ZigZag indicator: straight lines between the price's turning points, ignoring moves smaller than `deviation`. Drawn over the main series.

package/extended/reference/zoomablecontainer.md

@@ -2,7 +2,7 @@
 title: "ZoomableContainer"
 type: "class"
 source: "https://www.amcharts.com/docs/v5/reference/zoomablecontainer/"
-generatedFrom: "@amcharts/amcharts5@5.21.3"
+generatedFrom: "@amcharts/amcharts5@5.21.4"
 ---
 
 A `Container` whose `contents` can be zoomed with the wheel, a pinch or `ZoomTools`, and panned by dragging.

package/extended/reference/zoomcontrol.md

@@ -2,7 +2,7 @@
 title: "ZoomControl"
 type: "class"
 source: "https://www.amcharts.com/docs/v5/reference/zoomcontrol/"
-generatedFrom: "@amcharts/amcharts5@5.21.3"
+generatedFrom: "@amcharts/amcharts5@5.21.4"
 ---
 
 Buttons that zoom a `MapChart` in and out, set as its `zoomControl`. A home button is there too, hidden by default.

package/extended/reference/zoomtools.md

@@ -2,7 +2,7 @@
 title: "ZoomTools"
 type: "class"
 source: "https://www.amcharts.com/docs/v5/reference/zoomtools/"
-generatedFrom: "@amcharts/amcharts5@5.21.3"
+generatedFrom: "@amcharts/amcharts5@5.21.4"
 ---
 
 Home, zoom-in and zoom-out buttons for a zoomable `target`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amcharts/amcharts5-mcp",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "mcpName": "io.github.amcharts/amcharts5",
   "description": "On-demand access to amCharts 5 docs, code examples, and API reference",
   "type": "module",
@@ -18,13 +18,16 @@
   "scripts": {
     "start": "node src/index.js",
     "dev": "node --watch src/index.js",
-    "test": "node scripts/check-examples.js && node test.js",
+    "test": "node scripts/check-examples.js && node scripts/build-plugin.js --check && node test.js",
     "check:examples": "node scripts/check-examples.js",
     "build:examples": "node scripts/build-examples.js",
     "clean:examples": "node scripts/clean-examples2.js && node scripts/clean-all.js extended/examples && node scripts/check-examples.js",
     "build:worker": "node scripts/build-worker-content.js",
     "build:reference": "node scripts/generate-reference.cjs",
     "build:geodata": "node scripts/generate-geodata-index.cjs",
+    "build:plugin": "node scripts/build-plugin.js",
+    "build:openai": "node scripts/build-openai-plugin.js",
+    "build:json-configs": "node scripts/build-json-configs.js",
     "dev:worker": "npm run build:worker && wrangler dev",
     "deploy": "npm run build:worker && wrangler deploy",
     "prepublishOnly": "node -e \"const fs=require('fs');if(!fs.existsSync('content'))fs.mkdirSync('content');fs.cpSync('amcharts5-skill/amcharts5-skill/SKILL.md','content/SKILL.md');for(const f of fs.readdirSync('amcharts5-skill/amcharts5-skill/references').filter(x=>x.endsWith('.md')))fs.cpSync('amcharts5-skill/amcharts5-skill/references/'+f,'content/'+f)\"",
@@ -58,7 +61,7 @@
     "zod": "^3.25 || ^4.0"
   },
   "devDependencies": {
-    "@amcharts/amcharts5": "5.21.3",
+    "@amcharts/amcharts5": "5.21.4",
     "agents": "^0.28.1",
     "jsdom": "^29.0.0",
     "turndown": "^7.2.2",

package/src/content.js

@@ -45,6 +45,8 @@ export const CHART_TYPE_MAP = {
   // UI
   "ui": "ui-elements", "ui-elements": "ui-elements", "button": "ui-elements",
   "slider": "ui-elements", "controls": "ui-elements",
+  // A chart as a JSON config (JsonParser, <am5-chart>, Chart Maker links)
+  "json": "json", "json-config": "json", "config": "json", "serialized": "json",
 };
 
 export function parseSections(content) {
@@ -171,6 +173,29 @@ export function isUnsearchedSection(key, section) {
   return key.startsWith("reference/") && section.heading.startsWith("Other inherited ");
 }
 
+/**
+ * The text search indexes for an example. A JSON config page (json-configs/)
+ * is searched by its description and the class names its config uses, not by
+ * the config: the configs repeat setting names ("autoAppear", "valueField")
+ * dozens of times and would crowd the docs and API reference out of a search
+ * for a setting. The page itself is still returned whole.
+ */
+export function searchableExample(text) {
+  const cut = text.indexOf("## JSON config");
+  if (cut === -1) return text;
+  const types = new Set();
+  for (const m of text.slice(cut).matchAll(/"type":\s*"([A-Za-z]+)"/g)) types.add(m[1]);
+  // Only what is the page's own: the boilerplate every config page shares
+  // (JsonParser, <am5-chart>, Chart Maker) would outrank the skill's JSON reference
+  const own = text.slice(0, cut).split(/\nA complete amCharts 5 JSON config/)[0];
+  return `${own}\nJSON config: ${[...types].join(" ")}`;
+}
+
+/** An example's title as search ranks it: a config page without its "(JSON config)" suffix. */
+export function searchableTitle(title) {
+  return title.replace(/ \(JSON config\)$/, "");
+}
+
 // ---------------------------------------------------------------------------
 // Search — one ranked index shared by search_docs and search_all.
 //
@@ -385,7 +410,7 @@ function buildSearchIndex(content) {
     const slug = key.split("/").pop();
     add(KIND_EXAMPLE,
       { kind: "example", file: key, docTitle: ex.title, heading: ex.category, body: ex.content },
-      `${ex.title} ${slug.replace(/-/g, " ")}`, ex.category.replace(/-/g, " "), ex.content, [ex.title, slug]);
+      `${searchableTitle(ex.title)} ${slug.replace(/-/g, " ")}`, ex.category.replace(/-/g, " "), searchableExample(ex.content), [ex.title, slug]);
   }
 
   const avgLength = [0, 0, 0];

package/src/tools.js

@@ -22,9 +22,117 @@ const FRAMEWORK_NOTE = `
 ## In a React, Vue, Angular, Svelte or React Native app
 Use amCharts' package for the framework: \`@amcharts/amcharts5-react\`, \`-vue\`, \`-angular\` or \`-svelte\`. It creates and disposes the root, and works with server rendering. Its setup function receives \`root\`, so put the code above that follows \`am5.Root.new(...)\` inside it, e.g. in React \`const { ref, result } = useAmChart((root) => { /* the chart */ return { series }; }, []);\` with \`<div ref={ref} style={{ height: "500px" }} />\`. Deps such as \`[data]\` make the chart again from scratch; to change data in place, return what you need and update it through \`result\`. \`@amcharts/amcharts5-react-native\` takes the chart code as a string instead. Details: \`get_section("SKILL", "Frameworks")\`, and \`get_doc("getting-started/integrations/react")\` (also \`vue\`, \`angular\`, \`sveltekit\`, \`next-js\`, \`nuxt\`, \`react-native\`).`;
 
+// A docs path from what an agent holds: an amcharts.com address
+// ("https://www.amcharts.com/docs/v5/concepts/events/#Global_events"),
+// a site path ("/docs/v5/concepts/events") or the tools' own form
+// ("concepts/events", "skill/xy.md"). Returns the tools' form.
+function docPathFromInput(input) {
+  return String(input ?? "").trim()
+    .replace(/[?#].*$/, "")
+    .replace(/^(https?:\/\/)?(www\.)?amcharts\.com(?=\/|$)/i, "")
+    .replace(/^\/+/, "")
+    .replace(/^docs\/v5\//i, "")
+    .replace(/\/+$/, "")
+    .replace(/\.md$/i, "");
+}
+
+// The demo slug of an amcharts.com demo address ("…/demos/sankey-diagram/")
+function demoSlug(input) {
+  const m = /amcharts\.com\/demos\/([^/?#]+)/i.exec(String(input ?? ""));
+  return m ? m[1].toLowerCase() : null;
+}
+
 // User text echoed back in a reply, capped so a huge query can't balloon it
 const echo = (s) => { s = String(s ?? ""); return s.length > 200 ? s.slice(0, 200) + "…" : s; };
 
+// --- Overviews of long references -------------------------------------------
+// A reference longer than OVERVIEW_CAP characters is answered with an
+// overview: as many of its parts as fit in the cap, in document order, then a
+// list of the parts left out, each one fetchable by get_section. The 2026-10
+// eval measured the long references (SKILL.md, map.md) as half of all input
+// tokens, because every later step of an answer reads them again.
+export const OVERVIEW_CAP = 12000;
+// A section longer than this is offered by its ### subsections
+export const SPLIT_OVER = 6000;
+// "Example 1: …", "Example: Spiral chart", "amCharts 5 XY Charts — Working Examples"
+const isExampleSection = (heading) => /^Example\b|Working Examples$/i.test(heading || "");
+
+// A section body split at its ### headings: the text before the first one
+// (heading null), then each subsection
+export function splitSubsections(body) {
+  const parts = [{ heading: null, text: [] }];
+  for (const line of String(body).split("\n")) {
+    const m = /^###\s+(.+)/.exec(line);
+    if (m) parts.push({ heading: m[1].trim(), text: [] });
+    else parts[parts.length - 1].text.push(line);
+  }
+  return parts
+    .map((p) => ({ heading: p.heading, text: p.text.join("\n").trim() }))
+    .filter((p) => p.heading || p.text);
+}
+
+// The parts an overview is made of: each ## section, or for a long section
+// with ### subsections, its opening text and each subsection
+function overviewUnits(doc) {
+  const units = [];
+  for (const s of doc.sections) {
+    const body = s.body.trim();
+    if (!s.heading && (!body || body.startsWith("---"))) continue; // front matter
+    const subs = splitSubsections(s.body);
+    if (s.body.length > SPLIT_OVER && subs.some((p) => p.heading)) {
+      for (const p of subs) units.push({ section: s.heading, heading: p.heading, text: p.text });
+    } else if (body) {
+      // an empty section is only a divider ("Working Examples" before the examples)
+      units.push({ section: s.heading, heading: null, text: body });
+    }
+  }
+  return units;
+}
+
+// The overview text, or null when the doc fits in `cap`. `file` is what
+// get_section takes for this doc ("map", "SKILL", "reference/ixyseriessettings").
+export function overviewOf(doc, { file, label, cap = OVERVIEW_CAP, title = true }) {
+  if (doc.content.length <= cap) return null;
+  const units = overviewUnits(doc);
+  const shown = new Set();
+  let used = 0;
+  let full = false;
+  for (const u of units) {
+    // Worked examples are long code; they always go to the list
+    if (isExampleSection(u.section)) continue;
+    // The first parts, in order, until one doesn't fit; everything after is listed
+    const size = u.text.length + (u.heading || u.section).length + 8;
+    if (!full && used + size <= cap) { shown.add(u); used += size; } else full = true;
+  }
+  let text = title ? `# ${doc.title}\n` : "";
+  text += `*(source: ${label}.md. An overview: ${used.toLocaleString("en-US")} of ${doc.content.length.toLocaleString("en-US")} characters. The parts not shown are listed at the end.)*\n\n`;
+  let openSection = null;
+  for (const u of units) {
+    if (!shown.has(u)) continue;
+    if (u.section !== openSection) {
+      // the doc's own title section is already the heading above
+      if (!(u.section === doc.title && title)) text += `## ${u.section}\n`;
+      openSection = u.section;
+    }
+    text += u.heading ? `### ${u.heading}\n${u.text}\n\n` : `${u.text}\n\n`;
+  }
+  const rest = units.filter((u) => !shown.has(u) && (u.heading || u.section));
+  text += `---\n\n## Not shown in this overview\n\n`;
+  text += `get_section("${file}", heading) returns each of these in full (the heading is matched case-insensitively):\n`;
+  const chars = (n) => `${n.toLocaleString("en-US")} characters`;
+  for (const u of rest) {
+    if (u.heading) {
+      text += `- "${u.heading}" (in "${u.section}", ${chars(u.text.length)})\n`;
+    } else {
+      // get_section on a section heading returns the whole section, subsections included
+      const whole = doc.sections.find((s) => s.heading === u.section);
+      const split = whole && units.some((v) => v.section === u.section && v.heading);
+      text += `- "${u.section}" (${split ? "the whole section, " : ""}${chars(whole ? whole.body.trim().length : u.text.length)})\n`;
+    }
+  }
+  return text.trim();
+}
+
 // Searches about map files get pointed at list_geodata, which has every name.
 const GEODATA_QUERY_RE = /geo ?data|congressional|am5geodata|\b(?:low|high)\.js\b/i;
 const GEODATA_HINT = "\n\n> Looking for a map file? list_geodata(filter) lists every geodata file (world, countries, regions, US congressional packs per Congress) with its CDN path, global name and ES import.";
@@ -33,13 +141,18 @@ const geodataHint = (query) => (GEODATA_QUERY_RE.test(query) ? GEODATA_HINT : ""
 export function registerTools(server, content) {
   const { docs, extendedDocs, examples } = content;
 
+  // Directories read a tool's display name from the top-level `title` or from
+  // `annotations.title` (Claude's directory portal): give both, from one title.
+  const registerTool = (name, config, handler) =>
+    server.registerTool(name, { ...config, annotations: { title: config.title, ...config.annotations } }, handler);
+
   // Resolve any identifier a search result prints — "skill/SKILL.md",
   // "skill/xy", "SKILL", "xy.md", "extended/charts/xy-chart/cursor",
   // "charts/xy-chart/cursor", "reference/xycursor" — to a doc. Search results
   // label their source exactly this way, so an agent can paste the label
   // straight into get_section / get_doc.
   function resolveDoc(id) {
-    let key = String(id || "").trim().replace(/^\/+|\/+$/g, "").replace(/\.md$/i, "");
+    let key = docPathFromInput(id);
     if (!key) return null;
     let skillKey = key.startsWith("skill/") ? key.slice("skill/".length) : key;
     if (docs.has(skillKey)) return { doc: docs.get(skillKey), label: `skill/${skillKey}` };
@@ -53,8 +166,38 @@ export function registerTools(server, content) {
     return null;
   }
 
+  // Examples by their amcharts.com demo slug, and by their own last path part
+  // (every key that has it: a shared name resolves only when it is unique)
+  const exampleByDemo = new Map();
+  const exampleBySlug = new Map();
+  for (const [key, ex] of examples) {
+    const demo = demoSlug(ex.source);
+    if (demo) exampleByDemo.set(demo, key);
+    const slug = key.split("/").pop().toLowerCase();
+    exampleBySlug.set(slug, [...(exampleBySlug.get(slug) || []), key]);
+  }
+
+  // Resolve an example from its key ("examples/flow/sankey-diagram"), the key
+  // without "examples/" ("flow/sankey-diagram"), its demo address
+  // ("https://www.amcharts.com/demos/sankey-diagram/"), or a unique last part
+  // ("sankey-diagram").
+  function resolveExample(input) {
+    const demo = demoSlug(input);
+    if (demo && exampleByDemo.has(demo)) return exampleByDemo.get(demo);
+    const key = String(input ?? "").trim().replace(/[?#].*$/, "").replace(/^\/+|\/+$/g, "").replace(/\.md$/i, "");
+    if (examples.has(key)) return key;
+    if (examples.has(`examples/${key}`)) return `examples/${key}`;
+    const bySlug = exampleBySlug.get(key.split("/").pop().toLowerCase()) || [];
+    return bySlug.length === 1 ? bySlug[0] : null;
+  }
+
+  // Keys sharing an example name, for a not-found message ("pie-chart" is both
+  // a demo and a JSON config)
+  const examplesNamed = (input) =>
+    exampleBySlug.get(String(input ?? "").trim().replace(/[?#].*$/, "").replace(/^\/+|\/+$/g, "").replace(/\.md$/i, "").split("/").pop().toLowerCase()) || [];
+
   // --- Tool: list_chart_types ---
-  server.registerTool(
+  registerTool(
     "list_chart_types",
     {
       title: "List chart types",
@@ -82,15 +225,18 @@ export function registerTools(server, content) {
   );
 
   // --- Tool: get_chart_reference ---
-  server.registerTool(
+  registerTool(
     "get_chart_reference",
     {
       title: "Get chart reference",
-      description: "Get the full reference documentation for a specific amCharts 5 chart type. Use list_chart_types first to see available types.",
-      inputSchema: { chartType: z.string().describe("Chart type keyword, e.g. 'pie', 'sankey', 'xy', 'treemap', 'map', 'radar', 'stock', 'gantt', 'venn', 'wordcloud', 'timeline', 'flow', 'hierarchy', 'ui-elements'") },
+      description: `Get the reference documentation for a specific amCharts 5 chart type. A reference longer than ${OVERVIEW_CAP.toLocaleString("en-US")} characters comes as an overview: its first parts in full and a list of the others, each of which get_section returns. With \`full: true\` it is the whole file. The chart type keywords are listed by list_chart_types.`,
+      inputSchema: {
+        chartType: z.string().describe("Chart type keyword, e.g. 'pie', 'sankey', 'xy', 'treemap', 'map', 'radar', 'stock', 'gantt', 'venn', 'wordcloud', 'timeline', 'flow', 'hierarchy', 'ui-elements'"),
+        full: z.boolean().optional().default(false).describe("true: the whole reference, however long. false (default): an overview when it is long."),
+      },
       annotations: READ_ONLY,
     },
-    async ({ chartType }) => {
+    async ({ chartType, full }) => {
       const key = CHART_TYPE_MAP[chartType.toLowerCase()] || chartType.toLowerCase();
       const doc = docs.get(key);
       if (!doc) {
@@ -99,34 +245,38 @@ export function registerTools(server, content) {
           content: [{ type: "text", text: `No reference found for "${echo(chartType)}". Available: ${available}` }],
         };
       }
-      return { content: [{ type: "text", text: doc.content }] };
+      const text = (!full && overviewOf(doc, { file: key, label: `skill/${key}` })) || doc.content;
+      return { content: [{ type: "text", text }] };
     }
   );
 
   // --- Tool: get_core_reference ---
-  server.registerTool(
+  registerTool(
     "get_core_reference",
     {
       title: "Get core reference (setup, themes, pitfalls)",
-      description: "Get the core amCharts 5 reference (SKILL.md) — covers setup, colors, themes, legends, tooltips, events, data, adapters, disposal, and common pitfalls. Read this first before any chart-specific reference.",
-      inputSchema: {},
+      description: `Get the core amCharts 5 reference (SKILL.md) — covers setup, colors, themes, legends, tooltips, events, data, adapters, disposal, and common pitfalls. It is the base for every chart type; the chart-specific references build on it. It comes as an overview: its first sections, up to ${OVERVIEW_CAP.toLocaleString("en-US")} characters, and a list of the others, each of which get_section("SKILL", heading) returns. With \`full: true\` it is the whole file.`,
+      inputSchema: {
+        full: z.boolean().optional().default(false).describe("true: the whole SKILL.md (about 105,000 characters). false (default): the overview."),
+      },
       annotations: READ_ONLY,
     },
-    async () => {
+    async ({ full }) => {
       const doc = docs.get("SKILL");
       if (!doc) {
         return { content: [{ type: "text", text: "Core SKILL.md not found." }] };
       }
-      return { content: [{ type: "text", text: doc.content }] };
+      const text = (!full && overviewOf(doc, { file: "SKILL", label: "skill/SKILL" })) || doc.content;
+      return { content: [{ type: "text", text }] };
     }
   );
 
   // --- Tool: search_docs ---
-  server.registerTool(
+  registerTool(
     "search_docs",
     {
       title: "Search docs",
-      description: "Search the curated amCharts 5 skill docs (SKILL.md + chart references) for a keyword or topic, returning matching sections ranked by relevance. NOTE: by default this scans ONLY the skill layer. The per-class API reference and per-setting DEFAULTS (e.g. tooltip background cornerRadius, axis tick `visible` default, cursor line strokeDasharray) live in the extended docs — pass scope:'all' here (which also searches the code examples), or use search_all / get_api_reference / get_doc, to reach them.",
+      description: "Search the curated amCharts 5 skill docs (SKILL.md + chart references) for a keyword or topic, returning matching sections ranked by relevance. By default it searches only the skill layer. With scope 'all' it also searches the extended docs, the per-class API reference and the code examples. Per-setting defaults (e.g. tooltip background cornerRadius, axis tick `visible` default, cursor line strokeDasharray) are in the extended docs and the API reference, which search_all, get_api_reference and get_doc also return.",
       inputSchema: {
         query: z.string().describe("Search query, e.g. 'legend', 'axis label rotation', 'tooltip format', 'data processor'"),
         maxResults: z.number().optional().default(5).describe("Maximum number of results to return (default 5)"),
@@ -186,14 +336,14 @@ export function registerTools(server, content) {
   );
 
   // --- Tool: get_section ---
-  server.registerTool(
+  registerTool(
     "get_section",
     {
       title: "Get doc section",
-      description: "Get the FULL text of one section of a doc by heading — use it to expand a truncated search_docs / search_all result. `file` accepts the source label exactly as search results print it ('skill/SKILL.md', 'skill/xy', 'extended/charts/xy-chart/cursor', 'reference/xycursor') as well as a bare skill file name ('SKILL', 'xy', 'map').",
+      description: "Get the full text of one section of a doc by heading, for example a section that a search_docs or search_all result shows truncated. `file` accepts the source label exactly as search results print it ('skill/SKILL.md', 'skill/xy', 'extended/charts/xy-chart/cursor', 'reference/xycursor') as well as a bare skill file name ('SKILL', 'xy', 'map').",
       inputSchema: {
         file: z.string().describe("Doc identifier: a skill file ('SKILL', 'xy', 'pie', 'map') or a source label from search results ('skill/SKILL.md', 'extended/concepts/events', 'reference/xycursor'). '.md' and 'skill/' / 'extended/' prefixes are optional."),
-        heading: z.string().describe("Section heading to retrieve (case-insensitive substring), e.g. 'Core setup pattern', 'Axis types', 'Common pitfalls', 'Recent API changes'"),
+        heading: z.string().describe("Section heading to retrieve (case-insensitive substring), e.g. 'Core setup pattern', 'Axis types', 'Common pitfalls', 'Recent API changes'. A ### subsection heading returns just that subsection."),
       },
       annotations: READ_ONLY,
     },
@@ -205,22 +355,30 @@ export function registerTools(server, content) {
       }
       const { doc, label } = resolved;
 
-      const needle = heading.toLowerCase();
-      const section = doc.sections.find(s => s.heading.toLowerCase().includes(needle));
-      if (!section) {
-        const available = doc.sections.map(s => s.heading).filter(Boolean).join("\n- ");
-        return {
-          content: [{ type: "text", text: `Section "${heading}" not found in ${label}.md.\n\nAvailable sections:\n- ${available}` }],
-        };
+      // In order: an exact ## heading; an exact ### heading in a long section
+      // (the subsections an overview lists); a ## heading containing the text;
+      // a ### heading containing it. A ### match returns just that subsection.
+      const needle = heading.trim().toLowerCase();
+      const subs = doc.sections.flatMap(s => splitSubsections(s.body).filter(p => p.heading).map(p => ({ ...p, section: s.heading, long: s.body.length > SPLIT_OVER })));
+      const exactSection = doc.sections.find(s => s.heading.toLowerCase() === needle);
+      const exactSub = !exactSection && subs.find(p => p.long && p.heading.toLowerCase() === needle);
+      const section = exactSection || (!exactSub && doc.sections.find(s => s.heading.toLowerCase().includes(needle)));
+      const sub = exactSub || (!section && subs.find(p => p.heading.toLowerCase().includes(needle)));
+      if (section) {
+        return { content: [{ type: "text", text: `# ${section.heading}\n*(source: ${label}.md)*\n\n${section.body}` }] };
       }
+      if (sub) {
+        return { content: [{ type: "text", text: `# ${sub.heading}\n*(source: ${label}.md, in "${sub.section}")*\n\n${sub.text}` }] };
+      }
+      const available = doc.sections.map(s => s.heading).filter(Boolean).join("\n- ");
       return {
-        content: [{ type: "text", text: `# ${section.heading}\n*(source: ${label}.md)*\n\n${section.body}` }],
+        content: [{ type: "text", text: `Section "${heading}" not found in ${label}.md.\n\nAvailable sections:\n- ${available}` }],
       };
     }
   );
 
   // --- Tool: get_quick_start ---
-  server.registerTool(
+  registerTool(
     "get_quick_start",
     {
       title: "Get quick-start template",
@@ -279,11 +437,11 @@ export function registerTools(server, content) {
   );
 
   // --- Tool: search_all ---
-  server.registerTool(
+  registerTool(
     "search_all",
     {
       title: "Search all content",
-      description: "Search across ALL amCharts 5 content: skill references, full documentation, and code examples. Use this for broad searches across everything.",
+      description: "Search across all amCharts 5 content: skill references, full documentation, and code examples. For broad searches across everything.",
       inputSchema: {
         query: z.string().describe("Search query, e.g. 'react integration', 'date axis formatting', 'stacked bar example'"),
         maxResults: z.number().optional().default(10).describe("Maximum results (default 10)"),
@@ -309,18 +467,18 @@ export function registerTools(server, content) {
   );
 
   // --- Tool: get_doc ---
-  server.registerTool(
+  registerTool(
     "get_doc",
     {
       title: "Get doc page",
-      description: "Get a full documentation page — an extended doc by path, or a skill file by 'skill/<name>'. Accepts the source label exactly as search_docs / search_all print it. Use search_all first to find the right path.",
+      description: "Get a full documentation page — an extended doc by path, or a skill file by 'skill/<name>'. Paths are the source labels that search_docs and search_all print.",
       inputSchema: {
-        path: z.string().describe("Doc path, e.g. 'charts/xy-chart/cursor', 'concepts/events', 'getting-started/integrations/react', 'reference/xycursor' (per-class API), or a skill file such as 'skill/SKILL.md' / 'skill/xy'. For a class's full settings + defaults prefer get_api_reference."),
+        path: z.string().describe("Doc path, e.g. 'charts/xy-chart/cursor', 'concepts/events', 'getting-started/integrations/react', 'reference/xycursor' (per-class API), or a skill file such as 'skill/SKILL.md' / 'skill/xy'. A class's full settings and defaults are in its API reference (get_api_reference)."),
       },
       annotations: READ_ONLY,
     },
     async ({ path: docPath }) => {
-      const key = String(docPath || "").replace(/^\/|\/$/g, "").replace(/\.md$/, "");
+      const key = docPathFromInput(docPath);
       // Extended docs take precedence for bare paths; 'skill/…' always means the skill layer.
       const resolved = key.startsWith("skill/")
         ? resolveDoc(key)
@@ -339,11 +497,11 @@ export function registerTools(server, content) {
   );
 
   // --- Tool: get_api_reference ---
-  server.registerTool(
+  registerTool(
     "get_api_reference",
     {
       title: "Get API reference",
-      description: "Get the per-class API reference for an amCharts 5 class — the class page PLUS its settings table (with DEFAULTS) and, optionally, its private/read-only settings. This is the authoritative source for exact setting names and default values (e.g. tooltip background cornerRadius, axis tick `visible` default). Pass a class name in any casing, e.g. 'XYCursor', 'Tooltip', 'PieSeries', 'AxisRendererX'.",
+      description: "Get the per-class API reference for an amCharts 5 class: the class page plus its settings table (with defaults) and, optionally, its private/read-only settings. It is generated from the library's typings, so it has the exact setting names and default values (e.g. tooltip background cornerRadius, axis tick `visible` default). Takes a class name in any casing, e.g. 'XYCursor', 'Tooltip', 'PieSeries', 'AxisRendererX'.",
       inputSchema: {
         className: z.string().describe("amCharts 5 class name, e.g. 'XYCursor', 'Tooltip', 'PieSeries', 'ColumnSeries', 'AxisRendererX'. Casing/punctuation are ignored."),
         includePrivate: z.boolean().optional().default(false).describe("Also include the private (read-only / internal) settings table. Default false."),
@@ -351,8 +509,10 @@ export function registerTools(server, content) {
       annotations: READ_ONLY,
     },
     async ({ className, includePrivate }) => {
-      // Normalize: "XYCursor" / "xy-cursor" / "XY Cursor" → "xycursor"
-      const norm = className.toLowerCase().replace(/[^a-z0-9]/g, "");
+      // Normalize: "XYCursor" / "xy-cursor" / "XY Cursor" → "xycursor"; an
+      // address or path ("…/docs/v5/reference/xycursor/") gives its last part
+      const name = /\//.test(className) ? docPathFromInput(className).split("/").pop() : className;
+      const norm = name.toLowerCase().replace(/[^a-z0-9]/g, "");
       const classDoc = extendedDocs.get(`reference/${norm}`);
       const settingsDoc = extendedDocs.get(`reference/i${norm}settings`);
       const privateDoc = extendedDocs.get(`reference/i${norm}private`);
@@ -393,13 +553,13 @@ export function registerTools(server, content) {
   );
 
   // --- Tool: list_examples ---
-  server.registerTool(
+  registerTool(
     "list_examples",
     {
       title: "List examples",
       description: "List all available amCharts 5 code examples, optionally filtered by category.",
       inputSchema: {
-        category: z.string().optional().describe("Filter by category, e.g. 'column-bar', 'line-area', 'pie-donut', 'maps', 'flow', 'hierarchy', 'stock', 'gantt', 'gauges', 'radar-polar', 'timeline', 'funnel-pyramid'. Omit to list all categories."),
+        category: z.string().optional().describe("Filter by category, e.g. 'column-bar', 'line-area', 'pie-donut', 'maps', 'flow', 'hierarchy', 'stock', 'gantt', 'gauges', 'radar-polar', 'timeline', 'funnel-pyramid', or 'json-configs' (complete JSON configs from the amCharts npm package). Without it, all categories are listed."),
       },
       annotations: READ_ONLY,
     },
@@ -438,21 +598,25 @@ export function registerTools(server, content) {
   );
 
   // --- Tool: get_example ---
-  server.registerTool(
+  registerTool(
     "get_example",
     {
       title: "Get example",
-      description: "Get the full code for a specific amCharts 5 example/demo. Use list_examples or search_all to find the path.",
+      description: "Get the full code for a specific amCharts 5 example/demo. Paths are listed by list_examples and printed in search results.",
       inputSchema: {
         path: z.string().describe("Example path, e.g. 'examples/flow/sankey-diagram', 'examples/pie-donut/donut-chart', 'examples/maps/drill-down-map'"),
       },
       annotations: READ_ONLY,
     },
     async ({ path: exPath }) => {
-      const key = exPath.replace(/^\/|\/$/g, "").replace(/\.md$/, "");
-      const ex = examples.get(key);
+      const key = resolveExample(exPath);
+      const ex = key && examples.get(key);
       if (!ex) {
-        return { content: [{ type: "text", text: `Example "${key}" not found. Use list_examples to browse available examples.` }] };
+        const named = examplesNamed(exPath);
+        const text = named.length > 1
+          ? `"${echo(exPath)}" names ${named.length} examples: ${named.map((k) => `\`${k}\``).join(", ")}. Use the full path.`
+          : `Example "${echo(exPath)}" not found. Use list_examples to browse available examples.`;
+        return { content: [{ type: "text", text }] };
       }
       let text = `# ${ex.title}\n`;
       text += `*Category: ${ex.category}*\n`;
@@ -463,13 +627,13 @@ export function registerTools(server, content) {
   );
 
   // --- Tool: list_geodata ---
-  server.registerTool(
+  registerTool(
     "list_geodata",
     {
       title: "List geodata (map files)",
-      description: "List amCharts 5 geodata (map) files with each one's CDN path, script global name and ES module import: world maps, continents, every country map, regional packs (US states and counties, Canada, Mexico) and the US congressional-district packs, which are versioned per Congress (congressional120 = 120th Congress is the newest). Also the data/countries2 and lang/* helper files. Use it before writing map code instead of guessing a file or global name.",
+      description: "List amCharts 5 geodata (map) files with each one's CDN path, script global name and ES module import: world maps, continents, every country map, regional packs (US states and counties, Canada, Mexico) and the US congressional-district packs, which are versioned per Congress (congressional120 = 120th Congress is the newest). Also the data/countries2 and lang/* helper files. It gives the exact file path and global name that map code needs.",
       inputSchema: {
-        filter: z.string().optional().describe("Words that must all match (case-insensitive) a map's path, label, group, ISO code or pack, e.g. 'germany', 'FR', 'region/canada', 'usa counties', 'congressional120', 'congressional whole country', 'continents', 'countries2'. A file or global name ('usaCongressionalLow', 'am5geodata_worldLow') works too. Omit for an overview."),
+        filter: z.string().optional().describe("Words that must all match (case-insensitive) a map's path, label, group, ISO code or pack, e.g. 'germany', 'FR', 'region/canada', 'usa counties', 'congressional120', 'congressional whole country', 'continents', 'countries2'. A file or global name ('usaCongressionalLow', 'am5geodata_worldLow') works too. Without it, the result is an overview."),
       },
       annotations: READ_ONLY,
     },