# VS Code Extension Development Notes

## Project Structure

```
vscode-extension/
├── src/
│   └── extension.ts          # Extension entry point
├── out/                       # Compiled JavaScript
│   ├── extension.js
│   └── extension.js.map
├── package.json               # Extension manifest
├── tsconfig.json             # TypeScript config
├── eslint.config.mjs         # Linting rules
├── README.md                 # Extension documentation
├── CHANGELOG.md              # Version history
├── INSTALL.md                # Installation guide
├── LICENSE                   # MIT License
├── icon.png                  # 128x128 extension icon
├── icon.svg                  # SVG source
├── skills/                   # Agent skills (copied during build)
│   ├── excel-mcp/            # MCP server skill
│   │   └── SKILL.md
│   ├── excel-cli/            # CLI skill
│   │   └── SKILL.md
│   └── shared/               # Shared reference docs
│       └── *.md
└── excelmcp-1.0.0.vsix      # Packaged extension
```

## Key Implementation Details

### MCP Server Registration

The extension uses VS Code's `mcpServerDefinitionProvider` contribution point:

```typescript
vscode.lm.registerMcpServerDefinitionProvider('excelmcp', {
  provideMcpServerDefinitions: async () => {
    const serverPath = path.join(context.extensionPath, 'bin', 'Sbroenne.ExcelMcp.McpServer.exe');
    return [
      new vscode.McpStdioServerDefinition(
        'Excel MCP Server',
        serverPath,
        [],
        {} // Optional environment variables
      )
    ];
  }
})
```

### Agent Skills Registration

The extension uses VS Code's `chatSkills` contribution point in `package.json` to declaratively register agent skills:

```json
"chatSkills": [
  { "name": "excel-mcp", "path": "./skills/excel-mcp/SKILL.md" },
  { "name": "excel-cli", "path": "./skills/excel-cli/SKILL.md" }
]
```

Skills are automatically available to GitHub Copilot when the extension is active — no file-copying needed.

### Activation

- **Activation Event**: `onStartupFinished` - Extension loads when VS Code starts
- **Welcome Message**: Shows once on first activation
- **State Management**: Uses `context.globalState` to track welcome message

### Dependencies

- **Runtime**: None - Extension bundles self-contained executables (MCP Server + CLI)
- **Dev Dependencies**:
  - `@types/vscode@^1.106.0` - VS Code API types
  - `@types/node@^22.0.0` - Node.js types
  - `typescript@^5.9.0` - TypeScript compiler
  - `@vscode/vsce@^3.0.0` - Extension packaging tool
  - `eslint` + `typescript-eslint` - Code quality

## Building

```powershell
npm install          # Install dependencies
npm run compile      # Compile TypeScript
npm run watch        # Watch mode for development
npm run lint         # Run ESLint
npm run package      # Create VSIX package
```

## Building Bundled Executables

The extension includes self-contained MCP server and CLI executables. To update them:

```powershell
# Build MCP server as self-contained single-file exe
cd d:\source\mcp-server-excel
dotnet publish src/ExcelMcp.McpServer/ExcelMcp.McpServer.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -p:PublishTrimmed=false -p:PublishReadyToRun=false -p:NuGetAudit=false -o vscode-extension/bin

# Build CLI as self-contained single-file exe
dotnet publish src/ExcelMcp.CLI/ExcelMcp.CLI.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -p:PublishTrimmed=false -p:PublishReadyToRun=false -p:NuGetAudit=false -o vscode-extension/bin

# Or use the npm script which builds both
npm run build:all

# Verify the executables work
vscode-extension/bin/Sbroenne.ExcelMcp.McpServer.exe --version
vscode-extension/bin/excelcli.exe --version
```

This creates self-contained executables with the .NET runtime and all dependencies included. No .NET SDK or runtime installation needed on end-user machines.

## Testing

### Prerequisites for Testing

The extension uses bundled self-contained executables. For development testing:

