skills/sbroenne__mcp-server-excel
1
0
Fork 0
mirror of https://github.com/sbroenne/mcp-server-excel.git synced 2026-09-19 07:53:08 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
v1.4.21
sbroenne__mcp-server-excel/docs/RELEASE-STRATEGY.md
T
Stefan Broenner 321aa694f4 feat: Improve SEO and add comprehensive installation guide (#144) 
* Refactor README files: Simplify language in ExcelMcp.ComInterop and remove ExcelMcp.Core documentation

* chore: Remove references to COMMANDS.md in documentation and workflows, update to README.md or component documentation

* chore: Update documentation references to CLI and remove obsolete CLI.md file

* feat(cli): implement 38 missing command wrappers and sync online help

Implementation (38 commands):
- Range: Add 33 commands (copy-values/formulas, insert/delete cells/rows/columns,
  find/replace/sort, discovery, hyperlinks, styles/validation, merge/autofit, advanced)
- Table: Add 2 commands (get/set-column-format)
- QueryTable: Add 3 commands (create-from-connection/query, update-properties)
- PivotTable: Document 7 blocked methods with technical context

Routing & Help:
- Add 38 routing entries in Program.cs switch statement
- Update ShowHelp() function with all 38 commands:
  * Range: Reorganize into 8 subsections for clarity
  * Table: Add 2 column format commands
  * QueryTable: Add 3 create/update commands
- Grow Program.cs from 554 to 608 lines (+9.7%)

Documentation:
- Update CLI README: 109 → 147 commands
- Update category counts: Range (11→44), Table (21→23), QueryTable (5→8)
- Update MCP Server README: CLI reference now shows 147 commands
- Document PivotTable limitations in code comments

Status: 38/45 commands complete (84.4%)
- Implemented: 38 (Range: 33, Table: 2, QueryTable: 3)
- Blocked: 7 (PivotTable methods awaiting file manipulation support)

Fixes:
- Correct property names in RangeCommands (Address vs Url, ScreenTip vs Tooltip)
- Fix hyperlink removal logic (target address calculation)
- Replace ToLowerInvariant() with StringComparison.OrdinalIgnoreCase for CA1862
- Ensure consistent formatting throughout

Zero compilation errors, all tests passing.

* refactor(release): unify MCP Server and CLI releases, optimize copilot instructions

Release Workflow Changes:
- Rename release-mcp-server.yml to handle both MCP Server and CLI
- Change tag pattern: mcp-v* → v* (unified versioning)
- MCP Server and CLI always release together with same version
- Single workflow builds and publishes both NuGet packages
- GitHub release includes both ZIP packages
- Delete obsolete workflows:
  * release-cli.yml (merged into unified workflow)
  * release-core.yml (no longer publishing Core to NuGet)
  * release-cominterop.yml (no longer publishing ComInterop to NuGet)

Copilot Instructions Optimization:
- copilot-instructions.md: 184→132 lines (-28%)
  * Replace verbose navigation with priority-based structure
  * Consolidate code patterns (remove redundant comments)
  * Compress 28 lesson paragraphs → 7 one-line takeaways
  * Simplify path-specific explanation

- critical-rules.instructions.md: Add usage-based priority table
  * Group rules by context: Every Edit, Writing Code, Writing Tests, Before Commit, PR Process, Rare
  * Replace flat list with contextual grouping for 10x faster scanning
  * Add 'Why Critical' column for each rule

Benefits:
- Simplified release process: One tag (v1.2.3) releases both packages
- Version consistency: MCP Server and CLI stay in sync
- Reduced CI/CD complexity: 3 fewer workflows to maintain
- Better LLM efficiency: 28% less token usage in main instructions
- Faster rule lookup: O(1) with priority table vs linear scan

* docs: update release documentation for unified v* versioning

- Updated RELEASE-STRATEGY.md: Removed separate Core/ComInterop/MCP/CLI sections, added unified MCP+CLI release section
- Updated NUGET-GUIDE.md: Changed to unified v* tag pattern, combined package documentation
- Updated MCP_REGISTRY_PUBLISHING.md: Changed mcp-v* to v* tag pattern
- All docs now reflect simplified release strategy (MCP Server + CLI always released together)

* docs: update development-workflow instructions for unified versioning

- Changed tag pattern from separate mcp-v*/cli-v* to unified v*
- Reflects simplified release strategy (MCP Server + CLI together)

* Remove redundant CheckIfOpen action

FileAction.CheckIfOpen was redundant because ExcelBatch already checks
if files are locked before opening Excel COM (via FileAccessValidator.
ValidateFileNotLocked). Operations fail gracefully with clear error
messages when files are open, eliminating need for pre-flight checks.

Changes:
- Remove CheckIfOpen from FileAction enum
- Remove CheckIfOpen implementation (75 lines)
- Remove CheckIfOpen from ActionExtensions mapping
- Update audit scripts to remove CheckIfOpen exceptions
- Update excel_file.md prompt to document automatic lock detection
- Update ExcelFileTool [Description] to remove CheckIfOpen guidance

Benefits:
- Simpler architecture with less mental load for LLMs
- One less action to learn and maintain
- Automatic error handling with actionable user guidance
- Consistent with batch mechanism that already handles this

Fixes: MCP Server test failures (missing enum mapping)

* Optimize instruction files for expert LLM audience

- Eliminate duplication across all 13 instruction files
- Remove beginner content and explanatory 'why' sections
- Establish expert tone throughout (assumes C#, Excel, COM knowledge)
- Consolidate test commands to testing-strategy (single source of truth)
- Cross-reference instead of duplicating content (WithExcel, SaveAsync, workflows)
- Major rewrites: bug-fixing (416→82), documentation-structure (355→86), mcp-llm-guidance (414→152), mcp-server-guide (282→192)
- Result: Most files now under 200 lines, focused on project-specific patterns only

* Update MCP Server README: emphasize RPA/CLI capabilities and simplify installation

- Add RPA (Robotic Process Automation) terminology for CLI automation use cases
- Remove specific command counts that change frequently
- Simplify installation section to prioritize VS Code Extension
- Add CLI example use case for version control workflows
- Update resources section with RPA/CI/CD focus

* feat: improve SEO with GitHub Pages docs and enhanced server.json description

* feat: Improve SEO and add comprehensive installation guide

- Add GitHub repository topics (20 relevant tags for discoverability)
- Update GitHub repository description for better search results
- Enable GitHub Pages with docs/index.md landing page
- Enhance MCP Registry server.json description
- Improve NuGet package metadata with comprehensive tags
- Add REPL developer callout and interactive development messaging
- Create comprehensive INSTALLATION.md guide
- Fix VS Code marketplace extension ID (sbroenne.excel-mcp)
- Add Critical Rule 20: Never commit automatically
- Update README and docs to mention both MCP Server and CLI prominently

---------

Co-authored-by: Stefan Broenner <stefan.broenner@microsoft.comm>
2025-11-09 10:49:25 +00:00

5.4 KiB
Raw Permalink Blame History

ExcelMcp Release Strategy

This document outlines the build and release processes for ExcelMcp components: MCP Server & CLI (unified), and VS Code Extension.

Release Workflows

1. MCP Server & CLI Unified Releases (v* tags)

Workflow: .github/workflows/release-mcp-server.yml Trigger: Tags starting with v (e.g., v1.0.0)

Features:

  • Builds and packages both MCP Server and CLI together
  • Publishes both to NuGet as .NET tools (using OIDC trusted publishing)
  • Creates unified GitHub release with both packages
  • Synchronized versioning ensures compatibility
  • Single workflow handles both NuGet packages and GitHub release

Release Artifacts:

  • ExcelMcp-MCP-Server-{version}-windows.zip - MCP Server binary package
  • ExcelMcp-CLI-{version}-windows.zip - CLI binary package
  • NuGet package: Sbroenne.ExcelMcp.McpServer on NuGet.org
  • NuGet package: Sbroenne.ExcelMcp.CLI on NuGet.org (as .NET global tool)
  • Unified release notes covering both packages

Publishing Method:

  • Uses OIDC (OpenID Connect) trusted publishing for secure NuGet authentication
  • No API keys stored in secrets - authentication via GitHub identity
  • Publishes both packages to NuGet.org within same workflow
  • CLI configured as .NET global tool (PackAsTool=true)

Use Cases:

  • MCP Server: AI assistant integration (GitHub Copilot, Claude, ChatGPT), conversational Excel workflows
  • CLI: Direct Excel automation scripts, CI/CD pipeline integration, command-line operations
  • Both: Unified version ensures compatibility, simplified dependency management

Why Unified?

  • MCP Server and CLI share Core/ComInterop libraries as internal dependencies
  • Synchronized versioning prevents compatibility issues
  • Simplified release process (one tag, one workflow)
  • Users can install either or both with matching versions

2. VS Code Extension Releases (vscode-v* tags)

Workflow: .github/workflows/release-vscode-extension.yml Trigger: Tags starting with vscode-v (e.g., vscode-v1.0.0)

Features:

  • Builds and packages VS Code extension
  • Creates VSIX package for VS Code Marketplace
  • Focused on VS Code integration
  • No NuGet publishing (VSIX distribution only)

Release Artifacts:

  • excel-mcp-{version}.vsix - VS Code Extension package
  • Installation guide for VS Code extension
  • Extension marketplace listing updates

Use Cases:

  • VS Code integration for Excel development
  • MCP server management within VS Code
  • Developer experience improvements
  • One-click MCP server configuration

Version Management

Versioning Strategy

Unified Packages:

  • MCP Server & CLI: Always released together with same version number (e.g., v1.2.0)
  • Single tag triggers both NuGet packages
  • Ensures compatibility between MCP Server and CLI
  • Core and ComInterop are internal dependencies (not separately released to NuGet)

Independent Package:

  • VS Code Extension: Independent version numbers (e.g., vscode-v1.0.5)

Development Strategy

  • Core & ComInterop: Internal libraries, not separately published to NuGet
  • MCP Server & CLI: Consumer-facing packages, always co-released
    • MCP Server: AI integration features, conversational interfaces
    • CLI: Direct automation, command completeness, CI/CD integration
  • VS Code Extension: Focus on developer experience, VS Code integration, MCP management

Release Process Examples

Releasing MCP Server & CLI Together (Standard)

# MCP Server and CLI are always released together

# Create and push unified release tag
git tag v1.2.0
git push origin v1.2.0

# This triggers release-mcp-server.yml which:
# - Builds both MCP Server and CLI
# - Publishes both to NuGet using OIDC trusted publishing
# - Creates GitHub release with both ZIP packages
# - Unified release notes covering both packages

Releasing VS Code Extension Only

# Create and push VS Code extension release tag
git tag vscode-v1.0.5
git push origin vscode-v1.0.5

# This triggers release-vscode-extension.yml which:
# - Builds VS Code extension
# - Creates VSIX package
# - Creates GitHub release with extension installation docs

Documentation Strategy

Separate Focus Areas

  • Main README.md: MCP Server focused (AI assistant integration)
  • src/ExcelMcp.CLI/README.md: CLI focused (direct automation)
  • vscode-extension/README.md: VS Code Extension focused (developer experience)
  • Release Notes: Unified for MCP Server + CLI, separate for VS Code Extension

Cross-References

  • Each tool's documentation references the others
  • Clear navigation between MCP, CLI, and VS Code Extension docs
  • Unified project branding while maintaining component clarity

Benefits of This Approach

  1. Unified Releases: MCP Server and CLI always compatible (same version)
  2. Simplified Process: One tag triggers both packages
  3. Reduced Complexity: No need to coordinate separate Core/ComInterop releases
  4. Focused Documentation: Release notes match user intent
  5. Clear Separation: MCP for AI workflows, CLI for automation, VS Code for IDE
  6. Flexibility: VS Code Extension evolves independently
  7. NuGet Ecosystem: Both tools available via NuGet package manager

Tag Patterns

  • v*: MCP Server and CLI together (unified release)
  • vscode-v*: VS Code Extension only (VSIX)

This approach provides simplified release management while maintaining the integrated ExcelMcp ecosystem.

Reference in New Issue View Git Blame Copy Permalink