ClawSharp.ServiceDefaults 0.1.0

ClawSharp

A modern, security-first .NET 10 implementation of the Claw AI agent framework, built on Aspire for multi-container orchestration and the official MCP C# SDK for Model Context Protocol tool serving.

ClawSharp draws on the best ideas from across the Claw ecosystem — NanoClaw's container isolation, IronClaw's security posture, OpenClaw's rich tooling, and NemoClaw's enterprise governance — delivered as clean, idiomatic C# with zero third-party AI dependencies.

Architecture

┌──────────────────────────────────────────────────┐
│                 Aspire AppHost                    │
│         (Orchestration & Service Discovery)       │
├──────────────┬───────────────────────────────────┤
│   Gateway    │        Internal Tool Servers       │
│  (Public)    │  ┌───────────┐  ┌──────────────┐  │
│  API Key     │  │ FileSystem│  │    Shell      │  │
│  Auth        │  │   Tools   │  │    Tools      │  │
│              │  └───────────┘  └──────────────┘  │
│  /tools      │  ┌───────────┐  ┌──────────────┐  │
│  /health     │  │   Web     │  │    Data       │  │
│              │  │   Tools   │  │    Tools      │  │
│              │  └───────────┘  └──────────────┘  │
│              │       ┌──────────────┐            │
│              │       │   Memory     │            │
│              │       │   Tools      │            │
│              │       └──────────────┘            │
├──────────────┴───────────────────────────────────┤
│           ServiceDefaults (shared)               │
│   OpenTelemetry · Health Checks · Resilience     │
├──────────────────────────────────────────────────┤
│              ClawSharp.Core (shared)             │
│   Security · Configuration · Path Validation     │
└──────────────────────────────────────────────────┘

Claw Ecosystem Comparison

ClawSharp was designed after studying the strengths and weaknesses of every major Claw variant:

Feature List

Core Platform

• .NET 10 with latest C# language features
• Aspire orchestration — single dotnet run starts everything
• MCP SDK v1.2 — Streamable HTTP transport (current spec)
• MCP Resources — FileSystem and Memory servers expose browsable resources
• MCP Prompts — 5 built-in prompt templates (code review, explain error, summarize file, git commit message, convert data)
• OpenTelemetry — distributed tracing, metrics, and structured logging out of the box
• Custom metrics — 6 instruments: tool invocations, errors, duration histogram, path/command denials, active connections
• Health checks — liveness, readiness, plus per-server checks (sandbox paths, git binary, memory storage)
• Service discovery — internal services resolve by name, no hardcoded URLs
• HTTP resilience — automatic retries and circuit breakers via Microsoft.Extensions.Http.Resilience
• Rate limiting — per-IP fixed window limits (100/10s global, 30/10s for MCP calls)
• Audit logging — every MCP tool invocation logged with name, duration, error status via source-generated LoggerMessage
• Skill system — markdown-defined capability packages with REST API at /skills
• Agent runtime — workflow engine with variable substitution, conditions, and built-in workflows at /workflows
• Plugin system — load external tool assemblies at runtime from /Plugins directory

Security

• Sandbox policies — configurable allowlists for paths, commands, and hosts
• Path validation — directory traversal prevention with OS-aware path comparison
• Command validation — regex-based dangerous pattern detection with pipe/chain operator parsing
• JWT Bearer authentication — OAuth 2.1 compatible JWT auth alongside API key auth
• API key authentication — gateway-level auth middleware (optional, off in dev)
• Internal-only services — tool servers are not externally exposed; only the gateway is public
• File size limits — configurable maximum file sizes prevent resource exhaustion

MCP Tool Servers

FileSystem Tools (ClawSharp.Tools.FileSystem)

Shell Tools (ClawSharp.Tools.Shell)

Web Tools (ClawSharp.Tools.Web)

Data Tools (ClawSharp.Tools.Data)

Git Tools (ClawSharp.Tools.Git)

Memory Tools (ClawSharp.Tools.Memory)

Gateway (MCP Reverse Proxy)

