Skip to content

Commit 69959ec

Browse files
rogeralsingclaude
rogeralsing
and
claude
committed
Add GitHub workflows, NuGet packaging, and documentation
- CI workflow: builds and tests on push/PR - Release workflow: publishes to NuGet on version tags (v*) - Updated csproj files with NuGet metadata and SourceLink - Added README with usage instructions - Added MIT LICENSE - Samples marked as non-packable To release: git tag v0.1.0 git push origin v0.1.0 Requires NUGET_API_KEY secret in GitHub repo settings. Co-Authored-By: Claude Opus 4.5 <[email protected]>
1 parent 849fae7 commit 69959ec

9 files changed

Lines changed: 312 additions & 1 deletion

File tree

‎.github/workflows/ci.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [master, main]
6+
pull_request:
7+
branches: [master, main]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- uses: actions/checkout@v4
15+
16+
- name: Setup .NET
17+
uses: actions/setup-dotnet@v4
18+
with:
19+
dotnet-version: '10.0.x'
20+
dotnet-quality: 'preview'
21+
22+
- name: Restore dependencies
23+
run: dotnet restore
24+
25+
- name: Build
26+
run: dotnet build --no-restore --configuration Release
27+
28+
- name: Test
29+
run: dotnet test --no-build --configuration Release --verbosity normal

