feat: Add NuGet package support and Docker volume mounting (#9)

* feat: Add NuGet package support and Docker volume mounting for .csx files

- Added NuGet package resolver to support #r directives
- Updated Dockerfile to use SDK image for NuGet resolution
- Added Docker volume mounting in .mcp.json for file access
- Added --pull=always to ensure latest image is used
- Enhanced ScriptOptions with source and metadata resolvers
- Added test scripts and examples

🤖 Generated with Claude Code

Co-Authored-By: Claude <[email protected]>

* refactor: Move example scripts to examples folder

- Organized all .csx example files into dedicated examples directory
- Cleaner project root structure

🤖 Generated with Claude Code

Co-Authored-By: Claude <[email protected]>

* feat: Add comprehensive examples with tests

- Organized examples into categorized directories
- Added README and expected output for each example
- Created test suite to validate all examples
- Examples cover: basic execution, Fibonacci, data processing, NuGet packages

🤖 Generated with Claude Code

Co-Authored-By: Claude <[email protected]>

* fix: Update CSX_ALLOWED_PATH to only apply outside Docker

- CSX_ALLOWED_PATH restriction now only applies when NOT in Docker
- Docker containers use volume mounts for file access control
- Fixed example tests to handle dynamic content and ordering
- NuGet test properly skips when packages can't be resolved

🤖 Generated with Claude Code

Co-Authored-By: Claude <[email protected]>

* fix: Improve NuGet package error handling

- Return detailed errors when NuGet packages fail to resolve
- Validate #r directive syntax and report malformed directives
- Handle both missing packages and invalid versions gracefully
- Update tool description to mention NuGet support

🤖 Generated with Claude Code

Co-Authored-By: Claude <[email protected]>

* feat: Add NUnit testing example demonstrating programmatic test execution

- Create comprehensive NUnit example with Calculator and StringUtils tests
- Demonstrate test fixtures, setup methods, and assertions
- Show programmatic test execution without external test runner
- Include expected output for test validation
- Update ExamplesTests to dynamically discover example directories

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* docs: Update README with NuGet support and examples documentation

- Add NuGet package support to features list
- Document #r directive usage with examples
- Include links to all example directories
- Update Claude Code configuration with volume mounting
- Expand project structure to show NuGetPackageResolver
- Add all newly supported namespaces to documentation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* refactor: Clean up code formatting and remove unnecessary blank lines

* fix: Fix Docker test failure and syntax error

- Skip path restriction test when running in Docker container
- Fix syntax error in CSharpEvalTools async task creation
- Docker sets DOTNET_RUNNING_IN_CONTAINER=true which bypasses path checks

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

Author: ElanHasson

.mcp.json

@@ -7,9 +7,11 @@
         "run",
         "-i",
         "--rm",
+        "--pull=always",
+        "-v", "${HOME}:${HOME}",
+        "-w", "${PWD}",
         "ghcr.io/infinityflowapp/csharp-mcp:latest"
       ],
       "env": {}
     }
   }
-}

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "cSpell.words": [
+        "infinityflow"
+    ]
+}

Directory.Packages.props

@@ -10,6 +10,10 @@
     <!-- Roslyn Scripting -->
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Scripting" Version="4.14.0" />
 
+    <!-- NuGet Client Libraries -->
+    <PackageVersion Include="NuGet.Protocol" Version="6.12.1" />
+    <PackageVersion Include="NuGet.Resolver" Version="6.12.1" />
+    
     <!-- Testing -->
     <PackageVersion Include="NUnit" Version="4.4.0" />
     <PackageVersion Include="NUnit.Analyzers" Version="4.10.0" />

Dockerfile

@@ -22,8 +22,8 @@ RUN dotnet test -c Release --no-build --verbosity normal
 # Publish
 RUN dotnet publish src/InfinityFlow.CSharp.Eval/InfinityFlow.CSharp.Eval.csproj -c Release -o /app/publish --no-restore
 
-# Runtime stage
-FROM mcr.microsoft.com/dotnet/runtime:9.0 AS runtime
+# Runtime stage - Use SDK for NuGet package resolution
+FROM mcr.microsoft.com/dotnet/sdk:9.0 AS runtime
 WORKDIR /app
 
 # Install required dependencies for Roslyn scripting
@@ -34,11 +34,21 @@ RUN apt-get update && apt-get install -y \
 # Copy published app
 COPY --from=build /app/publish .
 
+# Create directories for NuGet packages
+RUN mkdir -p /tmp/csharp-mcp-packages && \
+    chmod 777 /tmp/csharp-mcp-packages
+
 # Create non-root user
 RUN useradd -m -s /bin/bash mcpuser && \
     chown -R mcpuser:mcpuser /app
 
 USER mcpuser
 
+# Set NuGet package cache directory
+ENV NUGET_PACKAGES=/tmp/csharp-mcp-packages
+
+# Indicate we're running in a container
+ENV DOTNET_RUNNING_IN_CONTAINER=true
+
 # The MCP server uses stdio for communication
 ENTRYPOINT ["dotnet", "InfinityFlow.CSharp.Eval.dll"]

