@amcharts/amcharts5-mcp 1.9.3 → 1.9.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -55,7 +55,7 @@ root.numberFormatter.set("numberFormat", "#,###.00"); // thousands separators an
55
55
 
56
56
  // Create a main stock panel (chart)
57
57
  // -------------------------------------------------------------------------------
58
- // https://docs.amcharts.com/v5/charts/stock/
58
+ // https://docs.amcharts.com/v5/charts/stock/#panels
59
59
  var mainPanel = stockChart.panels.push(am5stock.StockPanel.new(root, {
60
60
  wheelY: "zoomX", // the mouse wheel zooms in on the dates
61
61
  panX: true, // a drag pans through the dates...
@@ -55,7 +55,7 @@ root.numberFormatter.set("numberFormat", "#,###.00"); // thousands separators an
55
55
 
56
56
  // Create a main stock panel (chart)
57
57
  // -------------------------------------------------------------------------------
58
- // https://docs.amcharts.com/v5/charts/stock/
58
+ // https://docs.amcharts.com/v5/charts/stock/#panels
59
59
  var mainPanel = stockChart.panels.push(am5stock.StockPanel.new(root, {
60
60
  wheelY: "zoomX", // the mouse wheel zooms in on the dates
61
61
  panX: true, // a drag pans through the dates...
@@ -55,7 +55,7 @@ root.numberFormatter.set("numberFormat", "#,###.00"); // thousands separators an
55
55
 
56
56
  // Create a main stock panel (chart)
57
57
  // -------------------------------------------------------------------------------
58
- // https://docs.amcharts.com/v5/charts/stock/
58
+ // https://docs.amcharts.com/v5/charts/stock/#panels
59
59
  var mainPanel = stockChart.panels.push(am5stock.StockPanel.new(root, {
60
60
  wheelY: "zoomX", // the mouse wheel zooms in on the dates
61
61
  panX: true, // a drag pans through the dates...
@@ -54,7 +54,7 @@ root.numberFormatter.set("numberFormat", "#,###.00"); // thousands separators an
54
54
 
55
55
  // Create a main stock panel (chart)
56
56
  // -------------------------------------------------------------------------------
57
- // https://docs.amcharts.com/v5/charts/stock/
57
+ // https://docs.amcharts.com/v5/charts/stock/#panels
58
58
  var mainPanel = stockChart.panels.push(am5stock.StockPanel.new(root, {
59
59
  wheelY: "zoomX", // the mouse wheel zooms in on the dates
60
60
  height: am5.percent(70), // the price panel takes 70% of the height
@@ -123,7 +123,7 @@ var valueLegend = mainPanel.plotContainer.children.push(am5stock.StockLegend.new
123
123
 
124
124
  // Create a volume panel (chart)
125
125
  // -------------------------------------------------------------------------------
126
- // https://docs.amcharts.com/v5/charts/stock/
126
+ // https://docs.amcharts.com/v5/charts/stock/#panels
127
127
  var volumePanel = stockChart.panels.push(am5stock.StockPanel.new(root, {
128
128
  wheelY: "zoomX", // the mouse wheel zooms in on the dates here too
129
129
  panX: true, // a drag pans through the dates
@@ -60,7 +60,7 @@ root.numberFormatter.set("numberFormat", "#,###.00"); // thousands separators an
60
60
 
61
61
  // Create a main stock panel (chart)
62
62
  // -------------------------------------------------------------------------------
63
- // https://docs.amcharts.com/v5/charts/stock/
63
+ // https://docs.amcharts.com/v5/charts/stock/#panels
64
64
  var mainPanel = stockChart.panels.push(am5stock.StockPanel.new(root, {
65
65
  wheelY: "zoomX", // the mouse wheel zooms in on the times
66
66
  panX: true, // a drag pans through the times...
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@amcharts/amcharts5-mcp",
3
- "version": "1.9.3",
3
+ "version": "1.9.4",
4
4
  "mcpName": "io.github.amcharts/amcharts5",
5
5
  "description": "On-demand access to amCharts 5 docs, code examples, and API reference",
6
6
  "type": "module",
package/src/index.js CHANGED
@@ -6,7 +6,7 @@ import { readFileSync } from "fs";
6
6
  import { join, dirname } from "path";
7
7
  import { fileURLToPath } from "url";
8
8
  import { loadContentFromDisk } from "./content-fs.js";
9
- import { registerTools } from "./tools.js";
9
+ import { registerTools, serverInfo } from "./tools.js";
10
10
 
11
11
  const __dirname = dirname(fileURLToPath(import.meta.url));
12
12
  const ROOT = join(__dirname, "..");
@@ -18,10 +18,7 @@ const VERSION = PKG.version;
18
18
  // Load and index all content from disk (submodule + extended/).
19
19
  const content = loadContentFromDisk();
20
20
 
21
- const server = new McpServer({
22
- name: "amcharts5",
23
- version: VERSION,
24
- });
21
+ const server = new McpServer(serverInfo(VERSION));
25
22
 
26
23
  registerTools(server, content);
27
24
 
package/src/tools.js CHANGED
@@ -33,7 +33,7 @@ function docPathFromInput(input) {
33
33
  .replace(/[?#].*$/, "")
34
34
  .replace(/^(https?:\/\/)?((www|docs)\.)?amcharts\.com(?=\/|$)/i, "")
35
35
  .replace(/^\/+/, "")
36
- .replace(/^(docs\/)?v5\//i, "")
36
+ .replace(/^(docs\/)?v5(\/|$)/i, "")
37
37
  .replace(/\/+$/, "")
38
38
  .replace(/\.md$/i, "");
39
39
  }
@@ -44,6 +44,25 @@ function demoSlug(input) {
44
44
  return m ? m[1].toLowerCase() : null;
45
45
  }
46
46
 
47
+ // What the server says about itself when a client connects (MCP serverInfo;
48
+ // title, description, icons and websiteUrl are in the 2025-11-25 spec).
49
+ // Clients that read them can show them on a connector's card. The icon is
50
+ // served by the Worker (cloudflare/icon.png).
51
+ export function serverInfo(version) {
52
+ return {
53
+ name: "amcharts5",
54
+ title: "amCharts 5",
55
+ version,
56
+ description: "Docs, code examples and API reference for amCharts 5, the JavaScript library for charts and maps.",
57
+ websiteUrl: "https://docs.amcharts.com/v5/ai/mcp/",
58
+ icons: [{ src: "https://mcp.amcharts.com/icon.png", mimeType: "image/png", sizes: ["256x256"] }],
59
+ };
60
+ }
61
+
62
+ // An amcharts.com address in a text: a demo, a docs page, the docs' new host
63
+ // (Markdown around it, a code span's backtick or bold's asterisks, ends it)
64
+ const AMCHARTS_LINK = /(?:https?:\/\/)?(?:[\w-]+\.)*amcharts\.com\/[^\s)"'<>\]`*]*/gi;
65
+
47
66
  // User text echoed back in a reply, capped so a huge query can't balloon it
48
67
  const echo = (s) => { s = String(s ?? ""); return s.length > 200 ? s.slice(0, 200) + "…" : s; };
49
68
 
@@ -198,6 +217,72 @@ export function registerTools(server, content) {
198
217
  const examplesNamed = (input) =>
199
218
  exampleBySlug.get(String(input ?? "").trim().replace(/[?#].*$/, "").replace(/^\/+|\/+$/g, "").replace(/\.md$/i, "").split("/").pop().toLowerCase()) || [];
200
219
 
220
+ // An example as get_example returns it
221
+ function exampleText(key) {
222
+ const ex = examples.get(key);
223
+ let text = `# ${ex.title}\n`;
224
+ text += `*Category: ${ex.category}*\n`;
225
+ if (ex.source) text += `*Source: ${ex.source}*\n`;
226
+ return text + `\n${ex.content}`;
227
+ }
228
+
229
+ // A link someone pasted (Figma, for one, invites "a link from amCharts" as
230
+ // context): the first amcharts.com address in a text that is a demo or a
231
+ // docs page, and which call gets what it points to. Null when there is none
232
+ // (other amcharts.com addresses, e.g. the CDN's, are passed over).
233
+ function linkPointer(text) {
234
+ for (const m of String(text ?? "").matchAll(AMCHARTS_LINK)) {
235
+ const pointer = pointerFor(m[0].replace(/[.,;:!?]+$/, ""));
236
+ if (pointer) return pointer;
237
+ }
238
+ return null;
239
+ }
240
+
241
+ function pointerFor(link) {
242
+ if (/(?:docs\.amcharts\.com|amcharts\.com\/docs)\/v4(?:[/?#]|$)/i.test(link)) {
243
+ return `${link} is from the amCharts 4 docs; this server covers amCharts 5. search_all finds the amCharts 5 docs on the same topic.`;
244
+ }
245
+ const v4 = /amcharts\.com\/demos-v4\/([^/?#]+)/i.exec(link);
246
+ if (v4) {
247
+ const v5 = resolveExample(v4[1].toLowerCase().replace(/-v4$/, ""));
248
+ return `${link} is an amCharts 4 demo; this server covers amCharts 5.` +
249
+ (v5 ? ` The amCharts 5 version is get_example(path: "${v5}").` : " search_all finds the closest amCharts 5 examples.");
250
+ }
251
+ if (demoSlug(link)) {
252
+ const key = resolveExample(link);
253
+ return key
254
+ ? `${link} is the amCharts demo "${examples.get(key).title}": its full code is get_example(path: "${key}").`
255
+ : `${link} is an amCharts demo this server doesn't have; search_all finds similar examples.`;
256
+ }
257
+ if (!/(?:docs\.amcharts\.com\/v5|amcharts\.com\/docs\/v5)(?:[/?#.]|$)/i.test(link)) return null;
258
+ const key = docPathFromInput(link);
259
+ if (key.startsWith("reference/") && extendedDocs.has(key)) {
260
+ return `${link} is the API reference of ${extendedDocs.get(key).title}: get_api_reference(className: "${key.slice("reference/".length)}").`;
261
+ }
262
+ if (!key) return `${link} is the amCharts 5 docs home: get_core_reference gives the essentials, list_chart_types the chart types, search_all anything else.`;
263
+ const resolved = resolveDoc(key);
264
+ if (!resolved) return `${link} is a docs page this server doesn't have; search_all with the page's topic finds the nearest content.`;
265
+ const { doc, label } = resolved;
266
+ // A section anchor, new ("#date-formats") or old ("#Date_formats"): the heading it names
267
+ const anchor = (/#(.+)$/.exec(link) || [])[1];
268
+ if (anchor) {
269
+ const flat = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
270
+ let a = anchor; try { a = decodeURIComponent(anchor); } catch {}
271
+ const heading = [...doc.content.matchAll(/^#{2,4}\s+(.+?)\s*$/gm)].map((h) => h[1]).find((h) => flat(h) === flat(a));
272
+ if (heading) return `${link} is the section "${heading}" of the docs page "${doc.title}": get_section(file: "${label}", heading: "${heading}"), or the whole page with get_doc(path: "${label}").`;
273
+ }
274
+ return `${link} is the docs page "${doc.title}": get_doc(path: "${label}").`;
275
+ }
276
+
277
+ // A search query with a pasted link in it: the link's pointer, and the
278
+ // words besides the link to search for ("" when the query is just the link)
279
+ function splitLink(query) {
280
+ const pointer = linkPointer(query);
281
+ if (!pointer) return { pointer: null, rest: query };
282
+ const rest = String(query).replace(AMCHARTS_LINK, " ").replace(/[()<>[\]`*]+/g, " ").replace(/\s+/g, " ").trim();
283
+ return { pointer, rest: /[a-z]{3}/i.test(rest) ? rest : "" };
284
+ }
285
+
201
286
  // --- Tool: list_chart_types ---
202
287
  registerTool(
203
288
  "list_chart_types",
@@ -286,13 +371,18 @@ export function registerTools(server, content) {
286
371
  },
287
372
  annotations: READ_ONLY,
288
373
  },
289
- async ({ query, maxResults, scope }) => {
374
+ async ({ query: asked, maxResults, scope }) => {
375
+ // A pasted amcharts.com link: where it points comes first, then results
376
+ // for the words besides it, if any
377
+ const { pointer, rest: query } = splitLink(asked);
378
+ if (pointer && !query) return { content: [{ type: "text", text: pointer }] };
379
+ const lead = pointer ? `> ${pointer}\n\n` : "";
290
380
  const results = searchDocs(content, query, maxResults, scope);
291
381
  if (results.length === 0) {
292
382
  const hint = scope === "skill"
293
383
  ? ` Nothing in the skill docs — retry with scope:'all' to include the API reference, or use search_all.`
294
384
  : "";
295
- return { content: [{ type: "text", text: `No results found for "${echo(query)}".${hint}${geodataHint(query)}` }] };
385
+ return { content: [{ type: "text", text: `${lead}No results found for "${echo(query)}".${hint}${geodataHint(query)}` }] };
296
386
  }
297
387
 
298
388
  // Per-result excerpt budget. When only one or two sections match, the
@@ -300,7 +390,7 @@ export function registerTools(server, content) {
300
390
  // answer off.
301
391
  const budget = results.length <= 2 ? 6000 : 2000;
302
392
 
303
- let text = `# Search results for "${echo(query)}" (scope: ${scope})\n\n`;
393
+ let text = `${lead}# Search results for "${echo(query)}" (scope: ${scope})\n\n`;
304
394
  for (const r of results) {
305
395
  // Examples aren't sections of a doc: label them by their example path
306
396
  // and point at get_example for the full code.
@@ -445,19 +535,24 @@ export function registerTools(server, content) {
445
535
  title: "Search all content",
446
536
  description: "Search across all amCharts 5 content: skill references, full documentation, and code examples. For broad searches across everything.",
447
537
  inputSchema: {
448
- query: z.string().describe("Search query, e.g. 'react integration', 'date axis formatting', 'stacked bar example'"),
538
+ query: z.string().describe("Search query, e.g. 'react integration', 'date axis formatting', 'stacked bar example'. An amcharts.com link (a demo or a docs page) is answered with the call that returns it."),
449
539
  maxResults: z.number().optional().default(10).describe("Maximum results (default 10)"),
450
540
  },
451
541
  annotations: READ_ONLY,
452
542
  },
453
- async ({ query, maxResults }) => {
543
+ async ({ query: asked, maxResults }) => {
544
+ // A pasted amcharts.com link: where it points comes first, then results
545
+ // for the words besides it, if any
546
+ const { pointer, rest: query } = splitLink(asked);
547
+ if (pointer && !query) return { content: [{ type: "text", text: pointer }] };
548
+ const lead = pointer ? `> ${pointer}\n\n` : "";
454
549
  const { total, results } = rankContent(content, query, { maxResults });
455
550
  if (results.length === 0) {
456
- return { content: [{ type: "text", text: `No results found for "${echo(query)}".${geodataHint(query)}` }] };
551
+ return { content: [{ type: "text", text: `${lead}No results found for "${echo(query)}".${geodataHint(query)}` }] };
457
552
  }
458
553
 
459
554
  const TYPE_LABEL = { skill: "skill", extended: "docs", example: "example" };
460
- let text = `# Search results for "${echo(query)}" (${total} total, showing ${results.length})\n\n`;
555
+ let text = `${lead}# Search results for "${echo(query)}" (${total} total, showing ${results.length})\n\n`;
461
556
  for (const r of results) {
462
557
  const source = r.kind === "skill" ? `skill/${r.file}` : r.file;
463
558
  text += `## [${TYPE_LABEL[r.kind]}] ${r.docTitle}${r.heading ? ` → ${r.heading}` : ""}\n`;
@@ -475,17 +570,22 @@ export function registerTools(server, content) {
475
570
  title: "Get doc page",
476
571
  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.",
477
572
  inputSchema: {
478
- 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)."),
573
+ 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 docs address works too ('https://docs.amcharts.com/v5/concepts/events/', its '.md', or the older www.amcharts.com/docs/v5/ form); a demo address returns that demo's example. A class's full settings and defaults are in its API reference (get_api_reference)."),
479
574
  },
480
575
  annotations: READ_ONLY,
481
576
  },
482
577
  async ({ path: docPath }) => {
578
+ // A demo address: the demo's example
579
+ const exampleKey = demoSlug(docPath) && resolveExample(docPath);
580
+ if (exampleKey) return { content: [{ type: "text", text: `*(${echo(docPath)} is a demo: its example, as get_example returns it)*\n\n${exampleText(exampleKey)}` }] };
483
581
  const key = docPathFromInput(docPath);
484
582
  // Extended docs take precedence for bare paths; 'skill/…' always means the skill layer.
485
583
  const resolved = key.startsWith("skill/")
486
584
  ? resolveDoc(key)
487
585
  : (extendedDocs.has(key) ? { doc: extendedDocs.get(key), label: `extended/${key}` } : resolveDoc(key));
488
586
  if (!resolved) {
587
+ const pointer = linkPointer(docPath);
588
+ if (pointer) return { content: [{ type: "text", text: pointer }] };
489
589
  // List available top-level paths
490
590
  const paths = [...extendedDocs.keys()];
491
591
  const topLevel = [...new Set(paths.map(p => p.split("/")[0]))].sort();
@@ -505,7 +605,7 @@ export function registerTools(server, content) {
505
605
  title: "Get API reference",
506
606
  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'.",
507
607
  inputSchema: {
508
- className: z.string().describe("amCharts 5 class name, e.g. 'XYCursor', 'Tooltip', 'PieSeries', 'ColumnSeries', 'AxisRendererX'. Casing/punctuation are ignored."),
608
+ className: z.string().describe("amCharts 5 class name, e.g. 'XYCursor', 'Tooltip', 'PieSeries', 'ColumnSeries', 'AxisRendererX'. Casing/punctuation are ignored. Its reference address works too: 'https://docs.amcharts.com/v5/reference/xycursor/'."),
509
609
  includePrivate: z.boolean().optional().default(false).describe("Also include the private (read-only / internal) settings table. Default false."),
510
610
  },
511
611
  annotations: READ_ONLY,
@@ -604,27 +704,23 @@ export function registerTools(server, content) {
604
704
  "get_example",
605
705
  {
606
706
  title: "Get example",
607
- description: "Get the full code for a specific amCharts 5 example/demo. Paths are listed by list_examples and printed in search results.",
707
+ description: "Get the full code for a specific amCharts 5 example/demo, by its path or its amcharts.com demo address. Paths are listed by list_examples and printed in search results.",
608
708
  inputSchema: {
609
- path: z.string().describe("Example path, e.g. 'examples/flow/sankey-diagram', 'examples/pie-donut/donut-chart', 'examples/maps/drill-down-map'"),
709
+ path: z.string().describe("Example path, e.g. 'examples/flow/sankey-diagram', 'examples/pie-donut/donut-chart', 'examples/maps/drill-down-map', or a demo address such as 'https://www.amcharts.com/demos/sankey-diagram/'"),
610
710
  },
611
711
  annotations: READ_ONLY,
612
712
  },
613
713
  async ({ path: exPath }) => {
614
714
  const key = resolveExample(exPath);
615
- const ex = key && examples.get(key);
616
- if (!ex) {
715
+ if (!key) {
617
716
  const named = examplesNamed(exPath);
717
+ const pointer = linkPointer(exPath);
618
718
  const text = named.length > 1
619
719
  ? `"${echo(exPath)}" names ${named.length} examples: ${named.map((k) => `\`${k}\``).join(", ")}. Use the full path.`
620
- : `Example "${echo(exPath)}" not found. Use list_examples to browse available examples.`;
720
+ : pointer || `Example "${echo(exPath)}" not found. Use list_examples to browse available examples.`;
621
721
  return { content: [{ type: "text", text }] };
622
722
  }
623
- let text = `# ${ex.title}\n`;
624
- text += `*Category: ${ex.category}*\n`;
625
- if (ex.source) text += `*Source: ${ex.source}*\n`;
626
- text += `\n${ex.content}`;
627
- return { content: [{ type: "text", text }] };
723
+ return { content: [{ type: "text", text: exampleText(key) }] };
628
724
  }
629
725
  );
630
726