mirror of https://github.com/sbroenne/mcp-server-excel.git synced 2026-09-19 07:53:08 +08:00

Files

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

14 KiB

Raw Permalink Blame History

NuGet Publishing Guide for ExcelMcp

Complete guide for publishing and managing all ExcelMcp NuGet packages using OIDC Trusted Publishing.

Published Packages
NuGet Trusted Publishing Overview
Initial Setup
Release Process
Version Numbering Strategy
Package Testing
Troubleshooting
Security & Maintenance

Published Packages

ExcelMcp publishes two NuGet packages (unified release):

1. Sbroenne.ExcelMcp.McpServer (.NET Tool)

Package Type: .NET Global Tool (executable)
Purpose: MCP server for AI assistant integration
Tag Pattern: v* (e.g., v1.2.0) - unified with CLI
Workflow: .github/workflows/release-mcp-server.yml (handles both packages)
NuGet Page: https://www.nuget.org/packages/Sbroenne.ExcelMcp.McpServer
Installation: dotnet tool install --global Sbroenne.ExcelMcp.McpServer

2. Sbroenne.ExcelMcp.CLI (.NET Tool)

Package Type: .NET Global Tool (executable)
Purpose: Command-line interface for Excel automation
Tag Pattern: v* (e.g., v1.2.0) - unified with MCP Server
Workflow: .github/workflows/release-mcp-server.yml (handles both packages)
NuGet Page: https://www.nuget.org/packages/Sbroenne.ExcelMcp.CLI
Installation: dotnet tool install --global Sbroenne.ExcelMcp.CLI

Note: MCP Server and CLI are always released together with the same version number. Core and ComInterop libraries are internal dependencies and not separately published to NuGet.

NuGet Trusted Publishing Overview

All packages use NuGet Trusted Publishing via OpenID Connect (OIDC) for secure, automated package publishing without API keys.

What is Trusted Publishing?

Trusted Publishing uses short-lived OIDC tokens instead of long-lived API keys for authentication with NuGet.org.

Benefits

✅ More Secure: No long-lived API keys to manage or store
✅ Zero Maintenance: No API key rotation needed
✅ Auditable: All publishes tied to specific GitHub workflows
✅ Best Practice: Recommended by NuGet.org and Microsoft

How It Works

1. Git Tag Pushed (e.g., v1.2.2)
   ↓
2. GitHub Actions Workflow Triggered (release-mcp-server.yml)
   └─> Generates OIDC token with claims:
       • Repository: sbroenne/mcp-server-excel
       • Workflow: release-mcp-server.yml
       • Actor: (whoever triggered)
   ↓
3. NuGet Login Action Exchanges OIDC Token
   └─> Receives short-lived API key
   ↓
4. .NET CLI Publishes Both Packages
   └─> Uses short-lived API key
   └─> Publishes MCP Server
   └─> Publishes CLI
   ↓
5. NuGet.org Validates Token
   └─> Checks against trusted publisher configuration
   ↓
6. Packages Published ✅
   └─> Available at nuget.org/packages/[PackageId]

Initial Setup

Step 1: Configure GitHub Secret

Add your NuGet.org username as a repository secret (one-time setup):

Go to Repository Settings
- Navigate to: https://github.com/sbroenne/mcp-server-excel/settings/secrets/actions
- Or: Repository → Settings → Secrets and variables → Actions
Add Repository Secret
- Click "New repository secret"
- Name: NUGET_USER
- Secret: Your NuGet.org username (profile name, NOT email)
- Click "Add secret"

Step 2: First-Time Package Publishing

Trusted publishing requires packages to exist on NuGet.org before configuration.

Option A: Manual Publishing (Recommended)

# Build the package
dotnet pack src/ExcelMcp.ComInterop/ExcelMcp.ComInterop.csproj -c Release -o ./nupkg

# Publish using your NuGet API key (first time only)
dotnet nuget push ./nupkg/Sbroenne.ExcelMcp.ComInterop.1.0.0.nupkg \
  --api-key YOUR_API_KEY \
  --source https://api.nuget.org/v3/index.json

Option B: Temporary Workflow API Key

Add NUGET_API_KEY as repository secret temporarily
Modify workflow to use API key for first release
Create and publish release
Configure trusted publisher (Step 3)
Remove API key and restore OIDC authentication

Step 3: Configure Trusted Publishers on NuGet.org

For each package, configure a trusted publisher:

ComInterop Library

Go to: https://www.nuget.org/packages/Sbroenne.ExcelMcp.ComInterop/manage
Click "Trusted Publishers" tab → "Add Trusted Publisher"
Select "GitHub Actions"
Enter:
- Owner: sbroenne
- Repository: mcp-server-excel
- Workflow: release-cominterop.yml
- Environment: (leave empty)
Click "Add"

