equilibria-mcp-server 1.0.0

package/dist/tools/models.js

@@ -0,0 +1,828 @@
+/**
+ * Model Building Tools
+ *
+ * Mid-level tools for incrementally constructing economic visualizations.
+ */
+import { YAMLBuilder } from '../builders/YAMLBuilder.js';
+import { formatAsYAML } from '../formatters/yaml.js';
+// Shared builder instance for multi-step construction
+let currentBuilder = null;
+/**
+ * Tool: create_chart
+ *
+ * Creates a new chart or starts a new document.
+ */
+const createChart = {
+    tool: {
+        name: 'create_chart',
+        description: 'Create a new economic chart. This initializes or adds to the current document being built. Use export_document to get the final YAML.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Unique identifier for the chart',
+                },
+                title: {
+                    type: 'string',
+                    description: 'Display title for the chart',
+                },
+                xAxis: {
+                    type: 'object',
+                    properties: {
+                        label: { type: 'string' },
+                        min: { type: 'number' },
+                        max: { type: 'number' },
+                    },
+                    required: ['label', 'min', 'max'],
+                },
+                yAxis: {
+                    type: 'object',
+                    properties: {
+                        label: { type: 'string' },
+                        min: { type: 'number' },
+                        max: { type: 'number' },
+                    },
+                    required: ['label', 'min', 'max'],
+                },
+                newDocument: {
+                    type: 'boolean',
+                    description: 'Start a new document (discards current if any)',
+                    default: false,
+                },
+            },
+            required: ['id', 'xAxis', 'yAxis'],
+        },
+    },
+    handler: async (args, context) => {
+        const id = args.id;
+        const title = args.title;
+        const xAxis = args.xAxis;
+        const yAxis = args.yAxis;
+        const newDocument = args.newDocument;
+        if (newDocument || !currentBuilder) {
+            currentBuilder = new YAMLBuilder();
+        }
+        currentBuilder.addChart({
+            id,
+            title,
+            xAxis: {
+                label: xAxis.label,
+                min: xAxis.min,
+                max: xAxis.max,
+            },
+            yAxis: {
+                label: yAxis.label,
+                min: yAxis.min,
+                max: yAxis.max,
+            },
+            elements: [],
+        });
+        context.sessionState.set('currentChartId', id);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Created chart "${id}". Use add_curve, add_point, add_area to add elements, then export_document to get the YAML.`,
+                },
+            ],
+        };
+    },
+};
+/**
+ * Tool: add_curve
+ *
+ * Adds a curve/line to the current chart.
+ */
+const addCurve = {
+    tool: {
+        name: 'add_curve',
+        description: 'Add a curve or line to the current chart. The equation should be a mathematical expression in terms of x.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Unique identifier for the curve',
+                },
+                equation: {
+                    type: 'string',
+                    description: 'Mathematical equation (e.g., "100 - 2*x", "x^2", "50 + slope * x")',
+                },
+                label: {
+                    type: 'string',
+                    description: 'Label for the curve (shown in legend)',
+                },
+                color: {
+                    type: 'string',
+                    description: 'Hex color (e.g., "#FF0000")',
+                },
+                chartId: {
+                    type: 'string',
+                    description: 'Chart to add to (uses current chart if not specified)',
+                },
+                lineStyle: {
+                    type: 'string',
+                    enum: ['solid', 'dashed', 'dotted'],
+                    description: 'Line style',
+                },
+                domain: {
+                    type: 'object',
+                    properties: {
+                        min: { type: 'number' },
+                        max: { type: 'number' },
+                    },
+                    description: 'Domain restriction for the curve',
+                },
+            },
+            required: ['id', 'equation'],
+        },
+    },
+    handler: async (args, context) => {
+        if (!currentBuilder) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No document started. Use create_chart first.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const chartId = args.chartId ||
+            context.sessionState.get('currentChartId');
+        if (!chartId) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No chart specified. Use create_chart first or specify chartId.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const element = {
+            id: args.id,
+            type: 'line',
+            equation: args.equation,
+        };
+        if (args.label)
+            element.label = args.label;
+        if (args.color)
+            element.color = args.color;
+        if (args.lineStyle)
+            element.lineStyle = args.lineStyle;
+        if (args.domain)
+            element.domain = args.domain;
+        currentBuilder.addElement(chartId, element);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Added curve "${args.id}" with equation "${args.equation}" to chart "${chartId}".`,
+                },
+            ],
+        };
+    },
+};
+/**
+ * Tool: add_point
+ *
+ * Adds a point to the current chart.
+ */
+const addPoint = {
+    tool: {
+        name: 'add_point',
+        description: 'Add a point to the current chart. Can be at explicit coordinates or at the intersection of two curves.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Unique identifier for the point',
+                },
+                x: {
+                    type: ['number', 'string'],
+                    description: 'X coordinate (number or expression)',
+                },
+                y: {
+                    type: ['number', 'string'],
+                    description: 'Y coordinate (number or expression)',
+                },
+                intersection: {
+                    type: 'object',
+                    properties: {
+                        curve1: { type: 'string' },
+                        curve2: { type: 'string' },
+                        index: { type: 'number' },
+                    },
+                    description: 'Find point at intersection of two curves (alternative to x,y)',
+                },
+                label: {
+                    type: 'string',
+                    description: 'Label for the point',
+                },
+                color: {
+                    type: 'string',
+                    description: 'Hex color',
+                },
+                chartId: {
+                    type: 'string',
+                    description: 'Chart to add to',
+                },
+                droplines: {
+                    type: 'object',
+                    properties: {
+                        x: { type: 'boolean' },
+                        y: { type: 'boolean' },
+                    },
+                    description: 'Show droplines to axes',
+                },
+            },
+            required: ['id'],
+        },
+    },
+    handler: async (args, context) => {
+        if (!currentBuilder) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No document started. Use create_chart first.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const chartId = args.chartId ||
+            context.sessionState.get('currentChartId');
+        if (!chartId) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No chart specified.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const element = {
+            id: args.id,
+            type: 'point',
+        };
+        if (args.intersection) {
+            element.intersection = args.intersection;
+        }
+        else {
+            if (args.x !== undefined)
+                element.x = args.x;
+            if (args.y !== undefined)
+                element.y = args.y;
+        }
+        if (args.label)
+            element.label = args.label;
+        if (args.color)
+            element.color = args.color;
+        if (args.droplines)
+            element.droplines = args.droplines;
+        currentBuilder.addElement(chartId, element);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Added point "${args.id}" to chart "${chartId}".`,
+                },
+            ],
+        };
+    },
+};
+/**
+ * Tool: add_area
+ *
+ * Adds a shaded area to the current chart.
+ */
+const addArea = {
+    tool: {
+        name: 'add_area',
+        description: 'Add a shaded area to the current chart. Useful for showing surplus, deadweight loss, etc.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Unique identifier for the area',
+                },
+                topBoundary: {
+                    type: 'string',
+                    description: 'Top boundary (curve ID or expression)',
+                },
+                bottomBoundary: {
+                    type: 'string',
+                    description: 'Bottom boundary (curve ID or expression)',
+                },
+                leftBoundary: {
+                    type: 'string',
+                    description: 'Left boundary (curve ID or value)',
+                },
+                rightBoundary: {
+                    type: 'string',
+                    description: 'Right boundary (curve ID or value)',
+                },
+                label: {
+                    type: 'string',
+                    description: 'Label for the area',
+                },
+                color: {
+                    type: 'string',
+                    description: 'Fill color',
+                },
+                opacity: {
+                    type: 'number',
+                    description: 'Fill opacity (0-1)',
+                },
+                chartId: {
+                    type: 'string',
+                    description: 'Chart to add to',
+                },
+            },
+            required: ['id', 'topBoundary', 'bottomBoundary', 'leftBoundary', 'rightBoundary'],
+        },
+    },
+    handler: async (args, context) => {
+        if (!currentBuilder) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No document started. Use create_chart first.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const chartId = args.chartId ||
+            context.sessionState.get('currentChartId');
+        if (!chartId) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No chart specified.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const element = {
+            id: args.id,
+            type: 'area',
+            topBoundary: args.topBoundary,
+            bottomBoundary: args.bottomBoundary,
+            leftBoundary: args.leftBoundary,
+            rightBoundary: args.rightBoundary,
+        };
+        if (args.label)
+            element.label = args.label;
+        if (args.color)
+            element.color = args.color;
+        if (args.opacity !== undefined)
+            element.opacity = args.opacity;
+        currentBuilder.addElement(chartId, element);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Added area "${args.id}" to chart "${chartId}".`,
+                },
+            ],
+        };
+    },
+};
+/**
+ * Tool: add_parameter
+ *
+ * Adds a parameter to the document.
+ */
+const addParameter = {
+    tool: {
+        name: 'add_parameter',
+        description: 'Add a parameter to the document. Parameters can be used in expressions and made interactive with sliders.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Parameter name (used in expressions)',
+                },
+                value: {
+                    type: 'number',
+                    description: 'Initial value',
+                },
+                min: {
+                    type: 'number',
+                    description: 'Minimum value (for slider)',
+                },
+                max: {
+                    type: 'number',
+                    description: 'Maximum value (for slider)',
+                },
+                step: {
+                    type: 'number',
+                    description: 'Step size (for slider)',
+                },
+                label: {
+                    type: 'string',
+                    description: 'Display label',
+                },
+                chartId: {
+                    type: 'string',
+                    description: 'Chart to add to (global if not specified)',
+                },
+            },
+            required: ['name', 'value'],
+        },
+    },
+    handler: async (args) => {
+        if (!currentBuilder) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No document started. Use create_chart first.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const name = args.name;
+        const param = {
+            value: args.value,
+        };
+        if (args.min !== undefined)
+            param.min = args.min;
+        if (args.max !== undefined)
+            param.max = args.max;
+        if (args.step !== undefined)
+            param.step = args.step;
+        if (args.label)
+            param.label = args.label;
+        const chartId = args.chartId;
+        currentBuilder.addParameter(name, param, chartId);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: chartId
+                        ? `Added parameter "${name}" to chart "${chartId}".`
+                        : `Added global parameter "${name}".`,
+                },
+            ],
+        };
+    },
+};
+/**
+ * Tool: add_annotation
+ *
+ * Adds a text annotation to the current chart.
+ */
+const addAnnotation = {
+    tool: {
+        name: 'add_annotation',
+        description: 'Add a text annotation (label, callout, or note) to the current chart at specified coordinates.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Unique identifier for the annotation',
+                },
+                text: {
+                    type: 'string',
+                    description: 'Text content of the annotation (can include parameter interpolation like "${P_eq:.2f}")',
+                },
+                x: {
+                    type: ['number', 'string'],
+                    description: 'X position (number or expression)',
+                },
+                y: {
+                    type: ['number', 'string'],
+                    description: 'Y position (number or expression)',
+                },
+                color: {
+                    type: 'string',
+                    description: 'Text color (hex code)',
+                },
+                fontSize: {
+                    type: 'number',
+                    description: 'Font size in pixels',
+                },
+                chartId: {
+                    type: 'string',
+                    description: 'Chart to add to (uses current chart if not specified)',
+                },
+            },
+            required: ['id', 'text', 'x', 'y'],
+        },
+    },
+    handler: async (args, context) => {
+        if (!currentBuilder) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No document started. Use create_chart first.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const chartId = args.chartId ||
+            context.sessionState.get('currentChartId');
+        if (!chartId) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No chart specified. Use create_chart first or specify chartId.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const annotation = {
+            id: args.id,
+            text: args.text,
+            x: args.x,
+            y: args.y,
+            color: args.color,
+            fontSize: args.fontSize,
+        };
+        // Remove undefined properties
+        Object.keys(annotation).forEach((key) => {
+            if (annotation[key] === undefined) {
+                delete annotation[key];
+            }
+        });
+        currentBuilder.addAnnotation(chartId, annotation);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Added annotation "${args.id}" at (${args.x}, ${args.y}) to chart "${chartId}".`,
+                },
+            ],
+        };
+    },
+};
+/**
+ * Tool: add_vertical_line
+ *
+ * Adds a vertical line to the current chart.
+ */
+const addVerticalLine = {
+    tool: {
+        name: 'add_vertical_line',
+        description: 'Add a vertical line at a specific x value. Useful for marking quantities, reference points, or constraints.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Unique identifier for the line',
+                },
+                x: {
+                    type: ['number', 'string'],
+                    description: 'X position (number or expression)',
+                },
+                label: {
+                    type: 'string',
+                    description: 'Label for the line',
+                },
+                color: {
+                    type: 'string',
+                    description: 'Line color (hex code)',
+                },
+                lineStyle: {
+                    type: 'string',
+                    enum: ['solid', 'dashed', 'dotted'],
+                    description: 'Line style',
+                },
+                chartId: {
+                    type: 'string',
+                    description: 'Chart to add to',
+                },
+            },
+            required: ['id', 'x'],
+        },
+    },
+    handler: async (args, context) => {
+        if (!currentBuilder) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No document started. Use create_chart first.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const chartId = args.chartId ||
+            context.sessionState.get('currentChartId');
+        if (!chartId) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No chart specified.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const element = {
+            id: args.id,
+            type: 'verticalLine',
+            x: args.x,
+        };
+        if (args.label)
+            element.label = args.label;
+        if (args.color)
+            element.color = args.color;
+        if (args.lineStyle)
+            element.lineStyle = args.lineStyle;
+        currentBuilder.addElement(chartId, element);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Added vertical line "${args.id}" at x=${args.x} to chart "${chartId}".`,
+                },
+            ],
+        };
+    },
+};
+/**
+ * Tool: add_horizontal_line
+ *
+ * Adds a horizontal line to the current chart.
+ */
+const addHorizontalLine = {
+    tool: {
+        name: 'add_horizontal_line',
+        description: 'Add a horizontal line at a specific y value. Useful for marking prices, reference levels, or constraints.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Unique identifier for the line',
+                },
+                y: {
+                    type: ['number', 'string'],
+                    description: 'Y position (number or expression)',
+                },
+                label: {
+                    type: 'string',
+                    description: 'Label for the line',
+                },
+                color: {
+                    type: 'string',
+                    description: 'Line color (hex code)',
+                },
+                lineStyle: {
+                    type: 'string',
+                    enum: ['solid', 'dashed', 'dotted'],
+                    description: 'Line style',
+                },
+                chartId: {
+                    type: 'string',
+                    description: 'Chart to add to',
+                },
+            },
+            required: ['id', 'y'],
+        },
+    },
+    handler: async (args, context) => {
+        if (!currentBuilder) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No document started. Use create_chart first.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const chartId = args.chartId ||
+            context.sessionState.get('currentChartId');
+        if (!chartId) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No chart specified.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const element = {
+            id: args.id,
+            type: 'horizontalLine',
+            y: args.y,
+        };
+        if (args.label)
+            element.label = args.label;
+        if (args.color)
+            element.color = args.color;
+        if (args.lineStyle)
+            element.lineStyle = args.lineStyle;
+        currentBuilder.addElement(chartId, element);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Added horizontal line "${args.id}" at y=${args.y} to chart "${chartId}".`,
+                },
+            ],
+        };
+    },
+};
+/**
+ * Tool: export_document
+ *
+ * Exports the current document as YAML.
+ */
+const exportDocument = {
+    tool: {
+        name: 'export_document',
+        description: 'Export the current document being built as YAML. This is the final step after using create_chart, add_curve, etc.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: {
+                    type: 'string',
+                    description: 'Document title',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Document description',
+                },
+                clear: {
+                    type: 'boolean',
+                    description: 'Clear the document after export',
+                    default: false,
+                },
+            },
+        },
+    },
+    handler: async (args) => {
+        if (!currentBuilder) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'No document to export. Use create_chart first.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        if (args.title) {
+            currentBuilder.setTitle(args.title);
+        }
+        if (args.description) {
+            currentBuilder.setDescription(args.description);
+        }
+        const document = currentBuilder.build();
+        const yaml = formatAsYAML(document);
+        if (args.clear) {
+            currentBuilder = null;
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: yaml,
+                },
+            ],
+        };
+    },
+};
+export const modelTools = [
+    createChart,
+    addCurve,
+    addPoint,
+    addArea,
+    addParameter,
+    addAnnotation,
+    addVerticalLine,
+    addHorizontalLine,
+    exportDocument,
+];
+//# sourceMappingURL=models.js.map