diff --git a/.github/BRANCH_PROTECTION.md b/.github/BRANCH_PROTECTION.md deleted file mode 100644 index 067a40ca..00000000 --- a/.github/BRANCH_PROTECTION.md +++ /dev/null @@ -1,346 +0,0 @@ -# Branch Protection Configuration Guide - -This document provides step-by-step instructions for setting up branch protection rules for the ExcelMcp repository to ensure code quality, security, and proper PR-based workflow. - -## Prerequisites - -- Repository administrator access -- GitHub Pro, Team, or Enterprise account (for some advanced features) - -## Main Branch Protection Rules - -### Step 1: Navigate to Branch Protection Settings - -1. Go to your repository on GitHub -2. Click **Settings** (gear icon) -3. Click **Branches** in the left sidebar -4. Click **Add branch protection rule** -5. Enter `main` as the branch name pattern - -### Step 2: Configure Protection Rules - -Apply the following settings for the `main` branch: - -#### ✅ Require Pull Request Reviews Before Merging - -**Enable:** ✓ Require a pull request before merging - -**Settings:** -- ✓ Require approvals: **1** (minimum) -- ✓ Dismiss stale pull request approvals when new commits are pushed -- ✓ Require review from Code Owners (optional - requires CODEOWNERS file) -- ✓ Require approval of the most recent reviewable push - -**Purpose:** Ensures all code is reviewed before merging, catching issues early. - -#### ✅ Require Status Checks to Pass Before Merging - -**Enable:** ✓ Require status checks to pass before merging - -**Settings:** -- ✓ Require branches to be up to date before merging -- **Required status checks** (add these): - - `build` - Build workflow must pass - - `analyze / Analyze Code with CodeQL` - CodeQL security scan must pass - - `dependency-review` - Dependency review must pass - -**Purpose:** Ensures code builds successfully and passes security scans before merging. - -**Note:** Status checks will only appear after they've run at least once. Create a test PR to see them populate. - -#### ✅ Require Conversation Resolution Before Merging - -**Enable:** ✓ Require conversation resolution before merging - -**Purpose:** Ensures all review comments are addressed before merging. - -#### ✅ Require Signed Commits (Recommended) - -**Enable:** ✓ Require signed commits - -**Purpose:** Ensures all commits are cryptographically verified (GPG/SSH signature). - -**Setup Guide:** https://docs.github.com/en/authentication/managing-commit-signature-verification - -#### ✅ Require Linear History (Optional) - -**Enable:** ✓ Require linear history - -**Purpose:** Prevents merge commits, keeps history clean with rebase/squash only. - -**Note:** This may conflict with some workflows. Enable based on team preference. - -#### ✅ Include Administrators - -**Disable:** ☐ Do not allow bypassing the above settings (even for admins) - -**Purpose:** Enforces rules for everyone, including repository administrators. - -**Recommendation:** Enable this for maximum security, disable if you need emergency access. - -#### ✅ Restrict Who Can Push to Matching Branches - -**Enable:** ✓ Restrict pushes that create matching branches - -**Settings:** -- Add specific users or teams who can push (usually just CI/CD service accounts) -- Most developers should only merge through PRs - -**Purpose:** Prevents direct pushes to main branch. - -#### ✅ Allow Force Pushes - -**Disable:** ☐ Allow force pushes (keep unchecked) - -**Purpose:** Prevents history rewriting on main branch. - -#### ✅ Allow Deletions - -**Disable:** ☐ Allow deletions (keep unchecked) - -**Purpose:** Prevents accidental deletion of main branch. - -### Step 3: Save Protection Rules - -Click **Create** or **Save changes** at the bottom of the page. - -## Develop Branch Protection Rules (Optional) - -For the `develop` branch, you can use slightly relaxed rules: - -1. Create another branch protection rule for `develop` -2. Apply similar settings but with: - - Require approvals: **1** (same as main) - - All status checks required (same as main) - - Optional: Disable "Require branches to be up to date" for faster iteration - - Optional: Allow force pushes (for rebasing feature branches) - -## Feature Branch Naming Convention - -Recommended branch naming patterns: -- `feature/*` - New features -- `bugfix/*` - Bug fixes -- `hotfix/*` - Critical production fixes -- `release/*` - Release preparation -- `copilot/*` - AI-generated changes (current pattern) - -## PR Workflow with Branch Protection - -### For Contributors - -1. **Create Feature Branch** - ```bash - git checkout -b feature/my-feature - ``` - -2. **Make Changes and Commit** - ```bash - git add . - git commit -m "feat: add new feature" - git push origin feature/my-feature - ``` - -3. **Create Pull Request** - - Go to GitHub and create PR from your branch to `main` - - Fill out PR template - - Request review from team members - -4. **Address Review Comments** - - Make requested changes - - Push new commits to the same branch - - Mark conversations as resolved - -5. **Wait for Status Checks** - - Build must pass - - CodeQL must pass - - Dependency review must pass (if dependencies changed) - -6. **Merge PR** - - Once approved and all checks pass, merge using: - - **Squash and merge** (recommended - keeps history clean) - - **Rebase and merge** (if linear history required) - - **Create a merge commit** (preserves feature branch history) - -### For Reviewers - -1. **Review Code Changes** - - Check code quality and logic - - Verify tests are included - - Check for security issues - -2. **Check Status Checks** - - Ensure all automated checks pass - - Review CodeQL findings if any - -3. **Approve or Request Changes** - - Use GitHub's review feature - - Provide constructive feedback - - Request changes if needed - -4. **Merge After Approval** - - Wait for all required approvals - - Ensure conversations are resolved - - Merge using preferred method - -## Automation with GitHub Actions - -With branch protection enabled, the CI/CD pipeline works as follows: - -### On Pull Request - -1. **Build Workflow** (`build.yml`) - - Triggers on: PR to main with code changes - - Runs: Build and verification - - Output: Build artifacts - - Duration: ~2-3 minutes - -2. **CodeQL Analysis** (`codeql.yml`) - - Triggers on: PR to main with code changes - - Runs: Security code scanning - - Output: Security findings - - Duration: ~5-10 minutes - -3. **Dependency Review** (`dependency-review.yml`) - - Triggers on: PR to main (always) - - Runs: Vulnerability and license checking - - Output: Dependency analysis - - Duration: ~1 minute - -### On Push to Main - -1. **Build Workflow** - - Builds and uploads artifacts - - Validates deployment readiness - -2. **CodeQL Analysis** - - Runs full security scan - - Updates security dashboard - -3. **Dependabot** - - Monitors for new vulnerabilities - - Creates PRs for updates - -### Weekly Schedule - -1. **CodeQL** (Monday 10 AM UTC) - - Full security scan - - Updates security posture - -2. **Dependabot** (Monday 9 AM EST) - - Checks for dependency updates - - Creates update PRs - -## Path Filters for Efficient CI/CD - -The workflows are now optimized to only run when relevant files change: - -### Build-Relevant Changes -```yaml -paths: - - 'src/**' # Source code - - 'tests/**' # Test code - - '**.csproj' # Project files - - '**.sln' # Solution files - - 'Directory.Build.props' # Build configuration - - 'Directory.Packages.props' # Package versions - - '.github/workflows/build.yml' # Build workflow itself -``` - -### Non-Build Changes (workflows skip) -- `README.md` and other documentation -- `docs/**` directory -- `.github/ISSUE_TEMPLATE/**` -- `SECURITY.md` -- License files - -**Benefit:** Saves CI/CD minutes and provides faster feedback on documentation-only changes. - -## Troubleshooting - -### Problem: Required Status Checks Not Appearing - -**Solution:** -1. Create a test PR -2. Let workflows run at least once -3. Return to branch protection settings -4. Status checks should now be selectable - -### Problem: PR Cannot Be Merged Due to Outdated Branch - -**Solution:** -```bash -git checkout feature/my-feature -git pull origin main -git push origin feature/my-feature -``` - -Or use GitHub's "Update branch" button on the PR. - -### Problem: Status Check Failing - -**Solution:** -1. Review the workflow logs on GitHub Actions tab -2. Fix the issue in your branch -3. Push the fix - checks will re-run automatically - -### Problem: Cannot Force Push to Fix History - -**Solution:** -This is intentional! Branch protection prevents force pushes to main. Instead: -1. Create a new commit with the fix -2. Or create a revert commit: `git revert ` - -### Problem: Need to Merge Urgently - -**Solution for Emergencies:** -1. Temporarily disable branch protection (admin only) -2. Make the critical change -3. Re-enable branch protection immediately -4. Document the reason in commit message - -## Security Considerations - -### Principle of Least Privilege -- Only grant repository admin access to team leads -- Most contributors should only have write access -- Use CODEOWNERS for sensitive files - -### Audit Trail -- All changes require PR approval -- Signed commits provide verification -- GitHub maintains audit log of all actions - -### Automated Security -- Dependabot alerts for vulnerabilities -- CodeQL scans for security issues -- Dependency review blocks risky dependencies - -## Monitoring and Maintenance - -### Weekly Tasks -1. Review Dependabot PRs -2. Check CodeQL findings -3. Review open PRs for stale reviews - -### Monthly Tasks -1. Review branch protection rules -2. Update required status checks if workflows change -3. Audit team access levels - -### Quarterly Tasks -1. Review security incidents -2. Update security policies -3. Train team on new security features - -## Additional Resources - -- [GitHub Branch Protection Documentation](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) -- [Status Checks Documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks) -- [Signed Commits Guide](https://docs.github.com/en/authentication/managing-commit-signature-verification) -- [CODEOWNERS Documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) - ---- - -**Last Updated:** 2024-10-19 - -**Note:** These settings should be applied to the new `sbroenne/mcp-server-excel` repository once it's created. diff --git a/.github/CODEQL_SETUP_FIX.md b/.github/CODEQL_SETUP_FIX.md deleted file mode 100644 index 66be5b95..00000000 --- a/.github/CODEQL_SETUP_FIX.md +++ /dev/null @@ -1,86 +0,0 @@ -# CodeQL Setup Issue - Quick Fix - -## Error Message -``` -Code Scanning could not process the submitted SARIF file: -CodeQL analyses from advanced configurations cannot be processed when the default setup is enabled -``` - -## Problem -The repository has **both** GitHub's automatic default CodeQL setup **and** a custom advanced CodeQL workflow. GitHub only allows one at a time. - -## Quick Fix (Choose One) - -### Option 1: Use Advanced Setup (Recommended) - -This keeps the custom configuration with COM interop exceptions and path filters. - -**Steps:** -1. Go to **Settings** → **Code security and analysis** -2. Find **"Code scanning"** section -3. Look for **"CodeQL analysis"** -4. If it shows **"Default"**: - - Click the **"..."** (three dots) menu - - Select **"Switch to advanced"** -5. If prompted, **do not create a new workflow** (we already have one) -6. Done! GitHub will now use `.github/workflows/codeql.yml` - -**Benefits:** -- ✅ Custom COM interop false positive filters -- ✅ Path filters (only scans code changes, not docs) -- ✅ Custom query suites (security-extended) -- ✅ Windows runner for proper .NET build - -### Option 2: Use Default Setup (Simpler) - -GitHub manages everything, but you lose customization. - -**Steps:** -1. Delete the custom workflow files: - ```bash - git rm .github/workflows/codeql.yml - git rm -r .github/codeql/ - git commit -m "Remove custom CodeQL config for default setup" - git push - ``` -2. Go to **Settings** → **Code security and analysis** -3. Click **"Set up"** for CodeQL analysis -4. Choose **"Default"** - -**Trade-offs:** -- ❌ No custom exclusions for COM interop -- ❌ Scans on all file changes (including docs) -- ✅ Zero maintenance required -- ✅ Automatic updates from GitHub - -## Verification - -After switching to advanced: -1. Push a code change or trigger the workflow manually -2. Go to **Actions** tab -3. You should see **"CodeQL Advanced Security"** workflow running -4. No more SARIF processing errors - -## Why This Happens - -GitHub's default CodeQL setup (enabled through Settings) conflicts with custom workflows that use: -- `github/codeql-action/init@v3` with `config-file` -- Custom query packs -- Advanced configuration options - -You must choose **one approach** - either fully automated (default) or fully customized (advanced). - -## Recommended Choice - -For **ExcelMcp/mcp-server-excel**: Use **Advanced Setup (Option 1)** - -**Reasons:** -1. COM interop requires specific exclusions (weak crypto, unmanaged code) -2. Path filters save CI minutes (docs don't need code scanning) -3. Windows runner needed for proper .NET/Excel build -4. Custom query suites provide better coverage - -## Need Help? - -- See `.github/SECURITY_SETUP.md` for detailed security configuration guide -- Check GitHub's [CodeQL documentation](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning) diff --git a/.github/SECURITY_SETUP.md b/.github/SECURITY_SETUP.md deleted file mode 100644 index bcd026bd..00000000 --- a/.github/SECURITY_SETUP.md +++ /dev/null @@ -1,353 +0,0 @@ -# GitHub Advanced Security Setup Guide - -This document describes the security features enabled for the ExcelMcp project. - -## Enabled Security Features - -### 1. Dependabot - -### 0. CodeQL Configuration (Important - Read First!) - -**IMPORTANT:** This repository includes an advanced CodeQL workflow configuration. You must choose between: - -#### Option A: Use Advanced CodeQL Workflow (Recommended for this project) -This provides custom configuration with COM interop exceptions and path filters. - -**Setup Steps:** -1. Go to Settings → Code security and analysis -2. If "CodeQL analysis" shows "Set up" → Click it and choose "Advanced" -3. If "CodeQL analysis" shows "Default" → Click "..." → "Switch to advanced" -4. Delete the auto-generated `.github/workflows/codeql-analysis.yml` if created -5. Keep our custom `.github/workflows/codeql.yml` -6. The custom config `.github/codeql/codeql-config.yml` will be used automatically - -**Why Advanced?** -- Custom path filters (only scans code changes, not docs) -- COM interop false positive exclusions -- Custom query suites (security-and-quality + security-extended) -- Windows runner for proper .NET/Excel COM build - -#### Option B: Use Default Setup (Simpler but less customized) -GitHub manages everything automatically, but you lose custom configuration. - -**Setup Steps:** -1. Delete `.github/workflows/codeql.yml` -2. Delete `.github/codeql/codeql-config.yml` -3. Go to Settings → Code security and analysis -4. Click "Set up" for CodeQL analysis → Choose "Default" - -**Trade-offs:** -- ❌ No custom COM interop exclusions -- ❌ No path filters (scans on all changes) -- ❌ Cannot customize query suites -- ✅ Fully automated by GitHub -- ✅ No workflow maintenance - -**Current Error Fix:** -If you see: `CodeQL analyses from advanced configurations cannot be processed when the default setup is enabled` - -**Solution:** Follow Option A steps above to switch from default to advanced setup. - -### 1. Dependabot -**Configuration**: `.github/dependabot.yml` - -Automatically monitors and updates dependencies: -- **NuGet packages**: Weekly updates on Mondays -- **GitHub Actions**: Weekly updates on Mondays -- **Security alerts**: Immediate notifications for vulnerabilities - -**Features**: -- Grouped updates for minor/patch versions -- Automatic PR creation for security updates -- License compliance checking -- Vulnerability scanning - -**To enable** (Repository Admin only): -1. Go to Settings → Code security and analysis -2. Enable "Dependabot alerts" -3. Enable "Dependabot security updates" -4. Enable "Dependabot version updates" - -### 2. CodeQL Analysis -**Configuration**: `.github/workflows/codeql.yml` and `.github/codeql/codeql-config.yml` - -Performs advanced security code scanning: -- **Languages**: C# -- **Schedule**: Weekly on Mondays + every push/PR -- **Query suites**: security-and-quality, security-extended -- **ML-powered**: Advanced vulnerability detection - -**Security Checks**: -- SQL injection (CA2100) -- Path traversal (CA3003) -- Command injection (CA3006) -- Cryptographic issues (CA5389, CA5390, CA5394) -- Input validation -- Resource management -- Sensitive data exposure - -**To enable** (Repository Admin only): -1. Go to Settings → Code security and analysis -2. Enable "Code scanning" -3. Click "Set up" → "Advanced" -4. The workflow file is already configured - -### 3. Dependency Review -**Configuration**: `.github/workflows/dependency-review.yml` - -Reviews pull requests for: -- Vulnerable dependencies -- License compliance issues -- Breaking changes in dependencies - -**Blocks PRs with**: -- Moderate or higher severity vulnerabilities -- GPL/AGPL/LGPL licenses -- Malicious packages - -**To enable**: -Automatically runs on all pull requests to main/develop branches. - -### 4. Secret Scanning -**Built-in GitHub feature** - -Scans for accidentally committed secrets: -- API keys -- Tokens -- Passwords -- Private keys -- Database connection strings - -**To enable** (Repository Admin only): -1. Go to Settings → Code security and analysis -2. Enable "Secret scanning" -3. Enable "Push protection" (prevents commits with secrets) - -### 5. Security Policy -**Configuration**: `SECURITY.md` - -Provides: -- Supported versions -- Vulnerability reporting process -- Security best practices -- Disclosure policy - -### 6. Branch Protection Rules - -**Recommended settings for `main` branch**: - -1. **Require pull request reviews** - - At least 1 approval required - - Dismiss stale reviews when new commits pushed - -2. **Require status checks** - - Build must pass - - CodeQL analysis must pass - - Dependency review must pass - - Unit tests must pass - -3. **Require conversation resolution** - - All review comments must be resolved - -4. **Require signed commits** (optional but recommended) - - GPG/SSH signature verification - -5. **Restrict pushes** - - Only allow admins to bypass - -**To configure**: -1. Go to Settings → Branches -2. Add rule for `main` branch -3. Configure protection options - -## Security Scanning Results - -### Viewing Results - -**CodeQL Alerts**: -- Go to Security → Code scanning alerts -- Filter by severity, status, tool -- View detailed findings with remediation guidance - -**Dependabot Alerts**: -- Go to Security → Dependabot alerts -- Review vulnerable dependencies -- Auto-generate PRs to fix - -**Secret Scanning Alerts**: -- Go to Security → Secret scanning alerts -- Review detected secrets -- Revoke and rotate compromised credentials - -### Responding to Alerts - -1. **Critical/High Severity**: - - Review immediately - - Create private security advisory if needed - - Fix within 7 days - - Release patch version - -2. **Medium Severity**: - - Review within 30 days - - Fix in next minor release - - Document in release notes - -3. **Low Severity**: - - Review as time permits - - Consider for future releases - - May be accepted as risk - -## Security Workflows - -### Weekly Security Review -Every Monday: -1. Dependabot creates update PRs -2. CodeQL runs full analysis -3. Review new security alerts -4. Merge approved updates - -### Pull Request Security -On every PR: -1. CodeQL scans changed code -2. Dependency review checks new dependencies -3. Build must pass with zero warnings -4. Unit tests must pass -5. At least 1 review required - -### Release Security -Before each release: -1. Review all open security alerts -2. Run full test suite -3. Update SECURITY.md with changes -4. Create security advisory if needed - -## Best Practices - -### For Contributors - -1. **Never commit secrets**: - - Use environment variables - - Use .gitignore for sensitive files - - Use push protection - -2. **Keep dependencies updated**: - - Review Dependabot PRs promptly - - Test updates thoroughly - - Merge security updates quickly - -3. **Write secure code**: - - Validate all inputs - - Use parameterized queries - - Avoid hard-coded credentials - - Follow OWASP guidelines - -4. **Review security alerts**: - - Check CodeQL findings - - Understand the vulnerability - - Test the fix - - Document the remediation - -### For Maintainers - -1. **Enable all security features**: - - Dependabot alerts and updates - - CodeQL scanning - - Secret scanning with push protection - - Dependency review - -2. **Configure branch protection**: - - Require reviews - - Require status checks - - Restrict pushes to main - -3. **Respond to security issues**: - - Acknowledge within 48 hours - - Create security advisory - - Develop fix privately - - Coordinate disclosure - -4. **Monitor security posture**: - - Review Security tab weekly - - Update security policy - - Train contributors - - Audit access regularly - -## Troubleshooting - -### CodeQL Configuration Conflict - -**Error:** `CodeQL analyses from advanced configurations cannot be processed when the default setup is enabled` - -**Cause:** The repository has GitHub's default CodeQL setup enabled, which conflicts with the custom advanced workflow. - -**Solution:** -1. Go to Settings → Code security and analysis -2. Find "Code scanning" section -3. Look for "CodeQL analysis" -4. If it shows "Default" with a gear icon: - - Click the "..." menu - - Select "Switch to advanced" -5. If prompted to create a workflow: - - Don't create a new one (we already have `.github/workflows/codeql.yml`) - - Close the dialog -6. GitHub will now use the advanced configuration from `.github/workflows/codeql.yml` -7. The custom config `.github/codeql/codeql-config.yml` will be applied automatically - -**Alternative:** If you prefer default setup, delete the custom workflows: -```bash -rm .github/workflows/codeql.yml -rm -rf .github/codeql/ -``` -Then enable default setup through Settings → Code security and analysis. - -### CodeQL False Positives - -If CodeQL reports false positives: -1. Review the finding thoroughly -2. Document why it's a false positive -3. Add exclusion to `.github/codeql/codeql-config.yml` -4. Include detailed reason - -Example: -```yaml -query-filters: - - exclude: - id: cs/specific-rule-id - reason: "Detailed explanation of why this is safe" -``` - -### Dependabot PR Conflicts - -If Dependabot PRs have conflicts: -1. Close the PR -2. Dependabot will recreate it -3. Or manually update the dependency - -### Build Failures After Updates - -If build fails after dependency update: -1. Review breaking changes in release notes -2. Update code to match new API -3. Run tests locally -4. Commit fixes to Dependabot branch - -## Resources - -- [GitHub Security Best Practices](https://docs.github.com/en/code-security/getting-started/github-security-features) -- [CodeQL Documentation](https://codeql.github.com/docs/) -- [Dependabot Documentation](https://docs.github.com/en/code-security/dependabot) -- [OWASP Top 10](https://owasp.org/www-project-top-ten/) -- [CWE Database](https://cwe.mitre.org/) - -## Support - -For security-related questions: -- Security vulnerabilities: Follow SECURITY.md -- General questions: Open a discussion -- Bug reports: Open an issue - ---- - -**Last Updated**: 2024-10-19 - -This security setup ensures ExcelMcp maintains high security standards and protects users from vulnerabilities. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index d78c70b6..9f7d2277 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,10 +1,10 @@ -# ExcelMcp - Excel Command Line Interface for Coding Agents +# excelcli - Excel Command Line Interface for Coding Agents -> **📎 Related Instructions:** For projects using ExcelMcp in other repositories, copy `docs/excel-powerquery-vba-copilot-instructions.md` to your project's `.github/copilot-instructions.md` for specialized Excel automation support. +> **📎 Related Instructions:** For projects using excelcli in other repositories, copy `docs/excel-powerquery-vba-copilot-instructions.md` to your project's `.github/copilot-instructions.md` for specialized Excel automation support. ## What is ExcelMcp? -ExcelMcp is a Windows-only command-line tool that provides programmatic access to Microsoft Excel through COM interop. It's specifically designed for coding agents and automation scripts to manipulate Excel workbooks without requiring the Excel UI. +excelcli is a Windows-only command-line tool that provides programmatic access to Microsoft Excel through COM interop. It's specifically designed for coding agents and automation scripts to manipulate Excel workbooks without requiring the Excel UI. ## Core Capabilities @@ -60,7 +60,7 @@ ExcelMcp is a Windows-only command-line tool that provides programmatic access t ## MCP Server for AI Development Workflows ✨ **NEW CAPABILITY** -ExcelMcp now includes a **Model Context Protocol (MCP) server** that transforms CLI commands into conversational development workflows for AI assistants like GitHub Copilot. +excelcli now includes a **Model Context Protocol (MCP) server** that transforms CLI commands into conversational development workflows for AI assistants like GitHub Copilot. ### Starting the MCP Server ```powershell @@ -80,7 +80,7 @@ The MCP server consolidates 40+ CLI commands into 6 resource-based tools with ac ### Development-Focused Use Cases ⚠️ **NOT for ETL!** -ExcelMcp (both MCP server and CLI) is designed for **Excel development workflows**, not data processing: +excelcli (both MCP server and CLI) is designed for **Excel development workflows**, not data processing: - **Power Query Refactoring** - AI helps optimize M code for better performance - **VBA Development & Debugging** - Add error handling, logging, and code improvements @@ -137,7 +137,7 @@ Copilot: [Uses excel_powerquery view -> analyzes for query folding issues -> pro ### Technical Requirements - **Windows Only** - Requires Excel installation (uses COM interop) -- **.NET 8.0** - Modern .NET runtime required +- **.NET 10** - Modern .NET runtime required - **Excel Installed** - Must have Microsoft Excel installed on the machine - **Command Line Access** - Designed for terminal/script usage @@ -146,31 +146,31 @@ Copilot: [Uses excel_powerquery view -> analyzes for query folding issues -> pro ### PowerShell Integration ```powershell # Create and populate a report with VBA automation -ExcelMcp setup-vba-trust # One-time setup -ExcelMcp create-empty "monthly-report.xlsm" -ExcelMcp param-set "monthly-report.xlsm" "ReportDate" "2024-01-01" -ExcelMcp pq-import "monthly-report.xlsm" "SalesData" "sales-query.pq" -ExcelMcp pq-refresh "monthly-report.xlsm" "SalesData" -ExcelMcp script-run "monthly-report.xlsm" "ReportModule.FormatReport" +excelcli setup-vba-trust # One-time setup +excelcli create-empty "monthly-report.xlsm" +excelcli param-set "monthly-report.xlsm" "ReportDate" "2024-01-01" +excelcli pq-import "monthly-report.xlsm" "SalesData" "sales-query.pq" +excelcli pq-refresh "monthly-report.xlsm" "SalesData" +excelcli script-run "monthly-report.xlsm" "ReportModule.FormatReport" ``` ### VBA Automation Workflow ```powershell # Complete VBA workflow -ExcelMcp setup-vba-trust -ExcelMcp create-empty "automation.xlsm" -ExcelMcp script-import "automation.xlsm" "DataProcessor" "processor.vba" -ExcelMcp script-run "automation.xlsm" "DataProcessor.ProcessData" "Sheet1" "A1:D100" -ExcelMcp sheet-read "automation.xlsm" "Sheet1" "A1:D10" -ExcelMcp script-export "automation.xlsm" "DataProcessor" "updated-processor.vba" +excelcli setup-vba-trust +excelcli create-empty "automation.xlsm" +excelcli script-import "automation.xlsm" "DataProcessor" "processor.vba" +excelcli script-run "automation.xlsm" "DataProcessor.ProcessData" "Sheet1" "A1:D100" +excelcli sheet-read "automation.xlsm" "Sheet1" "A1:D10" +excelcli script-export "automation.xlsm" "DataProcessor" "updated-processor.vba" ``` ### Batch Processing ```batch REM Process multiple files for %%f in (*.xlsx) do ( - ExcelMcp pq-refresh "%%f" "DataQuery" - ExcelMcp sheet-read "%%f" "Results" > "%%~nf-results.csv" + excelcli pq-refresh "%%f" "DataQuery" + excelcli sheet-read "%%f" "Results" > "%%~nf-results.csv" ) ``` @@ -196,7 +196,7 @@ for %%f in (*.xlsx) do ( 4. **VBA Automation Pipeline**: script-list → script-export → modify → script-run 5. **Bulk Processing**: sheet-list → sheet-read → processing → sheet-write -Use ExcelMcp when you need reliable, programmatic Excel automation without UI dependencies. +Use excelcli when you need reliable, programmatic Excel automation without UI dependencies. ## Architecture Patterns @@ -709,7 +709,7 @@ return args[0] switch private static void ShowHelp() { var help = @" -ExcelMcp - Excel Command Line Interface +excelcli - Excel Command Line Interface New Commands: new-operation Description of operation @@ -891,7 +891,7 @@ Critical security rules are treated as errors: - **File paths**: Use `Path.GetFullPath()` to resolve paths safely ✅ **Enhanced** - **User input**: Always use `.EscapeMarkup()` before displaying in Spectre.Console ✅ **Enforced** -- **Macros**: ExcelMcp does not execute macros (DisplayAlerts = false) +- **Macros**: excelcli does not execute macros (DisplayAlerts = false) - **Credentials**: Never log connection strings or credentials ✅ **Enhanced** - **Resource Management**: Strict COM cleanup prevents resource leaks ✅ **Verified** @@ -1012,8 +1012,8 @@ dotnet_diagnostic.CA5394.severity = error # Insecure randomness ```bash # Create empty workbook (essential for automation) -ExcelMcp create-empty "analysis.xlsx" -ExcelMcp create-empty "reports/monthly-report.xlsx" # Auto-creates directory +excelcli create-empty "analysis.xlsx" +excelcli create-empty "reports/monthly-report.xlsx" # Auto-creates directory ``` **Copilot Prompts:** @@ -1026,28 +1026,28 @@ ExcelMcp create-empty "reports/monthly-report.xlsx" # Auto-creates directory ```bash # List all Power Queries -ExcelMcp pq-list "data.xlsx" +excelcli pq-list "data.xlsx" # View Power Query M code -ExcelMcp pq-view "data.xlsx" "WebData" +excelcli pq-view "data.xlsx" "WebData" # Import M code from file -ExcelMcp pq-import "data.xlsx" "APIData" "fetch-data.pq" +excelcli pq-import "data.xlsx" "APIData" "fetch-data.pq" # Export M code to file (for version control) -ExcelMcp pq-export "data.xlsx" "APIData" "backup.pq" +excelcli pq-export "data.xlsx" "APIData" "backup.pq" # Update existing query -ExcelMcp pq-update "data.xlsx" "APIData" "new-logic.pq" +excelcli pq-update "data.xlsx" "APIData" "new-logic.pq" # Load Connection-Only query to worksheet -ExcelMcp pq-loadto "data.xlsx" "APIData" "DataSheet" +excelcli pq-loadto "data.xlsx" "APIData" "DataSheet" # Refresh query data -ExcelMcp pq-refresh "data.xlsx" "APIData" +excelcli pq-refresh "data.xlsx" "APIData" # Delete query -ExcelMcp pq-delete "data.xlsx" "OldQuery" +excelcli pq-delete "data.xlsx" "OldQuery" ``` **Copilot Prompts:** @@ -1060,31 +1060,31 @@ ExcelMcp pq-delete "data.xlsx" "OldQuery" ```bash # List all worksheets -ExcelMcp sheet-list "workbook.xlsx" +excelcli sheet-list "workbook.xlsx" # Read data from range -ExcelMcp sheet-read "workbook.xlsx" "Sheet1" "A1:D10" +excelcli sheet-read "workbook.xlsx" "Sheet1" "A1:D10" # Write CSV data to sheet -ExcelMcp sheet-write "workbook.xlsx" "Sheet1" "data.csv" +excelcli sheet-write "workbook.xlsx" "Sheet1" "data.csv" # Create new worksheet -ExcelMcp sheet-create "workbook.xlsx" "Analysis" +excelcli sheet-create "workbook.xlsx" "Analysis" # Copy worksheet -ExcelMcp sheet-copy "workbook.xlsx" "Template" "NewSheet" +excelcli sheet-copy "workbook.xlsx" "Template" "NewSheet" # Rename worksheet -ExcelMcp sheet-rename "workbook.xlsx" "Sheet1" "RawData" +excelcli sheet-rename "workbook.xlsx" "Sheet1" "RawData" # Clear worksheet data -ExcelMcp sheet-clear "workbook.xlsx" "Sheet1" "A1:Z100" +excelcli sheet-clear "workbook.xlsx" "Sheet1" "A1:Z100" # Append data to existing content -ExcelMcp sheet-append "workbook.xlsx" "Sheet1" "additional-data.csv" +excelcli sheet-append "workbook.xlsx" "Sheet1" "additional-data.csv" # Delete worksheet -ExcelMcp sheet-delete "workbook.xlsx" "TempSheet" +excelcli sheet-delete "workbook.xlsx" "TempSheet" ``` **Copilot Prompts:** @@ -1097,19 +1097,19 @@ ExcelMcp sheet-delete "workbook.xlsx" "TempSheet" ```bash # List all named ranges -ExcelMcp param-list "config.xlsx" +excelcli param-list "config.xlsx" # Get parameter value -ExcelMcp param-get "config.xlsx" "StartDate" +excelcli param-get "config.xlsx" "StartDate" # Set parameter value -ExcelMcp param-set "config.xlsx" "StartDate" "2024-01-01" +excelcli param-set "config.xlsx" "StartDate" "2024-01-01" # Create named range -ExcelMcp param-create "config.xlsx" "FilePath" "Settings!A1" +excelcli param-create "config.xlsx" "FilePath" "Settings!A1" # Delete named range -ExcelMcp param-delete "config.xlsx" "OldParam" +excelcli param-delete "config.xlsx" "OldParam" ``` **Copilot Prompts:** @@ -1122,16 +1122,16 @@ ExcelMcp param-delete "config.xlsx" "OldParam" ```bash # Get cell value -ExcelMcp cell-get-value "data.xlsx" "Sheet1" "A1" +excelcli cell-get-value "data.xlsx" "Sheet1" "A1" # Set cell value -ExcelMcp cell-set-value "data.xlsx" "Sheet1" "A1" "Hello World" +excelcli cell-set-value "data.xlsx" "Sheet1" "A1" "Hello World" # Get cell formula -ExcelMcp cell-get-formula "data.xlsx" "Sheet1" "B1" +excelcli cell-get-formula "data.xlsx" "Sheet1" "B1" # Set cell formula -ExcelMcp cell-set-formula "data.xlsx" "Sheet1" "B1" "=SUM(A1:A10)" +excelcli cell-set-formula "data.xlsx" "Sheet1" "B1" "=SUM(A1:A10)" ``` **Copilot Prompts:** @@ -1199,7 +1199,7 @@ When Copilot suggests code, verify: ### Testing Strategy (Updated) -ExcelMcp uses a three-tier testing approach: +excelcli uses a three-tier testing approach: ```csharp // Unit Tests - Fast, no Excel required @@ -1239,7 +1239,7 @@ dotnet test --filter "Category=RoundTrip" ## Contributing Guidelines -When extending ExcelMcp with Copilot: +When extending excelcli with Copilot: 1. **Follow Existing Patterns:** Use `@workspace` to understand current architecture 2. **Test Thoroughly:** Create both unit and integration tests @@ -1299,6 +1299,242 @@ When extending ExcelMcp with Copilot: - Practical GitHub Copilot integration examples essential for adoption - Resource-based architecture must be explained vs granular approach +## 🔧 **CRITICAL: GitHub Workflows Configuration Management** + +### **Keep Workflows in Sync with Project Configuration** + +**ALWAYS update GitHub workflows when making configuration changes.** This prevents build and deployment failures. + +#### **Configuration Points That Require Workflow Updates** + +When making ANY of these changes, you MUST update all relevant workflows: + +1. **.NET SDK Version Changes** + ```yaml + # If you change global.json or .csproj target frameworks: + # UPDATE ALL workflows that use actions/setup-dotnet@v4 + + - name: Setup .NET + uses: actions/setup-dotnet@v4 + with: + dotnet-version: 10.0.x # ⚠️ MUST match global.json and project files + ``` + + **Files to check:** + - `.github/workflows/build-cli.yml` + - `.github/workflows/build-mcp-server.yml` + - `.github/workflows/release-cli.yml` + - `.github/workflows/release-mcp-server.yml` + - `.github/workflows/codeql.yml` + - `.github/workflows/publish-nuget.yml` + +2. **Assembly/Package Name Changes** + ```yaml + # If you change AssemblyName or PackageId in .csproj: + # UPDATE ALL workflow references to executables and packages + + # Example: Build verification + if (Test-Path "src/ExcelMcp.McpServer/bin/Release/net10.0/Sbroenne.ExcelMcp.McpServer.exe") + + # Example: NuGet package operations + $packagePath = "nupkg/Sbroenne.ExcelMcp.McpServer.$version.nupkg" + dotnet tool install --global Sbroenne.ExcelMcp.McpServer + ``` + + **Files to check:** + - `.github/workflows/build-mcp-server.yml` - Executable name checks + - `.github/workflows/publish-nuget.yml` - Package names + - `.github/workflows/release-mcp-server.yml` - Installation instructions + - `.github/workflows/release-cli.yml` - DLL references + +3. **Runtime Requirements Documentation** + ```powershell + # If you change target framework (net8.0 → net10.0): + # UPDATE ALL release notes that mention runtime requirements + + $releaseNotes += "- .NET 10.0 runtime`n" # ⚠️ MUST match project target + ``` + + **Files to check:** + - `.github/workflows/release-cli.yml` - Quick start and release notes + - `.github/workflows/release-mcp-server.yml` - Installation requirements + +4. **Project Structure Changes** + ```yaml + # If you rename projects or move directories: + # UPDATE path filters and build commands + + paths: + - 'src/ExcelMcp.CLI/**' # ⚠️ MUST match actual directory structure + + run: dotnet build src/ExcelMcp.CLI/ExcelMcp.CLI.csproj # ⚠️ MUST be valid path + ``` + +### **Workflow Validation Checklist** + +Before committing configuration changes, run this validation: + +```powershell +# 1. Check .NET version consistency +$globalJsonVersion = (Get-Content global.json | ConvertFrom-Json).sdk.version +$workflowVersions = Select-String -Path .github/workflows/*.yml -Pattern "dotnet-version:" -Context 0,0 +Write-Output "global.json: $globalJsonVersion" +Write-Output "Workflows:" +$workflowVersions + +# 2. Check assembly names match +$assemblyNames = Select-String -Path src/**/*.csproj -Pattern "(.*)" +$workflowExeRefs = Select-String -Path .github/workflows/*.yml -Pattern "\.exe" -Context 1,0 +Write-Output "Assembly Names in .csproj:" +$assemblyNames +Write-Output "Executable references in workflows:" +$workflowExeRefs + +# 3. Check package IDs match +$packageIds = Select-String -Path src/**/*.csproj -Pattern "(.*)" +$workflowPkgRefs = Select-String -Path .github/workflows/*.yml -Pattern "\.nupkg|tool install" -Context 1,0 +Write-Output "Package IDs in .csproj:" +$packageIds +Write-Output "Package references in workflows:" +$workflowPkgRefs +``` + +### **Automated Workflow Validation (Future Enhancement)** + +Create `.github/scripts/validate-workflows.ps1`: + +```powershell +#!/usr/bin/env pwsh +# Validates workflow configurations match project files + +param( + [switch]$Fix # Auto-fix issues if possible +) + +$errors = @() + +# Check .NET versions +$globalJson = Get-Content global.json | ConvertFrom-Json +$expectedVersion = $globalJson.sdk.version -replace '^\d+\.(\d+)\..*', '$1.0.x' + +$workflows = Get-ChildItem .github/workflows/*.yml +foreach ($workflow in $workflows) { + $content = Get-Content $workflow.FullName -Raw + if ($content -match 'dotnet-version:\s*(\d+\.\d+\.x)') { + $workflowVersion = $Matches[1] + if ($workflowVersion -ne $expectedVersion) { + $errors += "❌ $($workflow.Name): Uses .NET $workflowVersion but should be $expectedVersion" + } + } +} + +# Check assembly names +$projects = Get-ChildItem src/**/*.csproj +foreach ($project in $projects) { + [xml]$csproj = Get-Content $project.FullName + $assemblyName = $csproj.Project.PropertyGroup.AssemblyName + + if ($assemblyName) { + # Check if workflows reference this assembly + $exeName = "$assemblyName.exe" + $workflowRefs = Select-String -Path .github/workflows/*.yml -Pattern $exeName -Quiet + + if (-not $workflowRefs -and $project.Name -match "McpServer") { + $errors += "⚠️ Assembly $assemblyName not found in workflows" + } + } +} + +# Report results +if ($errors.Count -eq 0) { + Write-Output "✅ All workflow configurations are valid!" + exit 0 +} else { + Write-Output "❌ Found $($errors.Count) workflow configuration issues:" + $errors | ForEach-Object { Write-Output " $_" } + exit 1 +} +``` + +### **When to Run Validation** + +Run workflow validation: +- ✅ Before creating PR with configuration changes +- ✅ After upgrading .NET SDK version +- ✅ After renaming projects or assemblies +- ✅ After changing package IDs or branding +- ✅ As part of pre-commit hooks (recommended) + +### **Common Workflow Configuration Mistakes to Prevent** + +❌ **Don't:** +- Change .NET version in code without updating workflows +- Rename assemblies without updating executable checks +- Change package IDs without updating install commands +- Update target frameworks without updating runtime requirements +- Assume workflows will "just work" after configuration changes + +✅ **Always:** +- Update ALL affected workflows when changing configuration +- Validate executable names match AssemblyName properties +- Verify package IDs match PackageId properties +- Keep runtime requirement docs in sync with target frameworks +- Test workflows locally with `act` or similar tools before pushing + +### **Workflow Update Template** + +When making configuration changes, use this checklist: + +```markdown +## Configuration Change: [Brief Description] + +### Changes Made: +- [ ] Updated global.json/.csproj files +- [ ] Updated all workflow .NET versions +- [ ] Updated executable name references +- [ ] Updated package ID references +- [ ] Updated runtime requirement documentation +- [ ] Tested workflow locally (if possible) +- [ ] Verified all path filters still match +- [ ] Updated this checklist in PR description + +### Workflows Reviewed: +- [ ] build-cli.yml +- [ ] build-mcp-server.yml +- [ ] release-cli.yml +- [ ] release-mcp-server.yml +- [ ] codeql.yml +- [ ] publish-nuget.yml +- [ ] dependency-review.yml (if applicable) +``` + +### **Integration with CI/CD** + +Add workflow validation to CI pipeline: + +```yaml +# .github/workflows/validate-config.yml +name: Validate Configuration + +on: + pull_request: + paths: + - 'src/**/*.csproj' + - 'global.json' + - 'Directory.*.props' + - '.github/workflows/**' + +jobs: + validate: + runs-on: windows-latest + steps: + - uses: actions/checkout@v4 + + - name: Validate Workflows + run: .github/scripts/validate-workflows.ps1 + shell: pwsh +``` + ## �🚨 **CRITICAL: Development Workflow Requirements** ### **All Changes Must Use Pull Requests** @@ -1312,7 +1548,7 @@ When extending ExcelMcp with Copilot: ### **Required Development Process** -When helping with ExcelMcp development, always guide users through this workflow: +When helping with excelcli development, always guide users through this workflow: #### 1. **Create Feature Branch First** ```powershell diff --git a/.github/workflows/build-cli.yml b/.github/workflows/build-cli.yml new file mode 100644 index 00000000..f64efb46 --- /dev/null +++ b/.github/workflows/build-cli.yml @@ -0,0 +1,81 @@ +name: Build CLI + +permissions: + contents: read + +on: + push: + branches: [ main, develop ] + paths: + - 'src/ExcelMcp.CLI/**' + - 'src/ExcelMcp.Core/**' + - 'tests/ExcelMcp.CLI.Tests/**' + - 'global.json' + - 'Directory.Build.props' + - 'Directory.Packages.props' + - '.github/workflows/build-cli.yml' + pull_request: + branches: [ main ] + paths: + - 'src/ExcelMcp.CLI/**' + - 'src/ExcelMcp.Core/**' + - 'tests/ExcelMcp.CLI.Tests/**' + - 'global.json' + - 'Directory.Build.props' + - 'Directory.Packages.props' + - '.github/workflows/build-cli.yml' + +jobs: + build-cli: + runs-on: windows-latest + + steps: + - uses: actions/checkout@v4 + + - name: Setup .NET + uses: actions/setup-dotnet@v4 + with: + dotnet-version: 10.0.x + + - name: Restore dependencies + run: dotnet restore src/ExcelMcp.CLI/ExcelMcp.CLI.csproj + + - name: Build CLI + run: dotnet build src/ExcelMcp.CLI/ExcelMcp.CLI.csproj --no-restore --configuration Release + + - name: Verify CLI build + run: | + # Check excelcli main executable + if (Test-Path "src/ExcelMcp.CLI/bin/Release/net10.0/excelcli.exe") { + Write-Output "✅ excelcli.exe built successfully" + $version = (Get-Item "src/ExcelMcp.CLI/bin/Release/net10.0/excelcli.exe").VersionInfo.FileVersion + Write-Output "Version: $version" + + # Test CLI help command (safe - no Excel COM required) + $helpOutput = & "src/ExcelMcp.CLI/bin/Release/net10.0/excelcli.exe" --help + if ($helpOutput -match "Excel Command Line Interface") { + Write-Output "✅ CLI help command working" + Write-Output "📋 Help output preview: $($helpOutput | Select-Object -First 3 | Out-String)" + } else { + Write-Warning "⚠️ CLI help command may have issues" + Write-Output "Help output: $($helpOutput | Select-Object -First 5 | Out-String)" + } + } else { + Write-Error "❌ excelcli.exe not found" + exit 1 + } + + Write-Output "🔧 CLI tool ready for direct automation" + shell: pwsh + + - name: Test CLI (requires Excel) + run: | + Write-Output "ℹ️ Note: CLI tests skipped in CI - they require Microsoft Excel" + Write-Output " Run 'dotnet test tests/ExcelMcp.CLI.Tests/' locally with Excel installed" + shell: pwsh + + - name: Upload CLI build artifacts + uses: actions/upload-artifact@v4 + with: + name: ExcelMcp-CLI-${{ github.sha }} + path: src/ExcelMcp.CLI/bin/Release/net10.0/ \ No newline at end of file diff --git a/.github/workflows/build-mcp-server.yml b/.github/workflows/build-mcp-server.yml new file mode 100644 index 00000000..b812577e --- /dev/null +++ b/.github/workflows/build-mcp-server.yml @@ -0,0 +1,72 @@ +name: Build MCP Server + +permissions: + contents: read + +on: + push: + branches: [ main, develop ] + paths: + - 'src/ExcelMcp.McpServer/**' + - 'src/ExcelMcp.Core/**' + - 'tests/ExcelMcp.McpServer.Tests/**' + - 'global.json' + - 'Directory.Build.props' + - 'Directory.Packages.props' + - '.github/workflows/build-mcp-server.yml' + pull_request: + branches: [ main ] + paths: + - 'src/ExcelMcp.McpServer/**' + - 'src/ExcelMcp.Core/**' + - 'tests/ExcelMcp.McpServer.Tests/**' + - 'global.json' + - 'Directory.Build.props' + - 'Directory.Packages.props' + - '.github/workflows/build-mcp-server.yml' + +jobs: + build-mcp-server: + runs-on: windows-latest + + steps: + - uses: actions/checkout@v4 + + - name: Setup .NET + uses: actions/setup-dotnet@v4 + with: + dotnet-version: 10.0.x + + - name: Restore dependencies + run: dotnet restore src/ExcelMcp.McpServer/ExcelMcp.McpServer.csproj + + - name: Build MCP Server + run: dotnet build src/ExcelMcp.McpServer/ExcelMcp.McpServer.csproj --no-restore --configuration Release + + - name: Verify MCP Server build + run: | + # Check MCP Server executable + if (Test-Path "src/ExcelMcp.McpServer/bin/Release/net10.0/Sbroenne.ExcelMcp.McpServer.exe") { + Write-Output "✅ Sbroenne.ExcelMcp.McpServer.exe built successfully" + $mcpVersion = (Get-Item "src/ExcelMcp.McpServer/bin/Release/net10.0/Sbroenne.ExcelMcp.McpServer.exe").VersionInfo.FileVersion + Write-Output "📦 MCP Server Version: $mcpVersion" + + # Check for MCP server.json configuration + if (Test-Path "src/ExcelMcp.McpServer/bin/Release/net10.0/.mcp/server.json") { + Write-Output "✅ MCP server.json configuration found" + } else { + Write-Warning "⚠️ MCP server.json configuration not found" + } + } else { + Write-Error "❌ Sbroenne.ExcelMcp.McpServer.exe not found" + exit 1 + } + + Write-Output "🧠 MCP Server ready for AI assistant integration" + shell: pwsh + + - name: Upload MCP Server build artifacts + uses: actions/upload-artifact@v4 + with: + name: ExcelMcp-MCP-Server-${{ github.sha }} + path: src/ExcelMcp.McpServer/bin/Release/net10.0/ \ No newline at end of file diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml deleted file mode 100644 index 1a4cd3fe..00000000 --- a/.github/workflows/build.yml +++ /dev/null @@ -1,87 +0,0 @@ -name: Build - -permissions: - contents: read - -on: - push: - branches: [ main, develop ] - paths: - - 'src/**' - - 'tests/**' - - '**.csproj' - - '**.sln' - - 'Directory.Build.props' - - 'Directory.Packages.props' - - '.github/workflows/build.yml' - pull_request: - branches: [ main ] - paths: - - 'src/**' - - 'tests/**' - - '**.csproj' - - '**.sln' - - 'Directory.Build.props' - - 'Directory.Packages.props' - - '.github/workflows/build.yml' - -jobs: - build: - runs-on: windows-latest - - steps: - - uses: actions/checkout@v4 - - - name: Setup .NET - uses: actions/setup-dotnet@v4 - with: - dotnet-version: 8.0.x - - - name: Restore dependencies - run: dotnet restore - - - name: Build - run: dotnet build --no-restore --configuration Release - - - name: Verify build (no tests - requires Excel) - run: | - Write-Output "ℹ️ Note: Unit tests skipped in CI - they require Microsoft Excel" - Write-Output " Run 'dotnet test' locally with Excel installed for full validation" - shell: pwsh - - - name: Test build output - run: | - # Check ExcelMcp main executable - if (Test-Path "src/ExcelMcp/bin/Release/net8.0/ExcelMcp.exe") { - Write-Output "✅ ExcelMcp.exe built successfully" - $version = (Get-Item "src/ExcelMcp/bin/Release/net8.0/ExcelMcp.exe").VersionInfo.FileVersion - Write-Output "📦 CLI Version: $version" - } else { - Write-Error "❌ ExcelMcp.exe not found" - exit 1 - } - - # Check MCP Server executable - if (Test-Path "src/ExcelMcp.McpServer/bin/Release/net8.0/ExcelMcp.McpServer.exe") { - Write-Output "✅ ExcelMcp.McpServer.exe built successfully" - $mcpVersion = (Get-Item "src/ExcelMcp.McpServer/bin/Release/net8.0/ExcelMcp.McpServer.exe").VersionInfo.FileVersion - Write-Output "📦 MCP Server Version: $mcpVersion" - } else { - Write-Error "❌ ExcelMcp.McpServer.exe not found" - exit 1 - } - - Write-Output "🎯 Both CLI and MCP Server ready for distribution" - shell: pwsh - - - name: Upload CLI build artifacts - uses: actions/upload-artifact@v4 - with: - name: ExcelMcp-CLI-${{ github.sha }} - path: src/ExcelMcp/bin/Release/net8.0/ - - - name: Upload MCP Server build artifacts - uses: actions/upload-artifact@v4 - with: - name: ExcelMcp-MCP-Server-${{ github.sha }} - path: src/ExcelMcp.McpServer/bin/Release/net8.0/ \ No newline at end of file diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 864e003d..fee45de8 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -56,7 +56,7 @@ jobs: - name: Setup .NET uses: actions/setup-dotnet@v4 with: - dotnet-version: 8.0.x + dotnet-version: 10.0.x # Initializes the CodeQL tools for scanning - name: Initialize CodeQL diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml index c8e26ba1..160cb271 100644 --- a/.github/workflows/dependency-review.yml +++ b/.github/workflows/dependency-review.yml @@ -25,7 +25,8 @@ jobs: fail-on-severity: moderate # Fail if GPL/AGPL/LGPL licenses detected (stricter than MIT) - deny-licenses: GPL-2.0, GPL-3.0, AGPL-3.0, LGPL-2.1, LGPL-3.0 + license-check: true + allow-licenses: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, 0BSD # Comment on PR with summary comment-summary-in-pr: always diff --git a/.github/workflows/publish-nuget.yml b/.github/workflows/publish-nuget.yml index 28daf860..0d38a272 100644 --- a/.github/workflows/publish-nuget.yml +++ b/.github/workflows/publish-nuget.yml @@ -17,7 +17,7 @@ jobs: - name: Setup .NET uses: actions/setup-dotnet@v4 with: - dotnet-version: 8.0.x + dotnet-version: 10.0.x - name: Extract version from tag id: version @@ -58,13 +58,13 @@ jobs: --output ./nupkg ` /p:PackageVersion=$version - Write-Output "📦 Created NuGet package: ExcelMcp.McpServer.$version.nupkg" + Write-Output "📦 Created NuGet package: Sbroenne.ExcelMcp.McpServer.$version.nupkg" shell: pwsh - name: Verify package contents run: | $version = "${{ steps.version.outputs.version }}" - $packagePath = "nupkg/ExcelMcp.McpServer.$version.nupkg" + $packagePath = "nupkg/Sbroenne.ExcelMcp.McpServer.$version.nupkg" if (Test-Path $packagePath) { Write-Output "✅ Package created successfully" @@ -78,14 +78,14 @@ jobs: - name: Publish to NuGet.org run: | $version = "${{ steps.version.outputs.version }}" - $packagePath = "nupkg/ExcelMcp.McpServer.$version.nupkg" + $packagePath = "nupkg/Sbroenne.ExcelMcp.McpServer.$version.nupkg" dotnet nuget push $packagePath ` --source https://api.nuget.org/v3/index.json ` --skip-duplicate - Write-Output "🚀 Published ExcelMcp.McpServer.$version to NuGet.org" - Write-Output "🔗 Package will be available at: https://www.nuget.org/packages/ExcelMcp.McpServer/$version" + Write-Output "🚀 Published Sbroenne.ExcelMcp.McpServer.$version to NuGet.org" + Write-Output "🔗 Package will be available at: https://www.nuget.org/packages/Sbroenne.ExcelMcp.McpServer/$version" shell: pwsh - name: Upload package artifact diff --git a/.github/workflows/release-cli.yml b/.github/workflows/release-cli.yml new file mode 100644 index 00000000..6200e459 --- /dev/null +++ b/.github/workflows/release-cli.yml @@ -0,0 +1,180 @@ +name: Release CLI + +on: + push: + tags: + - 'cli-v*' + +jobs: + release-cli: + runs-on: windows-latest + permissions: + contents: write + issues: write + pull-requests: write + + steps: + - uses: actions/checkout@v4 + + - name: Setup .NET + uses: actions/setup-dotnet@v4 + with: + dotnet-version: 10.0.x + + - name: Update CLI Version + run: | + $tagName = "${{ github.ref_name }}" + $version = $tagName -replace '^cli-v', '' + + Write-Output "Updating CLI to version $version" + + # Update CLI project version + $cliCsprojPath = "src/ExcelMcp.CLI/ExcelMcp.CLI.csproj" + $cliContent = Get-Content $cliCsprojPath -Raw + $cliContent = $cliContent -replace '[\d\.]+', "$version" + $cliContent = $cliContent -replace '[\d\.]+\.[\d\.]+', "$version.0" + $cliContent = $cliContent -replace '[\d\.]+\.[\d\.]+', "$version.0" + Set-Content $cliCsprojPath $cliContent + + Write-Output "Updated CLI version to $version" + + # Set environment variable for later steps + echo "PACKAGE_VERSION=$version" >> $env:GITHUB_ENV + shell: pwsh + + - name: Restore dependencies + run: dotnet restore src/ExcelMcp.CLI/ExcelMcp.CLI.csproj + + - name: Build CLI + run: dotnet build src/ExcelMcp.CLI/ExcelMcp.CLI.csproj --configuration Release --no-restore + + - name: Run CLI Tests (Unit only - no Excel required) + run: dotnet test tests/ExcelMcp.CLI.Tests --filter "Category=Unit" --configuration Release --no-build + + - name: Create CLI Release Package + run: | + $version = $env:PACKAGE_VERSION + + # Create release directory structure + New-Item -ItemType Directory -Path "release" -Force + New-Item -ItemType Directory -Path "release/ExcelMcp-CLI-$version" -Force + + # Copy CLI files + Copy-Item "src/ExcelMcp.CLI/bin/Release/net10.0/excelcli.exe" "release/ExcelMcp-CLI-$version/" + Copy-Item "src/ExcelMcp.CLI/bin/Release/net10.0/excelcli.dll" "release/ExcelMcp-CLI-$version/" + Copy-Item "src/ExcelMcp.CLI/bin/Release/net10.0/Sbroenne.ExcelMcp.Core.dll" "release/ExcelMcp-CLI-$version/" + Copy-Item "src/ExcelMcp.CLI/bin/Release/net10.0/excelcli.runtimeconfig.json" "release/ExcelMcp-CLI-$version/" + Copy-Item "src/ExcelMcp.CLI/bin/Release/net10.0/*.dll" "release/ExcelMcp-CLI-$version/" -Exclude "excelcli.dll", "Sbroenne.ExcelMcp.Core.dll" + + # Copy documentation + Copy-Item "docs/CLI.md" "release/ExcelMcp-CLI-$version/README.md" + Copy-Item "LICENSE" "release/ExcelMcp-CLI-$version/" + Copy-Item "docs/COMMANDS.md" "release/ExcelMcp-CLI-$version/" + + # Create quick start guide + $quickStartContent = "# ExcelMcp CLI v$version`n`n" + $quickStartContent += "## Quick Start`n`n" + $quickStartContent += "### Basic Usage`n" + $quickStartContent += "``````powershell`n" + $quickStartContent += "# Show help`n" + $quickStartContent += ".\excelcli.exe`n`n" + $quickStartContent += "# Create empty workbook`n" + $quickStartContent += ".\excelcli.exe create-empty `"test.xlsx`"`n`n" + $quickStartContent += "# List Power Queries`n" + $quickStartContent += ".\excelcli.exe pq-list `"workbook.xlsx`"`n`n" + $quickStartContent += "# Read worksheet data`n" + $quickStartContent += ".\excelcli.exe sheet-read `"workbook.xlsx`" `"Sheet1`" `"A1:D10`"`n" + $quickStartContent += "``````n`n" + $quickStartContent += "### VBA Operations (One-time setup)`n" + $quickStartContent += "``````powershell`n" + $quickStartContent += "# Enable VBA trust (run once)`n" + $quickStartContent += ".\excelcli.exe setup-vba-trust`n`n" + $quickStartContent += "# Create macro-enabled workbook`n" + $quickStartContent += ".\excelcli.exe create-empty `"macros.xlsm`"`n`n" + $quickStartContent += "# List VBA modules`n" + $quickStartContent += ".\excelcli.exe script-list `"macros.xlsm`"`n" + $quickStartContent += "``````n`n" + $quickStartContent += "## Documentation`n`n" + $quickStartContent += "- **README.md** - Complete CLI documentation`n" + $quickStartContent += "- **COMMANDS.md** - All 40+ command reference`n" + $quickStartContent += "- **GitHub**: https://github.com/sbroenne/mcp-server-excel`n`n" + $quickStartContent += "## Requirements`n`n" + $quickStartContent += "- Windows OS with Microsoft Excel installed`n" + $quickStartContent += "- .NET 10.0 runtime`n" + $quickStartContent += "- Excel 2016+ (for COM interop)`n`n" + $quickStartContent += "## Features`n`n" + $quickStartContent += "- 40+ Excel automation commands`n" + $quickStartContent += "- Power Query development tools`n" + $quickStartContent += "- VBA development and execution`n" + $quickStartContent += "- Worksheet data manipulation`n" + $quickStartContent += "- Named range parameter management`n" + $quickStartContent += "- Individual cell operations`n`n" + $quickStartContent += "## License`n`n" + $quickStartContent += "MIT License - see LICENSE file for details.`n" + + Set-Content "release/ExcelMcp-CLI-$version/QUICK-START.md" $quickStartContent + + # Create ZIP + Compress-Archive -Path "release/ExcelMcp-CLI-$version/*" -DestinationPath "ExcelMcp-CLI-$version-windows.zip" + + Write-Output "Created ExcelMcp-CLI-$version-windows.zip" + shell: pwsh + + - name: Create GitHub Release + run: | + $tagName = "${{ github.ref_name }}" + $version = $env:PACKAGE_VERSION + + # Create release notes + $releaseNotes = "## ExcelMcp CLI $tagName`n`n" + $releaseNotes += "### Command-Line Interface for Excel Automation`n`n" + $releaseNotes += "Direct command-line access to Excel operations for automation workflows, development, and CI/CD integration.`n`n" + $releaseNotes += "### Key Features`n" + $releaseNotes += "- 40+ Excel automation commands`n" + $releaseNotes += "- Power Query development tools (M code management)`n" + $releaseNotes += "- VBA development and macro execution`n" + $releaseNotes += "- Worksheet data manipulation`n" + $releaseNotes += "- Named range parameter management`n" + $releaseNotes += "- Individual cell operations`n" + $releaseNotes += "- CI/CD integration ready`n`n" + $releaseNotes += "### Installation`n`n" + $releaseNotes += "**Download Binary**`n" + $releaseNotes += "1. Download ExcelMcp-CLI-$version-windows.zip`n" + $releaseNotes += "2. Extract to your preferred directory`n" + $releaseNotes += "3. See QUICK-START.md for usage examples`n`n" + $releaseNotes += "### Command Categories`n" + $releaseNotes += "- **File Operations** (2) - Create Excel workbooks (.xlsx, .xlsm)`n" + $releaseNotes += "- **Power Query** (8) - M code management and data transformation`n" + $releaseNotes += "- **VBA Scripts** (6) - Macro development and execution`n" + $releaseNotes += "- **Worksheets** (9) - Data manipulation and sheet management`n" + $releaseNotes += "- **Parameters** (5) - Named range configuration`n" + $releaseNotes += "- **Cells** (4) - Individual cell operations`n`n" + $releaseNotes += "### Quick Examples`n" + $releaseNotes += "``````powershell`n" + $releaseNotes += "# Basic operations`n" + $releaseNotes += "excelcli.exe create-empty `"test.xlsx`"`n" + $releaseNotes += "excelcli.exe pq-list `"workbook.xlsx`"`n" + $releaseNotes += "excelcli.exe sheet-read `"workbook.xlsx`" `"Sheet1`" `"A1:D10`"`n`n" + $releaseNotes += "# VBA operations (requires setup-vba-trust)`n" + $releaseNotes += "excelcli.exe setup-vba-trust`n" + $releaseNotes += "excelcli.exe script-list `"macros.xlsm`"`n" + $releaseNotes += "excelcli.exe script-run `"macros.xlsm`" `"Module.Procedure`"`n" + $releaseNotes += "``````n`n" + $releaseNotes += "### Requirements`n" + $releaseNotes += "- Windows OS with Microsoft Excel installed`n" + $releaseNotes += "- .NET 10.0 runtime`n" + $releaseNotes += "- Excel 2016+ (for COM interop)`n`n" + $releaseNotes += "### Documentation`n" + $releaseNotes += "- Complete Command Reference: COMMANDS.md in package`n" + $releaseNotes += "- GitHub Repository: https://github.com/sbroenne/mcp-server-excel`n" + $releaseNotes += "- CLI Documentation: docs/CLI.md`n`n" + $releaseNotes += "### Related Tools`n" + $releaseNotes += "- ExcelMcp MCP Server: For AI assistant integration`n" + $releaseNotes += "- GitHub Copilot Integration: AI-assisted development workflows`n" + + # Create the release + gh release create "$tagName" "ExcelMcp-CLI-$version-windows.zip" --title "ExcelMcp CLI $tagName" --notes $releaseNotes + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PACKAGE_VERSION: ${{ env.PACKAGE_VERSION }} + shell: pwsh \ No newline at end of file diff --git a/.github/workflows/release-mcp-server.yml b/.github/workflows/release-mcp-server.yml new file mode 100644 index 00000000..0b846196 --- /dev/null +++ b/.github/workflows/release-mcp-server.yml @@ -0,0 +1,168 @@ +name: Release MCP Server + +on: + push: + tags: + - 'mcp-v*' + +jobs: + release-mcp-server: + runs-on: windows-latest + permissions: + contents: write + issues: write + pull-requests: write + packages: write + + steps: + - uses: actions/checkout@v4 + + - name: Setup .NET + uses: actions/setup-dotnet@v4 + with: + dotnet-version: 10.0.x + + - name: Update MCP Server Version + run: | + $tagName = "${{ github.ref_name }}" + $version = $tagName -replace '^mcp-v', '' + + Write-Output "Updating MCP Server to version $version" + + # Update MCP Server project version + $mcpCsprojPath = "src/ExcelMcp.McpServer/ExcelMcp.McpServer.csproj" + $mcpContent = Get-Content $mcpCsprojPath -Raw + $mcpContent = $mcpContent -replace '[\d\.]+', "$version" + $mcpContent = $mcpContent -replace '[\d\.]+\.[\d\.]+', "$version.0" + $mcpContent = $mcpContent -replace '[\d\.]+\.[\d\.]+', "$version.0" + Set-Content $mcpCsprojPath $mcpContent + + Write-Output "Updated MCP Server version to $version" + + # Set environment variable for later steps + echo "PACKAGE_VERSION=$version" >> $env:GITHUB_ENV + shell: pwsh + + - name: Restore dependencies + run: dotnet restore src/ExcelMcp.McpServer/ExcelMcp.McpServer.csproj + + - name: Build MCP Server + run: dotnet build src/ExcelMcp.McpServer/ExcelMcp.McpServer.csproj --configuration Release --no-restore + + - name: Skip MCP Server Tests (requires Excel) + run: | + Write-Output "ℹ️ Note: MCP Server tests skipped in CI - they require Microsoft Excel" + Write-Output " All MCP Server tests are Integration tests that need Excel COM interop" + Write-Output " Run 'dotnet test tests/ExcelMcp.McpServer.Tests/' locally with Excel installed" + shell: pwsh + + - name: Pack NuGet Package + run: dotnet pack src/ExcelMcp.McpServer/ExcelMcp.McpServer.csproj --configuration Release --no-build --output ./nupkg + + - name: Create MCP Server Release Package + run: | + $version = $env:PACKAGE_VERSION + + # Create release directory structure + New-Item -ItemType Directory -Path "release" -Force + New-Item -ItemType Directory -Path "release/ExcelMcp-MCP-Server-$version" -Force + + # Copy MCP Server files + Copy-Item "src/ExcelMcp.McpServer/bin/Release/net10.0/*" "release/ExcelMcp-MCP-Server-$version/" -Recurse + + # Copy documentation + Copy-Item "README.md" "release/ExcelMcp-MCP-Server-$version/" + Copy-Item "LICENSE" "release/ExcelMcp-MCP-Server-$version/" + Copy-Item "src/ExcelMcp.McpServer/README.md" "release/ExcelMcp-MCP-Server-$version/MCP-SERVER-README.md" + + # Create installation README with proper content + $readmeContent = "# ExcelMcp MCP Server v$version`n`n" + $readmeContent += "## Quick Start`n`n" + $readmeContent += "### Option 1: Install as .NET Tool (Recommended)`n" + $readmeContent += "``````powershell`n" + $readmeContent += "# Install globally`n" + $readmeContent += "dotnet tool install --global Sbroenne.ExcelMcp.McpServer --version $version`n`n" + $readmeContent += "# Run MCP server`n" + $readmeContent += "mcp-excel`n`n" + $readmeContent += "# Update`n" + $readmeContent += "dotnet tool update --global Sbroenne.ExcelMcp.McpServer`n" + $readmeContent += "``````n`n" + $readmeContent += "### Option 2: Run from Binary`n" + $readmeContent += "``````powershell`n" + $readmeContent += "dotnet ExcelMcp.McpServer.dll`n" + $readmeContent += "``````n`n" + $readmeContent += "## Features`n`n" + $readmeContent += "- AI Assistant Integration - Native MCP protocol support`n" + $readmeContent += "- Conversational Interface - Natural language Excel operations`n" + $readmeContent += "- 6 Resource-Based Tools - Structured API for AI assistants`n" + $readmeContent += "- Excel Development Focus - Power Query, VBA, worksheets`n`n" + $readmeContent += "## Requirements`n`n" + $readmeContent += "- Windows OS with Microsoft Excel installed`n" + $readmeContent += "- .NET 10.0 runtime`n" + $readmeContent += "- Excel 2016+ (for COM interop)`n`n" + $readmeContent += "## License`n`n" + $readmeContent += "MIT License - see LICENSE file for details.`n" + + Set-Content "release/ExcelMcp-MCP-Server-$version/README.md" $readmeContent + + # Create ZIP + Compress-Archive -Path "release/ExcelMcp-MCP-Server-$version/*" -DestinationPath "ExcelMcp-MCP-Server-$version-windows.zip" + + Write-Output "Created ExcelMcp-MCP-Server-$version-windows.zip" + shell: pwsh + + - name: Publish to NuGet + run: | + $nupkgFiles = Get-ChildItem -Path "./nupkg" -Filter "*.nupkg" + foreach ($nupkg in $nupkgFiles) { + Write-Output "Publishing $($nupkg.Name) to NuGet..." + dotnet nuget push $nupkg.FullName --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate + } + shell: pwsh + + - name: Create GitHub Release + run: | + $tagName = "${{ github.ref_name }}" + $version = $env:PACKAGE_VERSION + + # Create release notes + $releaseNotes = "## ExcelMcp MCP Server $tagName`n`n" + $releaseNotes += "### MCP Server for AI-Powered Excel Development`n`n" + $releaseNotes += "The Model Context Protocol (MCP) Server enables AI assistants like GitHub Copilot, Claude, and ChatGPT to perform Excel development tasks through conversational interfaces.`n`n" + $releaseNotes += "### Key Features`n" + $releaseNotes += "- Native AI Integration - Built for GitHub Copilot and AI assistants`n" + $releaseNotes += "- Conversational Excel - Natural language Excel operations`n" + $releaseNotes += "- Resource-Based API - 6 structured tools instead of 40+ commands`n" + $releaseNotes += "- Development Focus - Power Query refactoring, VBA enhancement, code review`n" + $releaseNotes += "- Smart Context - AI understands Excel development workflows`n`n" + $releaseNotes += "### Installation`n`n" + $releaseNotes += "**Option 1: .NET Tool (Recommended)**`n" + $releaseNotes += "``````powershell`n" + $releaseNotes += "dotnet tool install --global Sbroenne.ExcelMcp.McpServer --version $version`n" + $releaseNotes += "mcp-excel`n" + $releaseNotes += "``````n`n" + $releaseNotes += "**Option 2: Download Binary**`n" + $releaseNotes += "1. Download ExcelMcp-MCP-Server-$version-windows.zip`n" + $releaseNotes += "2. Extract and run: dotnet ExcelMcp.McpServer.dll`n`n" + $releaseNotes += "### MCP Tools Available`n" + $releaseNotes += "- excel_file - File management (create, validate, check-exists)`n" + $releaseNotes += "- excel_powerquery - Power Query operations (list, view, import, export, update, refresh, delete)`n" + $releaseNotes += "- excel_worksheet - Worksheet operations (list, read, write, create, rename, copy, delete, clear, append)`n" + $releaseNotes += "- excel_parameter - Named range management (list, get, set, create, delete)`n" + $releaseNotes += "- excel_cell - Cell operations (get-value, set-value, get-formula, set-formula)`n" + $releaseNotes += "- excel_vba - VBA script management (list, export, import, update, run, delete)`n`n" + $releaseNotes += "### Requirements`n" + $releaseNotes += "- Windows OS with Microsoft Excel installed`n" + $releaseNotes += "- .NET 10.0 runtime`n" + $releaseNotes += "- Excel 2016+ (for COM interop)`n`n" + $releaseNotes += "### Documentation`n" + $releaseNotes += "- Configuration Guide: See README.md in package`n" + $releaseNotes += "- GitHub Repository: https://github.com/sbroenne/mcp-server-excel`n" + $releaseNotes += "- MCP Server Details: src/ExcelMcp.McpServer/README.md`n" + + # Create the release + gh release create "$tagName" "ExcelMcp-MCP-Server-$version-windows.zip" --title "ExcelMcp MCP Server $tagName" --notes $releaseNotes + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PACKAGE_VERSION: ${{ env.PACKAGE_VERSION }} + shell: pwsh \ No newline at end of file diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml deleted file mode 100644 index bf06b330..00000000 --- a/.github/workflows/release.yml +++ /dev/null @@ -1,165 +0,0 @@ -name: Release - -on: - push: - tags: - - 'v*' - -jobs: - release: - runs-on: windows-latest - permissions: - contents: write - issues: write - pull-requests: write - - steps: - - uses: actions/checkout@v4 - - - name: Setup .NET - uses: actions/setup-dotnet@v4 - with: - dotnet-version: 8.0.x - - - name: Update Version Numbers - run: | - $tagName = "${{ github.ref_name }}" - $version = $tagName -replace '^v', '' - - # Update main CLI project version - $csprojPath = "src/ExcelMcp/ExcelMcp.csproj" - $content = Get-Content $csprojPath -Raw - $content = $content -replace '[\d\.]+', "$version" - $content = $content -replace '[\d\.]+', "$version.0" - $content = $content -replace '[\d\.]+', "$version.0" - Set-Content $csprojPath $content - - # Update MCP Server project version - $mcpCsprojPath = "src/ExcelMcp.McpServer/ExcelMcp.McpServer.csproj" - $mcpContent = Get-Content $mcpCsprojPath -Raw - $mcpContent = $mcpContent -replace '[\d\.]+', "$version" - $mcpContent = $mcpContent -replace '[\d\.]+', "$version.0" - $mcpContent = $mcpContent -replace '[\d\.]+', "$version.0" - Set-Content $mcpCsprojPath $mcpContent - - # Also update Directory.Build.props - $buildPropsPath = "Directory.Build.props" - $buildContent = Get-Content $buildPropsPath -Raw - $buildContent = $buildContent -replace '[\d\.]+', "$version" - $buildContent = $buildContent -replace '[\d\.]+', "$version.0" - $buildContent = $buildContent -replace '[\d\.]+', "$version.0" - Set-Content $buildPropsPath $buildContent - - Write-Output "Updated version to $version for CLI and MCP Server" - shell: pwsh - - - name: Restore dependencies - run: dotnet restore - - - name: Build Release - run: dotnet build --configuration Release --no-restore - - - name: Create Release Package - run: | - $tagName = "${{ github.ref_name }}" - $version = $tagName -replace '^v', '' - - # Create release directory structure - New-Item -ItemType Directory -Path "release" -Force - New-Item -ItemType Directory -Path "release/ExcelMcp-$version" -Force - New-Item -ItemType Directory -Path "release/ExcelMcp-$version/CLI" -Force - New-Item -ItemType Directory -Path "release/ExcelMcp-$version/MCP-Server" -Force - - # Copy CLI files - Copy-Item "src/ExcelMcp/bin/Release/net8.0/ExcelMcp.exe" "release/ExcelMcp-$version/CLI/" - Copy-Item "src/ExcelMcp/bin/Release/net8.0/ExcelMcp.dll" "release/ExcelMcp-$version/CLI/" - Copy-Item "src/ExcelMcp/bin/Release/net8.0/ExcelMcp.Core.dll" "release/ExcelMcp-$version/CLI/" - Copy-Item "src/ExcelMcp/bin/Release/net8.0/ExcelMcp.runtimeconfig.json" "release/ExcelMcp-$version/CLI/" - Copy-Item "src/ExcelMcp/bin/Release/net8.0/Spectre.Console.dll" "release/ExcelMcp-$version/CLI/" - - # Copy MCP Server files - Copy-Item "src/ExcelMcp.McpServer/bin/Release/net8.0/*" "release/ExcelMcp-$version/MCP-Server/" -Recurse - - # Copy documentation - Copy-Item "README.md" "release/ExcelMcp-$version/" - Copy-Item "LICENSE" "release/ExcelMcp-$version/" - Copy-Item "docs/COMMANDS.md" "release/ExcelMcp-$version/" - Copy-Item "src/ExcelMcp.McpServer/README.md" "release/ExcelMcp-$version/MCP-Server-README.md" - - # Create installation README - $installReadme = "# ExcelMcp v$version`n`n## CLI Tools`nLocation: CLI/`nUsage: ExcelMcp.exe --help`n`n## MCP Server`nLocation: MCP-Server/`nUsage: dotnet MCP-Server/ExcelMcp.McpServer.dll`n`nSee README.md and MCP-Server-README.md for complete documentation." - Set-Content "release/ExcelMcp-$version/INSTALL.md" $installReadme - - # Create ZIP - Compress-Archive -Path "release/ExcelMcp-$version/*" -DestinationPath "ExcelMcp-$version-windows.zip" - - Write-Output "Created ExcelMcp-$version-windows.zip with CLI and MCP Server" - shell: pwsh - - - name: Create Release with GitHub CLI - run: | - $tagName = "${{ github.ref_name }}" - $version = $tagName -replace '^v', '' - - # Create release notes - $releaseNotes = @" - ## ExcelMcp $tagName - - ### 🆕 What's New - - **MCP Server**: Model Context Protocol server for AI assistant integration - - **GitHub Copilot Ready**: Built for AI-assisted Excel development workflows - - **Development Focus**: Power Query refactoring and VBA enhancement - - Enhanced error handling and diagnostics - - Complete Power Query, worksheet, and VBA automation - - ### 📦 Package Contents - - **CLI/**: Command-line tools (ExcelMcp.exe) - - **MCP-Server/**: MCP server for AI assistants - - Documentation: README.md, MCP-Server-README.md, COMMANDS.md - - ### 🚀 Installation - - **Option 1: Download Binary** - 1. Download ``ExcelMcp-$version-windows.zip`` - 2. Extract to your preferred directory - 3. See INSTALL.md for setup instructions - - **Option 2: NuGet Package (.NET Tool)** - `````` - dotnet tool install --global ExcelMcp.McpServer --version $version - `````` - - ### 💻 CLI Usage - `````` - CLI/ExcelMcp.exe --version - CLI/ExcelMcp.exe pq-list "workbook.xlsx" - CLI/ExcelMcp.exe pq-view "workbook.xlsx" "QueryName" - CLI/ExcelMcp.exe sheet-read "workbook.xlsx" "Sheet1" "A1:D10" - `````` - - ### 🧠 MCP Server Usage - `````` - # From binary - dotnet MCP-Server/ExcelMcp.McpServer.dll - - # From .NET tool - mcp-excel - `````` - - ### 🎯 Development Features - - **Power Query Development**: M code refactoring with AI assistance - - **VBA Enhancement**: Error handling and code quality improvements - - **Code Review**: AI-powered analysis of Excel automation code - - **Version Control**: Export/import for Git workflows - - **Testing**: Automated Excel development workflows - - ### ⚙️ Requirements - - Windows OS with Microsoft Excel installed - - .NET 8.0 runtime - "@ - - # Create the release - gh release create "$tagName" "ExcelMcp-$version-windows.zip" --title "ExcelMcp $tagName" --notes $releaseNotes - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - shell: pwsh \ No newline at end of file diff --git a/Directory.Build.props b/Directory.Build.props index 822e1c0c..e5810d53 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -6,13 +6,13 @@ 1.0.0.0 1.0.0.0 Stefan Broenner - Stefan Broenner - ExcelCLI + Sbroenne + Sbroenne.ExcelMcp Copyright © 2025 Stefan Broenner - https://github.com/sbroenne/ExcelCLI - https://github.com/sbroenne/ExcelCLI + https://github.com/sbroenne/mcp-server-excel + https://github.com/sbroenne/mcp-server-excel git LICENSE @@ -24,6 +24,10 @@ CA1416;CS8602;SYSLIB1045;IL2026;IL3050 + + true + true + true latest diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md deleted file mode 100644 index e6d46140..00000000 --- a/MIGRATION_GUIDE.md +++ /dev/null @@ -1,187 +0,0 @@ -# Migration Guide: Moving to mcp-server-excel - -This guide outlines the process for migrating the ExcelMcp project to the new repository at `https://github.com/sbroenne/mcp-server-excel.git` without preserving Git history. - -## Prerequisites - -1. Ensure you have created the new repository at GitHub: `https://github.com/sbroenne/mcp-server-excel.git` -2. Have write access to the new repository -3. Have all your changes committed in the current repository - -## Migration Steps - -### Option 1: Direct Push (No History) - -```powershell -# 1. Navigate to your current repository -cd d:\source\ExcelCLI - -# 2. Add the new remote -git remote add new-origin https://github.com/sbroenne/mcp-server-excel.git - -# 3. Create a fresh branch without history -git checkout --orphan main-new - -# 4. Stage all files -git add -A - -# 5. Create initial commit -git commit -m "Initial commit: ExcelMcp - Excel Command Line Interface and MCP Server - -Migrated from github.com/sbroenne/ExcelCLI -- Complete CLI tool for Excel automation -- MCP Server for AI-assisted Excel development -- Power Query, VBA, and worksheet operations -- Comprehensive test suite and documentation" - -# 6. Push to new repository -git push new-origin main-new:main - -# 7. Clean up old remote reference -git remote remove new-origin -``` - -### Option 2: Pull Request Approach (Recommended) - -This approach creates a PR in the new repository for review before merging: - -```powershell -# 1. Navigate to your current repository -cd d:\source\ExcelCLI - -# 2. Add the new remote -git remote add new-origin https://github.com/sbroenne/mcp-server-excel.git - -# 3. Fetch the new repository (if it has any initial content) -git fetch new-origin - -# 4. Create a fresh branch without history -git checkout --orphan migration-pr - -# 5. Stage all files -git add -A - -# 6. Create initial commit -git commit -m "Initial commit: ExcelMcp - Excel Command Line Interface and MCP Server - -Migrated from github.com/sbroenne/ExcelCLI - -Key Features: -- CLI tool for Excel automation (Power Query, VBA, worksheets) -- MCP Server for AI-assisted Excel development workflows -- Comprehensive test suite with unit, integration, and round-trip tests -- Security-focused with input validation and resource limits -- Well-documented with extensive developer guides - -Components: -- ExcelMcp.Core: Shared Excel COM interop operations -- ExcelMcp: Command-line interface executable -- ExcelMcp.McpServer: Model Context Protocol server -- ExcelMcp.Tests: Comprehensive test suite - -Documentation: -- README.md: Project overview and quick start -- docs/COMMANDS.md: Complete command reference -- docs/DEVELOPMENT.md: Developer guide for contributors -- docs/COPILOT.md: GitHub Copilot integration patterns -- .github/copilot-instructions.md: AI assistant instructions" - -# 7. Push to new repository as a feature branch -git push new-origin migration-pr - -# 8. Create Pull Request via GitHub UI -# - Go to https://github.com/sbroenne/mcp-server-excel -# - You'll see a prompt to create PR from migration-pr branch -# - Add detailed description about the migration -# - Review changes and merge when ready - -# 9. After PR is merged, update your local repository -git checkout main -git remote set-url origin https://github.com/sbroenne/mcp-server-excel.git -git fetch origin -git reset --hard origin/main - -# 10. Clean up migration branch -git branch -D migration-pr -``` - -## Post-Migration Tasks - -### 1. Update Repository References - -Update all references to the old repository URL in: - -- [ ] `README.md` - Update any links or references -- [ ] `docs/INSTALLATION.md` - Update installation instructions -- [ ] `.github/workflows/*.yml` - Update any workflow references -- [ ] `ExcelMcp.csproj` and other project files - Check for repository URLs -- [ ] `Directory.Build.props` - Update package metadata - -### 2. Configure New Repository - -In the new GitHub repository, configure: - -- [ ] Branch protection rules for `main` -- [ ] Required status checks (CI/CD) -- [ ] Code owners (if applicable) -- [ ] Repository description and topics -- [ ] Enable GitHub Pages (if documentation site exists) -- [ ] Configure secrets for CI/CD - -### 3. Update CI/CD Workflows - -Verify all GitHub Actions workflows work in the new repository: - -- [ ] Build and test workflow -- [ ] Release workflow -- [ ] Any deployment workflows - -### 4. Update Documentation - -- [ ] Update README badges with new repository path -- [ ] Update contributing guidelines -- [ ] Update issue/PR templates -- [ ] Add migration note to documentation - -### 5. Notify Users - -If this is a public project: - -- [ ] Create an issue in the old repository noting the migration -- [ ] Update old repository README with migration notice -- [ ] Archive the old repository (optional) - -## Verification Checklist - -After migration, verify: - -- [ ] All files are present in new repository -- [ ] `.gitignore` is working correctly -- [ ] CI/CD pipelines execute successfully -- [ ] All documentation links work -- [ ] NuGet package publishing works (if applicable) -- [ ] MCP server configuration is correct -- [ ] Tests pass in new repository - -## Rollback Plan - -If issues arise, you can: - -1. Keep the old repository active until migration is confirmed successful -2. The old repository remains at `https://github.com/sbroenne/ExcelCLI.git` -3. No data is lost in the original location - -## Notes - -- This migration does NOT preserve Git history (as requested) -- All files are preserved, only commit history is reset -- The old repository can be archived or deleted after successful migration -- Consider adding a "migrated from" note in the new repository's README - -## Questions? - -Review the documentation: - -- GitHub's guide on renaming/moving repositories -- Git documentation on orphan branches -- Model Context Protocol server setup diff --git a/README.md b/README.md index d1b2da60..8d7ea096 100644 --- a/README.md +++ b/README.md @@ -1,116 +1,113 @@ -# ExcelMcp - Excel MCP Server and CLI for AI-Powered Development +# ExcelMcp - Excel MCP Server for AI-Powered Development -[![Build](https://github.com/sbroenne/mcp-server-excel/actions/workflows/build.yml/badge.svg)](https://github.com/sbroenne/mcp-server-excel/actions/workflows/build.yml) +[![Build MCP Server](https://github.com/sbroenne/mcp-server-excel/actions/workflows/build-mcp-server.yml/badge.svg)](https://github.com/sbroenne/mcp-server-excel/actions/workflows/build-mcp-server.yml) +[![Build CLI](https://github.com/sbroenne/mcp-server-excel/actions/workflows/build-cli.yml/badge.svg)](https://github.com/sbroenne/mcp-server-excel/actions/workflows/build-cli.yml) [![Release](https://img.shields.io/github/v/release/sbroenne/mcp-server-excel)](https://github.com/sbroenne/mcp-server-excel/releases/latest) -[![NuGet](https://img.shields.io/nuget/v/ExcelMcp.McpServer.svg)](https://www.nuget.org/packages/ExcelMcp.McpServer) +[![NuGet](https://img.shields.io/nuget/v/Sbroenne.ExcelMcp.McpServer.svg)](https://www.nuget.org/packages/Sbroenne.ExcelMcp.McpServer) [![Downloads](https://img.shields.io/github/downloads/sbroenne/mcp-server-excel/total)](https://github.com/sbroenne/mcp-server-excel/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![.NET](https://img.shields.io/badge/.NET-8.0-blue.svg)](https://dotnet.microsoft.com/download/dotnet/8.0) +[![.NET](https://img.shields.io/badge/.NET-10.0-blue.svg)](https://dotnet.microsoft.com/download/dotnet/10.0) [![Platform](https://img.shields.io/badge/platform-Windows-lightgrey.svg)](https://github.com/sbroenne/mcp-server-excel) [![Built with Copilot](https://img.shields.io/badge/Built%20with-GitHub%20Copilot-0366d6.svg)](https://copilot.github.com/) -`Excel Development` • `Power Query CLI` • `VBA Command Line` • `Excel COM Interop` • `MCP Server` +`MCP Server` • `Excel Development` • `AI Assistant Integration` • `Model Context Protocol` • `GitHub Copilot` -A comprehensive command-line interface tool designed specifically for **Excel development workflows** with **AI assistants** and **coding agents**. ExcelMcp enables GitHub Copilot, Claude, ChatGPT, and other AI tools to refactor Power Query M code, enhance VBA macros, review Excel automation code, and manage development workflows—all without requiring the Excel UI. +A **Model Context Protocol (MCP) server** that enables **AI assistants** like GitHub Copilot, Claude, and ChatGPT to perform Excel development tasks through conversational interfaces. Transform Excel development workflows with AI-assisted Power Query refactoring, VBA enhancement, code review, and automation—all through natural language interactions. -**🎯 How does it work?** ExcelMcp controls the actual Excel application itself (not just Excel files), providing access to Power Query transformations, VBA execution environment, and all native Excel development features through COM interop. +**🎯 How does it work?** The MCP server provides AI assistants with structured access to Excel operations through 6 resource-based tools, enabling conversational Excel development workflows while maintaining the power of direct Excel COM interop integration. -## 🔍 **Perfect for Excel Development with AI Assistants** +## 🤖 **AI-Powered Excel Development** -- **GitHub Copilot** - Built specifically for AI-powered Excel development workflows -- **Claude, ChatGPT, Cursor** - Command-line interface ideal for Excel code development -- **Power Query Development** - Refactor and optimize M code with AI assistance -- **VBA Development** - Enhance macros with error handling and best practices -- **Code Review & Testing** - Automated Excel development workflows and CI/CD +- **GitHub Copilot** - Native MCP integration for conversational Excel development +- **Claude & ChatGPT** - Natural language Excel operations through MCP protocol +- **Power Query AI Enhancement** - AI-assisted M code refactoring and optimization +- **VBA AI Development** - Intelligent macro enhancement with error handling +- **Conversational Workflows** - Ask AI to perform complex Excel tasks naturally ## 🚀 Quick Start -### Option 1: Download Pre-built Binary (Recommended) +### Install MCP Server using Microsoft's NuGet MCP Approach (Recommended) ```powershell -# Download from https://github.com/sbroenne/mcp-server-excel/releases -# Extract ExcelCLI-1.0.3-windows.zip to C:\Tools\ExcelMcp +# Install .NET 10 SDK first (required for dnx command) +winget install Microsoft.DotNet.SDK.10 -# Add to PATH (optional) -$env:PATH += ";C:\Tools\ExcelCLI" - -# Basic usage -ExcelMcp --version -ExcelMcp create-empty "test.xlsx" -ExcelMcp sheet-read "test.xlsx" "Sheet1" - -# For VBA operations (one-time setup) -ExcelMcp setup-vba-trust -ExcelMcp create-empty "macros.xlsm" +# Download and execute MCP server using dnx +dnx Sbroenne.ExcelMcp.McpServer@latest --yes ``` -### Option 2: Install MCP Server as .NET Tool (NuGet) +The `dnx` command automatically downloads the latest version from NuGet.org and executes the MCP server. This follows Microsoft's official [NuGet MCP approach](https://learn.microsoft.com/en-us/nuget/concepts/nuget-mcp) for packaging and distributing MCP servers. -```powershell -# Install globally as .NET tool -dotnet tool install --global ExcelMcp.McpServer +> **Note:** The MCP server will appear to "hang" after startup - this is expected behavior as it waits for MCP protocol messages from your AI assistant. -# Run MCP server -mcp-excel +### Configure with AI Assistants + +**GitHub Copilot Integration:** -# Update to latest version -dotnet tool update --global ExcelMcp.McpServer +```json +// Add to your VS Code settings.json or MCP client configuration +{ + "mcp": { + "servers": { + "excel": { + "command": "dnx", + "args": ["Sbroenne.ExcelMcp.McpServer@latest", "--yes"], + "description": "Excel development operations through MCP" + } + } + } +} +``` -# Uninstall -dotnet tool uninstall --global ExcelMcp.McpServer +**Claude Desktop Integration:** + +```json +// Add to Claude Desktop MCP configuration +{ + "mcpServers": { + "excel": { + "command": "dnx", + "args": ["Sbroenne.ExcelMcp.McpServer@latest", "--yes"] + } + } +} ``` -### Option 3: Build from Source +### Build from Source ```powershell # Clone and build git clone https://github.com/sbroenne/mcp-server-excel.git -cd ExcelMcp +cd mcp-server-excel dotnet build -c Release -# Run tests (requires Excel installed locally) -dotnet test +# Run MCP server +dotnet run --project src/ExcelMcp.McpServer -# Basic usage -.\src\ExcelMcp\bin\Release\net8.0\ExcelMcp.exe --version -.\src\ExcelMcp\bin\Release\net8.0\ExcelMcp.exe create-empty "test.xlsx" +# Run tests (requires Excel installed locally) +dotnet test --filter "Category=Unit" ``` ## ✨ Key Features -- 🤖 **AI Development Assistant** - Built for GitHub Copilot and AI-assisted Excel development -- 🔧 **Power Query Development** - Extract, refactor, and version control M code with AI assistance -- 📋 **VBA Development Tools** - Enhance macros, add error handling, and manage VBA modules -- 📊 **Excel Development API** - 40+ commands for Excel development workflows and testing -- 🛡️ **Production Ready** - Enterprise-grade with security validation and robust error handling -- 💾 **COM Interop Excellence** - Controls the actual Excel application for full development access -- 🔄 **Development Integration** - Perfect for CI/CD pipelines and Excel development workflows -- 📈 **Code Quality Focus** - Excel development with proper testing and code review practices - -## 🧠 **MCP Server for AI Development** *(New!)* - -ExcelMcp includes a **Model Context Protocol (MCP) server** for AI assistants like GitHub Copilot to provide conversational Excel development workflows - Power Query refactoring, VBA enhancement, and code review. +- 🤖 **MCP Protocol Integration** - Native support for AI assistants through Model Context Protocol +- �️ **Conversational Interface** - Natural language Excel operations with AI assistants +- � **Resource-Based Architecture** - 6 structured tools instead of 40+ individual commands +- � **AI-Assisted Development** - Power Query refactoring, VBA enhancement, code review +- 🧠 **Smart Context Management** - AI assistants understand Excel development workflows +- 💾 **Full Excel Integration** - Controls actual Excel application for complete feature access +- �️ **Production Ready** - Enterprise-grade with security validation and robust error handling +- 📈 **Development Focus** - Optimized for Excel development, not data processing workflows > 📚 **[Complete MCP Server Guide →](src/ExcelMcp.McpServer/README.md)** - Setup, configuration, and AI integration examples -## 🏷️ **Keywords & Technologies** - -**Primary:** `Excel CLI`, `Excel Development`, `Power Query CLI`, `VBA Command Line`, `Excel COM Interop` - -**AI/Development:** `GitHub Copilot`, `MCP Server`, `Model Context Protocol`, `AI Assistant`, `Code Refactoring`, `VBA Development` - -**Technologies:** `.NET 8`, `C#`, `COM Interop`, `Windows`, `PowerShell`, `Command Line Interface`, `MCP Protocol` - -**Excel Features:** `Power Query M Code`, `VBA Macros`, `Excel Worksheets`, `Named Ranges`, `Excel Formulas` - -**Use Cases:** `Excel Development`, `Power Query Refactoring`, `VBA Coding`, `Code Review`, `Development Testing` - ## 📖 Documentation | Document | Description | |----------|-------------| -| **[📋 Command Reference](docs/COMMANDS.md)** | Complete reference for all 40+ ExcelMcp commands | -| **[🧠 MCP Server](src/ExcelMcp.McpServer/README.md)** | Model Context Protocol server for AI assistant integration | +| **[🧠 MCP Server Guide](src/ExcelMcp.McpServer/README.md)** | Complete MCP server setup and AI integration examples | +| **[🔧 ExcelMcp.CLI](docs/CLI.md)** | Command-line interface for direct Excel automation | +| **[📋 Command Reference](docs/COMMANDS.md)** | Complete reference for all 40+ CLI commands | | **[⚙️ Installation Guide](docs/INSTALLATION.md)** | Building from source and installation options | | **[🤖 GitHub Copilot Integration](docs/COPILOT.md)** | Using ExcelMcp with GitHub Copilot | | **[🔧 Development Workflow](docs/DEVELOPMENT.md)** | Contributing guidelines and PR requirements | @@ -139,40 +136,33 @@ ExcelMcp includes a **Model Context Protocol (MCP) server** for AI assistants li - **Development Environment** - Create and configure Excel files for coding workflows - **Documentation** - Generate code documentation and comments for Excel automation -## 🔄 **Compared to Excel Development Alternatives** - -| Feature | ExcelMcp | Python openpyxl | Excel VBA | PowerShell Excel | -|---------|----------|-----------------|-----------|------------------| -| **Power Query Development** | ✅ Full M code access | ❌ No support | ❌ Limited | ❌ No support | -| **VBA Development** | ✅ Full module control | ❌ No support | ✅ Native | ✅ Limited | -| **AI Development Assistant** | ✅ Built for Copilot | ⚠️ Requires custom setup | ❌ Manual only | ⚠️ Complex integration | -| **Development Approach** | ✅ **Excel App Control** | ❌ File parsing only | ✅ **Excel App Control** | ✅ **Excel App Control** | -| **CLI Development Tools** | ✅ Purpose-built CLI | ⚠️ Script required | ❌ No CLI | ⚠️ Complex commands | -| **Excel Installation** | ⚠️ **Required** | ✅ Not needed | ⚠️ **Required** | ⚠️ **Required** | -| **Cross-Platform** | ❌ Windows only | ✅ Cross-platform | ❌ Windows only | ❌ Windows only | - ## ⚙️ System Requirements | Requirement | Details | Why Required | |-------------|---------|--------------| | **Windows OS** | Windows 10/11 or Server | COM interop is Windows-specific | | **Microsoft Excel** | Any recent version (2016+) | ExcelMcp controls the actual Excel application | -| **.NET 8.0 Runtime** | [Download here](https://dotnet.microsoft.com/download/dotnet/8.0) | ExcelMcp runtime dependency | +| **.NET 10 SDK** | `winget install Microsoft.DotNet.SDK.10` | Required for `dnx` command execution | > **🚨 Critical:** ExcelMcp controls the actual running Excel application through COM interop, not just Excel file formats. This provides access to Excel's full feature set (Power Query engine, VBA runtime, formula calculations, charts, pivot tables) but requires Excel to be installed and available for automation. -## 📋 Commands Overview +## 6️⃣ MCP Tools Overview + +The MCP server provides 6 resource-based tools for AI assistants: + +- **excel_file** - File management (create, validate, check-exists) +- **excel_powerquery** - Power Query operations (list, view, import, export, update, refresh, delete) +- **excel_worksheet** - Worksheet operations (list, read, write, create, rename, copy, delete, clear, append) +- **excel_parameter** - Named range management (list, get, set, create, delete) +- **excel_cell** - Cell operations (get-value, set-value, get-formula, set-formula) +- **excel_vba** - VBA script management (list, export, import, update, run, delete) -ExcelMcp provides 40+ commands across 6 categories: +> 🧠 **[Complete MCP Server Guide →](src/ExcelMcp.McpServer/README.md)** - Detailed MCP integration and AI examples -- **File Operations** (2) - Create Excel workbooks (.xlsx, .xlsm) -- **Power Query** (8) - M code management and data transformation -- **VBA Scripts** (6) - Macro development and execution -- **Worksheets** (9) - Data manipulation and sheet management -- **Parameters** (5) - Named range configuration -- **Cells** (4) - Individual cell operations +## 🔗 Additional Tools -> 📖 **[Complete Command Reference →](docs/COMMANDS.md)** - Detailed syntax and examples for all commands +- **[ExcelMcp.CLI](docs/CLI.md)** - Command-line interface for direct Excel automation +- **[Command Reference](docs/COMMANDS.md)** - All 40+ CLI commands for script-based workflows ## 🤝 Contributing @@ -184,7 +174,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file ## 🏷️ **SEO & Discovery Tags** -**Excel CLI** | **Power Query CLI** | **VBA Command Line** | **Excel Development** | **MCP Server** | **Model Context Protocol** | **AI Excel Development** | **GitHub Copilot Excel** | **Power Query Refactoring** | **VBA Development** | **Excel Code Review** | **Excel COM Interop** | **Excel DevOps** +**MCP Server** | **Model Context Protocol** | **AI Excel Development** | **GitHub Copilot Excel** | **Excel MCP** | **Conversational Excel** | **AI Assistant Integration** | **Power Query AI** | **VBA AI Development** | **Excel Code Review** | **Excel COM Interop** | **Excel Development AI** ## �🙏 Acknowledgments diff --git a/SECURITY.md b/SECURITY.md index 3a68ab4f..38ad9d50 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -14,23 +14,27 @@ We actively support the following versions of ExcelMcp with security updates: ExcelMcp includes several security measures: ### Input Validation + - **Path Traversal Protection**: All file paths are validated with `Path.GetFullPath()` - **File Size Limits**: 1GB maximum file size to prevent DoS attacks - **Extension Validation**: Only `.xlsx` and `.xlsm` files are accepted - **Path Length Validation**: Maximum 32,767 characters (Windows limit) ### Code Analysis + - **Enhanced Security Rules**: CA2100, CA3003, CA3006, CA5389, CA5390, CA5394 enforced as errors - **Treat Warnings as Errors**: All code quality issues must be resolved - **Static Analysis**: SecurityCodeScan.VS2019 package integrated - **CodeQL Scanning**: Automated security scanning on every push ### COM Security + - **Controlled Excel Automation**: Excel.Application runs with `Visible=false` and `DisplayAlerts=false` - **Resource Cleanup**: Comprehensive COM object disposal and garbage collection - **No Remote Connections**: Only local Excel automation supported ### Dependency Management + - **Dependabot**: Automated dependency updates and security patches - **Dependency Review**: Pull request scanning for vulnerable dependencies - **Central Package Management**: Consistent versioning across all projects @@ -40,13 +44,16 @@ ExcelMcp includes several security measures: We take security vulnerabilities seriously. If you discover a security issue, please follow these steps: ### 1. **DO NOT** Create a Public Issue + Please do not create a public GitHub issue for security vulnerabilities. This could put all users at risk. ### 2. Report Privately + Report security vulnerabilities using one of these methods: **Preferred Method: GitHub Security Advisories** -1. Go to https://github.com/sbroenne/mcp-server-excel/security/advisories + +1. Go to 2. Click "Report a vulnerability" 3. Fill out the advisory form with detailed information @@ -56,6 +63,7 @@ Send an email to: [maintainer email - to be added] Subject: `[SECURITY] ExcelMcp Vulnerability Report` ### 3. Information to Include + Please provide as much information as possible: - **Description**: Clear description of the vulnerability @@ -65,6 +73,7 @@ Please provide as much information as possible: - **Suggested Fix**: If you have a fix or mitigation (optional) Example: + ``` Vulnerability: Path traversal in file operations Impact: Attacker could read/write files outside intended directory @@ -78,13 +87,14 @@ Suggested Fix: Validate resolved paths are within allowed directories - **Acknowledgment**: Within 48 hours - **Initial Assessment**: Within 5 business days - **Status Updates**: Regular updates on progress -- **Fix Timeline**: +- **Fix Timeline**: - Critical: 7 days - High: 30 days - Medium: 90 days - Low: Best effort ### 5. Coordinated Disclosure + We follow responsible disclosure practices: 1. **Private Fix**: We'll develop a fix privately @@ -96,18 +106,21 @@ We follow responsible disclosure practices: ## Security Best Practices for Users ### MCP Server Security + - **Validate AI Requests**: Review Excel operations requested by AI assistants - **File Path Restrictions**: Only allow MCP Server access to specific directories - **Audit Logs**: Monitor MCP Server operations in logs - **Trust Configuration**: Only enable VBA trust when necessary ### CLI Security + - **Script Validation**: Review automation scripts before execution - **File Permissions**: Ensure Excel files have appropriate permissions - **Isolated Environment**: Run in sandboxed environment when processing untrusted files - **Excel Security Settings**: Maintain appropriate Excel macro security settings ### Development Security + - **Code Review**: All changes require review before merge - **Branch Protection**: Main branch protected with required checks - **Signed Commits**: Consider using signed commits (recommended) @@ -116,17 +129,20 @@ We follow responsible disclosure practices: ## Known Security Considerations ### Excel COM Automation + - **Local Only**: ExcelMcp only supports local Excel automation - **Windows Only**: Requires Windows with Excel installed - **Excel Process**: Creates Excel.Application COM objects - **Macro Security**: VBA operations require user consent via `setup-vba-trust` ### File System Access + - **Full Path Resolution**: All paths resolved to absolute paths - **No Network Paths**: UNC paths and network drives not supported - **Current User Context**: Operations run with current user permissions ### AI Integration (MCP Server) + - **Trusted AI Assistants**: Only use with trusted AI platforms - **Request Validation**: Review operations before Excel executes them - **Sensitive Data**: Avoid exposing workbooks with sensitive data to AI assistants @@ -135,8 +151,9 @@ We follow responsible disclosure practices: ## Security Updates Security updates are published through: -- **GitHub Security Advisories**: https://github.com/sbroenne/mcp-server-excel/security/advisories -- **Release Notes**: https://github.com/sbroenne/mcp-server-excel/releases + +- **GitHub Security Advisories**: +- **Release Notes**: - **NuGet Advisories**: Package vulnerabilities shown in NuGet Subscribe to repository notifications to receive security alerts. @@ -144,12 +161,14 @@ Subscribe to repository notifications to receive security alerts. ## Vulnerability Disclosure Policy ### Our Commitment + - We will acknowledge receipt of vulnerability reports within 48 hours - We will keep reporters informed of progress - We will credit researchers in security advisories (if desired) - We will not take legal action against researchers following responsible disclosure ### Researcher Guidelines + - **Responsible Disclosure**: Give us time to fix before public disclosure - **No Harm**: Do not access, modify, or delete other users' data - **Good Faith**: Act in good faith to help improve security @@ -157,7 +176,7 @@ Subscribe to repository notifications to receive security alerts. ## Security Contacts -- **GitHub Security**: https://github.com/sbroenne/mcp-server-excel/security +- **GitHub Security**: - **Maintainer**: @sbroenne ## Additional Resources diff --git a/ExcelMcp.sln b/Sbroenne.ExcelMcp.sln similarity index 65% rename from ExcelMcp.sln rename to Sbroenne.ExcelMcp.sln index 9c4c635d..1622a687 100644 --- a/ExcelMcp.sln +++ b/Sbroenne.ExcelMcp.sln @@ -5,11 +5,13 @@ VisualStudioVersion = 17.0.31903.59 MinimumVisualStudioVersion = 10.0.40219.1 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{827E0CD3-B72D-47B6-A68D-7590B98EB39B}" EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ExcelMcp", "src\ExcelMcp\ExcelMcp.csproj", "{3ACC5AFF-2C15-4546-BDDC-6785C9D79B72}" +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ExcelMcp.CLI", "src\ExcelMcp.CLI\ExcelMcp.CLI.csproj", "{3ACC5AFF-2C15-4546-BDDC-6785C9D79B72}" EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{0AB3BF05-4346-4AA6-1389-037BE0695223}" EndProject -Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ExcelMcp.Tests", "tests\ExcelMcp.Tests\ExcelMcp.Tests.csproj", "{EA8077F0-2FDB-4433-BEF7-5012C7EBC213}" +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ExcelMcp.CLI.Tests", "tests\ExcelMcp.CLI.Tests\ExcelMcp.CLI.Tests.csproj", "{B1234567-1234-1234-1234-123456789ABC}" +EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ExcelMcp.McpServer.Tests", "tests\ExcelMcp.McpServer.Tests\ExcelMcp.McpServer.Tests.csproj", "{C2345678-2345-2345-2345-23456789ABCD}" EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ExcelMcp.Core", "src\ExcelMcp.Core\ExcelMcp.Core.csproj", "{819048D2-BF4F-4D6C-A7C3-B37869988003}" EndProject @@ -37,18 +39,30 @@ Global {3ACC5AFF-2C15-4546-BDDC-6785C9D79B72}.Release|x64.Build.0 = Release|Any CPU {3ACC5AFF-2C15-4546-BDDC-6785C9D79B72}.Release|x86.ActiveCfg = Release|Any CPU {3ACC5AFF-2C15-4546-BDDC-6785C9D79B72}.Release|x86.Build.0 = Release|Any CPU - {EA8077F0-2FDB-4433-BEF7-5012C7EBC213}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {EA8077F0-2FDB-4433-BEF7-5012C7EBC213}.Debug|Any CPU.Build.0 = Debug|Any CPU - {EA8077F0-2FDB-4433-BEF7-5012C7EBC213}.Debug|x64.ActiveCfg = Debug|Any CPU - {EA8077F0-2FDB-4433-BEF7-5012C7EBC213}.Debug|x64.Build.0 = Debug|Any CPU - {EA8077F0-2FDB-4433-BEF7-5012C7EBC213}.Debug|x86.ActiveCfg = Debug|Any CPU - {EA8077F0-2FDB-4433-BEF7-5012C7EBC213}.Debug|x86.Build.0 = Debug|Any CPU - {EA8077F0-2FDB-4433-BEF7-5012C7EBC213}.Release|Any CPU.ActiveCfg = Release|Any CPU - {EA8077F0-2FDB-4433-BEF7-5012C7EBC213}.Release|Any CPU.Build.0 = Release|Any CPU - {EA8077F0-2FDB-4433-BEF7-5012C7EBC213}.Release|x64.ActiveCfg = Release|Any CPU - {EA8077F0-2FDB-4433-BEF7-5012C7EBC213}.Release|x64.Build.0 = Release|Any CPU - {EA8077F0-2FDB-4433-BEF7-5012C7EBC213}.Release|x86.ActiveCfg = Release|Any CPU - {EA8077F0-2FDB-4433-BEF7-5012C7EBC213}.Release|x86.Build.0 = Release|Any CPU + {B1234567-1234-1234-1234-123456789ABC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {B1234567-1234-1234-1234-123456789ABC}.Debug|Any CPU.Build.0 = Debug|Any CPU + {B1234567-1234-1234-1234-123456789ABC}.Debug|x64.ActiveCfg = Debug|Any CPU + {B1234567-1234-1234-1234-123456789ABC}.Debug|x64.Build.0 = Debug|Any CPU + {B1234567-1234-1234-1234-123456789ABC}.Debug|x86.ActiveCfg = Debug|Any CPU + {B1234567-1234-1234-1234-123456789ABC}.Debug|x86.Build.0 = Debug|Any CPU + {B1234567-1234-1234-1234-123456789ABC}.Release|Any CPU.ActiveCfg = Release|Any CPU + {B1234567-1234-1234-1234-123456789ABC}.Release|Any CPU.Build.0 = Release|Any CPU + {B1234567-1234-1234-1234-123456789ABC}.Release|x64.ActiveCfg = Release|Any CPU + {B1234567-1234-1234-1234-123456789ABC}.Release|x64.Build.0 = Release|Any CPU + {B1234567-1234-1234-1234-123456789ABC}.Release|x86.ActiveCfg = Release|Any CPU + {B1234567-1234-1234-1234-123456789ABC}.Release|x86.Build.0 = Release|Any CPU + {C2345678-2345-2345-2345-23456789ABCD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {C2345678-2345-2345-2345-23456789ABCD}.Debug|Any CPU.Build.0 = Debug|Any CPU + {C2345678-2345-2345-2345-23456789ABCD}.Debug|x64.ActiveCfg = Debug|Any CPU + {C2345678-2345-2345-2345-23456789ABCD}.Debug|x64.Build.0 = Debug|Any CPU + {C2345678-2345-2345-2345-23456789ABCD}.Debug|x86.ActiveCfg = Debug|Any CPU + {C2345678-2345-2345-2345-23456789ABCD}.Debug|x86.Build.0 = Debug|Any CPU + {C2345678-2345-2345-2345-23456789ABCD}.Release|Any CPU.ActiveCfg = Release|Any CPU + {C2345678-2345-2345-2345-23456789ABCD}.Release|Any CPU.Build.0 = Release|Any CPU + {C2345678-2345-2345-2345-23456789ABCD}.Release|x64.ActiveCfg = Release|Any CPU + {C2345678-2345-2345-2345-23456789ABCD}.Release|x64.Build.0 = Release|Any CPU + {C2345678-2345-2345-2345-23456789ABCD}.Release|x86.ActiveCfg = Release|Any CPU + {C2345678-2345-2345-2345-23456789ABCD}.Release|x86.Build.0 = Release|Any CPU {819048D2-BF4F-4D6C-A7C3-B37869988003}.Debug|Any CPU.ActiveCfg = Debug|Any CPU {819048D2-BF4F-4D6C-A7C3-B37869988003}.Debug|Any CPU.Build.0 = Debug|Any CPU {819048D2-BF4F-4D6C-A7C3-B37869988003}.Debug|x64.ActiveCfg = Debug|Any CPU @@ -79,7 +93,8 @@ Global EndGlobalSection GlobalSection(NestedProjects) = preSolution {3ACC5AFF-2C15-4546-BDDC-6785C9D79B72} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B} - {EA8077F0-2FDB-4433-BEF7-5012C7EBC213} = {0AB3BF05-4346-4AA6-1389-037BE0695223} + {B1234567-1234-1234-1234-123456789ABC} = {0AB3BF05-4346-4AA6-1389-037BE0695223} + {C2345678-2345-2345-2345-23456789ABCD} = {0AB3BF05-4346-4AA6-1389-037BE0695223} {819048D2-BF4F-4D6C-A7C3-B37869988003} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B} {C9CF661A-9104-417F-A3EF-F9D5E4D59681} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B} EndGlobalSection diff --git a/docs/AUTHOR.md b/docs/AUTHOR.md index 95ecfdd0..cda6cb14 100644 --- a/docs/AUTHOR.md +++ b/docs/AUTHOR.md @@ -15,7 +15,7 @@ ExcelMcp was born from the need for a simple, reliable way for coding agents lik ### Contact -For questions, contributions, or collaboration opportunities related to ExcelCLI: +For questions, contributions, or collaboration opportunities related to Sbroenne.ExcelMcp: - **Email**: [stefan_broenner@yahoo.com](mailto:stefan_broenner@yahoo.com) - **GitHub Issues**: [ExcelMcp Issues](https://github.com/sbroenne/mcp-server-excel/issues) diff --git a/docs/CLI.md b/docs/CLI.md new file mode 100644 index 00000000..799490c4 --- /dev/null +++ b/docs/CLI.md @@ -0,0 +1,130 @@ +# ExcelMcp.CLI - Excel Command Line Interface + +[![Build CLI](https://github.com/sbroenne/mcp-server-excel/actions/workflows/build-cli.yml/badge.svg)](https://github.com/sbroenne/mcp-server-excel/actions/workflows/build-cli.yml) +[![Release](https://img.shields.io/github/v/release/sbroenne/mcp-server-excel)](https://github.com/sbroenne/mcp-server-excel/releases/latest) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![.NET](https://img.shields.io/badge/.NET-10.0-blue.svg)](https://dotnet.microsoft.com/download/dotnet/10.0) +[![Platform](https://img.shields.io/badge/platform-Windows-lightgrey.svg)](https://github.com/sbroenne/mcp-server-excel) + +`Excel Automation` • `Power Query CLI` • `VBA Command Line` • `Excel COM Interop` • `Development Tools` + +A comprehensive command-line interface tool for **Excel development workflows** and **automation**. ExcelMcp.CLI provides direct programmatic access to Microsoft Excel through COM interop, enabling developers to manage Excel workbooks, Power Query transformations, VBA scripts, and data operations without requiring the Excel UI. + +**🎯 How does it work?** ExcelMcp.CLI controls the actual Excel application itself (not just Excel files), providing access to Power Query transformations, VBA execution environment, and all native Excel development features through COM interop. + +## 🚀 Quick Start + +### Download Pre-built Binary (Recommended) + +```powershell +# Download from https://github.com/sbroenne/mcp-server-excel/releases +# Extract excelcli-{version}-windows.zip to C:\Tools\excelcli + +# Add to PATH (optional) +$env:PATH += ";C:\Tools\excelcli" + +# Basic usage +excelcli create-empty "test.xlsx" +excelcli sheet-read "test.xlsx" "Sheet1" + +# For VBA operations (one-time setup) +excelcli setup-vba-trust +excelcli create-empty "macros.xlsm" +``` + +### Build from Source + +```powershell +# Clone and build +git clone https://github.com/sbroenne/mcp-server-excel.git +cd mcp-server-excel +dotnet build -c Release + +# Run tests (requires Excel installed locally) +dotnet test --filter "Category=Unit" + +# Basic usage +.\src\ExcelMcp.CLI\bin\Release\net10.0\excelcli.exe create-empty "test.xlsx" +``` + +## ✨ Key Features + +- 🔧 **Power Query Development** - Extract, refactor, and version control M code +- 📋 **VBA Development Tools** - Manage VBA modules, run macros, and enhance code +- 📊 **Excel Automation API** - 40+ commands for Excel operations and workflows +- 💾 **COM Interop Excellence** - Controls the actual Excel application for full access +- 🛡️ **Production Ready** - Enterprise-grade with security validation and robust error handling +- 🔄 **CI/CD Integration** - Perfect for automated Excel development workflows +- 📈 **Development Focus** - Excel development with proper testing and code practices + +## 🎯 Excel Development Use Cases + +### **Power Query Development** + +- **M Code Management** - Export, import, and update Power Query transformations +- **Performance Testing** - Refresh and validate Power Query operations +- **Code Review** - Analyze M code for optimization opportunities +- **Version Control** - Export/import Power Query code for Git workflows + +### **VBA Development & Enhancement** + +- **Module Management** - Export, import, and update VBA modules +- **Macro Execution** - Run VBA macros with parameters from command line +- **Code Quality** - Implement error handling and best practices +- **Testing & Debugging** - Automated testing workflows for Excel macros + +### **Excel Automation Workflows** + +- **Data Processing** - Automate Excel data manipulation tasks +- **Report Generation** - Create and populate Excel reports programmatically +- **Configuration Management** - Manage Excel parameters through named ranges +- **Batch Operations** - Process multiple Excel files in automated workflows + +## ⚙️ System Requirements + +| Requirement | Details | Why Required | +|-------------|---------|--------------| +| **Windows OS** | Windows 10/11 or Server | COM interop is Windows-specific | +| **Microsoft Excel** | Any recent version (2016+) | ExcelMcp.CLI controls the actual Excel application | +| **.NET 10 Runtime** | [Download here](https://dotnet.microsoft.com/download/dotnet/10.0) | ExcelMcp.CLI runtime dependency | + +> **🚨 Critical:** ExcelMcp.CLI controls the actual running Excel application through COM interop, not just Excel file formats. This provides access to Excel's full feature set (Power Query engine, VBA runtime, formula calculations) but requires Excel to be installed and available for automation. + +## 📋 Commands Overview + +ExcelMcp.CLI provides 40+ commands across 6 categories: + +- **File Operations** (2) - Create Excel workbooks (.xlsx, .xlsm) +- **Power Query** (8) - M code management and data transformation +- **VBA Scripts** (6) - Macro development and execution +- **Worksheets** (9) - Data manipulation and sheet management +- **Parameters** (5) - Named range configuration +- **Cells** (4) - Individual cell operations + +> 📖 **[Complete Command Reference →](COMMANDS.md)** - Detailed syntax and examples for all commands + +## 🔗 Related Tools + +- **[ExcelMcp MCP Server](../README.md)** - Model Context Protocol server for AI assistant integration +- **[GitHub Copilot Integration](COPILOT.md)** - AI-assisted Excel development workflows + +## 📖 Documentation + +| Document | Description | +|----------|-------------| +| **[📋 Command Reference](COMMANDS.md)** | Complete reference for all 40+ ExcelMcp.CLI commands | +| **[⚙️ Installation Guide](INSTALLATION.md)** | Building from source and installation options | +| **[🤖 GitHub Copilot Integration](COPILOT.md)** | Using ExcelMcp.CLI with GitHub Copilot | +| **[🔧 Development Workflow](DEVELOPMENT.md)** | Contributing guidelines and PR requirements | + +## 🤝 Contributing + +We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. + +## 📜 License + +This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details. + +--- + +**🏠 [← Back to Main Project](../README.md)** | **🧠 [MCP Server →](../src/ExcelMcp.McpServer/README.md)** diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index dbd240be..a42f8511 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -1,6 +1,6 @@ # Command Reference -Complete reference for all ExcelMcp commands. +Complete reference for all ExcelMcp.CLI commands. ## File Commands @@ -9,7 +9,7 @@ Create and manage Excel workbooks. **create-empty** - Create empty Excel workbook ```powershell -ExcelMcp create-empty +excelcli create-empty ``` Essential for coding agents to programmatically create Excel workbooks. Use `.xlsm` extension for macro-enabled workbooks that support VBA. @@ -21,49 +21,49 @@ Manage Power Query queries in Excel workbooks. **pq-list** - List all Power Queries ```powershell -ExcelMcp pq-list +excelcli pq-list ``` **pq-view** - View Power Query M code ```powershell -ExcelMcp pq-view +excelcli pq-view ``` **pq-import** - Create or import query from file ```powershell -ExcelMcp pq-import +excelcli pq-import ``` **pq-export** - Export query to file ```powershell -ExcelMcp pq-export +excelcli pq-export ``` **pq-update** - Update existing query from file ```powershell -ExcelMcp pq-update +excelcli pq-update ``` **pq-refresh** - Refresh query data ```powershell -ExcelMcp pq-refresh +excelcli pq-refresh ``` **pq-loadto** - Load connection-only query to worksheet ```powershell -ExcelMcp pq-loadto +excelcli pq-loadto ``` **pq-delete** - Delete Power Query ```powershell -ExcelMcp pq-delete +excelcli pq-delete ``` ## Sheet Commands (`sheet-*`) @@ -73,59 +73,59 @@ Manage worksheets in Excel workbooks. **sheet-list** - List all worksheets ```powershell -ExcelMcp sheet-list +excelcli sheet-list ``` **sheet-read** - Read data from worksheet ```powershell -ExcelMcp sheet-read [range] +excelcli sheet-read [range] # Examples -ExcelMcp sheet-read "Plan.xlsx" "Data" # Read entire used range -ExcelMcp sheet-read "Plan.xlsx" "Data" "A1:C10" # Read specific range +excelcli sheet-read "Plan.xlsx" "Data" # Read entire used range +excelcli sheet-read "Plan.xlsx" "Data" "A1:C10" # Read specific range ``` **sheet-write** - Write CSV data to worksheet ```powershell -ExcelMcp sheet-write +excelcli sheet-write ``` **sheet-create** - Create new worksheet ```powershell -ExcelMcp sheet-create +excelcli sheet-create ``` **sheet-copy** - Copy worksheet ```powershell -ExcelMcp sheet-copy +excelcli sheet-copy ``` **sheet-rename** - Rename worksheet ```powershell -ExcelMcp sheet-rename +excelcli sheet-rename ``` **sheet-delete** - Delete worksheet ```powershell -ExcelMcp sheet-delete +excelcli sheet-delete ``` **sheet-clear** - Clear worksheet data ```powershell -ExcelMcp sheet-clear [range] +excelcli sheet-clear [range] ``` **sheet-append** - Append CSV data to worksheet ```powershell -ExcelMcp sheet-append +excelcli sheet-append ``` ## Parameter Commands (`param-*`) @@ -135,31 +135,31 @@ Manage named ranges and parameters. **param-list** - List all named ranges ```powershell -ExcelMcp param-list +excelcli param-list ``` **param-get** - Get named range value ```powershell -ExcelMcp param-get +excelcli param-get ``` **param-set** - Set named range value ```powershell -ExcelMcp param-set +excelcli param-set ``` **param-create** - Create named range ```powershell -ExcelMcp param-create +excelcli param-create ``` **param-delete** - Delete named range ```powershell -ExcelMcp param-delete +excelcli param-delete ``` ## Cell Commands (`cell-*`) @@ -169,25 +169,25 @@ Manage individual cells. **cell-get-value** - Get cell value ```powershell -ExcelMcp cell-get-value +excelcli cell-get-value ``` **cell-set-value** - Set cell value ```powershell -ExcelMcp cell-set-value +excelcli cell-set-value ``` **cell-get-formula** - Get cell formula ```powershell -ExcelMcp cell-get-formula +excelcli cell-get-formula ``` **cell-set-formula** - Set cell formula ```powershell -ExcelMcp cell-set-formula +excelcli cell-set-formula ``` ## VBA Script Commands (`script-*`) @@ -199,41 +199,41 @@ Manage VBA scripts and macros in macro-enabled Excel workbooks. **script-list** - List all VBA modules and procedures ```powershell -ExcelMcp script-list +excelcli script-list ``` **script-export** - Export VBA module to file ```powershell -ExcelMcp script-export +excelcli script-export ``` **script-import** - Import VBA module from file ```powershell -ExcelMcp script-import +excelcli script-import ``` **script-update** - Update existing VBA module ```powershell -ExcelMcp script-update +excelcli script-update ``` **script-run** - Execute VBA macro with parameters ```powershell -ExcelMcp script-run [param1] [param2] ... +excelcli script-run [param1] [param2] ... # Examples -ExcelMcp script-run "Report.xlsm" "ProcessData" -ExcelMcp script-run "Analysis.xlsm" "CalculateTotal" "Sheet1" "A1:C10" +excelcli script-run "Report.xlsm" "ProcessData" +excelcli script-run "Analysis.xlsm" "CalculateTotal" "Sheet1" "A1:C10" ``` **script-delete** - Remove VBA module ```powershell -ExcelMcp script-delete +excelcli script-delete ``` ## Setup Commands @@ -243,13 +243,13 @@ Configure VBA trust settings for automation. **setup-vba-trust** - Enable VBA project access ```powershell -ExcelMcp setup-vba-trust +excelcli setup-vba-trust ``` **check-vba-trust** - Check VBA trust configuration ```powershell -ExcelMcp check-vba-trust +excelcli check-vba-trust ``` ## File Format Support @@ -260,6 +260,6 @@ ExcelMcp check-vba-trust Use `create-empty` with `.xlsm` extension to create macro-enabled workbooks: ```powershell -ExcelMcp create-empty "macros.xlsm" # Creates macro-enabled workbook -ExcelMcp create-empty "data.xlsx" # Creates standard workbook -``` \ No newline at end of file +excelcli create-empty "macros.xlsm" # Creates macro-enabled workbook +excelcli create-empty "data.xlsx" # Creates standard workbook +``` diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 593371c4..66f5afee 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to ExcelMcp -Thank you for your interest in contributing to ExcelCLI! This project is designed to be extended by the community, especially to support coding agents like GitHub Copilot. +Thank you for your interest in contributing to Sbroenne.ExcelMcp! This project is designed to be extended by the community, especially to support coding agents like GitHub Copilot. ## 🎯 Project Vision @@ -18,7 +18,7 @@ ExcelMcp aims to be the go-to command-line tool for coding agents to interact wi 1. **Prerequisites**: - Windows OS (required for Excel COM) - Visual Studio 2022 or VS Code - - .NET 8.0 SDK + - .NET 10 SDK - Microsoft Excel installed 2. **Setup**: @@ -270,4 +270,4 @@ Great feature requests include: --- -Thank you for contributing to ExcelCLI! Together we're making Excel automation more accessible to coding agents and developers worldwide. 🚀 +Thank you for contributing to Sbroenne.ExcelMcp! Together we're making Excel automation more accessible to coding agents and developers worldwide. 🚀 diff --git a/docs/COPILOT.md b/docs/COPILOT.md index 545ccf4e..1448c7f9 100644 --- a/docs/COPILOT.md +++ b/docs/COPILOT.md @@ -48,14 +48,14 @@ To make GitHub Copilot aware of ExcelMcp in your own projects: ## Effective Copilot Prompting -With the ExcelMcp instructions installed, Copilot will automatically suggest ExcelMcp commands. Here's how to get the best results: +With the ExcelMcp instructions installed, Copilot will automatically suggest ExcelMcp.CLI commands. Here's how to get the best results: ### General Prompting Tips ```text -"Use ExcelMcp to..." - Start prompts this way for targeted suggestions +"Use ExcelMcp.CLI to..." - Start prompts this way for targeted suggestions "Create a complete workflow using ExcelMcp that..." - For end-to-end automation -"Help me troubleshoot this ExcelMcp command..." - For debugging assistance +"Help me troubleshoot this ExcelMcp.CLI command..." - For debugging assistance ``` ### Reference the Instructions @@ -92,7 +92,7 @@ Use pq-test to verify my query connections work properly ### Advanced Excel Automation ```text -Use ExcelMcp to refresh pq-refresh then sheet-read to extract updated data +Use ExcelMcp.CLI to refresh pq-refresh then sheet-read to extract updated data Load connection-only queries to worksheets with pq-loadto command Manage cell formulas with cell-get-formula and cell-set-formula commands Run VBA macros with script-run and check results with sheet-read commands @@ -105,17 +105,17 @@ Create macro-enabled workbooks with create-empty "file.xlsm" for VBA support ### Context-Aware Code Generation -When working with ExcelCLI, provide context to Copilot: +When working with Sbroenne.ExcelMcp, provide context to Copilot: ```text -I'm working with ExcelMcp to process Excel files. +I'm working with ExcelMcp.CLI to process Excel files. I need to: - Read data from multiple worksheets - Combine data using Power Query - Apply business logic with VBA - Export results to CSV -Generate a complete PowerShell script using ExcelMcp commands. +Generate a complete PowerShell script using ExcelMcp.CLI commands. ``` ### Error Handling Patterns @@ -123,7 +123,7 @@ Generate a complete PowerShell script using ExcelMcp commands. Ask Copilot to generate robust error handling: ```text -Create error handling for ExcelMcp commands that: +Create error handling for ExcelMcp.CLI commands that: - Checks if Excel files exist - Validates VBA trust configuration - Handles Excel COM errors gracefully @@ -158,7 +158,7 @@ Help me troubleshoot VBA trust configuration issues ``` ```text -Excel processes are not cleaning up after ExcelMcp commands +Excel processes are not cleaning up after ExcelMcp.CLI commands Help me identify and fix process cleanup issues ``` @@ -168,8 +168,8 @@ Copilot can suggest best practices: ```text What are the best practices for using ExcelMcp in CI/CD pipelines? -How should I structure ExcelMcp commands for maintainable automation scripts? -What error handling patterns should I use with ExcelCLI? +How should I structure ExcelMcp.CLI commands for maintainable automation scripts? +What error handling patterns should I use with Sbroenne.ExcelMcp? ``` ## Integration with Other Tools @@ -179,7 +179,7 @@ What error handling patterns should I use with ExcelCLI? Ask Copilot to create PowerShell wrappers: ```text -Create a PowerShell module that wraps ExcelMcp commands with: +Create a PowerShell module that wraps ExcelMcp.CLI commands with: - Parameter validation - Error handling - Logging @@ -189,7 +189,7 @@ Create a PowerShell module that wraps ExcelMcp commands with: ### Azure DevOps Integration ```text -Create Azure DevOps pipeline tasks that use ExcelMcp to: +Create Azure DevOps pipeline tasks that use ExcelMcp.CLI to: - Process Excel reports in build pipelines - Generate data exports for deployment - Validate Excel file formats and content diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index e47e2b6a..4ef3e5f0 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -191,7 +191,7 @@ dotnet test dotnet build -c Release # Test the built executable -.\src\ExcelMcp\bin\Release\net8.0\ExcelMcp.exe --version +.\src\ExcelMcp.CLI\bin\Release\net10.0\excelcli.exe --version ``` ## 📞 **Need Help?** diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index 290e5421..66bd2c8f 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -1,53 +1,116 @@ # Installation Guide -## Requirements +Choose your installation method based on your use case: + +- **🧠 MCP Server**: For AI assistant integration (GitHub Copilot, Claude, ChatGPT) +- **🔧 CLI Tool**: For direct automation and development workflows +- **📦 Combined**: Both tools for complete Excel development environment + +## 🎯 System Requirements - **Windows OS** - Required for Excel COM interop -- **Microsoft Excel** - Must be installed on the machine -- **.NET 8.0 Runtime** - Download from [Microsoft](https://dotnet.microsoft.com/download/dotnet/8.0) +- **Microsoft Excel** - Must be installed on the machine (2016+) +- **.NET 10 SDK** - Install via: `winget install Microsoft.DotNet.SDK.10` -## 📦 Installation Options +--- -### Option 1: Install MCP Server via NuGet (Recommended for MCP) +## 🧠 MCP Server Installation -Install the MCP Server as a global .NET tool: +**For AI assistant integration and conversational Excel workflows** -```powershell -# Install globally -dotnet tool install --global ExcelMcp.McpServer +### Option 1: Microsoft's NuGet MCP Approach (Recommended) -# Run the MCP server -mcp-excel +Use the official `dnx` command to download and execute the MCP Server: -# Update to latest version -dotnet tool update --global ExcelMcp.McpServer +```powershell +# Download and execute MCP server using dnx +dnx Sbroenne.ExcelMcp.McpServer@latest --yes + +# Execute specific version +dnx Sbroenne.ExcelMcp.McpServer@1.0.0 --yes -# Uninstall -dotnet tool uninstall --global ExcelMcp.McpServer +# Use with private feed +dnx Sbroenne.ExcelMcp.McpServer@latest --source https://your-feed.com --yes ``` **Benefits:** -- ✅ Easy installation with a single command -- ✅ Automatic updates via `dotnet tool update` -- ✅ Global availability from any directory +- ✅ Official Microsoft approach for NuGet MCP servers +- ✅ Automatic download and execution in one command +- ✅ No separate installation step required - ✅ Perfect for AI assistant integration +- ✅ Follows [Microsoft's NuGet MCP guidance](https://learn.microsoft.com/en-us/nuget/concepts/nuget-mcp) + +### Option 2: Download Binary + +1. **Download the latest MCP Server release**: + - Go to [Releases](https://github.com/sbroenne/mcp-server-excel/releases) + - Download `ExcelMcp-MCP-Server-{version}-windows.zip` + +2. **Extract and run**: + + ```powershell + # Extract to your preferred location + Expand-Archive -Path "ExcelMcp-MCP-Server-1.0.0-windows.zip" -DestinationPath "C:\Tools\ExcelMcp-MCP" + + # Run the MCP server + dotnet C:\Tools\ExcelMcp-MCP\ExcelMcp.McpServer.dll + ``` + +### Configure with AI Assistants + +**GitHub Copilot Integration:** + +Add to your VS Code settings.json or MCP client configuration: + +```json +{ + "mcp": { + "servers": { + "excel": { + "command": "dnx", + "args": ["Sbroenne.ExcelMcp.McpServer@latest", "--yes"], + "description": "Excel development operations through MCP" + } + } + } +} +``` + +**Claude Desktop Integration:** + +Add to Claude Desktop MCP configuration: -### Option 2: Download Pre-built Binary (Recommended for CLI) +```json +{ + "mcpServers": { + "excel": { + "command": "dnx", + "args": ["Sbroenne.ExcelMcp.McpServer@latest", "--yes"] + } + } +} +``` + +--- + +## 🔧 CLI Tool Installation -You can download the latest pre-built version: +**For direct automation, development workflows, and CI/CD integration** -1. **Download the latest release**: +### Option 1: Download Binary (Recommended) + +1. **Download the latest CLI release**: - Go to [Releases](https://github.com/sbroenne/mcp-server-excel/releases) - - Download `ExcelCLI-1.0.3-windows.zip` (or the latest version) + - Download `ExcelMcp-CLI-{version}-windows.zip` 2. **Extract and install**: ```powershell # Extract to your preferred location - Expand-Archive -Path "ExcelCLI-1.0.3-windows.zip" -DestinationPath "C:\Tools\ExcelCLI" + Expand-Archive -Path "ExcelMcp-CLI-2.0.0-windows.zip" -DestinationPath "C:\Tools\ExcelMcp-CLI" # Add to PATH (optional but recommended) - $env:PATH += ";C:\Tools\ExcelMcp\CLI" + $env:PATH += ";C:\Tools\ExcelMcp-CLI" # Make PATH change permanent [Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User") @@ -56,22 +119,73 @@ You can download the latest pre-built version: 3. **Verify installation**: ```powershell - # Check CLI version - ExcelMcp --version + # Check CLI version and help + excelcli.exe # Test CLI functionality - ExcelMcp create-empty "test.xlsx" + excelcli.exe create-empty "test.xlsx" + ``` + +### CLI Quick Start + +```powershell +# Basic operations +excelcli.exe create-empty "workbook.xlsx" +excelcli.exe pq-list "workbook.xlsx" +excelcli.exe sheet-read "workbook.xlsx" "Sheet1" "A1:D10" + +# VBA operations (requires one-time setup) +excelcli.exe setup-vba-trust +excelcli.exe create-empty "macros.xlsm" +excelcli.exe script-list "macros.xlsm" +``` + +--- + +## 📦 Combined Installation + +**For users who need both MCP Server and CLI tools** + +### Download Combined Package + +1. **Download the combined release**: + - Go to [Releases](https://github.com/sbroenne/mcp-server-excel/releases) + - Download `ExcelMcp-{version}-windows.zip` (combined package) + +2. **Extract and setup**: + + ```powershell + # Extract to your preferred location + Expand-Archive -Path "ExcelMcp-3.0.0-windows.zip" -DestinationPath "C:\Tools\ExcelMcp" - # Check MCP Server (if downloaded binary) - dotnet C:\Tools\ExcelMcp\MCP-Server\ExcelMcp.McpServer.dll + # Add CLI to PATH + $env:PATH += ";C:\Tools\ExcelMcp\CLI" + [Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User") + + # Install MCP Server as .NET tool (from extracted files) + dotnet tool install --global --add-source C:\Tools\ExcelMcp\MCP-Server ExcelMcp.McpServer ``` -### Option 3: Build from Source +3. **Verify both tools**: + + ```powershell + # Test CLI + excelcli.exe create-empty "test.xlsx" + + # Test MCP Server + mcp-excel --help + ``` -### Prerequisites for Building +--- + +## 🔨 Build from Source + +**For developers who want to build both tools from source** + +### Prerequisites - Windows OS with Excel installed -- .NET 8.0 SDK ([Download](https://dotnet.microsoft.com/download/dotnet/8.0)) +- .NET 10 SDK ([Download](https://dotnet.microsoft.com/download/dotnet/10.0)) - Git (for cloning the repository) ### Build Steps @@ -80,7 +194,7 @@ You can download the latest pre-built version: ```powershell git clone https://github.com/sbroenne/mcp-server-excel.git - cd ExcelMcp + cd mcp-server-excel ``` 2. **Build the solution**: @@ -92,16 +206,40 @@ You can download the latest pre-built version: 3. **Run tests** (requires Excel installed locally): ```powershell - dotnet test - ``` + # Run unit tests only (no Excel required) + dotnet test --filter "Category=Unit" - > **Note**: Tests require Microsoft Excel to be installed and accessible via COM automation. The GitHub Actions CI only builds the project (tests are skipped) since runners don't have Excel installed. + # Run integration tests (requires Excel) + dotnet test --filter "Category=Integration" + ``` -4. **Locate the executable**: +### After Building - ```text - src\ExcelMcp\bin\Release\net8.0\ExcelMcp.exe - ``` +**MCP Server:** + +```powershell +# Run MCP server from build +dotnet run --project src/ExcelMcp.McpServer + +# Or install as .NET tool from local build +dotnet pack src/ExcelMcp.McpServer -c Release +dotnet tool install --global --add-source src/ExcelMcp.McpServer/bin/Release ExcelMcp.McpServer +``` + +**CLI Tool:** + +```powershell +# CLI executable location +.\src\ExcelMcp.CLI\bin\Release\net10.0\excelcli.exe + +# Add to PATH for easier access +$buildPath = "$(Get-Location)\src\ExcelMcp.CLI\bin\Release\net10.0" +$env:PATH += ";$buildPath" +[Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User") + +# Test CLI +excelcli.exe create-empty "test.xlsx" +``` ### Installation Options @@ -109,7 +247,7 @@ You can download the latest pre-built version: ```powershell # Add the build directory to your system PATH -$buildPath = "$(Get-Location)\src\ExcelMcp\bin\Release\net8.0" +$buildPath = "$(Get-Location)\src\\ExcelMcp.CLI\\bin\Release\net10.0" $env:PATH += ";$buildPath" # Make permanent (requires admin privileges) @@ -119,52 +257,75 @@ $env:PATH += ";$buildPath" #### Option 2: Copy to a tools directory ```powershell -# Create a tools directory -mkdir C:\Tools\ExcelMcp -copy "src\ExcelMcp\bin\Release\net8.0\*" "C:\Tools\ExcelMcp\" +--- -# Add to PATH -$env:PATH += ";C:\Tools\ExcelCLI" -``` +## 🔧 VBA Configuration + +**Required for VBA script operations (both MCP Server and CLI)** -#### Option 3: Use directly with full path +If you plan to use VBA script commands, configure VBA trust: ```powershell -# Use the full path in scripts -.\src\ExcelMcp\bin\Release\net8.0\ExcelMcp.exe pq-list "myfile.xlsx" +# One-time setup for VBA automation (works with both tools) +# For CLI: +excelcli.exe setup-vba-trust + +# For MCP Server (through AI assistant): +# Ask your AI assistant: "Setup VBA trust for Excel automation" ``` -### Verify Installation +This configures the necessary registry settings to allow programmatic access to VBA projects. -Test that ExcelMcp is working correctly: +--- -```powershell -# Check version -ExcelMcp --version +## 📋 Installation Summary -# Test functionality -ExcelMcp create-empty "test.xlsx" -``` +| Use Case | Tool | Installation Method | Command | +|----------|------|-------------------|---------| +| **AI Assistant Integration** | MCP Server | .NET Tool | `dotnet tool install --global Sbroenne.ExcelMcp.McpServer` | +| **Direct Automation** | CLI | Binary Download | Download `ExcelMcp-CLI-{version}-windows.zip` | +| **Development/Testing** | Both | Build from Source | `git clone` + `dotnet build` | +| **Complete Environment** | Combined | Binary Download | Download `ExcelMcp-{version}-windows.zip` | -If successful, you should see confirmation that the Excel file was created. +## 🆘 Troubleshooting -## For VBA Operations +### Common Issues -If you plan to use VBA script commands, you'll need to configure VBA trust: +**"Excel is not installed" error:** -```powershell -# One-time setup for VBA automation -ExcelMcp setup-vba-trust -``` +- Ensure Microsoft Excel is installed and accessible +- Try running Excel manually first to ensure it works -This configures the necessary registry settings to allow programmatic access to VBA projects. +**"COM interop failed" error:** + +- Restart your computer after Excel installation +- Check that Excel is not running with administrator privileges while your tool runs without + +**".NET runtime not found" error:** + +- Install .NET 10 SDK: `winget install Microsoft.DotNet.SDK.10` +- Verify installation: `dotnet --version` + +**VBA access denied:** + +- Run the VBA trust setup command once +- Restart Excel after running the trust setup + +### Getting Help + +- 📖 **Documentation**: [Complete command reference](COMMANDS.md) +- 🧠 **MCP Server Guide**: [MCP Server README](../src/ExcelMcp.McpServer/README.md) +- 🔧 **CLI Guide**: [CLI documentation](CLI.md) +- 🐛 **Issues**: [GitHub Issues](https://github.com/sbroenne/mcp-server-excel/issues) + +--- -## 🔄 **Development & Contributing** +## 🔄 Development & Contributing **Important:** All changes to this project must be made through **Pull Requests (PRs)**. Direct commits to `main` are not allowed. - 📋 **Development Workflow**: See [DEVELOPMENT.md](DEVELOPMENT.md) for complete PR process - 🤝 **Contributing Guide**: See [CONTRIBUTING.md](CONTRIBUTING.md) for code standards -- 🐛 **Report Issues**: Use [GitHub Issues](https://github.com/sbroenne/mcp-server-excel/issues) for bugs and feature requests +- � **Release Strategy**: See [RELEASE-STRATEGY.md](RELEASE-STRATEGY.md) for release processes Version numbers are automatically managed by the release workflow - **do not update version numbers manually**. diff --git a/docs/NUGET_TRUSTED_PUBLISHING.md b/docs/NUGET_TRUSTED_PUBLISHING.md index b59098f9..f019a91e 100644 --- a/docs/NUGET_TRUSTED_PUBLISHING.md +++ b/docs/NUGET_TRUSTED_PUBLISHING.md @@ -60,11 +60,13 @@ Trusted publishing requires the package to exist on NuGet.org before configurati **Option A: Publish Manually** 1. Build the package locally: + ```bash dotnet pack src/ExcelMcp.McpServer/ExcelMcp.McpServer.csproj -c Release -o ./nupkg ``` 2. Publish using your existing NuGet API key: + ```bash dotnet nuget push ./nupkg/ExcelMcp.McpServer.*.nupkg \ --api-key YOUR_API_KEY \ @@ -75,6 +77,7 @@ Trusted publishing requires the package to exist on NuGet.org before configurati 1. Add `NUGET_API_KEY` as a repository secret temporarily 2. Modify the workflow to use the API key for the first release: + ```yaml - name: Publish to NuGet.org run: | @@ -82,6 +85,7 @@ Trusted publishing requires the package to exist on NuGet.org before configurati --api-key ${{ secrets.NUGET_API_KEY }} \ --source https://api.nuget.org/v3/index.json ``` + 3. Create and publish a release 4. After successful publish, remove the `--api-key` parameter and delete the secret @@ -90,11 +94,11 @@ Trusted publishing requires the package to exist on NuGet.org before configurati Once the package exists on NuGet.org: 1. **Sign in to NuGet.org** - - Go to https://www.nuget.org + - Go to - Sign in with your Microsoft account 2. **Navigate to Package Management** - - Go to https://www.nuget.org/packages/ExcelMcp.McpServer/manage + - Go to - Or: Find your package → Click "Manage Package" 3. **Add Trusted Publisher** @@ -102,9 +106,9 @@ Once the package exists on NuGet.org: - Click "Add Trusted Publisher" button 4. **Configure GitHub Actions Publisher** - + Enter the following values: - + | Field | Value | |-------|-------| | **Publisher Type** | GitHub Actions | @@ -162,6 +166,7 @@ jobs: **Cause**: Trusted publisher not configured or misconfigured on NuGet.org **Solution**: + 1. Verify the package exists on NuGet.org 2. Check trusted publisher configuration matches exactly: - Owner: `sbroenne` @@ -179,7 +184,8 @@ jobs: **Cause**: Workflow filename in trusted publisher config doesn't match -**Solution**: +**Solution**: + 1. Check the exact workflow filename in `.github/workflows/` 2. Update trusted publisher configuration if needed 3. Configuration is case-sensitive @@ -215,12 +221,14 @@ If you need to change the workflow filename or repository structure: ### Why Trusted Publishing is More Secure **Traditional API Key Approach**: + - Long-lived secrets (6-12 months or never expire) - Stored in GitHub secrets (potential for exposure) - Requires manual rotation - If leaked, valid until revoked **Trusted Publishing Approach**: + - Short-lived OIDC tokens (minutes) - Generated on-demand per workflow run - Automatically validated against configuration @@ -252,10 +260,10 @@ If you encounter issues: 1. Check the [Troubleshooting](#troubleshooting) section above 2. Review GitHub Actions workflow logs for detailed error messages 3. Verify trusted publisher configuration on NuGet.org -4. Open an issue at https://github.com/sbroenne/mcp-server-excel/issues +4. Open an issue at --- **Status**: ✅ Configured for trusted publishing -**Package**: https://www.nuget.org/packages/ExcelMcp.McpServer +**Package**: **Workflow**: `.github/workflows/publish-nuget.yml` diff --git a/docs/RELEASE-STRATEGY.md b/docs/RELEASE-STRATEGY.md new file mode 100644 index 00000000..3a25ed16 --- /dev/null +++ b/docs/RELEASE-STRATEGY.md @@ -0,0 +1,171 @@ +# ExcelMcp Release Strategy + +This document outlines the separate build and release processes for the ExcelMcp MCP Server and CLI components. + +## Release Workflows + +### 1. MCP Server Releases (`mcp-v*` tags) + +**Workflow**: `.github/workflows/release-mcp-server.yml` +**Trigger**: Tags starting with `mcp-v` (e.g., `mcp-v1.0.0`) + +**Features**: + +- Builds and packages only the MCP Server +- Publishes to NuGet as a .NET tool +- Creates GitHub release with MCP-focused documentation +- Optimized for AI assistant integration + +**Release Artifacts**: + +- `ExcelMcp-MCP-Server-{version}-windows.zip` - Binary package +- NuGet package: `ExcelMcp.McpServer` on NuGet.org +- Installation guide focused on MCP usage + +**Use Cases**: + +- AI assistant integration (GitHub Copilot, Claude, ChatGPT) +- Conversational Excel development workflows +- Model Context Protocol implementations + +### 2. CLI Releases (`cli-v*` tags) + +**Workflow**: `.github/workflows/release-cli.yml` +**Trigger**: Tags starting with `cli-v` (e.g., `cli-v2.0.0`) + +**Features**: + +- Builds and packages only the CLI tool +- Creates standalone CLI distribution +- Focused on direct automation workflows +- No NuGet publishing (binary-only distribution) + +**Release Artifacts**: + +- `ExcelMcp-CLI-{version}-windows.zip` - Complete CLI package +- Includes all 40+ commands documentation +- Quick start guide for CLI usage + +**Use Cases**: + +- Direct Excel automation scripts +- CI/CD pipeline integration +- Development workflows and testing +- Command-line Excel operations + +### 3. Combined Releases (`v*` tags) + +**Workflow**: `.github/workflows/release.yml` +**Trigger**: Tags starting with `v` (e.g., `v3.0.0`) + +**Features**: + +- Builds both MCP Server and CLI +- Creates combined distribution package +- Comprehensive release with both tools +- Maintains backward compatibility + +**Release Artifacts**: + +- `ExcelMcp-{version}-windows.zip` - Combined package +- Contains both CLI and MCP Server +- Unified documentation and installation guide + +**Use Cases**: + +- Users who need both tools +- Complete ExcelMcp installation +- Comprehensive Excel development environment + +## Version Management + +### Independent Versioning + +- **MCP Server**: Can have independent version numbers (e.g., mcp-v1.2.0) +- **CLI**: Can have independent version numbers (e.g., cli-v2.1.0) +- **Combined**: Major releases combining both (e.g., v3.0.0) + +### Development Strategy + +- **MCP Server**: Focus on AI integration features, conversational interfaces +- **CLI**: Focus on automation efficiency, command completeness, CI/CD integration +- **Combined**: Major milestones, breaking changes, coordinated releases + +## Release Process Examples + +### Releasing MCP Server Only + +```bash +# Create and push MCP server release tag +git tag mcp-v1.3.0 +git push origin mcp-v1.3.0 + +# This triggers: +# - Build MCP server only +# - Publish to NuGet +# - Create GitHub release with MCP-focused docs +``` + +### Releasing CLI Only + +```bash +# Create and push CLI release tag +git tag cli-v2.2.0 +git push origin cli-v2.2.0 + +# This triggers: +# - Build CLI only +# - Create binary distribution +# - Create GitHub release with CLI-focused docs +``` + +### Combined Release + +```bash +# Create and push combined release tag +git tag v3.1.0 +git push origin v3.1.0 + +# This triggers: +# - Build both MCP server and CLI +# - Combined distribution package +# - Comprehensive release documentation +``` + +## Documentation Strategy + +### Separate Focus Areas + +- **Main README.md**: MCP Server focused (AI assistant integration) +- **docs/CLI.md**: CLI focused (direct automation) +- **Release Notes**: Tailored to the specific component being released + +### Cross-References + +- Each tool's documentation references the other +- Clear navigation between MCP and CLI docs +- Unified project branding while maintaining component clarity + +## Benefits of This Approach + +1. **Targeted Releases**: Users can get updates for just the tool they use +2. **Independent Development**: MCP and CLI can evolve at different paces +3. **Focused Documentation**: Release notes and docs match user intent +4. **Reduced Package Size**: Users download only what they need +5. **Clear Separation**: MCP for AI workflows, CLI for direct automation +6. **Flexibility**: Combined releases still available for comprehensive updates + +## Migration from Single Release + +### Existing Tags + +- Previous `v*` tags remain as combined releases +- No breaking changes to existing release structure + +### New Tag Patterns + +- `mcp-v*`: MCP Server only +- `cli-v*`: CLI only +- `v*`: Combined (maintains compatibility) + +This approach provides maximum flexibility while maintaining the integrated ExcelMcp ecosystem. diff --git a/docs/SECURITY.md b/docs/SECURITY.md index 8ace3622..6856f20e 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -10,7 +10,7 @@ We currently support the following versions of ExcelMcp with security updates: ## Reporting a Vulnerability -We take security seriously. If you discover a security vulnerability in ExcelCLI, please report it responsibly. +We take security seriously. If you discover a security vulnerability in Sbroenne.ExcelMcp, please report it responsibly. ### How to Report @@ -82,7 +82,7 @@ ExcelMcp uses Excel COM automation with security safeguards: ExcelMcp has minimal dependencies to reduce attack surface: -- **.NET 8.0**: Microsoft-maintained runtime with regular security updates +- **.NET 10**: Microsoft-maintained runtime with regular security updates - **Spectre.Console**: Well-maintained library for console output - **No External APIs**: No network connections or external service dependencies diff --git a/docs/excel-powerquery-vba-copilot-instructions.md b/docs/excel-powerquery-vba-copilot-instructions.md index 78889387..cc41719f 100644 --- a/docs/excel-powerquery-vba-copilot-instructions.md +++ b/docs/excel-powerquery-vba-copilot-instructions.md @@ -1,164 +1,158 @@ -# ExcelMcp - Excel PowerQuery VBA Copilot Instructions +# ExcelMcp MCP Server - Excel PowerQuery VBA Copilot Instructions -Copy this file to your project's `.github/`-directory to enable GitHub Copilot support for ExcelMcp Excel automation with PowerQuery and VBA capabilities. +Copy this file to your project's `.github/`-directory to enable GitHub Copilot support for ExcelMcp MCP Server - AI-powered Excel development with PowerQuery and VBA capabilities. --- -## ExcelMcp Integration +## ExcelMcp MCP Server Integration -This project uses ExcelMcp for Excel automation. ExcelMcp is a command-line tool that provides programmatic access to Microsoft Excel through COM interop, supporting both standard Excel workbooks (.xlsx) and macro-enabled workbooks (.xlsm) with complete VBA support. +This project uses the ExcelMcp MCP Server for AI-assisted Excel development. The MCP server provides conversational access to Excel operations through 6 resource-based tools, enabling AI assistants like GitHub Copilot, Claude, and ChatGPT to perform Excel development tasks through natural language. -### Available ExcelMcp Commands +### Available MCP Server Tools -**File Operations:** +The MCP server provides 6 resource-based tools for Excel automation: -- `ExcelMcp create-empty "file.xlsx"` - Create empty Excel workbook (standard format) -- `ExcelMcp create-empty "file.xlsm"` - Create macro-enabled Excel workbook for VBA support +**1. excel_file** - File management +- Actions: `create-empty`, `validate`, `check-exists` +- Create Excel workbooks (.xlsx) or macro-enabled workbooks (.xlsm) +- Validate file format and accessibility -**Power Query Management:** - -- `ExcelMcp pq-list "file.xlsx"` - List all Power Query connections -- `ExcelMcp pq-view "file.xlsx" "QueryName"` - Display Power Query M code -- `ExcelMcp pq-import "file.xlsx" "QueryName" "code.pq"` - Import M code from file -- `ExcelMcp pq-export "file.xlsx" "QueryName" "output.pq"` - Export M code to file -- `ExcelMcp pq-update "file.xlsx" "QueryName" "code.pq"` - Update existing query -- `ExcelMcp pq-refresh "file.xlsx" "QueryName"` - Refresh query data -- `ExcelMcp pq-loadto "file.xlsx" "QueryName" "Sheet"` - Load query to worksheet -- `ExcelMcp pq-delete "file.xlsx" "QueryName"` - Delete Power Query - -**Worksheet Operations:** - -- `ExcelMcp sheet-list "file.xlsx"` - List all worksheets -- `ExcelMcp sheet-read "file.xlsx" "Sheet" "A1:D10"` - Read data from ranges -- `ExcelMcp sheet-write "file.xlsx" "Sheet" "data.csv"` - Write CSV data to worksheet -- `ExcelMcp sheet-create "file.xlsx" "NewSheet"` - Add new worksheet -- `ExcelMcp sheet-copy "file.xlsx" "Source" "Target"` - Copy worksheet -- `ExcelMcp sheet-rename "file.xlsx" "OldName" "NewName"` - Rename worksheet -- `ExcelMcp sheet-delete "file.xlsx" "Sheet"` - Remove worksheet -- `ExcelMcp sheet-clear "file.xlsx" "Sheet" "A1:Z100"` - Clear data ranges -- `ExcelMcp sheet-append "file.xlsx" "Sheet" "data.csv"` - Append data to existing content - -**Parameter Management:** - -- `ExcelMcp param-list "file.xlsx"` - List all named ranges -- `ExcelMcp param-get "file.xlsx" "ParamName"` - Get named range value -- `ExcelMcp param-set "file.xlsx" "ParamName" "Value"` - Set named range value -- `ExcelMcp param-create "file.xlsx" "ParamName" "Sheet!A1"` - Create named range -- `ExcelMcp param-delete "file.xlsx" "ParamName"` - Remove named range - -**Cell Operations:** - -- `ExcelMcp cell-get-value "file.xlsx" "Sheet" "A1"` - Get individual cell value -- `ExcelMcp cell-set-value "file.xlsx" "Sheet" "A1" "Value"` - Set individual cell value -- `ExcelMcp cell-get-formula "file.xlsx" "Sheet" "A1"` - Get cell formula -- `ExcelMcp cell-set-formula "file.xlsx" "Sheet" "A1" "=SUM(B1:B10)"` - Set cell formula +**2. excel_powerquery** - Power Query operations +- Actions: `list`, `view`, `import`, `export`, `update`, `refresh`, `delete` +- Manage Power Query M code for data transformations +- List, view, and edit Power Query connections +- Refresh queries and load results to worksheets -**VBA Script Management:** ⚠️ **Requires .xlsm files!** +**3. excel_worksheet** - Worksheet operations +- Actions: `list`, `read`, `write`, `create`, `rename`, `copy`, `delete`, `clear`, `append` +- Manage worksheets and data ranges +- Read/write data from/to Excel worksheets +- Create, rename, copy, and delete worksheets -- `ExcelMcp script-list "file.xlsm"` - List all VBA modules and procedures -- `ExcelMcp script-export "file.xlsm" "Module" "output.vba"` - Export VBA code to file -- `ExcelMcp script-import "file.xlsm" "ModuleName" "source.vba"` - Import VBA module from file -- `ExcelMcp script-update "file.xlsm" "ModuleName" "source.vba"` - Update existing VBA module -- `ExcelMcp script-run "file.xlsm" "Module.Procedure" [param1] [param2]` - Execute VBA macros with parameters -- `ExcelMcp script-delete "file.xlsm" "ModuleName"` - Remove VBA module +**4. excel_parameter** - Named range management +- Actions: `list`, `get`, `set`, `create`, `delete` +- Manage Excel named ranges as configuration parameters +- Get and set parameter values -**Setup Commands:** +**5. excel_cell** - Cell operations +- Actions: `get-value`, `set-value`, `get-formula`, `set-formula` +- Read and write individual cell values +- Manage cell formulas -- `ExcelMcp setup-vba-trust` - Enable VBA project access (one-time setup for VBA automation) -- `ExcelMcp check-vba-trust` - Check VBA trust configuration status +**6. excel_vba** - VBA script management ⚠️ **Requires .xlsm files!** +- Actions: `list`, `export`, `import`, `update`, `run`, `delete` +- Manage VBA modules and procedures +- Execute VBA macros with parameters +- Export/import VBA code for version control -### Common Workflows +### Conversational Workflow Examples -**Data Pipeline:** +**Power Query Refactoring:** -```bash -ExcelMcp create-empty "analysis.xlsx" -ExcelMcp pq-import "analysis.xlsx" "WebData" "api-query.pq" -ExcelMcp pq-refresh "analysis.xlsx" "WebData" -ExcelMcp pq-loadto "analysis.xlsx" "WebData" "DataSheet" -``` +Ask Copilot: "Review the Power Query 'WebData' in analysis.xlsx and optimize it for performance" -**VBA Automation Workflow:** +The AI will: +1. View the current M code +2. Analyze for performance issues +3. Suggest and apply optimizations +4. Update the query with improved code -```bash -# One-time VBA trust setup -ExcelMcp setup-vba-trust +**VBA Enhancement:** -# Create macro-enabled workbook -ExcelMcp create-empty "automation.xlsm" +Ask Copilot: "Add comprehensive error handling to the DataProcessor module in automation.xlsm" -# Import VBA module -ExcelMcp script-import "automation.xlsm" "DataProcessor" "processor.vba" +The AI will: +1. Export the current VBA module +2. Analyze the code structure +3. Add try-catch patterns and logging +4. Update the module with enhanced code -# Execute VBA macro with parameters -ExcelMcp script-run "automation.xlsm" "DataProcessor.ProcessData" "Sheet1" "A1:D100" +**Combined Power Query + VBA Workflow:** -# Verify results -ExcelMcp sheet-read "automation.xlsm" "Sheet1" "A1:D10" +Ask Copilot: "Set up a data pipeline in report.xlsm that loads data via Power Query, then generates charts with VBA" -# Export updated VBA for version control -ExcelMcp script-export "automation.xlsm" "DataProcessor" "updated-processor.vba" -``` +The AI will: +1. Import or create Power Query for data loading +2. Refresh the query to get latest data +3. Import or create VBA module for chart generation +4. Execute the VBA macro to create visualizations -**Combined PowerQuery + VBA Workflow:** +**Excel Development Automation:** -```bash -# Data transformation with PowerQuery -ExcelMcp pq-import "report.xlsm" "DataLoader" "load-data.pq" -ExcelMcp pq-refresh "report.xlsm" "DataLoader" +Ask Copilot: "Create a macro-enabled workbook with a data loader query and a formatting macro" -# Business logic with VBA -ExcelMcp script-run "report.xlsm" "ReportGenerator.CreateCharts" -ExcelMcp script-run "report.xlsm" "ReportGenerator.FormatReport" +The AI will: +1. Create a new .xlsm file +2. Import Power Query M code for data loading +3. Import VBA module for formatting +4. Set up named ranges for parameters -# Extract final results -ExcelMcp sheet-read "report.xlsm" "FinalReport" -``` +### When to Use ExcelMcp MCP Server -**Report Generation:** +The MCP server is ideal for AI-assisted Excel development workflows: -```bash -ExcelMcp create-empty "report.xlsx" -ExcelMcp param-set "report.xlsx" "ReportDate" "2024-01-01" -ExcelMcp sheet-write "report.xlsx" "Data" "input.csv" -ExcelMcp script-run "report.xlsx" "ReportModule.FormatReport" -``` +- **Power Query Refactoring** - AI analyzes and optimizes M code for performance +- **VBA Code Enhancement** - Add error handling, logging, and best practices to VBA modules +- **Code Review** - AI reviews existing Power Query/VBA code for issues and improvements +- **Development Automation** - AI creates and configures Excel workbooks with queries and macros +- **Documentation Generation** - Auto-generate comments and documentation for Excel code +- **Debugging Assistance** - AI helps troubleshoot Power Query and VBA issues +- **Best Practices Implementation** - AI applies Excel development patterns and standards -### When to Suggest ExcelMcp +### AI Development vs. Scripted Automation -Use ExcelMcp when the user needs to: +**Use MCP Server (AI-Assisted Development):** +- Conversational workflows with AI guidance +- Code refactoring and optimization +- Adding features to existing Excel solutions +- Learning and discovering Excel capabilities +- Complex multi-step development tasks -- Automate Excel data processing -- Create reports programmatically -- Manage Power Query M code for data transformations -- Execute VBA macros programmatically -- Process CSV/Excel data pipelines -- Set up configuration in Excel files -- Extract data from existing Excel workbooks -- Combine PowerQuery data transformation with VBA business logic -- Create macro-enabled workbooks for automation -- Version control VBA and PowerQuery code externally -- Automate complex Excel workflows without UI interaction +**Use CLI (Scripted Automation):** +- Available separately for scripted workflows +- See CLI.md documentation for command-line automation +- Ideal for CI/CD pipelines and batch processing ### File Format Requirements -- **Standard Excel files (.xlsx)**: Use for PowerQuery, worksheets, parameters, and cell operations +- **Standard Excel files (.xlsx)**: For Power Query, worksheets, parameters, and cell operations - **Macro-enabled files (.xlsm)**: Required for all VBA script operations -- **VBA Trust Setup**: Run `ExcelMcp setup-vba-trust` once before using VBA commands +- **VBA Trust**: Must be enabled for VBA operations (MCP server can guide setup) ### Requirements - Windows operating system - Microsoft Excel installed -- .NET 8.0 runtime -- ExcelMcp executable in PATH or specify full path -- For VBA operations: VBA trust must be enabled (use `setup-vba-trust` command) - -### Error Handling - -- ExcelMcp returns 0 for success, 1 for errors -- Always check return codes in scripts -- Handle file locking gracefully (Excel may be open) -- Use absolute file paths when possible -- VBA commands will fail on .xlsx files - use .xlsm for macro-enabled workbooks -- Run VBA trust setup before first VBA operation +- .NET 10 runtime +- MCP server running (via `dnx Sbroenne.ExcelMcp.McpServer@latest`) +- For VBA operations: VBA trust must be enabled + +### Getting Started + +1. **Install the MCP Server:** + ```powershell + # Install .NET 10 SDK + winget install Microsoft.DotNet.SDK.10 + + # Run MCP server + dnx Sbroenne.ExcelMcp.McpServer@latest --yes + ``` + +2. **Configure AI Assistant:** + - Add MCP server to your AI assistant configuration + - See README.md for GitHub Copilot, Claude, and ChatGPT setup + +3. **Start Conversational Development:** + - Ask AI to perform Excel operations naturally + - AI uses MCP tools to interact with Excel files + - Get real-time feedback and suggestions + +### Example Prompts for Copilot + +- "Review this Power Query and suggest performance improvements" +- "Add comprehensive error handling to the VBA module" +- "Create a macro-enabled workbook with a data loader query" +- "Optimize this M code for better query folding" +- "Export all VBA modules from this workbook for version control" +- "Set up named ranges for report parameters" +- "Debug why this Power Query isn't refreshing properly" diff --git a/global.json b/global.json new file mode 100644 index 00000000..d03a95c4 --- /dev/null +++ b/global.json @@ -0,0 +1,6 @@ +{ + "sdk": { + "version": "10.0.100-rc.1.25451.107", + "rollForward": "latestFeature" + } +} \ No newline at end of file diff --git a/rename-to-excelmcp-issue.md b/rename-to-excelmcp-issue.md deleted file mode 100644 index 6300bd65..00000000 --- a/rename-to-excelmcp-issue.md +++ /dev/null @@ -1,309 +0,0 @@ -# Rename Solution from ExcelCLI to ExcelMcp - -## 🎯 Objective - -Rename the entire C# solution from `ExcelCLI` to `ExcelMcp` and create a new GitHub repository named `mcp-server-excel` to align with MCP ecosystem naming conventions and follow Microsoft C# naming conventions for 3+ letter acronyms (PascalCase: `Mcp` not `MCP`). - -## 📋 Background - -- **Current:** Repository `sbroenne/ExcelCLI` with `ExcelCLI` namespace -- **Target:** New repository `sbroenne/mcp-server-excel` with `ExcelMcp` namespace -- **Reason:** Align with MCP ecosystem naming convention (`mcp-server-{technology}`) -- **C# Convention:** Three-letter acronyms should use PascalCase (`Xml`, `Json`, `Mcp`) per [Microsoft guidelines](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/capitalization-conventions) -- **Result:** New repo `mcp-server-excel` with solution `ExcelMcp.sln` and `ExcelMcp.*` projects - -## 🔧 Required Changes - -### Phase 1: Create New GitHub Repository - -Create a new GitHub repository following MCP naming conventions: - -**Repository Details:** - -- **Name:** `mcp-server-excel` -- **Owner:** `sbroenne` -- **Description:** "Excel Development MCP Server for AI Assistants - Power Query refactoring, VBA enhancement, and Excel automation for GitHub Copilot, Claude, and ChatGPT" -- **Visibility:** Public -- **Topics/Tags:** `mcp-server`, `excel`, `power-query`, `vba`, `github-copilot`, `ai-assistant`, `excel-development`, `model-context-protocol`, `excel-automation`, `dotnet` -- **License:** MIT (copy from existing repo) -- **README:** Will be updated in Phase 2 - -**Actions:** - -1. Create new repository `sbroenne/mcp-server-excel` on GitHub -2. DO NOT initialize with README (we'll push from existing repo) -3. Set repository description and topics as specified above -4. Configure branch protection rules for `main` branch (same as current repo) -5. Copy repository settings from `sbroenne/ExcelCLI`: - - Issues enabled - - Discussions enabled - - Security alerts enabled - - Dependabot enabled - -**Note:** Analyze the current repository settings and replicate them in the new repository. The Copilot agent should identify all relevant settings that need to be transferred. - -### Phase 2: Rename Solution and Projects - -### 1. Solution File Rename - -- **File:** `ExcelCLI.sln` → `ExcelMcp.sln` -- **Action:** Rename file and update all internal project references - -### 2. Project Files & Directories - -Rename these project files and their containing directories: - -#### Source Projects - -- `src/ExcelCLI/` → `src/ExcelMcp.CLI/` - - `ExcelCLI.csproj` → `ExcelMcp.CLI.csproj` -- `src/ExcelCLI.Core/` → `src/ExcelMcp.Core/` - - `ExcelCLI.Core.csproj` → `ExcelMcp.Core.csproj` -- `src/ExcelCLI.MCP.Server/` → `src/ExcelMcp.Server/` - - `ExcelCLI.MCP.Server.csproj` → `ExcelMcp.Server.csproj` - -#### Test Projects - -- `tests/ExcelCLI.Tests/` → `tests/ExcelMcp.Tests/` - - `ExcelCLI.Tests.csproj` → `ExcelMcp.Tests.csproj` - -### 3. Namespace Updates - -Update all C# files with namespace declarations: - -**Find and replace across ALL `.cs` files:** - -- `namespace ExcelCLI` → `namespace ExcelMcp.CLI` -- `namespace ExcelCLI.Commands` → `namespace ExcelMcp.CLI.Commands` -- `namespace ExcelCLI.Core` → `namespace ExcelMcp.Core` -- `namespace ExcelCLI.MCP.Server` → `namespace ExcelMcp.Server` -- `namespace ExcelCLI.Tests` → `namespace ExcelMcp.Tests` -- `using ExcelCLI` → `using ExcelMcp.CLI` -- `using ExcelCLI.Commands` → `using ExcelMcp.CLI.Commands` -- `using ExcelCLI.Core` → `using ExcelMcp.Core` -- `using ExcelCLI.MCP.Server` → `using ExcelMcp.Server` - -### 4. Project Reference Updates - -Update project references in all `.csproj` files: - -```xml - - - - - - - -``` - -### 5. Assembly Information Updates - -Update assembly names in `.csproj` files: - -```xml - -ExcelMcp -ExcelMcp.CLI - - -ExcelMcp.Core -ExcelMcp.Core - - -ExcelMcp.Server -ExcelMcp.Server -``` - -### 6. Documentation Updates - -Update references in documentation files: - -#### Files to Update - -- `README.md` - Update project structure, namespace references -- `.github/copilot-instructions.md` - Update namespace examples -- `.github/workflows/build.yml` - Update project paths -- `.github/workflows/release.yml` - Update project paths and artifact names -- `docs/DEVELOPMENT.md` - Update namespace examples -- `docs/CONTRIBUTING.md` - Update project structure references -- All other `docs/*.md` files mentioning `ExcelCLI` namespaces - -#### Key Updates - -- Replace `ExcelCLI` namespace references with `ExcelMcp.CLI` -- Replace `ExcelCLI.Core` with `ExcelMcp.Core` -- Replace `ExcelCLI.MCP.Server` with `ExcelMcp.Server` -- Update code examples showing namespace usage -- Update project structure diagrams - -### 7. CI/CD Workflow Updates - -#### build.yml workflow - -```yaml -# Update project paths -- name: Build ExcelMcp.CLI - run: dotnet build src/ExcelMcp.CLI/ExcelMcp.CLI.csproj - -- name: Build ExcelMcp.Core - run: dotnet build src/ExcelMcp.Core/ExcelMcp.Core.csproj - -- name: Build ExcelMcp.Server - run: dotnet build src/ExcelMcp.Server/ExcelMcp.Server.csproj -``` - -#### release.yml workflow - -```yaml -# Update binary paths and artifact names -- name: Publish CLI - run: dotnet publish src/ExcelMcp.CLI/ExcelMcp.CLI.csproj - -# Update file copy operations -- name: Copy binaries - run: | - Copy-Item "src/ExcelMcp.CLI/bin/Release/net8.0/publish/ExcelMcp.exe" ... -``` - -### 8. Test Project Updates - -Update test namespaces and usings in all test files: - -- `tests/ExcelMcp.Tests/` - All `*.cs` files -- Update `using ExcelCLI` statements to `using ExcelMcp.CLI` -- Update namespace declarations - -### 9. Git Considerations - -**IMPORTANT:** Use `git mv` for renames to preserve history: - -```bash -# Example commands (Copilot should use these) -git mv ExcelCLI.sln ExcelMcp.sln -git mv src/ExcelCLI src/ExcelMcp.CLI -git mv src/ExcelCLI.Core src/ExcelMcp.Core -git mv src/ExcelCLI.MCP.Server src/ExcelMcp.Server -git mv tests/ExcelCLI.Tests tests/ExcelMcp.Tests -``` - -### 10. Repository Migration - -After completing all renames and updates: - -**Actions:** - -1. Create feature branch for all changes: `git checkout -b feature/rename-to-excelmcp` -2. Commit all changes with comprehensive message -3. Push to new repository: `git remote add new-origin https://github.com/sbroenne/mcp-server-excel.git` -4. Push all branches: `git push new-origin --all` -5. Push all tags: `git push new-origin --tags` -6. Verify all GitHub Actions workflows execute successfully in new repository -7. Update any external references (badges, links) to point to new repository - -**Note:** The Copilot agent should analyze what else needs to be done for a complete repository migration, including: - -- Updating URLs in documentation -- Migrating GitHub Actions secrets (if needed) -- Updating external integrations -- Creating redirect notice in old repository (optional) -- Any other repository-specific configurations - -## ✅ Acceptance Criteria - -### New Repository - -- [ ] New repository `sbroenne/mcp-server-excel` created -- [ ] Repository description and topics set correctly -- [ ] Branch protection rules configured -- [ ] Repository settings match original repo -- [ ] License file present (MIT) - -### Build & Test -- [ ] Solution builds successfully with zero warnings -- [ ] All unit tests pass (`dotnet test`) -- [ ] All integration tests pass -- [ ] CI/CD workflows execute successfully - -### Naming Consistency: -- [ ] All namespaces follow `ExcelMcp.*` pattern -- [ ] "MCP" uses PascalCase (`Mcp`) not all caps -- [ ] CLI tool explicitly named `ExcelMcp.CLI` -- [ ] No remaining `ExcelCLI` references in code - -### File Structure: -- [ ] All directories renamed correctly -- [ ] All `.csproj` files renamed and updated -- [ ] Solution file references all projects correctly -- [ ] Git history preserved via `git mv` - -### Documentation: -- [ ] All code examples use new namespaces -- [ ] Project structure diagrams updated -- [ ] CI/CD workflow paths updated -- [ ] README and all docs reflect new names - -### Functionality: -- [ ] CLI executable works with all commands -- [ ] MCP server starts and responds correctly -- [ ] Core library exports correct assembly name -- [ ] No breaking changes to public APIs - -## 🚨 Critical Notes - -1. **Create new repository FIRST** before making code changes -2. **Use `git mv` for ALL renames** to preserve Git history -3. **Follow PascalCase for "Mcp"** - Not `MCP` (3+ letter acronym rule) -4. **CLI becomes `ExcelMcp.CLI`** - Explicit project naming -5. **Server becomes `ExcelMcp.Server`** - Remove redundant `.MCP.` -6. **Test after EACH major step** - Build/test incrementally -7. **Update Directory.Build.props** if it contains project-specific references -8. **Check for hardcoded paths** in any PowerShell scripts or batch files -9. **Analyze and identify** any additional changes needed beyond what's explicitly listed -10. **Complete repository migration** including all branches, tags, and settings## 📚 Reference - -- [Microsoft C# Naming Guidelines](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/capitalization-conventions) -- Current solution: `ExcelCLI.sln` -- Target solution: `ExcelMcp.sln` -- Projects: 4 total (3 source + 1 test) - -## 🎯 Definition of Done - -### Repository Setup - -- ✅ New repository `sbroenne/mcp-server-excel` created and configured -- ✅ Repository settings, branch protection, and topics configured -- ✅ All branches and tags migrated from old repository - -### Code Changes - -- ✅ Solution renamed to `ExcelMcp.sln` -- ✅ All projects renamed to `ExcelMcp.*` pattern -- ✅ All namespaces updated to `ExcelMcp.*` -- ✅ All file paths updated in CI/CD workflows -- ✅ Documentation updated with new repository name and namespaces -- ✅ All URLs updated to point to new repository -- ✅ Git history preserved via `git mv` -- ✅ No references to old `ExcelCLI` namespace remain in code - -### Validation - -- ✅ Build succeeds with zero warnings in new repository -- ✅ All tests pass in new repository -- ✅ CI/CD workflows execute successfully in new repository -- ✅ MCP server functionality verified -- ✅ CLI functionality verified - -### Additional Tasks (Agent to Identify) - -- ✅ All other required changes identified and completed by Copilot agent -- ✅ Repository migration checklist verified -- ✅ No breaking changes to public APIs (where possible) - ---- - -**Estimated Scope:** Large refactoring affecting ~100+ files + repository migration -**Breaking Changes:** Yes - namespace changes affect external consumers -**Git Strategy:** Feature branch with `git mv` for history preservation, then repository migration -**Testing Required:** Comprehensive - build, unit tests, integration tests, CI/CD validation in new repository -**Agent Autonomy:** Copilot agent should identify and complete additional required changes not explicitly listed diff --git a/src/ExcelMcp/Commands/CellCommands.cs b/src/ExcelMcp.CLI/Commands/CellCommands.cs similarity index 98% rename from src/ExcelMcp/Commands/CellCommands.cs rename to src/ExcelMcp.CLI/Commands/CellCommands.cs index dcc5d40d..12c6ade1 100644 --- a/src/ExcelMcp/Commands/CellCommands.cs +++ b/src/ExcelMcp.CLI/Commands/CellCommands.cs @@ -1,7 +1,7 @@ using Spectre.Console; -using static ExcelMcp.ExcelHelper; +using static Sbroenne.ExcelMcp.CLI.ExcelHelper; -namespace ExcelMcp.Commands; +namespace Sbroenne.ExcelMcp.CLI.Commands; /// /// Individual cell operation commands implementation diff --git a/src/ExcelMcp/Commands/FileCommands.cs b/src/ExcelMcp.CLI/Commands/FileCommands.cs similarity index 98% rename from src/ExcelMcp/Commands/FileCommands.cs rename to src/ExcelMcp.CLI/Commands/FileCommands.cs index 9a0fa2a8..6d049a78 100644 --- a/src/ExcelMcp/Commands/FileCommands.cs +++ b/src/ExcelMcp.CLI/Commands/FileCommands.cs @@ -1,7 +1,7 @@ using Spectre.Console; -using static ExcelMcp.ExcelHelper; +using static Sbroenne.ExcelMcp.CLI.ExcelHelper; -namespace ExcelMcp.Commands; +namespace Sbroenne.ExcelMcp.CLI.Commands; /// /// File management commands implementation diff --git a/src/ExcelMcp/Commands/ICellCommands.cs b/src/ExcelMcp.CLI/Commands/ICellCommands.cs similarity index 85% rename from src/ExcelMcp/Commands/ICellCommands.cs rename to src/ExcelMcp.CLI/Commands/ICellCommands.cs index 5bf09de0..048bdae3 100644 --- a/src/ExcelMcp/Commands/ICellCommands.cs +++ b/src/ExcelMcp.CLI/Commands/ICellCommands.cs @@ -1,4 +1,4 @@ -namespace ExcelMcp.Commands; +namespace Sbroenne.ExcelMcp.CLI.Commands; /// /// Individual cell operation commands diff --git a/src/ExcelMcp/Commands/IFileCommands.cs b/src/ExcelMcp.CLI/Commands/IFileCommands.cs similarity index 78% rename from src/ExcelMcp/Commands/IFileCommands.cs rename to src/ExcelMcp.CLI/Commands/IFileCommands.cs index fa03cb83..b7a57b3c 100644 --- a/src/ExcelMcp/Commands/IFileCommands.cs +++ b/src/ExcelMcp.CLI/Commands/IFileCommands.cs @@ -1,4 +1,4 @@ -namespace ExcelMcp.Commands; +namespace Sbroenne.ExcelMcp.CLI.Commands; /// /// File management commands for Excel workbooks diff --git a/src/ExcelMcp/Commands/IParameterCommands.cs b/src/ExcelMcp.CLI/Commands/IParameterCommands.cs similarity index 86% rename from src/ExcelMcp/Commands/IParameterCommands.cs rename to src/ExcelMcp.CLI/Commands/IParameterCommands.cs index a6a9e3e3..ce0a450c 100644 --- a/src/ExcelMcp/Commands/IParameterCommands.cs +++ b/src/ExcelMcp.CLI/Commands/IParameterCommands.cs @@ -1,4 +1,4 @@ -namespace ExcelMcp.Commands; +namespace Sbroenne.ExcelMcp.CLI.Commands; /// /// Named range/parameter management commands diff --git a/src/ExcelMcp/Commands/IPowerQueryCommands.cs b/src/ExcelMcp.CLI/Commands/IPowerQueryCommands.cs similarity index 90% rename from src/ExcelMcp/Commands/IPowerQueryCommands.cs rename to src/ExcelMcp.CLI/Commands/IPowerQueryCommands.cs index 8be2fdea..94ac3173 100644 --- a/src/ExcelMcp/Commands/IPowerQueryCommands.cs +++ b/src/ExcelMcp.CLI/Commands/IPowerQueryCommands.cs @@ -1,4 +1,4 @@ -namespace ExcelMcp.Commands; +namespace Sbroenne.ExcelMcp.CLI.Commands; /// /// Power Query management commands diff --git a/src/ExcelMcp/Commands/IScriptCommands.cs b/src/ExcelMcp.CLI/Commands/IScriptCommands.cs similarity index 86% rename from src/ExcelMcp/Commands/IScriptCommands.cs rename to src/ExcelMcp.CLI/Commands/IScriptCommands.cs index 4a02b062..a90addd1 100644 --- a/src/ExcelMcp/Commands/IScriptCommands.cs +++ b/src/ExcelMcp.CLI/Commands/IScriptCommands.cs @@ -1,4 +1,4 @@ -namespace ExcelMcp.Commands; +namespace Sbroenne.ExcelMcp.CLI.Commands; /// /// VBA script management commands diff --git a/src/ExcelMcp/Commands/ISetupCommands.cs b/src/ExcelMcp.CLI/Commands/ISetupCommands.cs similarity index 89% rename from src/ExcelMcp/Commands/ISetupCommands.cs rename to src/ExcelMcp.CLI/Commands/ISetupCommands.cs index 1fee29b7..fb886b9c 100644 --- a/src/ExcelMcp/Commands/ISetupCommands.cs +++ b/src/ExcelMcp.CLI/Commands/ISetupCommands.cs @@ -1,4 +1,4 @@ -namespace ExcelMcp.Commands; +namespace Sbroenne.ExcelMcp.CLI.Commands; /// /// Setup and configuration commands for ExcelCLI diff --git a/src/ExcelMcp/Commands/ISheetCommands.cs b/src/ExcelMcp.CLI/Commands/ISheetCommands.cs similarity index 89% rename from src/ExcelMcp/Commands/ISheetCommands.cs rename to src/ExcelMcp.CLI/Commands/ISheetCommands.cs index d67ecd74..9697516a 100644 --- a/src/ExcelMcp/Commands/ISheetCommands.cs +++ b/src/ExcelMcp.CLI/Commands/ISheetCommands.cs @@ -1,4 +1,4 @@ -namespace ExcelMcp.Commands; +namespace Sbroenne.ExcelMcp.CLI.Commands; /// /// Worksheet management commands diff --git a/src/ExcelMcp/Commands/ParameterCommands.cs b/src/ExcelMcp.CLI/Commands/ParameterCommands.cs similarity index 98% rename from src/ExcelMcp/Commands/ParameterCommands.cs rename to src/ExcelMcp.CLI/Commands/ParameterCommands.cs index 8bc55440..0e17ea9d 100644 --- a/src/ExcelMcp/Commands/ParameterCommands.cs +++ b/src/ExcelMcp.CLI/Commands/ParameterCommands.cs @@ -1,7 +1,7 @@ using Spectre.Console; -using static ExcelMcp.ExcelHelper; +using static Sbroenne.ExcelMcp.CLI.ExcelHelper; -namespace ExcelMcp.Commands; +namespace Sbroenne.ExcelMcp.CLI.Commands; /// /// Named range/parameter management commands implementation diff --git a/src/ExcelMcp/Commands/PowerQueryCommands.cs b/src/ExcelMcp.CLI/Commands/PowerQueryCommands.cs similarity index 99% rename from src/ExcelMcp/Commands/PowerQueryCommands.cs rename to src/ExcelMcp.CLI/Commands/PowerQueryCommands.cs index 3893036c..cf081131 100644 --- a/src/ExcelMcp/Commands/PowerQueryCommands.cs +++ b/src/ExcelMcp.CLI/Commands/PowerQueryCommands.cs @@ -1,7 +1,7 @@ using Spectre.Console; -using static ExcelMcp.ExcelHelper; +using static Sbroenne.ExcelMcp.CLI.ExcelHelper; -namespace ExcelMcp.Commands; +namespace Sbroenne.ExcelMcp.CLI.Commands; /// /// Power Query management commands implementation diff --git a/src/ExcelMcp/Commands/ScriptCommands.cs b/src/ExcelMcp.CLI/Commands/ScriptCommands.cs similarity index 99% rename from src/ExcelMcp/Commands/ScriptCommands.cs rename to src/ExcelMcp.CLI/Commands/ScriptCommands.cs index 5bfb6319..869b7b6b 100644 --- a/src/ExcelMcp/Commands/ScriptCommands.cs +++ b/src/ExcelMcp.CLI/Commands/ScriptCommands.cs @@ -1,8 +1,8 @@ using Spectre.Console; using System.Runtime.InteropServices; -using static ExcelMcp.ExcelHelper; +using static Sbroenne.ExcelMcp.CLI.ExcelHelper; -namespace ExcelMcp.Commands; +namespace Sbroenne.ExcelMcp.CLI.Commands; /// /// VBA script management commands diff --git a/src/ExcelMcp/Commands/SetupCommands.cs b/src/ExcelMcp.CLI/Commands/SetupCommands.cs similarity index 98% rename from src/ExcelMcp/Commands/SetupCommands.cs rename to src/ExcelMcp.CLI/Commands/SetupCommands.cs index 247575d5..0193923d 100644 --- a/src/ExcelMcp/Commands/SetupCommands.cs +++ b/src/ExcelMcp.CLI/Commands/SetupCommands.cs @@ -1,9 +1,9 @@ using Spectre.Console; using Microsoft.Win32; using System; -using static ExcelMcp.ExcelHelper; +using static Sbroenne.ExcelMcp.CLI.ExcelHelper; -namespace ExcelMcp.Commands; +namespace Sbroenne.ExcelMcp.CLI.Commands; /// /// Setup and configuration commands for ExcelCLI diff --git a/src/ExcelMcp/Commands/SheetCommands.cs b/src/ExcelMcp.CLI/Commands/SheetCommands.cs similarity index 99% rename from src/ExcelMcp/Commands/SheetCommands.cs rename to src/ExcelMcp.CLI/Commands/SheetCommands.cs index 5b928871..ca41de48 100644 --- a/src/ExcelMcp/Commands/SheetCommands.cs +++ b/src/ExcelMcp.CLI/Commands/SheetCommands.cs @@ -1,8 +1,8 @@ using Spectre.Console; using System.Text; -using static ExcelMcp.ExcelHelper; +using static Sbroenne.ExcelMcp.CLI.ExcelHelper; -namespace ExcelMcp.Commands; +namespace Sbroenne.ExcelMcp.CLI.Commands; /// /// Worksheet management commands implementation diff --git a/src/ExcelMcp/ExcelDiagnostics.cs b/src/ExcelMcp.CLI/ExcelDiagnostics.cs similarity index 99% rename from src/ExcelMcp/ExcelDiagnostics.cs rename to src/ExcelMcp.CLI/ExcelDiagnostics.cs index 98881c20..aa61e8c9 100644 --- a/src/ExcelMcp/ExcelDiagnostics.cs +++ b/src/ExcelMcp.CLI/ExcelDiagnostics.cs @@ -2,7 +2,7 @@ using System.Text; using Spectre.Console; -namespace ExcelMcp; +namespace Sbroenne.ExcelMcp.CLI; /// /// Enhanced Excel diagnostics and error reporting for coding agents diff --git a/src/ExcelMcp/ExcelHelper.cs b/src/ExcelMcp.CLI/ExcelHelper.cs similarity index 99% rename from src/ExcelMcp/ExcelHelper.cs rename to src/ExcelMcp.CLI/ExcelHelper.cs index 08bde783..aa3535e7 100644 --- a/src/ExcelMcp/ExcelHelper.cs +++ b/src/ExcelMcp.CLI/ExcelHelper.cs @@ -2,7 +2,7 @@ using System.Runtime.InteropServices; using Spectre.Console; -namespace ExcelMcp; +namespace Sbroenne.ExcelMcp.CLI; /// /// Helper class for Excel COM automation with proper resource management diff --git a/src/ExcelMcp/ExcelMcp.csproj b/src/ExcelMcp.CLI/ExcelMcp.CLI.csproj similarity index 55% rename from src/ExcelMcp/ExcelMcp.csproj rename to src/ExcelMcp.CLI/ExcelMcp.CLI.csproj index cb401145..7f1a7da7 100644 --- a/src/ExcelMcp/ExcelMcp.csproj +++ b/src/ExcelMcp.CLI/ExcelMcp.CLI.csproj @@ -2,23 +2,31 @@ Exe - net8.0 + net10.0 false true false + + excelcli + Sbroenne.ExcelMcp.CLI + - 1.0.0 - 1.0.0.0 - 1.0.0.0 + 2.0.0 + 2.0.0.0 + 2.0.0.0 - ExcelMcp - A command-line interface tool for automating Microsoft Excel operations using COM interop. Designed for coding agents like GitHub Copilot to programmatically manage Excel workbooks, Power Query queries, worksheets, and named ranges. - excel;cli;powerquery;automation;com;coding-agent;github-copilot;mcp - Initial open source release of ExcelMcp with complete CRUD operations + Sbroenne.ExcelMcp.CLI + A command-line interface tool for automating Microsoft Excel operations using COM interop by Sbroenne. Designed for coding agents like GitHub Copilot to programmatically manage Excel workbooks, Power Query queries, worksheets, and named ranges. Supports Windows x64 and ARM64. + excel;cli;powerquery;automation;com;coding-agent;github-copilot;mcp;arm64;windows;sbroenne + CLI.md + Initial open source release of ExcelMcp.CLI with complete CRUD operations false true + + + true @@ -31,6 +39,7 @@ + diff --git a/src/ExcelMcp/Program.cs b/src/ExcelMcp.CLI/Program.cs similarity index 92% rename from src/ExcelMcp/Program.cs rename to src/ExcelMcp.CLI/Program.cs index bc786aed..3b8c5d1f 100644 --- a/src/ExcelMcp/Program.cs +++ b/src/ExcelMcp.CLI/Program.cs @@ -1,8 +1,8 @@ using Spectre.Console; -using ExcelMcp.Core.Commands; +using Sbroenne.ExcelMcp.CLI.Commands; using System.Reflection; -namespace ExcelMcp; +namespace Sbroenne.ExcelMcp.CLI; class Program { @@ -11,7 +11,7 @@ static async Task Main(string[] args) // Set console encoding for better international character support Console.OutputEncoding = System.Text.Encoding.UTF8; - AnsiConsole.Write(new FigletText("ExcelCLI").Color(Color.Blue)); + AnsiConsole.Write(new FigletText("Excel CLI").Color(Color.Blue)); AnsiConsole.MarkupLine("[dim]Excel Command Line Interface for Coding Agents[/]\n"); if (args.Length == 0) @@ -187,12 +187,12 @@ static int ShowVersion() var informationalVersion = System.Reflection.Assembly.GetExecutingAssembly() .GetCustomAttribute()?.InformationalVersion ?? version?.ToString() ?? "Unknown"; - AnsiConsole.MarkupLine($"[bold cyan]ExcelCLI[/] [green]v{informationalVersion}[/]"); + AnsiConsole.MarkupLine($"[bold cyan]ExcelMcp.CLI[/] [green]v{informationalVersion}[/]"); AnsiConsole.MarkupLine("[dim]Excel Command Line Interface for Coding Agents[/]"); AnsiConsole.MarkupLine($"[dim]Runtime: {System.Runtime.InteropServices.RuntimeInformation.FrameworkDescription}[/]"); AnsiConsole.MarkupLine($"[dim]Platform: {System.Runtime.InteropServices.RuntimeInformation.OSDescription}[/]"); AnsiConsole.WriteLine(); - AnsiConsole.MarkupLine("[bold]Repository:[/] https://github.com/sbroenne/ExcelCLI"); + AnsiConsole.MarkupLine("[bold]Repository:[/] https://github.com/sbroenne/mcp-server-excel"); AnsiConsole.MarkupLine("[bold]License:[/] MIT"); return 0; @@ -200,10 +200,10 @@ static int ShowVersion() static int ShowHelp() { - AnsiConsole.Write(new Rule("[bold cyan]ExcelCLI - Excel Command Line Interface for Coding Agents[/]").RuleStyle("grey")); + AnsiConsole.Write(new Rule("[bold cyan]ExcelMcp.CLI - Excel Command Line Interface for Coding Agents[/]").RuleStyle("grey")); AnsiConsole.WriteLine(); - AnsiConsole.MarkupLine("[bold]Usage:[/] ExcelCLI command args"); + AnsiConsole.MarkupLine("[bold]Usage:[/] excelcli command args"); AnsiConsole.WriteLine(); AnsiConsole.MarkupLine("[bold yellow]File Commands:[/]"); @@ -263,19 +263,19 @@ static int ShowHelp() AnsiConsole.WriteLine(); AnsiConsole.MarkupLine("[bold green]Examples:[/]"); - AnsiConsole.MarkupLine(" [dim]ExcelCLI setup-vba-trust[/] [dim]# Enable VBA for testing[/]"); - AnsiConsole.MarkupLine(" [dim]ExcelCLI check-vba-trust \"test.xlsm\"[/] [dim]# Check VBA access[/]"); - AnsiConsole.MarkupLine(" [dim]ExcelCLI create-empty \"Plan.xlsm\"[/] [dim]# Create macro-enabled workbook[/]"); - AnsiConsole.MarkupLine(" [dim]ExcelCLI script-import \"Plan.xlsm\" \"Helper\" \"code.vba\"[/]"); - AnsiConsole.MarkupLine(" [dim]ExcelCLI pq-list \"Plan.xlsx\"[/]"); - AnsiConsole.MarkupLine(" [dim]ExcelCLI pq-view \"Plan.xlsx\" \"Milestones\"[/]"); - AnsiConsole.MarkupLine(" [dim]ExcelCLI pq-import \"Plan.xlsx\" \"fnHelper\" \"function.pq\"[/]"); - AnsiConsole.MarkupLine(" [dim]ExcelCLI sheet-read \"Plan.xlsx\" \"Data\" \"A1:D10\"[/]"); - AnsiConsole.MarkupLine(" [dim]ExcelCLI param-set \"Plan.xlsx\" \"Start_Date\" \"2025-01-01\"[/]"); + AnsiConsole.MarkupLine(" [dim]excelcli setup-vba-trust[/] [dim]# Enable VBA for testing[/]"); + AnsiConsole.MarkupLine(" [dim]excelcli check-vba-trust \"test.xlsm\"[/] [dim]# Check VBA access[/]"); + AnsiConsole.MarkupLine(" [dim]excelcli create-empty \"Plan.xlsm\"[/] [dim]# Create macro-enabled workbook[/]"); + AnsiConsole.MarkupLine(" [dim]excelcli script-import \"Plan.xlsm\" \"Helper\" \"code.vba\"[/]"); + AnsiConsole.MarkupLine(" [dim]excelcli pq-list \"Plan.xlsx\"[/]"); + AnsiConsole.MarkupLine(" [dim]excelcli pq-view \"Plan.xlsx\" \"Milestones\"[/]"); + AnsiConsole.MarkupLine(" [dim]excelcli pq-import \"Plan.xlsx\" \"fnHelper\" \"function.pq\"[/]"); + AnsiConsole.MarkupLine(" [dim]excelcli sheet-read \"Plan.xlsx\" \"Data\" \"A1:D10\"[/]"); + AnsiConsole.MarkupLine(" [dim]excelcli param-set \"Plan.xlsx\" \"Start_Date\" \"2025-01-01\"[/]"); AnsiConsole.WriteLine(); - AnsiConsole.MarkupLine("[bold]Requirements:[/] Windows + Excel + .NET 8.0"); - AnsiConsole.MarkupLine("[bold]License:[/] MIT | [bold]Repository:[/] https://github.com/sbroenne/ExcelCLI"); + AnsiConsole.MarkupLine("[bold]Requirements:[/] Windows + Excel + .NET 10.0"); + AnsiConsole.MarkupLine("[bold]License:[/] MIT | [bold]Repository:[/] https://github.com/sbroenne/mcp-server-excel"); return 0; } diff --git a/src/ExcelMcp.Core/Commands/CellCommands.cs b/src/ExcelMcp.Core/Commands/CellCommands.cs index 5ec822f7..33557001 100644 --- a/src/ExcelMcp.Core/Commands/CellCommands.cs +++ b/src/ExcelMcp.Core/Commands/CellCommands.cs @@ -1,13 +1,14 @@ using Spectre.Console; -using static ExcelMcp.Core.ExcelHelper; +using static Sbroenne.ExcelMcp.Core.ExcelHelper; -namespace ExcelMcp.Core.Commands; +namespace Sbroenne.ExcelMcp.Core.Commands; /// /// Individual cell operation commands implementation /// public class CellCommands : ICellCommands { + /// public int GetValue(string[] args) { if (!ValidateArgs(args, 4, "cell-get-value ")) return 1; @@ -46,6 +47,7 @@ public int GetValue(string[] args) }); } + /// public int SetValue(string[] args) { if (!ValidateArgs(args, 5, "cell-set-value ")) return 1; @@ -98,6 +100,7 @@ public int SetValue(string[] args) }); } + /// public int GetFormula(string[] args) { if (!ValidateArgs(args, 4, "cell-get-formula ")) return 1; @@ -146,6 +149,7 @@ public int GetFormula(string[] args) }); } + /// public int SetFormula(string[] args) { if (!ValidateArgs(args, 5, "cell-set-formula ")) return 1; diff --git a/src/ExcelMcp.Core/Commands/FileCommands.cs b/src/ExcelMcp.Core/Commands/FileCommands.cs index 55820db5..c566f0bf 100644 --- a/src/ExcelMcp.Core/Commands/FileCommands.cs +++ b/src/ExcelMcp.Core/Commands/FileCommands.cs @@ -1,13 +1,14 @@ using Spectre.Console; -using static ExcelMcp.Core.ExcelHelper; +using static Sbroenne.ExcelMcp.Core.ExcelHelper; -namespace ExcelMcp.Core.Commands; +namespace Sbroenne.ExcelMcp.Core.Commands; /// /// File management commands implementation /// public class FileCommands : IFileCommands { + /// public int CreateEmpty(string[] args) { if (!ValidateArgs(args, 2, "create-empty ")) return 1; diff --git a/src/ExcelMcp.Core/Commands/ICellCommands.cs b/src/ExcelMcp.Core/Commands/ICellCommands.cs index dfc75eab..9277bdf7 100644 --- a/src/ExcelMcp.Core/Commands/ICellCommands.cs +++ b/src/ExcelMcp.Core/Commands/ICellCommands.cs @@ -1,12 +1,35 @@ -namespace ExcelMcp.Core.Commands; +namespace Sbroenne.ExcelMcp.Core.Commands; /// /// Individual cell operation commands /// public interface ICellCommands { + /// + /// Gets the value of a specific cell + /// + /// Command arguments: [file.xlsx, sheet, cellAddress] + /// 0 on success, 1 on error int GetValue(string[] args); + + /// + /// Sets the value of a specific cell + /// + /// Command arguments: [file.xlsx, sheet, cellAddress, value] + /// 0 on success, 1 on error int SetValue(string[] args); + + /// + /// Gets the formula of a specific cell + /// + /// Command arguments: [file.xlsx, sheet, cellAddress] + /// 0 on success, 1 on error int GetFormula(string[] args); + + /// + /// Sets the formula of a specific cell + /// + /// Command arguments: [file.xlsx, sheet, cellAddress, formula] + /// 0 on success, 1 on error int SetFormula(string[] args); } diff --git a/src/ExcelMcp.Core/Commands/IFileCommands.cs b/src/ExcelMcp.Core/Commands/IFileCommands.cs index 80f34610..7f518a83 100644 --- a/src/ExcelMcp.Core/Commands/IFileCommands.cs +++ b/src/ExcelMcp.Core/Commands/IFileCommands.cs @@ -1,9 +1,14 @@ -namespace ExcelMcp.Core.Commands; +namespace Sbroenne.ExcelMcp.Core.Commands; /// /// File management commands for Excel workbooks /// public interface IFileCommands { + /// + /// Creates an empty Excel workbook file + /// + /// Command arguments: [file.xlsx] + /// 0 on success, 1 on error int CreateEmpty(string[] args); } diff --git a/src/ExcelMcp.Core/Commands/IParameterCommands.cs b/src/ExcelMcp.Core/Commands/IParameterCommands.cs index be17e210..cdff39e9 100644 --- a/src/ExcelMcp.Core/Commands/IParameterCommands.cs +++ b/src/ExcelMcp.Core/Commands/IParameterCommands.cs @@ -1,13 +1,42 @@ -namespace ExcelMcp.Core.Commands; +namespace Sbroenne.ExcelMcp.Core.Commands; /// /// Named range/parameter management commands /// public interface IParameterCommands { + /// + /// Lists all named ranges in the workbook + /// + /// Command arguments: [file.xlsx] + /// 0 on success, 1 on error int List(string[] args); + + /// + /// Sets the value of a named range + /// + /// Command arguments: [file.xlsx, paramName, value] + /// 0 on success, 1 on error int Set(string[] args); + + /// + /// Gets the value of a named range + /// + /// Command arguments: [file.xlsx, paramName] + /// 0 on success, 1 on error int Get(string[] args); + + /// + /// Creates a new named range + /// + /// Command arguments: [file.xlsx, paramName, reference] + /// 0 on success, 1 on error int Create(string[] args); + + /// + /// Deletes a named range + /// + /// Command arguments: [file.xlsx, paramName] + /// 0 on success, 1 on error int Delete(string[] args); } diff --git a/src/ExcelMcp.Core/Commands/IPowerQueryCommands.cs b/src/ExcelMcp.Core/Commands/IPowerQueryCommands.cs index 0d0496a0..e03ea1df 100644 --- a/src/ExcelMcp.Core/Commands/IPowerQueryCommands.cs +++ b/src/ExcelMcp.Core/Commands/IPowerQueryCommands.cs @@ -1,17 +1,70 @@ -namespace ExcelMcp.Core.Commands; +namespace Sbroenne.ExcelMcp.Core.Commands; /// /// Power Query management commands /// public interface IPowerQueryCommands { + /// + /// Lists all Power Query queries in the workbook + /// + /// Command arguments: [file.xlsx] + /// 0 on success, 1 on error int List(string[] args); + + /// + /// Views the M code of a Power Query + /// + /// Command arguments: [file.xlsx, queryName] + /// 0 on success, 1 on error int View(string[] args); + + /// + /// Updates an existing Power Query with new M code + /// + /// Command arguments: [file.xlsx, queryName, mCodeFile] + /// 0 on success, 1 on error Task Update(string[] args); + + /// + /// Exports a Power Query's M code to a file + /// + /// Command arguments: [file.xlsx, queryName, outputFile] + /// 0 on success, 1 on error Task Export(string[] args); + + /// + /// Imports M code from a file to create a new Power Query + /// + /// Command arguments: [file.xlsx, queryName, mCodeFile] + /// 0 on success, 1 on error Task Import(string[] args); + + /// + /// Refreshes a Power Query to update its data + /// + /// Command arguments: [file.xlsx, queryName] + /// 0 on success, 1 on error int Refresh(string[] args); + + /// + /// Shows errors from Power Query operations + /// + /// Command arguments: [file.xlsx, queryName] + /// 0 on success, 1 on error int Errors(string[] args); + + /// + /// Loads a connection-only Power Query to a worksheet + /// + /// Command arguments: [file.xlsx, queryName, sheetName] + /// 0 on success, 1 on error int LoadTo(string[] args); + + /// + /// Deletes a Power Query from the workbook + /// + /// Command arguments: [file.xlsx, queryName] + /// 0 on success, 1 on error int Delete(string[] args); } diff --git a/src/ExcelMcp.Core/Commands/IScriptCommands.cs b/src/ExcelMcp.Core/Commands/IScriptCommands.cs index d80067f5..3050ca22 100644 --- a/src/ExcelMcp.Core/Commands/IScriptCommands.cs +++ b/src/ExcelMcp.Core/Commands/IScriptCommands.cs @@ -1,13 +1,42 @@ -namespace ExcelMcp.Core.Commands; +namespace Sbroenne.ExcelMcp.Core.Commands; /// /// VBA script management commands /// public interface IScriptCommands { + /// + /// Lists all VBA modules and procedures in the workbook + /// + /// Command arguments: [file.xlsm] + /// 0 on success, 1 on error int List(string[] args); + + /// + /// Exports VBA module code to a file + /// + /// Command arguments: [file.xlsm, moduleName, outputFile] + /// 0 on success, 1 on error int Export(string[] args); + + /// + /// Imports VBA code from a file to create a new module + /// + /// Command arguments: [file.xlsm, moduleName, vbaFile] + /// 0 on success, 1 on error Task Import(string[] args); + + /// + /// Updates an existing VBA module with new code + /// + /// Command arguments: [file.xlsm, moduleName, vbaFile] + /// 0 on success, 1 on error Task Update(string[] args); + + /// + /// Runs a VBA procedure with optional parameters + /// + /// Command arguments: [file.xlsm, module.procedure, param1, param2, ...] + /// 0 on success, 1 on error int Run(string[] args); } diff --git a/src/ExcelMcp.Core/Commands/ISetupCommands.cs b/src/ExcelMcp.Core/Commands/ISetupCommands.cs index d366899a..930a69e2 100644 --- a/src/ExcelMcp.Core/Commands/ISetupCommands.cs +++ b/src/ExcelMcp.Core/Commands/ISetupCommands.cs @@ -1,4 +1,4 @@ -namespace ExcelMcp.Core.Commands; +namespace Sbroenne.ExcelMcp.Core.Commands; /// /// Setup and configuration commands for ExcelCLI diff --git a/src/ExcelMcp.Core/Commands/ISheetCommands.cs b/src/ExcelMcp.Core/Commands/ISheetCommands.cs index 0ec54b33..00d4bbd1 100644 --- a/src/ExcelMcp.Core/Commands/ISheetCommands.cs +++ b/src/ExcelMcp.Core/Commands/ISheetCommands.cs @@ -1,17 +1,70 @@ -namespace ExcelMcp.Core.Commands; +namespace Sbroenne.ExcelMcp.Core.Commands; /// /// Worksheet management commands /// public interface ISheetCommands { + /// + /// Lists all worksheets in the workbook + /// + /// Command arguments: [file.xlsx] + /// 0 on success, 1 on error int List(string[] args); + + /// + /// Reads data from a worksheet range + /// + /// Command arguments: [file.xlsx, sheetName, range] + /// 0 on success, 1 on error int Read(string[] args); + + /// + /// Writes CSV data to a worksheet + /// + /// Command arguments: [file.xlsx, sheetName, csvFile] + /// 0 on success, 1 on error Task Write(string[] args); + + /// + /// Copies a worksheet within the workbook + /// + /// Command arguments: [file.xlsx, sourceSheet, targetSheet] + /// 0 on success, 1 on error int Copy(string[] args); + + /// + /// Deletes a worksheet from the workbook + /// + /// Command arguments: [file.xlsx, sheetName] + /// 0 on success, 1 on error int Delete(string[] args); + + /// + /// Creates a new worksheet in the workbook + /// + /// Command arguments: [file.xlsx, sheetName] + /// 0 on success, 1 on error int Create(string[] args); + + /// + /// Renames an existing worksheet + /// + /// Command arguments: [file.xlsx, oldName, newName] + /// 0 on success, 1 on error int Rename(string[] args); + + /// + /// Clears data from a worksheet range + /// + /// Command arguments: [file.xlsx, sheetName, range] + /// 0 on success, 1 on error int Clear(string[] args); + + /// + /// Appends CSV data to existing worksheet content + /// + /// Command arguments: [file.xlsx, sheetName, csvFile] + /// 0 on success, 1 on error int Append(string[] args); } diff --git a/src/ExcelMcp.Core/Commands/ParameterCommands.cs b/src/ExcelMcp.Core/Commands/ParameterCommands.cs index 328167ae..35333465 100644 --- a/src/ExcelMcp.Core/Commands/ParameterCommands.cs +++ b/src/ExcelMcp.Core/Commands/ParameterCommands.cs @@ -1,13 +1,14 @@ using Spectre.Console; -using static ExcelMcp.Core.ExcelHelper; +using static Sbroenne.ExcelMcp.Core.ExcelHelper; -namespace ExcelMcp.Core.Commands; +namespace Sbroenne.ExcelMcp.Core.Commands; /// /// Named range/parameter management commands implementation /// public class ParameterCommands : IParameterCommands { + /// public int List(string[] args) { if (!ValidateArgs(args, 2, "param-list ")) return 1; @@ -66,6 +67,7 @@ public int List(string[] args) }); } + /// public int Set(string[] args) { if (!ValidateArgs(args, 4, "param-set ")) return 1; @@ -94,6 +96,7 @@ public int Set(string[] args) }); } + /// public int Get(string[] args) { if (!ValidateArgs(args, 3, "param-get ")) return 1; @@ -149,6 +152,7 @@ public int Get(string[] args) }); } + /// public int Create(string[] args) { if (!ValidateArgs(args, 4, "param-create ")) return 1; @@ -189,6 +193,7 @@ public int Create(string[] args) }); } + /// public int Delete(string[] args) { if (!ValidateArgs(args, 3, "param-delete ")) return 1; diff --git a/src/ExcelMcp.Core/Commands/PowerQueryCommands.cs b/src/ExcelMcp.Core/Commands/PowerQueryCommands.cs index 7ee93599..df34489e 100644 --- a/src/ExcelMcp.Core/Commands/PowerQueryCommands.cs +++ b/src/ExcelMcp.Core/Commands/PowerQueryCommands.cs @@ -1,7 +1,7 @@ using Spectre.Console; -using static ExcelMcp.Core.ExcelHelper; +using static Sbroenne.ExcelMcp.Core.ExcelHelper; -namespace ExcelMcp.Core.Commands; +namespace Sbroenne.ExcelMcp.Core.Commands; /// /// Power Query management commands implementation @@ -54,6 +54,8 @@ private static int ComputeLevenshteinDistance(string s1, string s2) return d[s1.Length, s2.Length]; } + + /// public int List(string[] args) { if (!ValidateArgs(args, 2, "pq-list ")) return 1; @@ -152,6 +154,7 @@ public int List(string[] args) }); } + /// public int View(string[] args) { if (!ValidateArgs(args, 3, "pq-view ")) return 1; @@ -257,6 +260,7 @@ public int View(string[] args) }); } + /// public async Task Update(string[] args) { if (!ValidateArgs(args, 4, "pq-update ")) return 1; @@ -290,6 +294,7 @@ public async Task Update(string[] args) }); } + /// public async Task Export(string[] args) { if (!ValidateArgs(args, 4, "pq-export ")) return 1; @@ -318,6 +323,7 @@ public async Task Export(string[] args) })); } + /// public async Task Import(string[] args) { if (!ValidateArgs(args, 4, "pq-import ")) return 1; @@ -356,6 +362,11 @@ public async Task Import(string[] args) }); } + /// + /// Analyzes and displays data sources used by Power Queries + /// + /// Command arguments: [file.xlsx] + /// 0 on success, 1 on error public int Sources(string[] args) { if (!ValidateArgs(args, 2, "pq-sources ")) return 1; @@ -451,6 +462,11 @@ public int Sources(string[] args) }); } + /// + /// Tests connectivity to a Power Query data source + /// + /// Command arguments: [file.xlsx, sourceName] + /// 0 on success, 1 on error public int Test(string[] args) { if (!ValidateArgs(args, 3, "pq-test ")) return 1; @@ -514,6 +530,11 @@ public int Test(string[] args) }); } + /// + /// Previews sample data from a Power Query data source + /// + /// Command arguments: [file.xlsx, sourceName] + /// 0 on success, 1 on error public int Peek(string[] args) { if (!ValidateArgs(args, 3, "pq-peek ")) return 1; @@ -600,6 +621,11 @@ public int Peek(string[] args) }); } + /// + /// Evaluates M code expressions interactively + /// + /// Command arguments: [file.xlsx, expression] + /// 0 on success, 1 on error public int Eval(string[] args) { if (args.Length < 3) @@ -711,6 +737,7 @@ public int Eval(string[] args) }); } + /// public int Refresh(string[] args) { if (!ValidateArgs(args, 2, "pq-refresh ")) @@ -829,6 +856,7 @@ public int Refresh(string[] args) }); } + /// public int Errors(string[] args) { if (!ValidateArgs(args, 2, "pq-errors (file.xlsx) (query-name)")) @@ -932,6 +960,7 @@ public int Errors(string[] args) }); } + /// public int LoadTo(string[] args) { if (!ValidateArgs(args, 3, "pq-loadto ")) @@ -1073,6 +1102,7 @@ public int LoadTo(string[] args) }); } + /// public int Delete(string[] args) { if (!ValidateArgs(args, 3, "pq-delete ")) return 1; diff --git a/src/ExcelMcp.Core/Commands/ScriptCommands.cs b/src/ExcelMcp.Core/Commands/ScriptCommands.cs index 9250b3a1..522e8dda 100644 --- a/src/ExcelMcp.Core/Commands/ScriptCommands.cs +++ b/src/ExcelMcp.Core/Commands/ScriptCommands.cs @@ -1,8 +1,8 @@ using Spectre.Console; using System.Runtime.InteropServices; -using static ExcelMcp.Core.ExcelHelper; +using static Sbroenne.ExcelMcp.Core.ExcelHelper; -namespace ExcelMcp.Core.Commands; +namespace Sbroenne.ExcelMcp.Core.Commands; /// /// VBA script management commands @@ -72,6 +72,7 @@ private static bool ValidateVbaFile(string filePath) return true; } + /// public int List(string[] args) { if (args.Length < 2) @@ -154,6 +155,7 @@ public int List(string[] args) }); } + /// public int Export(string[] args) { if (args.Length < 3) @@ -223,6 +225,7 @@ public int Export(string[] args) }); } + /// public int Run(string[] args) { if (args.Length < 3) diff --git a/src/ExcelMcp.Core/Commands/SetupCommands.cs b/src/ExcelMcp.Core/Commands/SetupCommands.cs index 5ca929e0..0d26113c 100644 --- a/src/ExcelMcp.Core/Commands/SetupCommands.cs +++ b/src/ExcelMcp.Core/Commands/SetupCommands.cs @@ -1,9 +1,9 @@ using Spectre.Console; using Microsoft.Win32; using System; -using static ExcelMcp.Core.ExcelHelper; +using static Sbroenne.ExcelMcp.Core.ExcelHelper; -namespace ExcelMcp.Core.Commands; +namespace Sbroenne.ExcelMcp.Core.Commands; /// /// Setup and configuration commands for ExcelCLI diff --git a/src/ExcelMcp.Core/Commands/SheetCommands.cs b/src/ExcelMcp.Core/Commands/SheetCommands.cs index 553260e3..8aaa42f8 100644 --- a/src/ExcelMcp.Core/Commands/SheetCommands.cs +++ b/src/ExcelMcp.Core/Commands/SheetCommands.cs @@ -1,14 +1,15 @@ using Spectre.Console; using System.Text; -using static ExcelMcp.Core.ExcelHelper; +using static Sbroenne.ExcelMcp.Core.ExcelHelper; -namespace ExcelMcp.Core.Commands; +namespace Sbroenne.ExcelMcp.Core.Commands; /// /// Worksheet management commands implementation /// public class SheetCommands : ISheetCommands { + /// public int List(string[] args) { if (!ValidateArgs(args, 2, "sheet-list ")) return 1; @@ -67,6 +68,7 @@ public int List(string[] args) }); } + /// public int Read(string[] args) { if (!ValidateArgs(args, 3, "sheet-read [range]")) return 1; @@ -349,6 +351,7 @@ private static int ComputeLevenshteinDistance(string s1, string s2) return d[s1.Length, s2.Length]; } + /// public async Task Write(string[] args) { if (!ValidateArgs(args, 4, "sheet-write ")) return 1; @@ -419,6 +422,7 @@ public async Task Write(string[] args) }); } + /// public int Copy(string[] args) { if (!ValidateArgs(args, 4, "sheet-copy ")) return 1; @@ -458,6 +462,7 @@ public int Copy(string[] args) }); } + /// public int Delete(string[] args) { if (!ValidateArgs(args, 3, "sheet-delete ")) return 1; @@ -492,6 +497,7 @@ public int Delete(string[] args) }); } + /// public int Create(string[] args) { if (!ValidateArgs(args, 3, "sheet-create ")) return 1; @@ -532,6 +538,7 @@ public int Create(string[] args) }); } + /// public int Rename(string[] args) { if (!ValidateArgs(args, 4, "sheet-rename ")) return 1; @@ -576,6 +583,7 @@ public int Rename(string[] args) }); } + /// public int Clear(string[] args) { if (!ValidateArgs(args, 3, "sheet-clear (range)")) return 1; @@ -614,6 +622,7 @@ public int Clear(string[] args) }); } + /// public int Append(string[] args) { if (!ValidateArgs(args, 4, "sheet-append ")) return 1; diff --git a/src/ExcelMcp.Core/ExcelDiagnostics.cs b/src/ExcelMcp.Core/ExcelDiagnostics.cs index 4b5035c4..251edcac 100644 --- a/src/ExcelMcp.Core/ExcelDiagnostics.cs +++ b/src/ExcelMcp.Core/ExcelDiagnostics.cs @@ -2,7 +2,7 @@ using System.Text; using Spectre.Console; -namespace ExcelMcp.Core; +namespace Sbroenne.ExcelMcp.Core; /// /// Enhanced Excel diagnostics and error reporting for coding agents diff --git a/src/ExcelMcp.Core/ExcelHelper.cs b/src/ExcelMcp.Core/ExcelHelper.cs index d8a1929c..62915786 100644 --- a/src/ExcelMcp.Core/ExcelHelper.cs +++ b/src/ExcelMcp.Core/ExcelHelper.cs @@ -2,13 +2,21 @@ using System.Runtime.InteropServices; using Spectre.Console; -namespace ExcelMcp.Core; +namespace Sbroenne.ExcelMcp.Core; /// /// Helper class for Excel COM automation with proper resource management /// public static class ExcelHelper { + /// + /// Executes an action with Excel COM automation using proper resource management + /// + /// Return type of the action + /// Path to the Excel file + /// Whether to save changes to the file + /// Action to execute with Excel application and workbook + /// Result of the action [SuppressMessage("Interoperability", "CA1416:Validate platform compatibility")] public static T WithExcel(string filePath, bool save, Func action) { @@ -159,6 +167,12 @@ public static T WithExcel(string filePath, bool save, Func + /// Finds a Power Query by name in the workbook + /// + /// Excel workbook COM object + /// Name of the query to find + /// The query COM object if found, null otherwise public static dynamic? FindQuery(dynamic workbook, string queryName) { try @@ -175,6 +189,12 @@ public static T WithExcel(string filePath, bool save, Func + /// Finds a named range by name in the workbook + /// + /// Excel workbook COM object + /// Name of the named range to find + /// The named range COM object if found, null otherwise public static dynamic? FindName(dynamic workbook, string name) { try @@ -191,6 +211,12 @@ public static T WithExcel(string filePath, bool save, Func + /// Finds a worksheet by name in the workbook + /// + /// Excel workbook COM object + /// Name of the worksheet to find + /// The worksheet COM object if found, null otherwise public static dynamic? FindSheet(dynamic workbook, string sheetName) { try @@ -207,6 +233,13 @@ public static T WithExcel(string filePath, bool save, Func + /// Validates command line arguments and displays usage if invalid + /// + /// Command line arguments array + /// Required number of arguments + /// Usage string to display if validation fails + /// True if arguments are valid, false otherwise public static bool ValidateArgs(string[] args, int required, string usage) { if (args.Length >= required) return true; diff --git a/src/ExcelMcp.Core/ExcelMcp.Core.csproj b/src/ExcelMcp.Core/ExcelMcp.Core.csproj index d5717b37..34515aa6 100644 --- a/src/ExcelMcp.Core/ExcelMcp.Core.csproj +++ b/src/ExcelMcp.Core/ExcelMcp.Core.csproj @@ -1,14 +1,27 @@  - net8.0 + net10.0 enable enable + + Sbroenne.ExcelMcp.Core + Sbroenne.ExcelMcp.Core + + + 2.0.0 + 2.0.0.0 + 2.0.0.0 + - ExcelMcp.Core - Core library for Excel automation operations via COM interop. Shared by ExcelMcp and ExcelMcp.McpServer. - excel;automation;com;powerquery;vba;core;mcp + Sbroenne.ExcelMcp.Core + Core library for Excel automation operations via COM interop by Sbroenne. Shared by ExcelMcp and ExcelMcp.McpServer. + excel;automation;com;powerquery;vba;core;mcp;sbroenne + + + true + bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml diff --git a/src/ExcelMcp.McpServer/.mcp/server.json b/src/ExcelMcp.McpServer/.mcp/server.json new file mode 100644 index 00000000..fc8821a1 --- /dev/null +++ b/src/ExcelMcp.McpServer/.mcp/server.json @@ -0,0 +1,176 @@ +{ + "mcpVersion": "2024-11-05", + "name": "ExcelMcp Server", + "version": "2.0.0", + "description": "Model Context Protocol server for Excel automation. Enables AI assistants to automate Excel development workflows - Power Query refactoring, VBA enhancement, and Excel automation through structured JSON API.", + "author": { + "name": "ExcelMcp Project", + "email": "support@excelmcp.io" + }, + "homepage": "https://github.com/sbroenne/mcp-server-excel", + "license": "MIT", + "repository": { + "type": "git", + "url": "https://github.com/sbroenne/mcp-server-excel.git" + }, + "bugs": "https://github.com/sbroenne/mcp-server-excel/issues", + "capabilities": { + "resources": {}, + "tools": { + "listChanged": false + }, + "prompts": {}, + "logging": {} + }, + "config": { + "commands": { + "start": "dnx Sbroenne.ExcelMcp.McpServer@latest --yes" + }, + "environment": { + "requirements": [ + { + "name": ".NET 10 SDK", + "install": "winget install Microsoft.DotNet.SDK.10" + }, + { + "name": "Microsoft Excel", + "platform": "windows" + } + ] + } + }, + "tools": [ + { + "name": "excel_file", + "description": "Manage Excel files - create, validate, check existence", + "inputSchema": { + "type": "object", + "properties": { + "action": { + "type": "string", + "enum": ["create-empty", "validate", "check-exists"] + }, + "filePath": { + "type": "string", + "description": "Path to Excel file" + } + }, + "required": ["action", "filePath"] + } + }, + { + "name": "excel_powerquery", + "description": "Manage Power Query operations - list, view, import, export, update, refresh, delete", + "inputSchema": { + "type": "object", + "properties": { + "action": { + "type": "string", + "enum": ["list", "view", "import", "export", "update", "refresh", "delete", "loadto"] + }, + "filePath": { + "type": "string", + "description": "Path to Excel file" + }, + "queryName": { + "type": "string", + "description": "Name of Power Query" + } + }, + "required": ["action", "filePath"] + } + }, + { + "name": "excel_worksheet", + "description": "Manage worksheets - list, read, write, create, rename, copy, delete, clear, append", + "inputSchema": { + "type": "object", + "properties": { + "action": { + "type": "string", + "enum": ["list", "read", "write", "create", "rename", "copy", "delete", "clear", "append"] + }, + "filePath": { + "type": "string", + "description": "Path to Excel file" + }, + "sheetName": { + "type": "string", + "description": "Name of worksheet" + } + }, + "required": ["action", "filePath"] + } + }, + { + "name": "excel_parameter", + "description": "Manage named ranges/parameters - list, get, set, create, delete", + "inputSchema": { + "type": "object", + "properties": { + "action": { + "type": "string", + "enum": ["list", "get", "set", "create", "delete"] + }, + "filePath": { + "type": "string", + "description": "Path to Excel file" + }, + "paramName": { + "type": "string", + "description": "Name of parameter/named range" + } + }, + "required": ["action", "filePath"] + } + }, + { + "name": "excel_cell", + "description": "Manage individual cells - get/set values and formulas", + "inputSchema": { + "type": "object", + "properties": { + "action": { + "type": "string", + "enum": ["get-value", "set-value", "get-formula", "set-formula"] + }, + "filePath": { + "type": "string", + "description": "Path to Excel file" + }, + "sheetName": { + "type": "string", + "description": "Name of worksheet" + }, + "cellAddress": { + "type": "string", + "description": "Cell address (e.g., A1)" + } + }, + "required": ["action", "filePath", "sheetName", "cellAddress"] + } + }, + { + "name": "excel_vba", + "description": "Manage VBA scripts - list, export, import, update, run, delete", + "inputSchema": { + "type": "object", + "properties": { + "action": { + "type": "string", + "enum": ["list", "export", "import", "update", "run", "delete"] + }, + "filePath": { + "type": "string", + "description": "Path to Excel file (.xlsm required for VBA operations)" + }, + "moduleName": { + "type": "string", + "description": "Name of VBA module" + } + }, + "required": ["action", "filePath"] + } + } + ] +} \ No newline at end of file diff --git a/src/ExcelMcp.McpServer/ExcelMcp.McpServer.csproj b/src/ExcelMcp.McpServer/ExcelMcp.McpServer.csproj index 4ac95c90..e255ddad 100644 --- a/src/ExcelMcp.McpServer/ExcelMcp.McpServer.csproj +++ b/src/ExcelMcp.McpServer/ExcelMcp.McpServer.csproj @@ -2,20 +2,25 @@ Exe - net8.0 + net10.0 enable enable + + Sbroenne.ExcelMcp.McpServer + Sbroenne.ExcelMcp.McpServer + - 1.0.3 - 1.0.3.0 - 1.0.3.0 + 2.0.0 + 2.0.0.0 + 2.0.0.0 - - ExcelMcp.McpServer - ExcelMcp Model Context Protocol Server - Model Context Protocol (MCP) server for ExcelMcp. Enables AI assistants like GitHub Copilot, Claude, and ChatGPT to automate Excel development workflows - Power Query refactoring, VBA enhancement, and Excel automation through structured JSON API. - excel;mcp;model-context-protocol;ai;automation;github-copilot;claude;chatgpt;power-query;vba;excel-automation;dotnet-tool + + Sbroenne.ExcelMcp.McpServer + McpServer + Sbroenne ExcelMcp Model Context Protocol Server + Model Context Protocol (MCP) server for ExcelMcp by Sbroenne. Enables AI assistants like GitHub Copilot, Claude, and ChatGPT to automate Excel development workflows - Power Query refactoring, VBA enhancement, and Excel automation through structured JSON API. Uses portable .NET 10 deployment supporting Windows x64 and ARM64. + excel;mcp;model-context-protocol;ai;automation;github-copilot;claude;chatgpt;power-query;vba;excel-automation;dotnet-tool;arm64;windows;sbroenne README.md See https://github.com/sbroenne/mcp-server-excel/releases for release notes false @@ -23,6 +28,14 @@ true mcp-excel + + + false + false + + + + true @@ -33,7 +46,6 @@ - all runtime; build; native; contentfiles; analyzers @@ -41,6 +53,13 @@ + + + PreserveNewest + true + .mcp/server.json + + diff --git a/src/ExcelMcp.McpServer/Program.cs b/src/ExcelMcp.McpServer/Program.cs index 0e90b837..255d059a 100644 --- a/src/ExcelMcp.McpServer/Program.cs +++ b/src/ExcelMcp.McpServer/Program.cs @@ -3,7 +3,7 @@ using Microsoft.Extensions.Logging; using ModelContextProtocol.Server; -namespace ExcelMcp.McpServer; +namespace Sbroenne.ExcelMcp.McpServer; /// /// ExcelCLI Model Context Protocol (MCP) Server diff --git a/src/ExcelMcp.McpServer/README.md b/src/ExcelMcp.McpServer/README.md index 6a2a5293..b7ade278 100644 --- a/src/ExcelMcp.McpServer/README.md +++ b/src/ExcelMcp.McpServer/README.md @@ -1,29 +1,25 @@ # ExcelMcp Model Context Protocol (MCP) Server -[![NuGet](https://img.shields.io/nuget/v/ExcelMcp.McpServer.svg)](https://www.nuget.org/packages/ExcelMcp.McpServer) -[![NuGet Downloads](https://img.shields.io/nuget/dt/ExcelMcp.McpServer.svg)](https://www.nuget.org/packages/ExcelMcp.McpServer) -[![.NET Tool](https://img.shields.io/badge/.NET%20Tool-Global-blue.svg)](https://www.nuget.org/packages/ExcelMcp.McpServer) +[![NuGet](https://img.shields.io/nuget/v/Sbroenne.ExcelMcp.McpServer.svg)](https://www.nuget.org/packages/Sbroenne.ExcelMcp.McpServer) +[![NuGet Downloads](https://img.shields.io/nuget/dt/Sbroenne.ExcelMcp.McpServer.svg)](https://www.nuget.org/packages/Sbroenne.ExcelMcp.McpServer) +[![MCP Server](https://img.shields.io/badge/MCP%20Server-NuGet-blue.svg)](https://www.nuget.org/packages/Sbroenne.ExcelMcp.McpServer) The ExcelMcp MCP Server provides AI assistants with powerful Excel automation capabilities through the official Model Context Protocol (MCP) SDK. This enables natural language interactions with Excel through AI coding assistants like **GitHub Copilot**, **Claude**, and **ChatGPT** using a modern resource-based architecture. ## 🚀 Quick Start -### Option 1: Install via NuGet (Recommended) +### Option 1: Microsoft's NuGet MCP Approach (Recommended) ```bash -# Install as a global .NET tool -dotnet tool install --global ExcelMcp.McpServer +# Download and execute using dnx command +dnx Sbroenne.ExcelMcp.McpServer@latest --yes -# Run the MCP server -mcp-excel - -# Update to latest version -dotnet tool update --global ExcelMcp.McpServer - -# Uninstall -dotnet tool uninstall --global ExcelMcp.McpServer +# Execute specific version +dnx Sbroenne.ExcelMcp.McpServer@1.0.0 --yes ``` +This follows Microsoft's official [NuGet MCP approach](https://learn.microsoft.com/en-us/nuget/concepts/nuget-mcp) where the `dnx` command automatically downloads and executes the MCP server from NuGet.org. + ### Option 2: Build and Run from Source ```bash @@ -36,12 +32,13 @@ dotnet run --project src/ExcelMcp.McpServer/ExcelMcp.McpServer.csproj ### Configuration with AI Assistants -**For .NET Tool Installation:** +**For NuGet MCP Installation (dnx):** ```json { "servers": { "excel": { - "command": "mcp-excel" + "command": "dnx", + "args": ["Sbroenne.ExcelMcp.McpServer@latest", "--yes"] } } } @@ -209,7 +206,7 @@ ExcelMcp.McpServer |-------------|---------| | **Windows OS** | COM interop for Excel automation | | **Microsoft Excel** | Direct Excel application control | -| **.NET 8.0** | MCP server runtime | +| **.NET 10 SDK** | Required for dnx command | | **ExcelMcp.Core** | Shared Excel automation logic | ## 🎯 Benefits of Resource-Based Architecture diff --git a/src/ExcelMcp.McpServer/Tools/ExcelTools.cs b/src/ExcelMcp.McpServer/Tools/ExcelTools.cs index 5c13e381..939db40b 100644 --- a/src/ExcelMcp.McpServer/Tools/ExcelTools.cs +++ b/src/ExcelMcp.McpServer/Tools/ExcelTools.cs @@ -1,9 +1,9 @@ -using ExcelMcp.Core.Commands; +using Sbroenne.ExcelMcp.Core.Commands; using ModelContextProtocol.Server; using System.ComponentModel; using System.Text.Json; -namespace ExcelMcp.McpServer.Tools; +namespace Sbroenne.ExcelMcp.McpServer.Tools; /// /// Excel automation tools for Model Context Protocol (MCP) server. diff --git a/tests/ExcelMcp.Tests/Commands/FileCommandsTests.cs b/tests/ExcelMcp.CLI.Tests/Commands/FileCommandsTests.cs similarity index 98% rename from tests/ExcelMcp.Tests/Commands/FileCommandsTests.cs rename to tests/ExcelMcp.CLI.Tests/Commands/FileCommandsTests.cs index 4c21d46e..1f074279 100644 --- a/tests/ExcelMcp.Tests/Commands/FileCommandsTests.cs +++ b/tests/ExcelMcp.CLI.Tests/Commands/FileCommandsTests.cs @@ -1,8 +1,8 @@ using Xunit; -using ExcelMcp.Core.Commands; +using Sbroenne.ExcelMcp.Core.Commands; using System.IO; -namespace ExcelMcp.Tests.Commands; +namespace Sbroenne.ExcelMcp.CLI.Tests.Commands; /// /// Integration tests for file operations including Excel workbook creation and management. diff --git a/tests/ExcelMcp.Tests/Commands/IntegrationRoundTripTests.cs b/tests/ExcelMcp.CLI.Tests/Commands/IntegrationRoundTripTests.cs similarity index 99% rename from tests/ExcelMcp.Tests/Commands/IntegrationRoundTripTests.cs rename to tests/ExcelMcp.CLI.Tests/Commands/IntegrationRoundTripTests.cs index cc3261c2..524b0ad0 100644 --- a/tests/ExcelMcp.Tests/Commands/IntegrationRoundTripTests.cs +++ b/tests/ExcelMcp.CLI.Tests/Commands/IntegrationRoundTripTests.cs @@ -1,8 +1,8 @@ using Xunit; -using ExcelMcp.Core.Commands; +using Sbroenne.ExcelMcp.Core.Commands; using System.IO; -namespace ExcelMcp.Tests.Commands; +namespace Sbroenne.ExcelMcp.CLI.Tests.Commands; /// /// Integration tests that verify complete round-trip workflows combining multiple ExcelCLI features. diff --git a/tests/ExcelMcp.Tests/Commands/PowerQueryCommandsTests.cs b/tests/ExcelMcp.CLI.Tests/Commands/PowerQueryCommandsTests.cs similarity index 99% rename from tests/ExcelMcp.Tests/Commands/PowerQueryCommandsTests.cs rename to tests/ExcelMcp.CLI.Tests/Commands/PowerQueryCommandsTests.cs index 6225b88e..74c59a5c 100644 --- a/tests/ExcelMcp.Tests/Commands/PowerQueryCommandsTests.cs +++ b/tests/ExcelMcp.CLI.Tests/Commands/PowerQueryCommandsTests.cs @@ -1,8 +1,8 @@ using Xunit; -using ExcelMcp.Core.Commands; +using Sbroenne.ExcelMcp.Core.Commands; using System.IO; -namespace ExcelMcp.Tests.Commands; +namespace Sbroenne.ExcelMcp.CLI.Tests.Commands; /// /// Integration tests for Power Query operations using Excel COM automation. diff --git a/tests/ExcelMcp.Tests/Commands/ScriptCommandsTests.cs b/tests/ExcelMcp.CLI.Tests/Commands/ScriptCommandsTests.cs similarity index 99% rename from tests/ExcelMcp.Tests/Commands/ScriptCommandsTests.cs rename to tests/ExcelMcp.CLI.Tests/Commands/ScriptCommandsTests.cs index 30cbc52c..c89e0291 100644 --- a/tests/ExcelMcp.Tests/Commands/ScriptCommandsTests.cs +++ b/tests/ExcelMcp.CLI.Tests/Commands/ScriptCommandsTests.cs @@ -1,8 +1,9 @@ using Xunit; -using ExcelMcp.Core.Commands; +using Sbroenne.ExcelMcp.Core.Commands; +using Sbroenne.ExcelMcp.Core; using System.IO; -namespace ExcelMcp.Tests.Commands; +namespace Sbroenne.ExcelMcp.CLI.Tests.Commands; /// /// Integration tests for VBA script operations using Excel COM automation. diff --git a/tests/ExcelMcp.Tests/Commands/SheetCommandsTests.cs b/tests/ExcelMcp.CLI.Tests/Commands/SheetCommandsTests.cs similarity index 96% rename from tests/ExcelMcp.Tests/Commands/SheetCommandsTests.cs rename to tests/ExcelMcp.CLI.Tests/Commands/SheetCommandsTests.cs index 98917f20..88e210e1 100644 --- a/tests/ExcelMcp.Tests/Commands/SheetCommandsTests.cs +++ b/tests/ExcelMcp.CLI.Tests/Commands/SheetCommandsTests.cs @@ -1,7 +1,7 @@ using Xunit; -using ExcelMcp.Core.Commands; +using Sbroenne.ExcelMcp.Core.Commands; -namespace ExcelMcp.Tests.Commands; +namespace Sbroenne.ExcelMcp.CLI.Tests.Commands; /// /// Integration tests for worksheet operations using Excel COM automation. diff --git a/tests/ExcelMcp.CLI.Tests/ExcelMcp.CLI.Tests.csproj b/tests/ExcelMcp.CLI.Tests/ExcelMcp.CLI.Tests.csproj new file mode 100644 index 00000000..ccdd387d --- /dev/null +++ b/tests/ExcelMcp.CLI.Tests/ExcelMcp.CLI.Tests.csproj @@ -0,0 +1,34 @@ + + + + net10.0 + latest + enable + enable + false + true + + + Sbroenne.ExcelMcp.CLI.Tests + Sbroenne.ExcelMcp.CLI.Tests + + + + + + all + runtime; build; native; contentfiles; analyzers; buildtransitive + + + + all + runtime; build; native; contentfiles; analyzers + + + + + + + + + \ No newline at end of file diff --git a/tests/ExcelMcp.Tests/UnitTests.cs b/tests/ExcelMcp.CLI.Tests/UnitTests.cs similarity index 98% rename from tests/ExcelMcp.Tests/UnitTests.cs rename to tests/ExcelMcp.CLI.Tests/UnitTests.cs index a9e8fbc9..0ec9a1ae 100644 --- a/tests/ExcelMcp.Tests/UnitTests.cs +++ b/tests/ExcelMcp.CLI.Tests/UnitTests.cs @@ -1,7 +1,7 @@ using Xunit; -using ExcelMcp.Core; +using Sbroenne.ExcelMcp.Core; -namespace ExcelMcp.Tests; +namespace Sbroenne.ExcelMcp.CLI.Tests; /// /// Fast unit tests that don't require Excel installation. diff --git a/tests/ExcelMcp.Tests/ExcelMcp.Tests.csproj b/tests/ExcelMcp.McpServer.Tests/ExcelMcp.McpServer.Tests.csproj similarity index 65% rename from tests/ExcelMcp.Tests/ExcelMcp.Tests.csproj rename to tests/ExcelMcp.McpServer.Tests/ExcelMcp.McpServer.Tests.csproj index 98f2b45a..14668bff 100644 --- a/tests/ExcelMcp.Tests/ExcelMcp.Tests.csproj +++ b/tests/ExcelMcp.McpServer.Tests/ExcelMcp.McpServer.Tests.csproj @@ -1,10 +1,16 @@ - + - net8.0 + net10.0 latest enable enable + false + true + + + Sbroenne.ExcelMcp.McpServer.Tests + Sbroenne.ExcelMcp.McpServer.Tests @@ -14,16 +20,15 @@ runtime; build; native; contentfiles; analyzers; buildtransitive - + all - runtime; build; native; contentfiles; analyzers; buildtransitive + runtime; build; native; contentfiles; analyzers - - + - + \ No newline at end of file diff --git a/tests/ExcelMcp.Tests/Commands/ExcelMcpServerTests.cs b/tests/ExcelMcp.McpServer.Tests/Tools/ExcelMcpServerTests.cs similarity index 98% rename from tests/ExcelMcp.Tests/Commands/ExcelMcpServerTests.cs rename to tests/ExcelMcp.McpServer.Tests/Tools/ExcelMcpServerTests.cs index df9bab46..f31b005b 100644 --- a/tests/ExcelMcp.Tests/Commands/ExcelMcpServerTests.cs +++ b/tests/ExcelMcp.McpServer.Tests/Tools/ExcelMcpServerTests.cs @@ -1,9 +1,9 @@ using Xunit; -using ExcelMcp.McpServer.Tools; +using Sbroenne.ExcelMcp.McpServer.Tools; using System.IO; using System.Text.Json; -namespace ExcelMcp.Tests.Commands; +namespace Sbroenne.ExcelMcp.McpServer.Tests.Tools; /// /// Integration tests for ExcelCLI MCP Server using official MCP SDK diff --git a/tests/TEST_GUIDE.md b/tests/TEST_GUIDE.md index e8360a8b..df88ff98 100644 --- a/tests/TEST_GUIDE.md +++ b/tests/TEST_GUIDE.md @@ -129,7 +129,7 @@ dotnet test --filter "Speed!=Slow" ```text tests/ -├── ExcelMcp.Tests/ +├── ExcelMcp.CLI.Tests/ │ ├── UnitTests.cs # [Unit, Fast] - No Excel required │ └── Commands/ │ ├── FileCommandsTests.cs # [Integration, Medium, Files] - Excel file operations @@ -137,6 +137,8 @@ tests/ │ ├── ScriptCommandsTests.cs # [Integration, Medium, VBA] - VBA script operations │ ├── SheetCommandsTests.cs # [Integration, Medium, Worksheets] - Sheet operations │ └── IntegrationRoundTripTests.cs # [RoundTrip, Slow, EndToEnd] - Complex workflows +├── ExcelMcp.McpServer.Tests/ +│ └── [MCP Server specific tests] ``` ## Test Organization in Test Explorer