Step 4: Verify Configuration

After configuration:

Create a test release tag
Watch GitHub Actions workflow run
Verify package publishes without API keys
Check package appears on NuGet.org

Release Process

Publishing Order (Important!)

Core, MCP Server, and CLI are typically released together since MCP Server and CLI are wrappers around Core.

1. ComInterop (if updated - foundation layer)
   ↓ Wait 5-10 minutes for NuGet indexing
   
2. Core (if updated)
   ↓ Wait 5-10 minutes for NuGet indexing
   
3. MCP Server + CLI (released together with same version as Core)

Standard Release Commands

# 1. Ensure main branch is up to date
git checkout main
git pull

# 2. Release ComInterop (if updated)
git tag cominterop-v1.1.0
git push origin cominterop-v1.1.0
# Wait 5-10 minutes for NuGet indexing

# 3. Release Core (if updated)
git tag core-v1.1.0
git push origin core-v1.1.0
# Wait 5-10 minutes for NuGet indexing

# 4. Release MCP Server and CLI together (aligned versions)
git tag mcp-v1.1.0
git push origin mcp-v1.1.0

git tag cli-v1.1.0
git push origin cli-v1.1.0

# 5. Monitor workflows
# - Go to: https://github.com/sbroenne/mcp-server-excel/actions
# - Watch release workflows run
# - Verify NuGet publishing succeeds
# - Verify GitHub releases created

# 6. Verify packages on NuGet.org (wait 5-10 minutes for indexing)
# - Check package pages for new versions
# - Test installation

Quick Release (Patch Version with Synced Numbers)

# Create and push both tags at once
git tag mcp-v1.2.2 -m "Release MCP Server v1.2.2"
git tag vscode-v1.2.2 -m "Release VS Code Extension v1.2.2"
git push origin mcp-v1.2.2 vscode-v1.2.2

Version Numbering Strategy

All packages follow Semantic Versioning (SemVer):

MAJOR (1.x.x): Breaking API changes
MINOR (x.1.x): New features, backward compatible
PATCH (x.x.1): Bug fixes, backward compatible

Version Alignment Strategy

Core, MCP Server, and CLI use aligned versions:

When Core updates to v1.2.0, both MCP Server and CLI should be v1.2.0
These packages are tightly coupled - MCP/CLI are wrappers around Core

ComInterop has independent versioning:

ComInterop can have different versions (e.g., ComInterop v1.1.0, Core v1.2.0)
Update independently when only COM interop layer changes

Example version progression:

Release 1: cominterop-v1.0.0, core-v1.0.0, mcp-v1.0.0, cli-v1.0.0
Release 2: cominterop-v1.0.0, core-v1.1.0, mcp-v1.1.0, cli-v1.1.0  (Core + wrappers)
Release 3: cominterop-v1.1.0, core-v1.1.0, mcp-v1.1.0, cli-v1.1.0  (Only ComInterop)
Release 4: cominterop-v1.1.0, core-v1.2.0, mcp-v1.2.0, cli-v1.2.0  (Core + wrappers)

Package Testing

Build Packages Locally

# Build all packages
dotnet pack src/ExcelMcp.ComInterop/ExcelMcp.ComInterop.csproj -c Release -o ./nupkg
dotnet pack src/ExcelMcp.Core/ExcelMcp.Core.csproj -c Release -o ./nupkg
dotnet pack src/ExcelMcp.McpServer/ExcelMcp.McpServer.csproj -c Release -o ./nupkg
dotnet pack src/ExcelMcp.CLI/ExcelMcp.CLI.csproj -c Release -o ./nupkg

Test Local Installation

# Install .NET tool from local package
dotnet tool install --global Sbroenne.ExcelMcp.CLI --add-source ./nupkg --version 1.0.0

# Test the tool
excelcli --help

# Uninstall
dotnet tool uninstall --global Sbroenne.ExcelMcp.CLI

Validate Package Contents

# Extract package (NuGet packages are ZIP files)
unzip -l ./nupkg/Sbroenne.ExcelMcp.Core.1.0.0.nupkg

# Verify:
# - README.md is included
# - LICENSE is included
# - DLLs are present
# - Dependencies are correct in .nuspec

Troubleshooting

Package Not Appearing on NuGet.org

Wait Time: NuGet.org indexing takes 5-10 minutes after publishing.

Check Workflow Logs:

Go to: https://github.com/sbroenne/mcp-server-excel/actions
Find the release workflow run
Check "Publish to NuGet.org" step for errors

Trusted Publishing Authentication Failed

Cause: Trusted publisher not configured or misconfigured

Solution:

Verify package exists on NuGet.org
Check trusted publisher configuration matches exactly:
- Owner: sbroenne
- Repository: mcp-server-excel
- Workflow: release-[package].yml (exact filename)
Ensure NUGET_USER secret is set correctly
Verify workflow has id-token: write permission

