Skip to content

Commit b3ca0db

Browse files
Copilotsbroenne
Copilot
and
sbroenne
authored
Add GitHub Copilot instructions file for MCP Server usage to VS Code extension (#242)
* Initial plan * Add GitHub Copilot instructions file to VS Code extension Co-authored-by: sbroenne <3026464+sbroenne@users.noreply.github.com> * Rewrite copilot-instructions.md to focus on MCP Server usage Co-authored-by: sbroenne <3026464+sbroenne@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: sbroenne <3026464+sbroenne@users.noreply.github.com>
1 parent b894585 commit b3ca0db

File tree

1 file changed

+184
-0
lines changed

1 file changed

+184
-0
lines changed

‎vscode-extension/.github/copilot-instructions.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Excel MCP Server - Usage Instructions
2+
3+
> **How to use the Excel MCP Server tools to automate Microsoft Excel**
4+
5+
## Prerequisites
6+
7+
- **Windows OS** - Excel COM automation requires Windows
8+
- **Microsoft Excel 2016 or later** - Must be installed
9+
- **File must be CLOSED in Excel** - ExcelMcp requires exclusive file access
10+
11+
---
12+
13+
## Available Tools (12 tools, 172 operations)
14+
15+
| Tool | Purpose |
16+
|------|---------|
17+
| `excel_file` | Open/close sessions, create workbooks |
18+
| `excel_powerquery` | Import external data, M code management |
19+
| `excel_datamodel` | DAX measures, relationships, Power Pivot |
20+
| `excel_table` | Excel Tables with filtering and sorting |
21+
| `excel_pivottable` | PivotTables from ranges/tables/data model |
22+
| `excel_chart` | Create and configure charts |
23+
| `excel_range` | Cell values, formulas, formatting |
24+
| `excel_worksheet` | Sheet lifecycle (create, delete, rename) |
25+
| `excel_namedrange` | Named ranges for parameters |
26+
| `excel_connection` | Manage OLEDB/ODBC connections |
27+
| `excel_vba` | VBA modules (.xlsm files only) |
28+
| `excel_conditionalformat` | Conditional formatting rules |
29+
30+
---
31+
32+
## Critical Rules
33+
34+
### Session Management
35+
- **ALWAYS** start with `excel_file(action: 'open')` before any operations
36+
- **KEEP session open** across multiple operations
37+
- **ONLY close** with `excel_file(action: 'close')` when all operations complete
38+
- Ask user "Should I close the session now?" if unclear
39+
40+
### File Access
41+
- File MUST be closed in Excel UI before automation
42+
- Tell user: "Please close the file in Excel before running automation"
43+
44+
---
45+
46+
## Tool Selection Guide
47+
48+
| Need | Use | NOT |
49+
|------|-----|-----|
50+
| External data (CSV, databases, APIs) | `excel_powerquery` | `excel_table` |
51+
| DAX measures / Data Model | `excel_datamodel` | `excel_range` |
52+
| Worksheet formulas | `excel_range` | `excel_datamodel` |
53+
| Convert range to table | `excel_table` | - |
54+
| Sheet lifecycle | `excel_worksheet` | - |
55+
| Named ranges | `excel_namedrange` | - |
56+
| VBA macros | `excel_vba` (.xlsm only) | - |
57+
58+
---
59+
60+
## Power Query (excel_powerquery)
61+
62+
**Actions**: list, view, create, update, refresh, load-to, unload, delete
63+
64+
**Load destinations** (critical for DAX):
65+
- `worksheet` - Users see data, NO DAX capability (default)
66+
- `data-model` - Ready for DAX, users DON'T see data
67+
- `both` - Users see data AND DAX works
68+
69+
**Common patterns**:
70+
```
71+
# Import CSV to worksheet
72+
excel_powerquery(action: 'create', mCode: 'let Source = Csv.Document(...) in Source', loadDestination: 'worksheet')
73+
74+
# Import for DAX analysis
75+
excel_powerquery(action: 'create', mCode: '...', loadDestination: 'data-model')
76+
```
77+
78+
**Mistakes to avoid**:
79+
- Using `create` on existing query → use `update` instead
80+
- Omitting `loadDestination` when DAX is needed
81+
82+
---
83+
84+
## Data Model & DAX (excel_datamodel)
85+
86+
**Actions**: list-tables, read-table, list-columns, create-measure, update-measure, delete-measure, list-measures, list-relationships, create-relationship, delete-relationship
87+
88+
**Prerequisites**: Data must be loaded with `loadDestination: 'data-model'` or `'both'`
89+
90+
**DAX syntax** (NOT worksheet formulas):
91+
```
92+
# Create measure
93+
excel_datamodel(action: 'create-measure', tableName: 'Sales', measureName: 'Total Revenue', formula: 'SUM(Sales[Amount])')
94+
```
95+
96+
---
97+
98+
## Range Operations (excel_range)
99+
100+
**Actions**: get-values, set-values, get-formulas, set-formulas, format-range, clear-all, clear-contents, copy, sort, find, replace, validate-range, add-hyperlink, merge-cells, autofit-columns, and more (42 total)
101+
102+
**Quirks**:
103+
- Single cell returns `[[value]]` (2D array), NOT scalar
104+
- Named ranges: use `sheetName: ''` (empty string)
105+
106+
**Format vs Style**:
107+
- Use `set-style` for built-in Excel styles (faster, theme-aware)
108+
- Use `format-range` only for custom brand colors
109+
110+
---
111+
112+
## Tables (excel_table)
113+
114+
**Actions**: create, list, get, resize, rename, delete, add-column, remove-column, append-rows, apply-filter, clear-filter, sort, get-data, add-to-datamodel, and more (24 total)
115+
116+
**When to use**: Structured data with headers, AutoFilter, structured references
117+
118+
---
119+
120+
## PivotTables (excel_pivottable)
121+
122+
**Actions**: create, list, get, add-field, remove-field, set-aggregation, apply-filter, sort-field, refresh, get-data, delete, and more (25 total)
123+
124+
**Create from different sources**:
125+
```
126+
# From range
127+
excel_pivottable(action: 'create', sourceType: 'range', sourceRange: 'Sheet1!A1:D100')
128+
129+
# From table
130+
excel_pivottable(action: 'create', sourceType: 'table', tableName: 'SalesData')
131+
132+
# From data model
133+
excel_pivottable(action: 'create', sourceType: 'datamodel')
134+
```
135+
136+
---
137+
138+
## Common Mistakes
139+
140+
| ❌ Wrong | ✅ Correct |
141+
|----------|-----------|
142+
| `excel_table(action: 'create')` for CSV import | `excel_powerquery(action: 'create', loadDestination: 'worksheet')` |
143+
| `excel_powerquery(action: 'create')` for DAX | `excel_powerquery(action: 'create', loadDestination: 'data-model')` |
144+
| `excel_namedrange(action: 'create')` called 5 times | `excel_namedrange(action: 'create-bulk')` with array |
145+
| `excel_range` for DAX formulas | `excel_datamodel(action: 'create-measure')` |
146+
| Working on file open in Excel | Ask user to close file first |
147+
| Closing session mid-workflow | Keep session open until complete |
148+
149+
---
150+
151+
## Error Handling
152+
153+
**"File is already open"** → Tell user to close Excel file first
154+
155+
**"Value does not fall within expected range"** → Usually invalid range address or unsupported operation
156+
157+
**"Query 'X' already exists"** → Use `update` action instead of `create`
158+
159+
**Refresh timeout** → Ask user to run refresh manually in Excel
160+
161+
---
162+
163+
## Example Workflows
164+
165+
### Import CSV and Create PivotTable
166+
1. `excel_file(action: 'open', filePath: 'workbook.xlsx')`
167+
2. `excel_powerquery(action: 'create', mCode: '...', loadDestination: 'worksheet')`
168+
3. `excel_table(action: 'list')` - verify table created
169+
4. `excel_pivottable(action: 'create', sourceType: 'table', tableName: '...')`
170+
5. `excel_pivottable(action: 'add-field', fieldName: 'Region', area: 'Row')`
171+
6. `excel_file(action: 'close', save: true)`
172+
173+
### Build DAX Measure
174+
1. `excel_file(action: 'open', filePath: 'workbook.xlsx')`
175+
2. `excel_powerquery(action: 'create', loadDestination: 'data-model', mCode: '...')`
176+
3. `excel_datamodel(action: 'create-measure', tableName: 'Sales', measureName: 'YoY Growth', formula: '...')`
177+
4. `excel_file(action: 'close', save: true)`
178+
179+
---
180+
181+
## References
182+
183+
- [Complete Feature Reference](https://github.com/sbroenne/mcp-server-excel/blob/main/FEATURES.md)
184+
- [Main Documentation](https://github.com/sbroenne/mcp-server-excel)

0 commit comments

Comments
 (0)