```powershell
# Build both executables (matches production)
npm run build:all

# Verify bundled executables work
vscode-extension/bin/Sbroenne.ExcelMcp.McpServer.exe --version
vscode-extension/bin/excelcli.exe --version
```

**Why this approach**: The extension bundles self-contained MCP server and CLI executables. No .NET runtime or SDK needed on the target machine.

### Manual Testing

1. **Build the extension**:
   ```powershell
   npm run compile
   ```

2. **Press F5 in VS Code** (opens Extension Development Host)

3. **Check the Debug Console** for activation logs:
   - ✅ `ExcelMcp extension is now active`
   - ❌ NO errors about "Cannot read properties of undefined"

4. **In the Extension Development Host**:
   - Check if extension is loaded: Extensions panel
   - Check if MCP server is registered: Settings → MCP
   - Ask GitHub Copilot to list Excel tools

5. **Check Developer Tools Console** (Ctrl+Shift+I):
   - Go to Console tab
   - Look for "ExcelMcp:" messages
   - Verify no errors

### Package Testing

1. **Package the extension**:
   ```powershell
   npm run package
   ```

2. **Install from VSIX**:
   - `Ctrl+Shift+P` → "Install from VSIX"
   - Select `excelmcp-1.0.0.vsix`

3. **Verify**:
   - Extension appears in Extensions panel
   - Welcome message shows on first activation
   - GitHub Copilot can access Excel tools

## Publishing

### Automated Publishing (Recommended)

The extension is automatically published to the VS Code Marketplace when a version tag is pushed:

```powershell
# 1. Create and push tag (releases ALL components with same version)
git tag vX.Y.Z
git push --tags
```

The GitHub Actions workflow will automatically:
- ✅ **Extract version from tag** (e.g., `v1.5.7` → `1.5.7`)
- ✅ **Update package.json version** using `npm version` (no manual editing needed)
- ✅ **Update CHANGELOG.md** with release date
- ✅ **Build and package the extension**
- ✅ **Publish to VS Code Marketplace** (if `VSCE_TOKEN` secret is configured)
- ✅ **Build all other components** (MCP Server, CLI, MCPB)
- ✅ **Create unified GitHub release** with all artifacts

**Important**: The workflow manages version numbers - you don't need to manually update `package.json` before tagging. The unified release workflow (`.github/workflows/release.yml`) releases all components together.

See [MARKETPLACE-PUBLISHING.md](MARKETPLACE-PUBLISHING.md) for setup instructions.

## CHANGELOG Maintenance

### How to Maintain CHANGELOG.md

The CHANGELOG.md file should always have a **top entry ready for the next release**. The release workflow will automatically update the version number and date.

**Before Release**:
```markdown
## [1.0.0] - 2025-10-29

### Added
- New feature A
- New feature B

### Fixed
- Bug fix C
```

**After Release** (workflow automatically updates):
```markdown
## [1.1.0] - 2025-10-30

### Added
- New feature A
- New feature B

### Fixed
- Bug fix C
```

### Workflow Process

1. **You maintain**: Keep root CHANGELOG.md updated with changes, but version number can be any placeholder
2. **Workflow updates**: When you push tag `v1.1.0`, the workflow extracts that version's section for release notes

### Best Practice

**After each release, add a new top section for the next version**:

```markdown
# Change Log

## [1.0.0] - 2025-10-29

### Added
- Prepare for next release
- Add changes here as you make them

## [1.0.0] - 2025-10-29

### Added
- Initial release
...
```

This way, the CHANGELOG is always ready, and the workflow just updates the version/date.

### Format