README.md

@@ -6,9 +6,10 @@ An MCP (Model Context Protocol) server that evaluates and executes C# scripts us
 
 - 🚀 Execute C# scripts directly or from files
 - 📦 Full Roslyn scripting support with common namespaces pre-imported
+- 📚 NuGet package support via `#r "nuget: PackageName, Version"` directives
 - 🔒 Console output capture (safe for MCP stdio protocol)
 - ⚡ Comprehensive error handling for compilation and runtime errors
-- 🐳 Available as both Docker container and dotnet tool
+- 🐳 Available as both Docker container and dotnet tool with volume mounting support
 - ✅ Full test coverage with NUnit and FluentAssertions
 
 ## Installation
@@ -56,12 +57,21 @@ The MCP server exposes a single tool: `EvalCSharp`
 
 - `csxFile` (optional): Full path to a .csx file to execute
 - `csx` (optional): C# script code to execute directly
+- `timeoutSeconds` (optional): Maximum execution time in seconds (default: 30)
 
 Either `csxFile` or `csx` must be provided, but not both.
 
 ### Examples
 
+For comprehensive examples, see the [examples directory](examples/):
+- [Basic Execution](examples/basic-execution/) - Simple C# script execution
+- [Fibonacci Sequence](examples/fibonacci-sequence/) - Generating number sequences
+- [Data Processing](examples/data-processing/) - LINQ and data manipulation
+- [NuGet Packages](examples/nuget-packages/) - Using external NuGet packages
+- [NUnit Testing](examples/nunit-testing/) - Running tests programmatically
+
 #### Direct code execution
+
 ```json
 {
   "tool": "EvalCSharp",
@@ -72,12 +82,14 @@ Either `csxFile` or `csx` must be provided, but not both.
 ```
 
 Output:
-```
+
+```text
 Hello World!
 Result: 4
 ```
 
 #### Execute from file
+
 ```json
 {
   "tool": "EvalCSharp",
@@ -88,6 +100,7 @@ Result: 4
 ```
 
 #### Complex example with LINQ
+
 ```csharp
 var numbers = Enumerable.Range(1, 10);
 var evenSum = numbers.Where(n => n % 2 == 0).Sum();
@@ -96,20 +109,47 @@ evenSum * 2
 ```
 
 Output:
-```
+
+```text
 Sum of even numbers: 30
 Result: 60
 ```
 
 ### Pre-imported namespaces
 
 The following namespaces are automatically available:
+
 - `System`
 - `System.IO`
 - `System.Linq`
 - `System.Text`
 - `System.Collections.Generic`
 - `System.Threading.Tasks`
+- `System.Net.Http`
+- `System.Text.Json`
+- `System.Text.RegularExpressions`
+
+### NuGet Package Support
+
+You can reference NuGet packages directly in your scripts using the `#r` directive:
+
+```csharp
+#r "nuget: Newtonsoft.Json, 13.0.3"
+#r "nuget: Humanizer, 2.14.1"
+
+using Newtonsoft.Json;
+using Humanizer;
+
+var json = JsonConvert.SerializeObject(new { Message = "Hello World" });
+Console.WriteLine(json);
+Console.WriteLine("5 days".Humanize());
+```
+
+The tool will automatically:
+- Download the specified packages from NuGet.org
+- Resolve and download dependencies
+- Cache packages for faster subsequent runs
+- Provide detailed error messages for invalid package specifications
 
 ## MCP Configuration
 
@@ -159,15 +199,19 @@ Add to your Claude Code configuration (`claude_desktop_config.json`):
   "mcpServers": {
     "csharp-eval": {
       "command": "docker",
-      "args": ["run", "-i", "--rm", "ghcr.io/infinityflowapp/csharp-mcp:latest"],
-      "env": {
-        "CSX_ALLOWED_PATH": "/scripts"
-      }
+      "args": [
+        "run", "-i", "--rm", "--pull=always",
+        "-v", "${HOME}:${HOME}",
+        "-w", "${PWD}",
+        "ghcr.io/infinityflowapp/csharp-mcp:latest"
+      ]
     }
   }
 }
 ```
 
+Note: The volume mounting (`-v ${HOME}:${HOME}`) allows the tool to access .csx files from your filesystem.
+
 Or if installed as a dotnet tool:
 
 ```json
@@ -262,18 +306,26 @@ docker run -it infinityflow/csharp-eval-mcp
 
 ## Project Structure
 
-```
+```text
 csharp-mcp/
 ├── src/
 │   └── InfinityFlow.CSharp.Eval/     # Main MCP server implementation
 │       ├── Tools/
-│       │   └── CSharpEvalTools.cs    # Roslyn script evaluation tool
+│       │   ├── CSharpEvalTools.cs    # Roslyn script evaluation tool
+│       │   └── NuGetPackageResolver.cs # NuGet package resolution
 │       ├── Program.cs                # MCP server entry point
 │       └── .mcp/
 │           └── server.json           # MCP server configuration
 ├── tests/
 │   └── InfinityFlow.CSharp.Eval.Tests/  # Unit tests
