calcslive_run_script

Instructions

Implementation Reference

• src/index.ts:236-285 (handler)

  Handler for executing the calcslive_run_script tool: extracts pqs, inputs, outputs; POSTs to CalcsLive API /articles/uac-script/run; formats human-readable results and detailed calculation for MCP response.

  if (request.params.name === "calcslive_run_script") {
    const { pqs, inputs = {}, outputs = {} } = request.params.arguments as any;
  
    try {
      const response = await fetch(`${CALCSLIVE_API_BASE}/api/v1/articles/uac-script/run`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          apiKey: API_KEY,
          pqs,
          inputs,
          outputs
        }),
      });
  
      if (!response.ok) {
        const errorData = await response.json() as any;
        throw new Error(errorData.error?.message || `API error: ${response.status}`);
      }
  
      const result = await response.json() as any;
  
      // Format response for MCP - use humanReadable for better AI consumption
      const humanReadable = result.data.humanReadable;
      const calculation = result.data.calculation;
  
      return {
        content: [
          {
            type: "text",
            text: `${humanReadable.summary}\n\nResults:\n${humanReadable.results.map((r: any) =>
              `• ${r.description} (${r.symbol}): ${r.result}${r.expression ? ` = ${r.expression}` : ''}`
            ).join('\n')}\n\nDetailed calculation:\n${JSON.stringify(calculation, null, 2)}`,
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: "text",
            text: `Error running script calculation: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:97-167 (registration)

  Tool registration in listTools handler: defines name, description, and detailed inputSchema for calcslive_run_script, including pqs array structure, optional inputs/outputs overrides.

  {
    name: "calcslive_run_script",
    description: "Run stateless unit-aware calculations from Physical Quantity (PQ) script definitions. Define inputs and outputs as PQ objects with symbols, values, units, and expressions. No article creation needed - fully stateless. Automatically handles unit conversions, dependency graphs, and Greek letters. Example: Calculate circle area from radius using expression 'pi * r^2'.",
    inputSchema: {
      type: "object",
      properties: {
        pqs: {
          type: "array",
          description: "Array of Physical Quantity definitions. Each PQ can be an input (with value) or output (with expression).",
          items: {
            type: "object",
            properties: {
              sym: {
                type: "string",
                description: "Symbol name for this PQ (e.g., 'r', 'v', 'A'). Supports Greek letters (α, β, η, ρ, etc.)."
              },
              description: {
                type: "string",
                description: "Human-readable description (e.g., 'radius', 'velocity', 'area')"
              },
              value: {
                type: "number",
                description: "Numeric value for input PQs. Omit for calculated outputs."
              },
              unit: {
                type: "string",
                description: "Unit (e.g., 'm', 'kg', 'kW'). Supports superscript (m³) and caret (m^3) notation."
              },
              expression: {
                type: "string",
                description: "Mathematical expression for calculated PQs (e.g., 'pi * r^2', 'v / t'). References other PQ symbols."
              },
              calcId: {
                type: "string",
                description: "Optional namespace for multi-calculation contexts (default: 'CA0')"
              },
              decimalPlaces: {
                type: "number",
                description: "Decimal places for display (default: 3)"
              }
            },
            required: ["sym", "unit"]
          },
          minItems: 1
        },
        inputs: {
          type: "object",
          description: "Optional: Override input PQ values. Example: {r: {value: 5, unit: 'cm'}}",
          additionalProperties: {
            type: "object",
            properties: {
              value: { type: "number" },
              unit: { type: "string" }
            },
            required: ["value", "unit"]
          }
        },
        outputs: {
          type: "object",
          description: "Optional: Specify output unit preferences. Example: {A: {unit: 'mm²'}}",
          additionalProperties: {
            type: "object",
            properties: {
              unit: { type: "string" }
            }
          }
        }
      },
      required: ["pqs"]
    }
  },