Skip to content

CLAUDE.md

Latest commit

 

History

History
144 lines (101 loc) · 5.11 KB

CLAUDE.md

File metadata and controls

144 lines (101 loc) · 5.11 KB

PostSharp.Engineering

Build orchestration SDK for PostSharp/Metalama repositories.

Important

Read this file entirely before doing any work or answering any question for this project, especially regarding loading skills.

Discovering Plugin Skills

  • The postsharp-engineering plugin provides skills and slash commands. To discover them:

  • ALWAYS Read which plug-ins and skills are available to you before doing ANY work, and confirm to the users that you have read these skills before any session.

Generated scripts

  • Never update DockerBuild.ps1, Dockerfile. Dockerfile.claude, eng/RunClaude.ps1. These files are generated by Build.ps1. Their source code is in the Resources directory.

MCP Approval Server (Docker Environment)

When running inside a Docker container, you have access to the host-approval MCP server for executing privileged commands on the host machine. These commands require human approval before execution.

Source code: src/PostSharp.Engineering.McpApprovalServer/

The MCP Approval Server is a WPF GUI application that:

  • Receives command execution requests from Claude in Docker via MCP protocol
  • Analyzes risk using both regex rules and AI (Claude CLI with Haiku/Opus)
  • Prompts the human for approval via a GUI dialog
  • Executes approved commands via PowerShell on the host

See src/PostSharp.Engineering.McpApprovalServer/CLAUDE.md for architecture details and how to add command rules.

Starting the MCP Approval Server

The MCP Approval Server is a standalone GUI application with system tray integration. Before running Claude in Docker mode, start the server:

  1. Build the solution: dotnet build
  2. Run the GUI application: .\src\PostSharp.Engineering.McpApprovalServer\bin\Debug\net8.0-windows\PostSharp.Engineering.McpApprovalServer.exe
  3. The server will appear as a tray icon (green = ready, orange = pending requests)
  4. Now run DockerBuild.ps1 -Claude - it will detect the running server automatically

Security Model

The MCP server uses localhost-only binding for security:

  • Server binds exclusively to localhost:9847 (not exposed to the network)
  • Docker containers access via the host gateway IP
  • No authentication tokens needed since only local processes can connect
  • Human approval required for all non-low-risk commands via the GUI

When to Use the MCP Server

Use the ExecuteCommand tool from the host-approval MCP server for:

GitHub Operations (requires host credentials)

  • gh pr create - Creating pull requests
  • gh pr merge - Merging pull requests
  • gh pr view - Viewing PR details (private repos)
  • gh release create - Creating releases
  • gh issue create/close/comment - Issue management
  • Any gh command that requires authentication

Git Push Operations

  • git push - Pushing commits to remote
  • git push --tags - Pushing tags
  • git push --force - Force pushing (use with caution)

TeamCity Operations

  • Any API calls to TeamCity
  • Triggering builds
  • Accessing build artifacts
  • Managing build configurations

Package Publishing

  • dotnet nuget push - Publishing NuGet packages
  • Any operation that publishes artifacts externally

How to Use

Call the ExecuteCommand tool with:

  • command: The command to execute
  • workingDirectory: The working directory (use forward slashes: c:/src/RepoName)
  • claimedPurpose: A clear explanation of why this command is needed

Example

To push a feature branch:

ExecuteCommand(
  command: "git push origin feature/my-feature",
  workingDirectory: "c:/src/PostSharp.Engineering",
  claimedPurpose: "Push the feature branch with MCP implementation to remote for PR creation"
)

What NOT to Use MCP For

Do NOT use the MCP server for:

  • Local git operations (commit, branch, checkout, status, diff, log)
  • Local builds (dotnet build, dotnet test)
  • File operations within the container
  • Reading files or exploring the codebase

These operations should be done directly in the container using standard tools.

Version Bumping

Before scheduling a TeamCity build or deploy, the version must be bumped. This is done via the VersionBump build configuration on TeamCity.

How to Bump Version

Use the MCP ExecuteCommand tool to trigger the VersionBump build via TeamCity API (requires TEAMCITY_CLOUD_TOKEN on host):

$headers = @{
    "Authorization" = "Bearer $env:TEAMCITY_CLOUD_TOKEN"
    "Content-Type" = "application/json"
    "Accept" = "application/json"
}
$body = @{
    buildType = @{ id = "<ProjectPrefix>_VersionBump" }
    branchName = "<branch>"
} | ConvertTo-Json
Invoke-RestMethod -Uri "https://postsharp.teamcity.com/app/rest/buildQueue" -Method Post -Headers $headers -Body $body

Finding the Build Type ID

  1. Check .teamcity/settings.kts for the VCS root: AbsoluteId("...")
  2. The build type ID is: <VcsRootId>_VersionBump
  3. For this repo: Engineering_PostSharpEngineering_VersionBump

How to deploy

  1. Commit
  2. Push
  3. Wait 1 seconds
  4. Bump version (see above)
  5. Monitor version bumping
  6. When completed, schedule deploy public

Warnings

NEVER COMMIT WITHOUT USER APPROVAL. Even if the user has given approval for a prior commit.