AfrenAI.Mosaic.Mcp 1.0.0

dotnet add package AfrenAI.Mosaic.Mcp --version 1.0.0
                    
NuGet\Install-Package AfrenAI.Mosaic.Mcp -Version 1.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="AfrenAI.Mosaic.Mcp" Version="1.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="AfrenAI.Mosaic.Mcp" Version="1.0.0" />
                    
Directory.Packages.props
<PackageReference Include="AfrenAI.Mosaic.Mcp" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add AfrenAI.Mosaic.Mcp --version 1.0.0
                    
#r "nuget: AfrenAI.Mosaic.Mcp, 1.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package AfrenAI.Mosaic.Mcp@1.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=AfrenAI.Mosaic.Mcp&version=1.0.0
                    
Install as a Cake Addin
#tool nuget:?package=AfrenAI.Mosaic.Mcp&version=1.0.0
                    
Install as a Cake Tool

MOSAIC

Model Orchestrated Sandboxed API Interaction Core is a .NET library for running short, structured workflows over host-registered tools. A model can compose tool calls, branch on an earlier boolean result, and map a bounded list through a registered tool while the host retains control of which capabilities are granted.

MOSAIC is an early reference implementation. Its v0.1 plan contract is shared by the .NET core and language wrappers. It is not a general-purpose code sandbox, an MCP server, or a replacement for operating-system isolation. It never evaluates generated C#, JavaScript, Python, shell, or other source code. A plan is data, and the only executable operations are handlers explicitly registered by the host.

What it does

  • Accepts a bounded JSON plan with an ordered list of tool calls and one selected output.
  • Allows a later step to consume the complete JSON result of an earlier step using {"$ref":"step-id"}.
  • Supports a boolean when branch and bounded forEach over earlier array results; each executed tool call still passes the same capability check.
  • Checks each tool's required capability against the host-supplied grants immediately before invocation.
  • Rejects unknown tools, unknown plan fields, repeated step IDs, missing grants, and forward references.
  • Applies host configured limits to plan size, call count, JSON nesting, and selected result size.
  • Observes cancellation between calls and forwards the cancellation token to handlers.

Quick start

Requirements: .NET 10 or .NET 11. The NuGet packages target both net10.0 (LTS) and net11.0. Building the full solution, including tests on both frameworks, needs the .NET 11 SDK plus the .NET 10 runtime. No SDK is installed by this project. CI uses GitHub hosted runners.

var readCapability = new Capability("catalog.read");
var registry = new ToolRegistry([
    new ToolDefinition("lookup", readCapability, (arguments, cancellationToken) =>
    {
        cancellationToken.ThrowIfCancellationRequested();
        var key = arguments.GetProperty("key").GetString();
        return ValueTask.FromResult(JsonSerializer.SerializeToElement(new { key, found = true }));
    })
]);

var executor = new WorkflowExecutor(registry, new WorkflowLimits(MaximumSteps: 5));
var grants = new HashSet<Capability> { readCapability };
var result = await executor.ExecuteAsync(Encoding.UTF8.GetBytes(planJson), grants, cancellationToken);

Run the complete example with dotnet run --project samples/Mosaic.Demo.

Plan shape:

{
  "steps": [
    { "id": "record", "tool": "lookup", "arguments": { "key": "item-42" } },
    { "id": "summary", "tool": "summarize", "arguments": { "record": { "$ref": "record" } } }
  ],
  "output": "summary"
}

The reference object replaces its argument value with the full result of the named earlier step. A loop refers to each item in its arguments with {"$item":true}. when accepts a boolean literal or reference to an earlier boolean result. Loops are capped by MaximumLoopIterations and all executed calls share MaximumSteps; there are no expressions, property paths, nested loops or dynamic tool creation.

{
  "steps": [
    { "id": "enabled", "tool": "feature.enabled", "arguments": {} },
    { "id": "users", "tool": "directory.list", "arguments": {}, "when": { "$ref": "enabled" } },
    {
      "id": "checks",
      "forEach": {
        "items": { "$ref": "users" },
        "tool": "policy.check",
        "arguments": { "user": { "$item": true } }
      }
    }
  ],
  "output": "checks"
}

Host protocol and process runner

The v1.0 stdio protocol carries a request ID, version, method and workflow plan. Callers cannot supply capabilities. The host applies its own grants. MosaicProcessClient starts a fresh host process per request and bounds request/response bytes, runtime, managed .NET heap and concurrent workers. It kills the worker tree on timeout or cancellation and discards worker stderr.

This worker mode is process separation, not a complete security sandbox: on its own the worker still inherits the launching user's operating-system permissions and may have network or filesystem access. For hostile tools, configure the executable to launch inside a separately enforced container or operating-system sandbox with read-only filesystems, resource quotas and network denial. The managed heap limit does not constrain native allocations; timeout is wall-clock, not a kernel CPU quota.

MCP integration

The AfrenAI.Mosaic.Mcp package adapts the engine to the official MCP C# SDK. It exposes one mosaic_execute tool that accepts a plan and invokes the same host-owned capability policy. Your application chooses and configures its MCP transport; the package does not start an implicit listener.

builder.Services
    .AddMosaicMcpServer(protocolServer)
    .WithStdioServerTransport();

Installation

Install from NuGet.org:

dotnet add package AfrenAI.Mosaic
dotnet add package AfrenAI.Mosaic.Mcp

Releases