Error: "Package does not exist"

Cause: Package not yet published to NuGet.org

Solution: Complete Step 2 (First-Time Package Publishing) using an API key

Error: "Workflow is not trusted"

Cause: Workflow filename in trusted publisher config doesn't match

Solution:

Check exact workflow filename in .github/workflows/
Update trusted publisher configuration if needed
Configuration is case-sensitive

Dependency Version Mismatch

Cause: Dependent package references outdated version

Solution:

Release ComInterop first
Wait 5-10 minutes for NuGet indexing
Release Core (references latest ComInterop)
Wait for indexing
Release MCP Server/CLI (reference latest Core)

Package Validation Errors

All packages have EnablePackageValidation=true which catches issues during build.

Common Issues:

Missing README or LICENSE
Incorrect package metadata
Missing dependencies

Solution: Check build output for validation warnings/errors

Security & Maintenance

Security Benefits of Trusted Publishing

vs. Traditional API Keys:

Aspect	Trusted Publishing	API Key
Security	✅ Short-lived tokens (minutes)	❌ Long-lived secrets (up to 1 year)
Maintenance	✅ Zero maintenance	❌ Annual rotation required
Setup	⚠️ Requires initial package	✅ Works immediately
Audit	✅ Full workflow traceability	⚠️ Limited to API key usage
Best Practice	✅ Microsoft/NuGet recommended	❌ Legacy approach
Storage	✅ No stored secrets	❌ Stored in GitHub secrets
Leak Risk	✅ Expires in minutes	❌ Valid until revoked

OIDC Token Claims

The OIDC token includes validated claims:

repository: Must match configured repository
workflow: Must match configured workflow file
actor: GitHub user who triggered workflow
ref: Git reference (branch/tag)
repository_owner: Must match configured owner

If any claim doesn't match trusted publisher configuration, authentication fails.

Zero Maintenance Required

Once configured:

✅ No API keys to rotate
✅ No secrets to update
✅ No expiration dates to track
✅ Automatic authentication on every release

Updating Configuration

If you rename a workflow file:

Update workflow file in repository
Go to NuGet.org package management
Remove old trusted publisher
Add new trusted publisher with updated workflow name

Monitoring Releases

GitHub Actions

Workflow Runs: https://github.com/sbroenne/mcp-server-excel/actions
Each release workflow creates:
- NuGet package upload
- GitHub release with notes
- Binary assets (for MCP Server and CLI)

NuGet.org Package Pages

ComInterop: https://www.nuget.org/packages/Sbroenne.ExcelMcp.ComInterop
Core: https://www.nuget.org/packages/Sbroenne.ExcelMcp.Core
MCP Server: https://www.nuget.org/packages/Sbroenne.ExcelMcp.McpServer
CLI: https://www.nuget.org/packages/Sbroenne.ExcelMcp.CLI

Download Statistics

Monitor package adoption via NuGet.org statistics pages (linked above).

References

Support

For issues with NuGet publishing:

Check this guide's troubleshooting section
Review GitHub Actions workflow logs
Verify NuGet.org trusted publisher configuration
Open an issue at: https://github.com/sbroenne/mcp-server-excel/issues

Status: ✅ All packages configured for trusted publishing
Workflows: Release workflows ready for all four packages
Security: OIDC trusted publishing eliminates API key management

14 KiB Raw Permalink Blame History

NuGet Publishing Guide for ExcelMcp

Table of Contents

Published Packages

1. Sbroenne.ExcelMcp.McpServer (.NET Tool)

2. Sbroenne.ExcelMcp.CLI (.NET Tool)

NuGet Trusted Publishing Overview

What is Trusted Publishing?

Benefits

How It Works

Initial Setup

Step 1: Configure GitHub Secret

Step 2: First-Time Package Publishing

Step 3: Configure Trusted Publishers on NuGet.org

ComInterop Library

Core Library

MCP Server

CLI Tool

Step 4: Verify Configuration

Release Process

Publishing Order (Important!)

Standard Release Commands

Quick Release (Patch Version with Synced Numbers)

Version Numbering Strategy

Version Alignment Strategy

Package Testing

Build Packages Locally

Test Local Installation

Validate Package Contents

Troubleshooting

Package Not Appearing on NuGet.org

Trusted Publishing Authentication Failed

Error: "Package does not exist"

Error: "Workflow is not trusted"

Dependency Version Mismatch

Package Validation Errors

Security & Maintenance

Security Benefits of Trusted Publishing

OIDC Token Claims

Zero Maintenance Required

Updating Configuration

Monitoring Releases

GitHub Actions

NuGet.org Package Pages

Download Statistics

References

Support

14 KiB

Raw Permalink Blame History