Follow [Keep a Changelog](https://keepachangelog.com/) format:
- **Added**: New features
- **Changed**: Changes in existing functionality
- **Deprecated**: Soon-to-be removed features
- **Removed**: Removed features
- **Fixed**: Bug fixes
- **Security**: Security fixes

### Manual Publishing

#### VS Code Marketplace

1. **Create publisher account**: https://marketplace.visualstudio.com/manage
2. **Generate PAT**: https://dev.azure.com (Marketplace Manage scope)
3. **Login**: `npx @vscode/vsce login <publisher>`
4. **Publish**: `npx @vscode/vsce publish`

#### GitHub Releases Only

To create a GitHub release without marketplace publishing:

```powershell
cd vscode-extension
npm run package
# Upload the .vsix file manually to GitHub releases
```

## Versioning

**Automatic Version Management** (Recommended):
The unified release workflow automatically calculates version numbers from the latest git tag:

1. Go to **Actions** → **Release All Components** → **Run workflow**
2. Select version bump type (patch/minor/major) or enter a custom version

The workflow will:
- Calculate the next version from the latest git tag
- Update `package.json` version for VS Code extension
- Update all component versions (MCP Server, CLI, MCPB manifest)
- Create git tag and unified GitHub release with all artifacts

**Manual Version Updates** (if needed):
If you need to update the version locally before tagging:

```powershell
npm version patch   # Bumps 1.0.0 → 1.0.1
npm version minor   # Bumps 1.0.0 → 1.1.0
npm version major   # Bumps 1.0.0 → 2.0.0
```

Follow Semantic Versioning (SemVer):
- **Major**: Breaking changes
- **Minor**: New features
- **Patch**: Bug fixes

**Important**: Don't manually edit version numbers in `package.json` - use either git tags (for releases) or `npm version` commands (for local testing).

## Maintenance

### Updating Dependencies

```powershell
npm outdated                    # Check for updates
npm update                      # Update minor/patch
npm install @types/vscode@latest --save-dev  # Update major
```

### VS Code API Updates

When VS Code releases new API features:
1. Update `engines.vscode` in package.json
2. Update `@types/vscode` to matching version
3. Test extension compatibility
4. Update CHANGELOG

## Troubleshooting

### Build Issues

**Error: "Cannot find module 'vscode'"**
- Run `npm install`

**Error: "TypeScript compile errors"**
- Check `tsconfig.json` settings
- Verify VS Code types version matches engines.vscode

### Packaging Issues

**Error: "LICENSE not found"**
- Ensure LICENSE file exists in extension root

**Error: "engines.vscode mismatch"**
- Update package.json `engines.vscode` to match `@types/vscode` version

### Runtime Issues

**Extension not activating**
- Check `activationEvents` in package.json
- Verify extension ID matches registration

**MCP server not found**
- Ensure bundled executable exists in `bin/Sbroenne.ExcelMcp.McpServer.exe`
- Run `npm run build:all` to build both MCP server and CLI executables
- Verify bundled executable runs: `bin/Sbroenne.ExcelMcp.McpServer.exe --version`

**CLI not found**
- Ensure `bin/excelcli.exe` exists
- Run `npm run build:all` to build both executables

## Extension Size 

Current size: **~68-70 MB** (includes bundled self-contained MCP server and CLI executables)

The extension includes:
- Main extension code (~10 KB)
- Bundled self-contained MCP server (~118 MB uncompressed, ~34 MB compressed)
- Bundled self-contained CLI (~115 MB uncompressed, ~34 MB compressed)
- Agent Skills (~130 KB for both excel-mcp and excel-cli)

Benefits of self-contained bundled approach:
- ✅ Zero-setup installation (no .NET runtime or SDK required)
- ✅ Version compatibility guaranteed (extension includes matching MCP server + CLI)
- ✅ Works offline after installation
- ✅ No dependency on dotnet tool installations
- ✅ CLI available directly for terminal-based automation

## Future Enhancements

Potential improvements:
- [ ] Add configuration options for MCP server
- [ ] Status bar item showing server status
- [ ] Commands to restart/reload MCP server
- [ ] Settings for custom tool arguments
- [ ] Telemetry for usage insights
- [ ] Automatic update notifications

## References

- [VS Code Extension API](https://code.visualstudio.com/api)
- [MCP Documentation](https://modelcontextprotocol.io/)
- [VS Code Extension Samples](https://github.com/microsoft/vscode-extension-samples)
- [Publishing Extensions](https://code.visualstudio.com/api/working-with-extensions/publishing-extension)