-│       └── CSharpEvalToolsTests.cs      # Comprehensive test suite
+│       ├── CSharpEvalToolsTests.cs      # Core functionality tests
+│       └── ExamplesTests.cs             # Example validation tests
+├── examples/                         # Example scripts with documentation
+│   ├── basic-execution/             # Simple C# script examples
+│   ├── fibonacci-sequence/          # Algorithm demonstrations
+│   ├── data-processing/             # LINQ and data manipulation
+│   ├── nuget-packages/              # External package usage
+│   └── nunit-testing/               # Programmatic test execution
 ├── Directory.Packages.props          # Central package management
 ├── Dockerfile                        # Docker containerization
 ├── docker-compose.yml               # Docker compose configuration
@@ -303,6 +355,7 @@ git push origin v1.0.0
 ```
 
 This will:
+
 1. Build and test the project
 2. Publish Docker image to GitHub Container Registry
 3. Publish NuGet package to NuGet.org

examples/README.md

@@ -0,0 +1,56 @@
+# C# MCP Examples
+
+This directory contains example C# scripts demonstrating various features of the C# MCP server.
+
+## Examples
+
+### 1. [Basic Execution](./basic-execution)
+Simple script demonstrating console output, variables, loops, and return values.
+
+### 2. [Fibonacci Sequence](./fibonacci-sequence)
+Recursive functions and LINQ operations for calculating Fibonacci numbers.
+
+### 3. [Data Processing](./data-processing)
+Complex data manipulation with custom classes, LINQ queries, and JSON serialization.
+
+### 4. [NuGet Packages](./nuget-packages)
+Using external NuGet packages with the `#r` directive (requires SDK runtime).
+
+## Running Examples
+
+Each example can be run in several ways:
+
+### Using the MCP Tool Directly
+```bash
+cd examples/basic-execution
+dotnet run --project ../../src/InfinityFlow.CSharp.Eval -- eval-csharp --csx-file script.csx
+```
+
+### Using Docker
+```bash
+docker run -i --rm -v $(pwd):/scripts ghcr.io/infinityflowapp/csharp-mcp:latest \
+  eval-csharp --csx-file /scripts/examples/basic-execution/script.csx
+```
+
+### Via MCP Client
+When using an MCP client like Claude or Cursor, provide the full path to the script file.
+
+## Testing Examples
+
+All examples are automatically tested to ensure they produce the expected output:
+
+```bash
+dotnet test --filter "FullyQualifiedName~ExamplesTests"
+```
+
+## Structure
+
+Each example directory contains:
+- `script.csx` - The C# script to execute
+- `README.md` - Documentation for the example
+- `expected-output.txt` - Expected output for validation
+
+The test suite validates that each example:
+1. Executes without errors
+2. Produces output matching the expected output
+3. Contains all required files

examples/basic-execution/README.md

@@ -0,0 +1,29 @@
+# Basic Execution Example
+
+This example demonstrates basic C# script execution with console output and return values.
+
+## Features
+
+- Console output
+- Variable declarations
+- Simple loops
+- Return values
+
+## Running the Example
+
+```bash
+# Using the MCP tool directly
+dotnet run --project ../../src/InfinityFlow.CSharp.Eval -- eval-csharp --csx-file script.csx
+
+# Or via MCP client
+# Provide the full path to script.csx when using the eval_c_sharp tool
+```
+
+## Expected Output
+
+The script will output:
+
+- A greeting message
+- Current timestamp
+- Sum calculation result
+- Return value with the final sum

examples/basic-execution/expected-output.txt

@@ -0,0 +1,5 @@
+Hello from C# MCP!
+Script is running...
+Sum of 1 to 10: 55
+
+Result: Script completed successfully with sum = 55

examples/basic-execution/script.csx

@@ -0,0 +1,17 @@
+using System;
+
+// Basic C# script execution example
+Console.WriteLine("Hello from C# MCP!");
+Console.WriteLine($"Script is running...");
+
+// Simple calculation
+var sum = 0;
+for (int i = 1; i <= 10; i++)
+{
+    sum += i;
+}
+
+Console.WriteLine($"Sum of 1 to 10: {sum}");
+
+// Return a value
+return $"Script completed successfully with sum = {sum}";

examples/data-processing/README.md

@@ -0,0 +1,28 @@
+# Data Processing Example
+
+This example demonstrates complex data processing with classes, LINQ, and JSON serialization.
+
+## Features
+- Custom class definitions  
+- Collection manipulation
+- LINQ queries and aggregations
+- Anonymous types
+- GroupBy operations
+- JSON serialization (System.Text.Json)
+
+## Running the Example
+
+```bash
+# Using the MCP tool directly
+dotnet run --project ../../src/InfinityFlow.CSharp.Eval -- eval-csharp --csx-file script.csx
+
+# Or via MCP client
+# Provide the full path to script.csx when using the eval_c_sharp tool
+```
+
+## Expected Output
+The script will output:
+- List of people with their hobbies
+- Statistical analysis
+- Age group distribution
+- Return value with processing summary