Skip to content

CLAUDE.md

Latest commit

 

History

History
137 lines (99 loc) · 4.6 KB

CLAUDE.md

File metadata and controls

137 lines (99 loc) · 4.6 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/new-tool)
  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. Write tests - All new/refactored code requires tests where applicable
  9. Run validation before commits - Run npm run build and npm run test and verify no errors before committing
  10. No co-authors - Do not add co-author information on commits or pull requests
  11. 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

VS Code Extension Development Rules

Project Structure:

  • Extension source in src/ directory
  • Main entry point: src/extension.ts
  • Tools in src/tools/
  • Server implementation in src/server/
  • Tests co-located with source files (*.test.ts)

Build Configuration:

  • Build tool: esbuild
  • Test framework: Vitest
  • TypeScript strict mode

Package Naming:

  • Package name: codingwithcalvin-mcp
  • Publisher: CodingWithCalvin
  • Command prefix: codingwithcalvin.mcp.*
  • Configuration prefix: codingwithcalvin.mcp.*

CI/CD:

  • Build workflow: Automated build on push/PR
  • Publish workflow: Automated VS Code Marketplace publishing

Project Overview

VSC-MCPServer is a Visual Studio Code extension that exposes an MCP (Model Context Protocol) server, providing access to VS Code's semantic code understanding capabilities. External tools can use MCP to access language server features like go-to-definition, find references, hover info, completions, and more.

Build Commands

# Install dependencies
npm install

# Build the extension
npm run build

# Run tests
npm run test

# Watch mode for development
npm run watch

# Run tests in watch mode
npm run test:watch

Architecture

The extension consists of several key components:

  • extension.ts - Main VS Code extension entry point. Manages server lifecycle and registers commands.

  • server/mcpServer.ts - HTTP server that exposes MCP endpoints. Handles JSON-RPC requests for tool listing and execution.

  • tools/ - Individual tool implementations that wrap VS Code's language server APIs:

    • Navigation: goToDefinition, findReferences, documentSymbols, workspaceSymbols
    • Code intelligence: hoverInfo, completions, signatureHelp, callHierarchy, typeHierarchy
    • Diagnostics & actions: diagnostics, codeActions, applyCodeAction, renameSymbol
    • Formatting: formatDocument, formatRange, organizeImports
    • Search: workspaceFileSearch, workspaceTextSearch

  • adapters/vscodeAdapter.ts - Abstraction layer for VS Code API interactions.

  • handlers/uriHandler.ts - Handles vscode://codingwithcalvin.mcp/... URI protocol.

  • config/settings.ts - Extension configuration management.

Technology Stack

  • TypeScript
  • VS Code Extension API (v1.85+)
  • MCP SDK (@modelcontextprotocol/sdk)
  • Express (HTTP server)
  • Vitest (testing)
  • esbuild (bundling)

CI/CD

GitHub Actions workflows in .github/workflows/:

  • build.yml - Triggered on push to main or PR. Builds and uploads VSIX artifact.
  • publish.yml - Manual trigger to publish to VS Code Marketplace.

Development Setup

  1. Open the project folder in VS Code
  2. Run npm install
  3. Run npm run build
  4. Press F5 to launch the extension in Extension Development Host
  5. Test MCP server at http://localhost:4000/mcp