feat: Chart Positioning Enhancements (#381) (#383)

* feat: Add chart positioning enhancements (#381)

- Add cell geometry (Left, Top, Width, Height) to RangeInfoResult get-info
- Add TopLeftCell, BottomRightCell anchor addresses to chart read
- Add Placement mode (1=move/size, 2=move, 3=floating) to chart read
- Add fit-to-range action to position/resize charts to cell boundaries
- Add set-placement action to control chart resize behavior
- Update operation count: 194 -> 196 operations across 22 tools
- Add SetPlacement to audit script known exceptions (exposed via ChartConfigAction)

Co-authored-by: GitHub Copilot

* feat(chart): Add targetRange parameter for one-step cell-relative positioning (#381)

- Add targetRange parameter to create-from-range and create-from-pivottable actions

- Auto-calls FitToRange when targetRange provided

- Update tool XML docs with CRITICAL positioning warnings

- Add LLM test scenario (excel-chart-positioning-test.yaml)

- Update prompts and skills documentation

---------

Co-authored-by: Stefan Broenner <[email protected]>

Author: sbroenne

scripts/audit-core-coverage.ps1

@@ -497,7 +497,7 @@ if ($CheckNaming) {
         "ChartAction" = @("SetSourceRange", "AddSeries", "RemoveSeries", "SetChartType", "SetTitle",
                           "SetAxisTitle", "GetAxisNumberFormat", "SetAxisNumberFormat", "ShowLegend", "SetStyle",
                           "SetDataLabels", "GetAxisScale", "SetAxisScale", "GetGridlines", "SetGridlines", "SetSeriesFormat",
-                          "ListTrendlines", "AddTrendline", "DeleteTrendline", "SetTrendline")  # Methods moved to ChartConfigAction
+                          "ListTrendlines", "AddTrendline", "DeleteTrendline", "SetTrendline", "SetPlacement")  # Methods moved to ChartConfigAction
     }
 
     $hasNamingIssues = $false

skills/excel-mcp/references/excel_chart.md

@@ -110,3 +110,41 @@ Specialized: `Waterfall`, `Funnel`, `Treemap`, `Sunburst`, `BoxWhisker`, `Histog
 3. **Use gridlines sparingly**: Minor gridlines often add clutter
 4. **Trendlines for insights**: Add R² to show fit quality
 5. **Data labels placement**: `OutsideEnd` for bar charts, `Center` for pie charts
+
+## Chart Positioning (CRITICAL)
+
+**ALWAYS position charts to avoid overlapping data:**
+
+### Use targetRange (PREFERRED - One Step)
+```
+excel_chart(create-from-range, sourceRange='A1:B10', chartType='Line', targetRange='F2:K15')
+```
+Creates chart AND positions it to cell range in one call.
+
+### Check Used Range First
+```
+excel_range(action: 'get-used-range') → e.g., "Sheet1!A1:D20"
+```
+
+### Position with Coordinates
+```
+excel_chart(create-from-range, sourceRange: 'A1:B10', left: 360, top: 20)
+# left/top in points (72 points = 1 inch)
+```
+
+### Use FitToRange (After Creation)
+```
+excel_chart(create-from-range, ...) -> chartName
+excel_chart(fit-to-range, chartName, rangeAddress: 'F2:K15')
+# Reposition existing chart to cell range
+```
+
+### Position Estimates
+- Rows: ~15 points per row (varies with row height)
+- Columns: ~60 points per column (varies with column width)
+- Default chart: 400x300 points
+
+### Positioning Workflow
+1. `get-used-range` -> Identify data boundaries
+2. **Option A (Preferred)**: Use `targetRange='F2:K15'` in create call
+3. **Option B**: Calculate `(lastRow + 2) * 15` for top, or `(lastCol + 2) * 60` for left

src/ExcelMcp.Core/Commands/Chart/ChartCommands.Appearance.cs

@@ -305,6 +305,41 @@ public void SetStyle(IExcelBatch batch, string chartName, int styleId)
         });
     }
 
+    /// <inheritdoc />
+    public void SetPlacement(IExcelBatch batch, string chartName, int placement)
+    {
+        batch.Execute((ctx, ct) =>
+        {
+            // Find chart by name
+            var findResult = FindChart(ctx.Book, chartName);
+            if (findResult.Chart == null)
+            {
+                throw new InvalidOperationException($"Chart '{chartName}' not found in workbook.");
+            }
+
+            try
+            {
+                // Validate placement value (xlMoveAndSize=1, xlMove=2, xlFreeFloating=3)
+                if (placement < 1 || placement > 3)
+                {
+                    throw new ArgumentException(
+                        $"Placement must be 1 (move and size with cells), 2 (move only), or 3 (free floating). Provided: {placement}",
+                        nameof(placement));
+                }
+
+                // Set placement on the shape (ChartObject)
+                findResult.Shape.Placement = placement;
+
+                return 0; // Void operation completed
+            }
+            finally
+            {
+                if (findResult.Shape != null) ComUtilities.Release(ref findResult.Shape!);
+                if (findResult.Chart != null) ComUtilities.Release(ref findResult.Chart!);
+            }
+        });
+    }
+
     // === DATA LABELS ===
 
     /// <inheritdoc />
@@ -1129,4 +1164,49 @@ public void SetTrendline(
             }
         });
     }
+
+    /// <inheritdoc />
+    public void FitToRange(IExcelBatch batch, string chartName, string sheetName, string rangeAddress)
+    {
+        batch.Execute((ctx, ct) =>
+        {
+            // Find chart by name
+            var findResult = FindChart(ctx.Book, chartName);
+            if (findResult.Chart == null)
+            {
+                throw new InvalidOperationException($"Chart '{chartName}' not found in workbook.");
+            }
+
+            dynamic? worksheet = null;
+            dynamic? range = null;
+
+            try
+            {
+                // Get the target range
+                worksheet = ctx.Book.Worksheets.Item(sheetName);
+                range = worksheet.Range[rangeAddress];
+
+                // Get range geometry
+                double left = Convert.ToDouble(range.Left);
+                double top = Convert.ToDouble(range.Top);
+                double width = Convert.ToDouble(range.Width);
+                double height = Convert.ToDouble(range.Height);
+
+                // Apply to chart shape
+                findResult.Shape.Left = left;
+                findResult.Shape.Top = top;
+                findResult.Shape.Width = width;
+                findResult.Shape.Height = height;
+
+                return 0; // Void operation completed
+            }
+            finally
+            {
+                if (range != null) ComUtilities.Release(ref range!);
+                if (worksheet != null) ComUtilities.Release(ref worksheet!);
+                if (findResult.Shape != null) ComUtilities.Release(ref findResult.Shape!);
+                if (findResult.Chart != null) ComUtilities.Release(ref findResult.Chart!);
+            }
+        });
+    }
 }

src/ExcelMcp.Core/Commands/Chart/ChartResults.cs

@@ -47,6 +47,23 @@ public class ChartInfo
 
     /// <summary>Number of data series</summary>
     public int SeriesCount { get; set; }
+
+    /// <summary>
+    /// Cell address of top-left anchor (e.g., "$A$1"). 
+    /// Chart's top-left corner overlaps this cell.
+    /// </summary>
+    public string? TopLeftCell { get; set; }
+
+    /// <summary>
+    /// Cell address of bottom-right anchor (e.g., "$D$10").
+    /// Chart's bottom-right corner overlaps this cell.
+    /// </summary>
+    public string? BottomRightCell { get; set; }
+
+    /// <summary>
+    /// Chart placement mode: 1=Move and size with cells, 2=Move but don't size with cells, 3=Don't move or size with cells
+    /// </summary>
+    public int? Placement { get; set; }
 }
 
 /// <summary>
@@ -84,6 +101,23 @@ public class ChartInfoResult : OperationResult
     /// <summary>Height in points</summary>
     public double Height { get; set; }
 
+    /// <summary>
+    /// Cell address of top-left anchor (e.g., "$A$1"). 
+    /// Chart's top-left corner overlaps this cell.
+    /// </summary>
+    public string? TopLeftCell { get; set; }
+
+    /// <summary>
+    /// Cell address of bottom-right anchor (e.g., "$D$10").
+    /// Chart's bottom-right corner overlaps this cell.
+    /// </summary>
+    public string? BottomRightCell { get; set; }
+
+    /// <summary>
+    /// Chart placement mode: 1=Move and size with cells, 2=Move but don't size with cells, 3=Don't move or size with cells
+    /// </summary>
+    public int? Placement { get; set; }
+
     /// <summary>Chart title text</summary>
     public string? Title { get; set; }
 

src/ExcelMcp.Core/Commands/Chart/IChartCommands.cs

@@ -211,6 +211,24 @@ void ShowLegend(
     /// <param name="styleId">Style number (1-48)</param>
     void SetStyle(IExcelBatch batch, string chartName, int styleId);
 
+    /// <summary>
+    /// Sets chart placement mode (how chart responds when underlying cells are resized).
+    /// </summary>
+    /// <param name="batch">Excel batch session</param>
+    /// <param name="chartName">Name of the chart</param>
+    /// <param name="placement">Placement mode: 1=Move and size with cells, 2=Move but don't size, 3=Don't move or size</param>
+    void SetPlacement(IExcelBatch batch, string chartName, int placement);
+
+    /// <summary>
+    /// Fits a chart to a cell range by setting position and size to match the range bounds.
+    /// Uses the range's Left, Top, Width, Height properties.
+    /// </summary>
+    /// <param name="batch">Excel batch session</param>
+    /// <param name="chartName">Name of the chart</param>
+    /// <param name="sheetName">Worksheet containing the range</param>
+    /// <param name="rangeAddress">Target range (e.g., "A1:D10")</param>
+    void FitToRange(IExcelBatch batch, string chartName, string sheetName, string rangeAddress);
+
     // === DATA LABELS ===
 
     /// <summary>

src/ExcelMcp.Core/Commands/Chart/PivotChartStrategy.cs

@@ -38,6 +38,46 @@ public ChartInfo GetInfo(dynamic chart, string chartName, string sheetName, dyna
             Height = Convert.ToDouble(shape.Height)
         };
 
+        // Get anchor cells and placement mode
+        dynamic? topLeftCell = null;
+        dynamic? bottomRightCell = null;
+        try
+        {
+            topLeftCell = shape.TopLeftCell;
+            info.TopLeftCell = topLeftCell.Address?.ToString();
+        }
+        catch
+        {
+            // TopLeftCell not available - optional property
+        }
+        finally
+        {
+            if (topLeftCell != null) ComUtilities.Release(ref topLeftCell!);
+        }
+
+        try
+        {
+            bottomRightCell = shape.BottomRightCell;
+            info.BottomRightCell = bottomRightCell.Address?.ToString();
+        }
+        catch
+        {
+            // BottomRightCell not available - optional property
+        }
+        finally
+        {
+            if (bottomRightCell != null) ComUtilities.Release(ref bottomRightCell!);
+        }
+
+        try
+        {
+            info.Placement = Convert.ToInt32(shape.Placement);
+        }
+        catch
+        {
+            // Placement not available - optional property
+        }
+
         // Get linked PivotTable name
         dynamic? pivotLayout = null;
         dynamic? pivotTable = null;
@@ -90,6 +130,46 @@ public ChartInfoResult GetDetailedInfo(dynamic chart, string chartName, string s
             Height = Convert.ToDouble(shape.Height)
         };
 
+        // Get anchor cells and placement mode
+        dynamic? topLeftCell = null;
+        dynamic? bottomRightCell = null;
+        try
+        {
+            topLeftCell = shape.TopLeftCell;
+            info.TopLeftCell = topLeftCell.Address?.ToString();
+        }
+        catch
+        {
+            // TopLeftCell not available - optional property
+        }
+        finally
+        {
+            if (topLeftCell != null) ComUtilities.Release(ref topLeftCell!);
+        }
+
+        try
+        {
+            bottomRightCell = shape.BottomRightCell;
+            info.BottomRightCell = bottomRightCell.Address?.ToString();
+        }
+        catch
+        {
+            // BottomRightCell not available - optional property
+        }
+        finally
+        {
+            if (bottomRightCell != null) ComUtilities.Release(ref bottomRightCell!);
+        }
+
+        try
+        {
+            info.Placement = Convert.ToInt32(shape.Placement);
+        }
+        catch
+        {
+            // Placement not available - optional property
+        }
+
         // Get linked PivotTable name
         dynamic? pivotLayout = null;
         dynamic? pivotTable = null;