Pushing a v* tag (for example v1.0.0) runs the tests, packs AfrenAI.Mosaic and AfrenAI.Mosaic.Mcp with the version taken from the tag, and publishes them to both NuGet.org and the AFREN-AI GitHub Packages feed (https://nuget.pkg.github.com/AFREN-AI/index.json). NuGet.org publishing uses Trusted Publishing: the workflow exchanges a GitHub OIDC token for a short-lived API key, so no long-lived NuGet key is stored in the repository. The workflow can also be run manually with an explicit version. NuGet.org versions are permanent; they can be unlisted but not deleted.

Progressive tool discovery

Add descriptions and JSON Schema input definitions to each ToolDefinition. Hosts can call ToolRegistry.Search(query) and ToolRegistry.Describe(name), or use the MCP tools mosaic_search and mosaic_describe. Discovery returns public metadata only; it never includes host capability names or grants. The host still checks capabilities immediately before invocation.

Durable approvals and replay

MosaicDurableToolRunner records a tool request before approval, persists an approval or rejection, and saves completed output for replay. FileMosaicExecutionStore stores JSON snapshots in a host-selected directory and is intended for a single host process. Protect that directory as application data: arguments and outputs may contain sensitive information. For multi-process or multi-region hosts, implement IMosaicExecutionStore with a transactional shared store. Completed executions replay their stored output. A crash after a side effect but before its result is journaled can cause the handler to run again; durable handlers must honor the execution ID as their idempotency key.

Generated JavaScript execution

MosaicCodeExecutor runs async JavaScript functions in a Linux container pinned by image digest. Build the runner from sandbox/Dockerfile, publish it to a trusted registry, and pass its immutable repository@sha256:... reference to MosaicCodeSandboxOptions. The host disables network access, uses a read-only filesystem and non-root UID, drops Linux capabilities, and applies process, memory, CPU, message, call-count, and wall-clock limits. Only explicitly selected, host-authorized tools are exposed through the RPC bridge. Every invocation waits for the host approval callback and is journaled with a stable idempotency key, so these tools must use idempotency-aware handlers. The Node vm module is not itself the security boundary; container isolation is required. Use a trusted rootless container runtime with its default seccomp/AppArmor or SELinux policy, and do not mount host paths or pass secrets into the image.

var runner = new MosaicDurableToolRunner(registry, new FileMosaicExecutionStore("mosaic-state"));
var sandbox = new MosaicCodeSandboxOptions("ghcr.io/afren-ai/mosaic-sandbox@sha256:<64-hex-digest>");
var codeExecutor = new MosaicCodeExecutor(registry, sandbox, runner);
var output = await codeExecutor.ExecuteAsync(
    executionId: "request-2026-0001",
    code: "async (tools) => await tools['catalog.lookup']({ key: 'item-42' })",
    allowedTools: ["catalog.lookup"],
    grantedCapabilities: grants,
    approvalCallback: async (id, toolName, arguments, token) =>
        await approvalUi.RequestAsync(id, toolName, arguments, token));

Language wrappers

The plan contract is stable enough for client libraries that construct and serialize plans. These wrappers share the JSON format and validate basic construction rules such as non-empty identifiers, duplicate steps, selected output, and references to earlier steps:

These wrappers build plan JSON; they do not invoke the .NET engine or execute tools. An application passes the serialized plan to its trusted .NET host, which owns tool registration, authorization, and execution. The shared plan schema is in conformance/plan.schema.json. Plan contract compatibility is intended to follow semantic versioning from v1.0; until then, wrappers are versioned 0.1.x alongside this early API.

Versioned host protocol

Protocol v1.0 accepts one JSON request per line over standard input and returns one JSON response per line on standard output. See conformance/host-request.schema.json and conformance/host-response.schema.json. The request carries a request ID, protocol version, method, and workflow plan. It cannot supply or expand capabilities; the host grants permissions from its own trusted configuration.

Run the reference host with dotnet run --project src/Mosaic.Host. The reference host exposes only a demonstration math.add tool under its math.read capability. For example:

{"protocolVersion":"1.0","requestId":"demo-1","method":"execute","plan":{"steps":[{"id":"sum","tool":"math.add","arguments":{"left":20,"right":22}}],"output":"sum"}}

Security model

The model that proposes a plan is untrusted. Tool handlers and capability grants belong to the integrating host. MOSAIC checks registered tool identity and its required capability; a plan cannot grant itself permissions. Unknown tools are denied. Give the executor only the tools and capabilities appropriate for a single task.

In-process handlers run with host process privileges. Use MosaicProcessClient to isolate the host's worker lifetime and bound protocol I/O, or use a container/OS sandbox for hostile handlers. Do not treat process separation alone as a security boundary.

The executor does not log plan arguments or tool results. Hosts should avoid recording sensitive payloads, credentials, or personal data in their own telemetry.

Build and verify

dotnet restore MOSAIC.slnx
dotnet test MOSAIC.slnx --configuration Release --no-restore
dotnet run --project samples/Mosaic.Demo

Packages

The core and MCP adapter are published to GitHub Packages as AfrenAI.Mosaic and AfrenAI.Mosaic.Mcp. Package feeds and install instructions are in the GitHub Packages section below.

MOSAIC is a workflow orchestrator, not a drop-in implementation of arbitrary-code Code Mode. It uses a constrained, registered-tool plan to make composition and host-side authorization explicit.

License

Apache-2.0. See LICENSE.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed.  net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.0 0 11/17/2026
0.3.0 93 10/24/2026