Skip to content

CLAUDE.md

Latest commit

 

History

History
174 lines (136 loc) · 6.64 KB

CLAUDE.md

File metadata and controls

174 lines (136 loc) · 6.64 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Critical Rules

These rules override all other instructions:

  1. NEVER commit directly to main - Always create a feature branch and submit a pull request
  2. Conventional commits - Format: type(scope): description
  3. GitHub Issues for TODOs - Use gh CLI to manage issues, no local TODO files. Use conventional commit format for issue titles
  4. Pull Request titles - Use conventional commit format (same as commits)
  5. Branch naming - Use format: type/scope/short-description (e.g., feat/tools/add-debug-tools)
  6. Working an issue - Always create a new branch from an updated main branch
  7. Check branch status before pushing - Verify the remote tracking branch still exists. If a PR was merged/deleted, create a new branch from main instead
  8. Microsoft coding guidelines - Follow Microsoft C# coding conventions and .NET library design guidelines
  9. WPF for all UI - All UI must be implemented using WPF (XAML/C#). No web-based technologies (HTML, JavaScript, WebView)
  10. Write tests - All new/refactored code requires tests where applicable
  11. Run validation before commits - Run dotnet build and verify no errors before committing
  12. No co-authors - Do not add co-author information on commits or pull requests
  13. No "generated by" statements - Do not add generated-by statements on pull requests

GitHub CLI Commands

gh issue list                    # List open issues
gh issue view <number>           # View details
gh issue create --title "type(scope): description" --body "..."
gh issue close <number>

Conventional Commit Types

Type Description
feat New feature
fix Bug fix
docs Documentation only
refactor Code change that neither fixes a bug nor adds a feature
test Adding or updating tests
chore Maintenance tasks
perf Performance improvement
ci CI/CD changes

VSIX Development Rules

Solution & Project Structure:

  • SLNX solution files only (no legacy .sln)
  • Solution naming: CodingWithCalvin.<ProjectFolder>
  • Primary project naming: CodingWithCalvin.<ProjectFolder>
  • Additional project naming: CodingWithCalvin.<ProjectFolder>.<Classifier>

Build Configuration:

  • Configurations: Debug and Release
  • Platform: AnyCPU (or x64 where required)
  • Build Tools: Latest 17.* release
  • VSSDK: Latest 17.* release

Target Frameworks:

  • Main VSIX project: .NET Framework 4.8
  • Server project: .NET 10.0
  • Shared library: Multi-target net48;net10.0

VSIX Manifest:

  • Version range: [17.0,19.0) — supports VS 2022 through VS 2026
  • Architectures: AMD64 and ARM64
  • Prerequisites: List Community edition only (captures Pro/Enterprise)

CI/CD:

  • Build workflow: Automated build on push/PR
  • Publish workflow: Automated marketplace publishing
  • Marketplace config: publish.manifest.json for automated publishing

Development Environment:

  • Required extension: Extensibility Essentials 2022
  • Helper library: Community.VisualStudio.Toolkit

Documentation:

  • README should be exciting and use emojis

Project Overview

VS-VSMCP is a Visual Studio 2022/2026 extension that exposes Visual Studio features as an MCP (Model Context Protocol) server, allowing AI assistants like Claude to interact with VS programmatically via HTTP/SSE.

Architecture

┌─────────────────┐                ┌─────────────────────┐    named pipes    ┌─────────────────┐
│  Claude Desktop │   HTTP/SSE    │  VSMCP.Server.exe   │ ◄────────────────► │  VS Extension   │
│  (MCP Client)   │ ◄────────────► │  (MCP Server)       │    JSON-RPC        │  (Tool Impl)    │
└─────────────────┘  :5050         └─────────────────────┘                    └─────────────────┘

Projects

Project Purpose
CodingWithCalvin.VSMCP Main VSIX extension - runs inside Visual Studio
CodingWithCalvin.VSMCP.Server MCP server process - hosts HTTP/SSE endpoint
CodingWithCalvin.VSMCP.Shared Shared DTOs and RPC contracts

Build Commands

# Build the solution
dotnet build src/CodingWithCalvin.VSMCP.slnx

# Build Release
dotnet build src/CodingWithCalvin.VSMCP.slnx -c Release

# Build specific project
dotnet build src/CodingWithCalvin.VSMCP/CodingWithCalvin.VSMCP.csproj

Key Files

  • VSMCPPackage.cs - Package initialization and service registration
  • VSCommandTable.vsct - Defines menu commands for Tools > VSMCP
  • source.extension.vsixmanifest - VSIX package metadata
  • Services/VisualStudioService.cs - VS API wrapper for all VS operations
  • Services/RpcServer.cs - Named pipe JSON-RPC server
  • Services/ServerProcessManager.cs - Server process lifecycle management
  • Server/Tools/*.cs - MCP tool definitions

MCP Tools Available

Solution Tools

  • solution_info - Get current solution information
  • solution_open - Open a solution file
  • solution_close - Close the current solution
  • project_list - List all projects
  • project_info - Get project details

Document Tools

  • document_list - List open documents
  • document_active - Get active document
  • document_open - Open a file
  • document_close - Close a document
  • document_read - Read document content
  • document_write - Write document content
  • selection_get - Get current selection
  • selection_set - Set selection range
  • editor_insert - Insert text at cursor
  • editor_replace - Find and replace text
  • editor_goto_line - Navigate to line
  • editor_find - Search in document

Build Tools

  • build_solution - Build entire solution
  • build_project - Build specific project
  • clean_solution - Clean solution
  • build_cancel - Cancel build
  • build_status - Get build status

Technology Stack

  • .NET Framework 4.8 (VSIX)
  • .NET 10.0 (Server)
  • Visual Studio SDK 17.x (VS 2022/2026)
  • Community.VisualStudio.Toolkit.17
  • ModelContextProtocol C# SDK
  • StreamJsonRpc for named pipe communication
  • WPF for UI
  • MSBuild + NuGet for builds
  • VSIX packaging format

Development Prerequisites

  • Visual Studio 2022 with "Visual Studio extension development" workload
  • .NET 10.0 SDK