• Unified MCP endpoint — single /mcp endpoint aggregates all 33 tools from 6 backend servers
• Automatic tool discovery — connects as MCP client to each backend on startup, caches tool list
• Smart routing — routes CallTool requests to the correct backend by tool name
• Resilient — tolerates backend unavailability, auto-reconnects on demand
• Tool refresh — POST /tools/refresh to re-discover tools without restart
• Tool registry — REST catalog at /tools and status at /
• Skills API — GET /skills, GET /skills/{name}, GET /skills/search/{query}
• Workflows API — GET /workflows, GET /workflows/{name}
• Plugins API — GET /plugins — dynamically loaded tool assemblies
• JWT + API key auth — dual authentication (off in dev)
• Aspire service discovery — resolves backend URLs by name, no hardcoded ports

Zero-Install with dnx

Run any ClawSharp tool server directly from NuGet — no clone, no build, no install:

# Run the Gateway (all 33 tools via unified MCP endpoint)
dnx ClawSharp.Gateway

# Run individual tool servers
dnx ClawSharp.Tools.FileSystem
dnx ClawSharp.Tools.Git
dnx ClawSharp.Tools.Shell
dnx ClawSharp.Tools.Web
dnx ClawSharp.Tools.Data
dnx ClawSharp.Tools.Memory

MCP Client Configuration

Configure your MCP client (Claude Desktop, Claude Code, VS Code, etc.) to use ClawSharp via dnx:

{
  "mcpServers": {
    "clawsharp": {
      "command": "dnx",
      "args": ["ClawSharp.Gateway"]
    }
  }
}

Or connect individual tool servers:

{
  "mcpServers": {
    "clawsharp-filesystem": {
      "command": "dnx",
      "args": ["ClawSharp.Tools.FileSystem"]
    },
    "clawsharp-git": {
      "command": "dnx",
      "args": ["ClawSharp.Tools.Git"]
    }
  }
}

Install as Global Tools (optional)

dotnet tool install -g ClawSharp.Gateway
clawsharp-gateway

Using as a Library

Build your own MCP tool servers on top of ClawSharp:

dotnet add package ClawSharp.Core
dotnet add package ClawSharp.Agent           # Optional: workflow engine
dotnet add package ClawSharp.ServiceDefaults  # Optional: Aspire defaults

NuGet Packages

Quick Start

Prerequisites