‎.github/workflows/release.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
8+
jobs:
9+
publish:
10+
runs-on: ubuntu-latest
11+
12+
steps:
13+
- uses: actions/checkout@v4
14+
15+
- name: Setup .NET
16+
uses: actions/setup-dotnet@v4
17+
with:
18+
dotnet-version: '10.0.x'
19+
dotnet-quality: 'preview'
20+
21+
- name: Get version from tag
22+
id: version
23+
run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
24+
25+
- name: Restore dependencies
26+
run: dotnet restore
27+
28+
- name: Build
29+
run: dotnet build --no-restore --configuration Release -p:Version=${{ steps.version.outputs.VERSION }}
30+
31+
- name: Pack Client Library
32+
run: dotnet pack src/Asynkron.McpDebugger.Client/Asynkron.McpDebugger.Client.csproj --no-build --configuration Release -p:Version=${{ steps.version.outputs.VERSION }} --output ./nupkg
33+
34+
- name: Pack Server Tool
35+
run: dotnet pack src/Asynkron.McpDebugger.Server/Asynkron.McpDebugger.Server.csproj --no-build --configuration Release -p:Version=${{ steps.version.outputs.VERSION }} --output ./nupkg
36+
37+
- name: Push to NuGet
38+
run: dotnet nuget push ./nupkg/*.nupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate
39+
40+
- name: Create GitHub Release
41+
uses: softprops/action-gh-release@v1
42+
with:
43+
files: ./nupkg/*.nupkg
44+
generate_release_notes: true
45+
env:
46+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,3 +52,6 @@ artifacts/
5252

5353
# JetBrains Rider
5454
*.sln.iml
55+
56+
# Local NuGet packages
57+
nupkg/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Asynkron
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Asynkron.McpDebugger
2+
3+
AI-controlled cooperative debugger via MCP (Model Context Protocol).
4+
5+
Add breakpoints to your C# code that pause execution until an AI (like Claude) resumes them. The AI can inspect the call stack, view source code context, and control program flow.
6+
7+
## How It Works
8+
9+
```
10+
┌─────────────────┐ MCP (stdio) ┌─────────────────────────┐
11+
│ AI (Claude) │ ◄──────────────────► │ mcpdebugger mcp │
12+
└─────────────────┘ └───────────┬─────────────┘
13+
│ HTTP
14+
┌───────────▼─────────────┐
15+
│ mcpdebugger serve │
16+
└───────────┬─────────────┘
17+
│ HTTP
18+
┌───────────▼─────────────┐
19+
│ Your Application │
20+
│ with DebugBreak calls │
21+
└─────────────────────────┘
22+
```
23+
24+
## Installation
25+
26+
### Install the CLI tool (global)
27+
28+
```bash
29+
dotnet tool install -g Asynkron.McpDebugger
30+
```
31+
32+
### Add the client library to your project
33+
34+
```bash
35+
dotnet add package Asynkron.McpDebugger.Client
36+
```
37+
38+
## Quick Start
39+
40+
### 1. Add breakpoints to your code
41+
42+
```csharp
43+
using Asynkron.McpDebugger.Client;
44+
45+
public class MyService
46+
{
47+
public async Task ProcessOrderAsync(Order order)
48+
{
49+
// Async breakpoint - doesn't block threadpool threads
50+
await DebugBreak.HereAsync();
51+
52+
// Your code continues after AI resumes...
53+
await ValidateOrder(order);
54+
55+
// Another breakpoint
56+
await DebugBreak.HereAsync();
57+
58+
await ChargeCustomer(order);
59+
}
60+
}
61+
```
62+
63+
### 2. Start the debug server
64+
65+
```bash
66+
mcpdebugger serve
67+
```
68+
69+
### 3. Configure Claude Code
70+
71+
Add to `~/.claude/settings.json`:
72+
73+
```json
74+
{
75+
"mcpServers": {
76+
"debugger": {
77+
"command": "mcpdebugger",
78+
"args": ["mcp"]
79+
}
80+
}
81+
}
82+
```
83+
84+
### 4. Run your application
85+
86+
Your app will pause at each `DebugBreak` call until the AI resumes it.
87+
88+
## API
89+
90+
### Client Library
91+
92+
```csharp
93+
// Async breakpoint (recommended) - doesn't steal threadpool threads
94+
await DebugBreak.HereAsync();
95+
96+
// Sync breakpoint - blocks the current thread
97+
DebugBreak.Here();
98+
99+
// Configure server URL (default: http://localhost:5200)
100+
DebugBreak.Configure("http://localhost:5200");
101+
102+
// Disable/enable breakpoints
103+
DebugBreak.Disable();
104+
DebugBreak.Enable();
105+
```
106+
107+
### MCP Tools (available to AI)
108+
109+
| Tool | Description |
110+
|------|-------------|
111+
| `get_breakpoints` | List all active breakpoints |
112+
| `get_context` | Get call stack and source code for a breakpoint |
113+
| `resume` | Resume a specific breakpoint |
114+
| `resume_all` | Resume all active breakpoints |
115+
116+
### HTTP API (for direct access)
117+
118+
```bash
119+
# List active breakpoints
120+
curl http://localhost:5200/status
121+
122+
# Resume a specific breakpoint
123+
curl -X POST http://localhost:5200/resume/{breakpoint-id}
124+
125+
# Resume all breakpoints
126+
curl -X POST http://localhost:5200/resume-all
127+
```
128+
129+
## CLI Commands
130+
131+
```bash
132+
mcpdebugger serve [--port 5200] # Start the HTTP debug server
133+
mcpdebugger mcp [--port 5200] # Start the MCP server (for AI integration)
134+
mcpdebugger --help # Show help
135+
```
136+
137+
## How the Breakpoints Work
138+
139+
The async breakpoint (`HereAsync`) uses `TaskCompletionSource` internally:
140+
- Your code awaits an HTTP POST to the debug server
141+
- The server holds the request until the AI calls `resume`
142+
- No threadpool threads are blocked
143+
144+
The sync breakpoint (`Here`) simply blocks on the HTTP call:
145+
- The calling thread is blocked until resume
146+
- Use sparingly to avoid thread starvation
147+
148+
## Building from Source
149+
150+
```bash
151+
git clone https://github.com/asynkron/Asynkron.McpDebugger.git
152+
cd Asynkron.McpDebugger
153+
dotnet build
154+
```
155+
156+
## License
157+
158+
MIT

‎samples/DummyTestApp/DummyTestApp.csproj‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
<TargetFramework>net10.0</TargetFramework>
66
<ImplicitUsings>enable</ImplicitUsings>
77
<Nullable>enable</Nullable>
8+
<IsPackable>false</IsPackable>
89
</PropertyGroup>
910

1011
<ItemGroup>

‎samples/SampleApp/SampleApp.csproj‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
<TargetFramework>net10.0</TargetFramework>
66
<ImplicitUsings>enable</ImplicitUsings>
77
<Nullable>enable</Nullable>
8+
<IsPackable>false</IsPackable>
89
</PropertyGroup>
910

1011
<ItemGroup>

‎src/Asynkron.McpDebugger.Client/Asynkron.McpDebugger.Client.csproj‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,33 @@
55
<ImplicitUsings>enable</ImplicitUsings>
66
<Nullable>enable</Nullable>
77
<RootNamespace>Asynkron.McpDebugger.Client</RootNamespace>
8+
9+
<!-- NuGet Package Metadata -->
10+
<PackageId>Asynkron.McpDebugger.Client</PackageId>
11+
<Version>0.1.0</Version>
12+
<Authors>Asynkron</Authors>
13+
<Company>Asynkron</Company>
14+
<Description>Client library for AI-controlled cooperative debugging via MCP. Add DebugBreak.Here() or DebugBreak.HereAsync() calls to pause execution until an AI resumes it.</Description>
15+
<PackageTags>debugging;mcp;ai;breakpoint;cooperative-debugging;claude</PackageTags>
16+
<PackageLicenseExpression>MIT</PackageLicenseExpression>
17+
<PackageProjectUrl>https://github.com/asynkron/Asynkron.McpDebugger</PackageProjectUrl>
18+
<RepositoryUrl>https://github.com/asynkron/Asynkron.McpDebugger</RepositoryUrl>
19+
<RepositoryType>git</RepositoryType>
20+
<PackageReadmeFile>README.md</PackageReadmeFile>
21+
22+
<!-- Source Link -->
23+
<PublishRepositoryUrl>true</PublishRepositoryUrl>
24+
<EmbedUntrackedSources>true</EmbedUntrackedSources>
25+
<IncludeSymbols>true</IncludeSymbols>
26+
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
827
</PropertyGroup>
928

29+
<ItemGroup>
30+
<None Include="../../README.md" Pack="true" PackagePath="/" />
31+
</ItemGroup>
32+
33+
<ItemGroup>
34+
<PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All" />
35+
</ItemGroup>
36+
1037
</Project>

‎src/Asynkron.McpDebugger.Server/Asynkron.McpDebugger.Server.csproj‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,42 @@
66
<ImplicitUsings>enable</ImplicitUsings>
77
<Nullable>enable</Nullable>
88
<RootNamespace>Asynkron.McpDebugger.Server</RootNamespace>
9+
10+
<!-- .NET Tool Configuration -->
911
<PackAsTool>true</PackAsTool>
1012
<ToolCommandName>mcpdebugger</ToolCommandName>
13+
<IsPackable>true</IsPackable>
14+
15+
<!-- NuGet Package Metadata -->
1116
<PackageId>Asynkron.McpDebugger</PackageId>
1217
<Version>0.1.0</Version>
1318
<Authors>Asynkron</Authors>
14-
<Description>AI-controlled cooperative debugger via MCP</Description>
19+
<Company>Asynkron</Company>
20+
<Description>AI-controlled cooperative debugger via MCP. Install as a global tool and use with Claude Code or other MCP-compatible AI assistants to inspect and control breakpoints in your .NET applications.</Description>
21+
<PackageTags>debugging;mcp;ai;breakpoint;cooperative-debugging;claude;dotnet-tool</PackageTags>
1522
<PackageLicenseExpression>MIT</PackageLicenseExpression>
23+
<PackageProjectUrl>https://github.com/asynkron/Asynkron.McpDebugger</PackageProjectUrl>
24+
<RepositoryUrl>https://github.com/asynkron/Asynkron.McpDebugger</RepositoryUrl>
25+
<RepositoryType>git</RepositoryType>
26+
<PackageReadmeFile>README.md</PackageReadmeFile>
27+
28+
<!-- Source Link -->
29+
<PublishRepositoryUrl>true</PublishRepositoryUrl>
30+
<EmbedUntrackedSources>true</EmbedUntrackedSources>
31+
<IncludeSymbols>true</IncludeSymbols>
32+
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
1633
</PropertyGroup>
1734

35+
<ItemGroup>
36+
<None Include="../../README.md" Pack="true" PackagePath="/" />
37+
</ItemGroup>
38+
1839
<ItemGroup>
1940
<ProjectReference Include="..\Asynkron.McpDebugger.Client\Asynkron.McpDebugger.Client.csproj" />
2041
</ItemGroup>
2142

43+
<ItemGroup>
44+
<PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All" />
45+
</ItemGroup>
46+
2247
</Project>

0 commit comments

Comments
 (0)