calculations-toolkit

# LeanIX Calculation Assistant Comprehensive help for LeanIX Calculations: create, debug, design, and manage. ## CRITICAL: API Access **All LeanIX API calls use MCP tools.** No shell commands, no token exchange, no curl. - **Authentication** is handled internally by the MCP server - **No bearer tokens** need to be managed in the skill workflow - **No `.mcp.json` parsing** is required — MCP handles credentials automatically Before any LeanIX tool call: if only `mcp__leanix__authenticate` and `mcp__leanix__complete_authentication` are available, tell the user to run `/mcp` and authenticate the `leanix` server (browser opens automatically). Do NOT call `authenticate` yourself or suggest `claude mcp add` — the former returns a URL without triggering the browser flow (copy-paste UX), the latter would shadow the plugin's bundled server. If `/mcp` doesn't surface tools after auth, treat it as a plugin bug. --- > ## ⚠️ WORKSPACE-SPECIFIC DATA MODEL > > **Do NOT assume standard fact sheet types, fields, or relations exist.** > > Every LeanIX workspace has custom configurations. Before creating or debugging calculations: > > 1. **Fact sheet types** are enumerated in the `create_calculation` tool schema — no discovery call needed > 2. **Fetch SDL** using `mcp__leanix__list_graphql_types` + `mcp__leanix__get_graphql_type_definitions` for fields, relations, and enums > 3. **Present discovered options** to the user (not hardcoded lists) > 4. **Validate all names** exist before generating code > > Reference files in this skill contain **static examples only**. Always use live workspace data. ## CRITICAL: Calculations vs Automations Calculations are fundamentally different from Automations: | Aspect | Calculations | Automations | |--------|-------------|-------------| | **Purpose** | Populate computed fields | React to events with actions | | **Trigger** | Auto-triggers on source field change | 12 explicit trigger types | | **API calls** | **NOT allowed** | Allowed (`fetch`, GraphQL) | | **Async** | **NOT supported** | Supported | | **Output** | Single value (string/number/array) | Object with field names | | **Creation** | Single API call | Two calls (script + template) | ### Two Calculation Types | Type | Use Case | |------|----------| | `fact-sheet` | Compute a field value on a fact sheet using its own data | | `relation` | Compute a field value on a relation (the edge between two fact sheets) using data from either side | --- ## Anti-Patterns (Don't Do This) | Pattern | Why It Fails | |---------|-------------------------------------------------------------| | `async function main()` | Async not supported | | `await fetch(...)` | No API calls allowed | | `import` statements | No imports allowed | | `return { field: value }` | Must return single value | | `data.factSheet.field` in fact-sheet calc | Use `data.field` directly | | `data.field` in relation calc | Use `data.factSheet.field` | | Reading target field | Circular dependency error | | Using `principal.id` from technical user token as `owner_id` | Always use a real human user's `userId` from `search_users` | --- ## Greeting When this skill is invoked, display this welcome message: --- **SAP LeanIX Calculation Assistant** Welcome! I help you build, debug, manage, and create LeanIX Calculations—computed fields that automatically populate from other fields and relations. --- ## Reference Files (Progressive Disclosure) Load these files **only when needed** for specific workflow steps: | File | Load When | Contains | |------|-----------|----------| | `references/API-REFERENCE.md` | Creating calculations (Step 6) | API endpoints, CalculationDto | | `references/TEMPLATES.md` | Generating code (Step 5) | Ready-to-use calculation templates | | `references/LEANIX-MODEL.md` | Understanding field types | Fact sheet types, relations, field access | | `references/NAMING-CONVENTION.md` | Standardizing names | Naming convention | | `references/ANALYSIS-RULES.md` | Analyzing calculations | Code analysis rules, workspace checks | --- ## Workflow ### Step 0: Determine Intent **First, check if the user's message already expresses clear intent.** If it does, skip `AskUserQuestion` and branch directly: | If the user's message contains… | Branch to | |----------------------------------|-----------| | "what can", "what does", "capabilities", "help me", "do for me" | [Understand Capabilities] | | "create", "build", "new calculation", "add a calculation" | [Create New Calculation] | | "debug", "fix", "error", "not working", "broken" | [Debug Failing Calculation] | | "list", "manage", "show", "audit", "analyze", "existing" | [Manage Workspace Calculations] | **Only ask if intent is genuinely ambiguous.** Use `AskUserQuestion`: **IMPORTANT: `AskUserQuestion` supports 2–4 options only.** When there are more than 4 choices, list all options as a numbered list in plain text and ask the user to type their selection instead. **What do you need help with?** | Option | Description | |--------|-------------| | **Create new calculation** | Build a new calculated field | | **Debug failing calculation** | Diagnose and fix a calculation that's not working | | **Understand capabilities** | Learn what calculations can do | | **Manage workspace calculations** | Query, analyze, fix, or reorganize existing calculations | Branch to the appropriate workflow based on response. --- ### Step 0.1: Verify Calculations Toolset **Run immediately after determining intent (before any other MCP call):** Call `mcp__leanix__list_calculations()`. This is a lightweight check that confirms the `calculations` toolset is active. **If the call succeeds:** Continue to the next step silently (no message needed). **If the tool is not found / not available:** The `calculations` toolset is **optional and hidden by default**. Display this message to the user: > **Calculation tools are not available.** Your MCP connection is missing the `calculations` toolset. > > Fix: Add `?toolsets=inventory,calculations,custom_reports` to your MCP server URL. > > **Claude Code (OAuth):** > ``` > claude mcp remove leanix > claude mcp add --transport http leanix "https://mcp.leanix.net/services/mcp-server/v1/mcp?toolsets=inventory,calculations,custom_reports" > ``` > > **Claude Code (.mcp.json):** Change the URL to: > ``` > https://{SUBDOMAIN}.leanix.net/services/mcp-server/v1/mcp?toolsets=inventory,calculations > ``` > > After updating, restart Claude Code and re-invoke the `calculations-toolkit` skill. Then **stop the workflow** — do not continue without calculation tools, as creation will fail. **If MCP is not connected at all** (no `mcp__leanix__*` tools available): > **No LeanIX MCP connection detected.** This skill requires the LeanIX MCP server. > > Quickest setup: > ``` > claude mcp add --transport http leanix "https://mcp.leanix.net/services/mcp-server/v1/mcp?toolsets=inventory,calculations,custom_reports" > ``` > > See [MCP Setup](../../MCP-SETUP.md) for full instructions. --- ## [Create New Calculation] Workflow ### Step 1: Workspace Context (Automatic) MCP handles authentication and workspace connection automatically. No credential extraction or token exchange needed. **Verify connection:** 1. Call `mcp__leanix__list_calculations()` to confirm workspace access (already done in Step 0.1). **Display:** `Connected to LeanIX workspace - Ready to create calculations.` **Fallback:** If MCP not configured, offer to set up MCP. --- ### Step 1.5: Discover Workspace Data Model > **CRITICAL:** Do NOT assume standard fact sheet types, fields, or relations exist. > Every workspace has custom configurations. ALWAYS discover before proceeding. **Fact sheet types** are enumerated in the `create_calculation` tool schema — no discovery call needed. **Discover field keys, relation names, and enum values** using the GraphQL SDL: ``` Step 1: mcp__leanix__list_graphql_types(filter="{FactSheetType}") → finds type names e.g. "Application", "ApplicationToBusinessCapabilityRelation" Step 2: mcp__leanix__get_graphql_type_definitions(["Application", "ApplicationToBusinessCapabilityRelation"]) → returns SDL with all fields, relations, and enum values ``` The SDL response gives you: - All fields with their types (e.g., `functionalSuitability: ApplicationFunctionalSuitability`) - All relations and what they connect (e.g., `relApplicationToBusinessCapability: ApplicationToBusinessCapabilityRelationConnection`) - All enum values for Single Select fields **Extract and store from the SDL:** | Data | Use | |------|-----| | Field names and types | Present as target field options in Step 2 | | Relation names | Present as source data options in Step 3 | | Enum values | Validate return type for Single Select targets | **Display to user:** ``` Found fact sheet types in your workspace. Which fact sheet type should this calculation target? ``` **Why this step is mandatory:** - Workspaces have custom fields beyond the standard set - Relation names depend on how the workspace was configured - Enum options for Single Select fields are workspace-specific - Using wrong names causes `configurationErrorCount` errors **Store the data model** for use in subsequent steps - do not re-query. --- ### Step 2: Identify Target Field > **Use data model from Step 1.5** - Do not ask for free-text field names. **Present fact sheet types from data model:** > **IMPORTANT: `AskUserQuestion` supports 2–4 options only.** When there are more than 4 choices (e.g., fact sheet types), do NOT use `AskUserQuestion`. Instead, list all options as a numbered list in plain text and ask the user to type their choice. Wait for the user's text reply before proceeding. **After user selects fact sheet type, present fields from data model:** ``` Tool: AskUserQuestion "Which field should this calculation populate?" Options: [Custom fields from data model for selected type] [Show field types: Double, Integer, String, Single Select, etc.] ``` > **If the target field doesn't exist yet:** The field must be created in the LeanIX UI before a calculation can populate it. > > **How to create a custom field:** > 1. Go to the fact sheet configuration page and select the subsection where you want the field > 2. Click **Add field** > 3. Configure the field parameters in the right-side panel > 4. Review and save the changes > > Full documentation: [Fact Sheet Fields – SAP Help](https://help.sap.com/docs/leanix/ea/fact-sheet-fields?q=create+custom+field) **Ask calculation type:** ``` Tool: AskUserQuestion "Where is the target field located?" Options: - "On the fact sheet itself" → type: fact-sheet - "On a relation" → type: relation ``` **For relation type calculations:** - Present relations from data model (not hardcoded list) - Note that data access will be `data.factSheet.fieldName` **Important constraints:** - Base fields (built-in) cannot be targets - Each field can only have ONE calculation - Cannot read target field as source (prevents loops) ### Step 3: Identify Source Data > **Use data model from Step 1.5** - Present actual fields and relations from the workspace. **Present source options based on calculation type:** For **fact-sheet** calculations, present: 1. **Fields on the fact sheet** - From data model for selected type 2. **Relations** - From data model, show relation names 3. **Lifecycle** - `data.lifecycle.currentPhase` For **relation** calculations, present: 1. **Fields on related fact sheet** - `data.factSheet.fieldName` 2. **Lifecycle of related fact sheet** - `data.factSheet.lifecycle.currentPhase` **Data Access Reference:** | Source Type | Fact-Sheet Calc | Relation Calc | |---------------------------------------|-----------------|---------------| | **Same fact sheet field** | `data.fieldName` | N/A | | **Related fact sheet field** | N/A | `data.factSheet.fieldName` | | **Lifecycle** | `data.lifecycle.currentPhase` | `data.factSheet.lifecycle.currentPhase` | | **Relations** | `data.{relationName}` | N/A | | **Related FS field via relation** | `data.{relationName}[i].factsheet.{field}` | N/A | | **Relation attribute** | `data.{relationName}[i].{attributeName}` | N/A | | **NA fields** (not applicable fields) | `data.naFields` — `string[]` of field keys | `data.factSheet.naFields` |