• .NET 10 SDK
• Docker Desktop (for Aspire dashboard)
• An IDE with Aspire support (VS 2022 17.9+, VS Code with C# Dev Kit, or JetBrains Rider)

Run with Aspire (Development)

cd src/ClawSharp.AppHost
dotnet run

The Aspire dashboard opens automatically showing all services, logs, traces, and custom metrics.

Run with Docker Compose (Production)

docker-compose up -d

Gateway available at http://localhost:5000.

Deploy to Azure Container Apps

azd init
azd up

Deploy to Kubernetes

helm install clawsharp deploy/helm/clawsharp/ \
  --set global.image.registry=myregistry.azurecr.io \
  --set gateway.auth.apiKey=my-secret-key

Connect an MCP Client

The Gateway aggregates all 33 tools from 6 backend servers into a single MCP endpoint:

# Gateway unified MCP endpoint (recommended — all tools in one place)
http://localhost:{gateway-port}/mcp

# Individual tool servers (for direct access)
http://localhost:{port}/mcp

Configuration

All settings are in appsettings.json on each service:

{
  "ClawSharp": {
    "WorkspacePath": "~/.clawsharp",
    "Sandbox": {
      "AllowedPaths": ["/home/user/projects", "C:\\Projects"],
      "AllowedCommands": ["dotnet", "git", "npm", "node", "python", "pip"],
      "AllowedHosts": ["*"],
      "MaxFileSizeBytes": 10485760,
      "CommandTimeoutSeconds": 30
    },
    "Memory": {
      "StoragePath": "memory",
      "MaxEntries": 10000,
      "MaxSearchResults": 20
    }
  }
}

Set the gateway API key via user secrets:

cd src/ClawSharp.Gateway
dotnet user-secrets set "ClawSharp:Gateway:ApiKey" "your-secret-key"

Project Structure

ClawSharp/
├── src/
│   ├── ClawSharp.AppHost/          # Aspire orchestrator
│   ├── ClawSharp.ServiceDefaults/  # Shared OTel, health, resilience, rate limiting
│   ├── ClawSharp.Core/             # Security, config, diagnostics, plugins, skills, prompts
│   │   ├── Configuration/
│   │   ├── Diagnostics/            # Audit logger, custom metrics
│   │   ├── Extensions/             # DI, audit, prompt extensions
│   │   ├── Health/                 # Sandbox, Git, Memory health checks
│   │   ├── Memory/                 # Vector index for semantic search
│   │   ├── Plugins/                # Plugin loader, registry, interface
│   │   ├── Prompts/                # Built-in MCP prompt templates
│   │   ├── Security/               # Path, command, sandbox validation
│   │   └── Skills/                 # Skill loader, registry, model
│   ├── ClawSharp.Agent/            # Workflow engine and built-in workflows
│   ├── ClawSharp.Gateway/          # Public API gateway + MCP proxy
│   │   ├── Authentication/         # JWT auth extensions
│   │   ├── Middleware/             # API key auth middleware
│   │   ├── Services/              # Tool aggregator, registry
│   │   ├── Skills/                # Markdown skill definitions
│   │   └── Plugins/               # Runtime plugin directory
│   ├── ClawSharp.Tools.FileSystem/ # File operations MCP server + resources
│   ├── ClawSharp.Tools.Shell/      # Shell execution MCP server
│   ├── ClawSharp.Tools.Web/        # HTTP/web MCP server
│   ├── ClawSharp.Tools.Data/       # Data transform MCP server
│   ├── ClawSharp.Tools.Git/        # Git repository MCP server
│   └── ClawSharp.Tools.Memory/     # Persistent memory MCP server + resources + vector search
├── tests/
│   ├── ClawSharp.Tests/            # Unit tests (34 tests)
│   └── ClawSharp.IntegrationTests/ # Aspire integration tests (20+ tests)
├── docker-compose.yml              # Production deployment without Aspire
├── azure.yaml                      # Azure Developer CLI project definition
├── infra/                          # Bicep templates for Azure Container Apps
├── deploy/helm/clawsharp/          # Helm chart for Kubernetes
└── Directory.Build.props           # Shared build settings (R2R, TieredPGO)

Testing

# Unit tests (fast, no Docker needed)
dotnet test tests/ClawSharp.Tests/

# Integration tests (requires Docker for Aspire)
dotnet test tests/ClawSharp.IntegrationTests/

Roadmap

Completed

• MCP Gateway proxy — unified tool endpoint
• MCP resource support (FileSystem and Memory)
• MCP prompt templates (5 built-in)
• Rate limiting (global + MCP-specific)
• Audit logging (source-generated + metrics)
• Custom OpenTelemetry metrics (6 instruments)
• Health check enrichment (sandbox, git, memory)
• Git tools server (8 tools)
• Regex-based command validation with pipe/chain support
• JWT Bearer + API key dual authentication
• Agent runtime with workflow engine
• Skill system with markdown definitions
• Plugin system for external tool assemblies
• Vector memory with TF-IDF semantic search
• ReadyToRun + TieredPGO compilation
• Dockerfiles for all services
• Docker Compose for non-Aspire deployment
• Container-per-session isolation (ephemeral Docker containers per MCP session)
• Azure Container Apps / azd deployment manifests (Bicep)
• Helm charts for Kubernetes
• Entra ID / OIDC provider support (Entra ID, Auth0, Keycloak)
• MCP sampling support for LLM-powered tool chains

Completed (continued)

• NuGet packaging with dnx zero-install support
• GitHub Actions CI/CD with auto-versioning (MinVer) and NuGet publishing
• Library packages for custom tool server development

Future

• Full NativeAOT when MCP SDK adds AOT tool discovery support
• Azure Developer CLI (azd up) integration testing
• Horizontal pod autoscaling based on MCP request rate
• Multi-tenant workspace isolation

License

MIT