Stefan Broenner
37aa032503
* docs: improve discovery and documentation UX Restructure feature documentation around canonical category pages, improve GitHub Pages navigation and SEO, and align contributor guidance with the canonical-first model. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: f3240d8f-e245-4dfb-a1f5-79373ca1ca1f * docs: add release note Document the user-visible discovery and documentation navigation improvements. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: f3240d8f-e245-4dfb-a1f5-79373ca1ca1f * docs: complete site SEO improvements Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: f3240d8f-e245-4dfb-a1f5-79373ca1ca1f * docs: add task guides, LLM discoverability layer, and skills reference to site Intent-matching content (docs/guides/): - Five canonical task guides built from verified material: refresh Power Query, automate PivotTables, query the Data Model with DAX, run VBA macros, and COM automation vs. file-parser libraries - Guides hub index, Guides nav section, cross-links from feature docs, FEATURES.md, home page and troubleshooting Machine-readable layer for AI assistants (gh-pages/hooks.py): - /llms.txt (llmstxt.org format) and /llms-full.txt, generated from the resolved MkDocs nav so they cannot go stale - Markdown mirror of every page, advertised via rel=alternate - /tools.json derived from canonical feature docs, build fails on count mismatch with FEATURES.md - FAQPage JSON-LD generated from existing question admonitions - Explicit AI-crawler allow policy in robots.txt Reference corpus (skills/shared/ -> /reference/): - Publish all 24 expert files as a nav-grouped Reference section - Fix stray outer code fences in conditionalformat, pivottable and slicer that also rendered wrong inside the shipped skill packages Distribution metadata: - Correct stale tool/operation counts in mcpb/manifest.json and the CLI package description - Point NuGet PackageProjectUrl and .mcp/server.json at the docs site - Extend check-doc-counts.ps1 to guard both, so this cannot recur Validation: - New gh-pages/audit_site.py gate (canonicals, metadata completeness, single H1, image dimensions, internal links, sitemap, llms outputs, mirror cleanliness, tools.json counts, robots policy) wired into the Pages deploy workflow, keeping the docs-only pre-commit path fast Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: f3240d8f-e245-4dfb-a1f5-79373ca1ca1f * docs: fix marketplace extension identifier and security PoC command The publisher guide linked to itemName=sbroenne.excelmcp, but the extension is published as sbroenne.excel-mcp (14 other references in the repo already use the correct form), so both links 404. The SECURITY.md path-traversal example invoked 'powerquery export', which is not a command. Replaced with 'powerquery view', which does take a file path and so actually illustrates the class of issue. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: f3240d8f-e245-4dfb-a1f5-79373ca1ca1f --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: f3240d8f-e245-4dfb-a1f5-79373ca1ca1f
3.3 KiB
ExcelMcp Architecture
ExcelMcp uses Windows COM automation to control the actual Microsoft Excel
application—not just .xlsx files. Because it drives Excel's official
Excel.Application API, it can refresh Power Query, recalculate formulas,
refresh PivotTables and the Data Model, evaluate DAX, and run VBA or Python
=PY() while preserving existing workbook features.
Two equal entry points
The project ships both an MCP Server and a CLI. They are first-class entry points backed by the same Core commands, parameters, defaults, and validation:
- MCP Server hosts
ExcelMcpServicein-process and uses direct method calls, which suits conversational and interactive AI clients. - CLI (
excelcli) communicates with anExcelMcpServicebackground daemon over a user-isolated Windows named pipe. The daemon keeps workbook sessions open across CLI invocations for scripting and coding-agent workflows.
MCP Server ──► In-process ExcelMcpService ──► Core Commands ──► Excel COM
CLI ─────────► CLI daemon (named pipe) ─────► Core Commands ──► Excel COM
The entry points run as separate processes, each managing its own Excel instance. They do not share live sessions.
The CLI also avoids loading the MCP tool schemas into a coding agent's context. In a same-task, same-model benchmark, the CLI workflow used about 59K tokens versus 163K for MCP—a 64% reduction. Actual usage varies by client, model, and workflow.
Core layers
- ComInterop (
src/ExcelMcp.ComInterop) provides reusable STA threading, session management, COM cleanup, write guards, and OLE message filtering. - Core (
src/ExcelMcp.Core) implements Excel operations for Power Query, DAX, VBA, worksheets, ranges, charts, and other domains. - Service (
src/ExcelMcp.Service) manages sessions and routes commands. - CLI (
src/ExcelMcp.CLI) exposes generated command categories and uses a persistent daemon. - MCP Server (
src/ExcelMcp.McpServer) exposes generated MCP tools and invokes the service in-process. - Source generators (
src/ExcelMcp.Generators*) generate CLI commands, MCP schemas, and skill manifests from Core interfaces.
Real Excel automation
ExcelMcp intentionally uses the Excel COM API rather than rewriting workbook packages. This provides:
- Excel's own calculation and refresh engines
- Preservation of formulas, formatting, charts, PivotTables, macros, and the Data Model
- Interactive authentication for protected workbooks
- The ability to show Excel and inspect changes as they happen
CLI desktop integration
The CLI daemon keeps sessions alive between commands and exposes a system-tray icon for monitoring sessions, update notifications, save prompts, and stopping the daemon. Excel can remain hidden for speed or be shown and arranged beside an AI assistant for interactive work.
Session lifecycle
Both entry points use explicit sessions:
- Open or create a workbook and receive a session ID.
- Run one or more operations against that session.
- Close the session, optionally saving changes.
This avoids repeatedly opening workbooks and gives ExcelMcp one controlled place to manage COM resources and Excel process shutdown.
Read the development guide for implementation details, or choose an installation path.