@tradecanvas/mcp 0.0.0-stage → 1.32.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TradeCanvas Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @tradecanvas/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [MCP](https://modelcontextprotocol.io) server for [TradeCanvas](https://tradecanvas.dev/), so a coding agent looks names up instead of guessing them. It answers from a catalog generated from the library's own code: the same version, the same names.
+
+```bash
+claude mcp add tradecanvas -- npx -y @tradecanvas/mcp
+```
+
+On Windows outside WSL, npx starts through `cmd`:
+
+```bash
+claude mcp add tradecanvas -- cmd /c npx -y @tradecanvas/mcp
+```
+
+Cursor, Claude Desktop and most other clients take the same command in their MCP settings (on Windows, `"command": "cmd", "args": ["/c", "npx", "-y", "@tradecanvas/mcp"]`):
+
+```json
+{
+  "mcpServers": {
+    "tradecanvas": { "command": "npx", "args": ["-y", "@tradecanvas/mcp"] }
+  }
+}
+```
+
+## Tools
+
+All of them read only; none touches the network or your files.
+
+| Tool | What it answers |
+|---|---|
+| `list_indicators` | The built-in indicators: id, name, and whether it draws over the price or in a pane. Search by words. |
+| `get_indicator` | One indicator in full: default params, inputs, the keys of its lines (RSI's is `value`, not `rsi`), levels, and code that adds it and reads it. |
+| `list_drawing_tools` | The drawing tools: the `type` that `addDrawing` and `setDrawingTool` take, the points each needs, its options. |
+| `list_options` | The options of `ChartWidget`, `Chart` or `ChartWidgetGrid`: name, TypeScript type, doc, allowed values. |
+| `list_widget_features` | The names `ChartWidget`'s `features` switch takes. |
+| `list_style_keys` | The chart's style keys and the value each takes, for `overrides` and `applyOverrides`. |
+| `validate_options` | Checks an options object before it is used: unknown names with the one likely meant, values outside the allowed ones, numbers given as strings, intervals, feature switches, style overrides, languages, and nested options. |
+
+A check, for instance:
+
+```json
+{ "target": "ChartWidget", "options": { "timeFrame": "5m", "chartType": "line", "locale": "ja" } }
+```
+
+```text
+- timeFrame: Unknown option 'timeFrame' for ChartWidget. Did you mean 'timeframe'?
+- chartType: Unknown option 'chartType' for ChartWidget. It is a Chart option: on ChartWidget it goes in `chartOptions`.
+Note: 日本語 ('ja') is not built into the widget: call registerWidgetLocales() from '@tradecanvas/chart/widget/locales' before creating it.
+```
+
+## Also
+
+- The agent skill teaches the API itself, with worked examples: `/plugin marketplace add bonguynvan/tradecanvas` in Claude Code, or `npx skills add bonguynvan/tradecanvas`.
+- [llms.txt](https://tradecanvas.dev/llms.txt) and [llms-full.txt](https://tradecanvas.dev/llms-full.txt) hold the docs in one file.
+
+Node 20.19 or later. MIT.

package/dist/catalog.d.ts

@@ -0,0 +1,65 @@
+/** A built-in indicator: what `chart.addIndicator(id, params)` takes and what it draws. */
+export interface IndicatorEntry {
+    id: string;
+    name: string;
+    shortName: string;
+    placement: 'overlay' | 'panel';
+    params: Record<string, unknown>;
+    inputs?: Record<string, unknown>;
+    plots: {
+        key: string;
+        title: string;
+        kind: string;
+    }[];
+    levels?: number[];
+    scale?: unknown;
+}
+/** A built-in drawing tool: its `type`, and the points (`anchors`) it takes. */
+export interface DrawingToolEntry {
+    type: string;
+    name: string;
+    anchors: number;
+    creation?: string;
+    options?: Record<string, {
+        kind: string;
+        label: string;
+        default: unknown;
+    }>;
+}
+/** One option of an entry point, read from its TypeScript declaration. */
+export interface OptionEntry {
+    name: string;
+    /** The type as written in the declaration. */
+    type: string;
+    doc?: string;
+    /** The only values it takes, when its type is a union of strings or numbers. */
+    values?: (string | number)[];
+    /** The values each item takes, when it is an array of such a union. */
+    items?: (string | number)[];
+    /** The one plain kind of value it takes, when it is that simple. */
+    kind?: 'boolean' | 'number' | 'string' | 'function';
+}
+export type Target = 'ChartWidget' | 'Chart' | 'ChartWidgetGrid';
+export declare const TARGETS: readonly Target[];
+export interface Catalog {
+    indicators: IndicatorEntry[];
+    drawingTools: DrawingToolEntry[];
+    chartTypes: string[];
+    /** The named intervals; `isTimeFrame` also takes any `<n><s|m|h|d|w|M>` and `<n>T`. */
+    timeframes: string[];
+    widgetFeatures: string[];
+    /** Each style key and the kind of value it takes: color, boolean, lineStyle or width. */
+    styleKeys: Record<string, string>;
+    looks: string[];
+    languages: {
+        code: string;
+        name: string;
+        builtIn: boolean;
+    }[];
+    options: Record<Target, OptionEntry[]>;
+    /** Nested option objects, by `<entry>.<option>`: `Chart.features`. */
+    nested: Record<string, OptionEntry[]>;
+}
+/** Generated from the code by scripts/gen-ai-docs.mjs. */
+export declare const CATALOG: Catalog;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAEA,2FAA2F;AAC3F,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC7E;AAED,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,MAAM,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC7B,uEAAuE;IACvE,KAAK,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC5B,oEAAoE;IACpE,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;CACrD;AAED,MAAM,MAAM,MAAM,GAAG,aAAa,GAAG,OAAO,GAAG,iBAAiB,CAAC;AACjE,eAAO,MAAM,OAAO,EAAE,SAAS,MAAM,EAAgD,CAAC;AAEtF,MAAM,WAAW,OAAO;IACtB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,uFAAuF;IACvF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,yFAAyF;IACzF,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IAC9D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;IACvC,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;CACvC;AAED,0DAA0D;AAC1D,eAAO,MAAM,OAAO,EAAW,OAAO,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { i as createServer, t as splitLines } from "./server.js";
+//#region src/cli.ts
+var server = createServer({ version: "1.32.0" });
+var pending = "";
+function answer(chunk, ended) {
+	const { lines, rest } = splitLines(pending, chunk, ended);
+	pending = rest;
+	for (const line of lines) {
+		const reply = server.handleLine(line);
+		if (reply) process.stdout.write(`${reply}\n`);
+	}
+}
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => answer(chunk, false));
+process.stdin.on("end", () => answer("", true));
+//#endregion

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { createServer, PROTOCOLS, LATEST_PROTOCOL } from './server.js';
+export type { Server, Response } from './server.js';
+export { TOOLS, runTool } from './tools.js';
+export type { ToolDefinition, ToolResult } from './tools.js';
+export { validateOptions } from './validate.js';
+export type { Problem, Validation } from './validate.js';
+export { CATALOG, TARGETS } from './catalog.js';
+export type { Catalog, Target, IndicatorEntry, DrawingToolEntry, OptionEntry } from './catalog.js';
+export { splitLines } from './lines.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACvE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACnG,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as TOOLS, c as CATALOG, i as createServer, l as TARGETS, n as LATEST_PROTOCOL, o as runTool, r as PROTOCOLS, s as validateOptions, t as splitLines } from "./server.js";
+export { CATALOG, LATEST_PROTOCOL, PROTOCOLS, TARGETS, TOOLS, createServer, runTool, splitLines, validateOptions };

package/dist/lines.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The stdio transport sends one JSON message a line. Splits what has arrived
+ * into whole lines (blank ones dropped, a `\r` before the `\n` too) and keeps
+ * the unfinished end for the next chunk; at the end of input (`ended`) that
+ * end is a message too, newline or not.
+ */
+export declare function splitLines(pending: string, chunk: string, ended?: boolean): {
+    lines: string[];
+    rest: string;
+};
+//# sourceMappingURL=lines.d.ts.map

package/dist/lines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lines.d.ts","sourceRoot":"","sources":["../src/lines.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,UAAQ,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAK3G"}

package/dist/server.d.ts

@@ -0,0 +1,32 @@
+import { Catalog } from './catalog.js';
+/** The protocol versions this server speaks, newest first. */
+export declare const PROTOCOLS: readonly ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+export declare const LATEST_PROTOCOL: "2025-11-25";
+type Id = string | number | null;
+export type Response = {
+    jsonrpc: '2.0';
+    id: Id;
+    result: unknown;
+} | {
+    jsonrpc: '2.0';
+    id: Id;
+    error: {
+        code: number;
+        message: string;
+    };
+};
+export interface Server {
+    /**
+     * Answers one JSON-RPC message, or a batch of them with an array; null when
+     * nothing needs an answer (notifications, and responses: the server asks nothing).
+     */
+    handle(message: unknown): Response | Response[] | null;
+    /** Answers one line of the stdio transport, as a line to write back (null: nothing to write). */
+    handleLine(line: string): string | null;
+}
+/** The TradeCanvas MCP server: tools only, every one of them read-only. */
+export declare function createServer(info: {
+    version: string;
+}, catalog?: Catalog): Server;
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAGrD,8DAA8D;AAC9D,eAAO,MAAM,SAAS,mEAAoE,CAAC;AAC3F,eAAO,MAAM,eAAe,cAAe,CAAC;AAS5C,KAAK,EAAE,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAEjC,MAAM,MAAM,QAAQ,GAChB;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,EAAE,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC3C;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,EAAE,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAezE,MAAM,WAAW,MAAM;IACrB;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,EAAE,GAAG,IAAI,CAAC;IACvD,iGAAiG;IACjG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACzC;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,GAAE,OAAiB,GAAG,MAAM,CA+E1F"}