Add MCP server support — expose Repl apps as AI agent tools

[carldebilly]

Summary

Enables any Repl app to become an MCP (Model Context Protocol) server with a single app.UseMcpServer() call. AI agents like Claude Desktop, VS Code Copilot, and Cursor can then discover and invoke commands as typed tools with real JSON Schema, behavioral annotations, and progressive interaction degradation.

var app = ReplApp.Create().UseDefaultInteractive();

app.Map("contacts", () => db.GetAll())
    .ReadOnly()
    .AsResource();

app.Map("contact add", (string name, string email) => db.Add(name, email))
    .OpenWorld().Idempotent();

app.Map("contact delete {id:guid}", async (Guid id, IReplInteractionChannel interaction, CancellationToken ct) =>
    {
        if (!await interaction.AskConfirmationAsync("confirm", $"Delete {id}?", options: new(ct)))
            return Results.Cancelled("Aborted.");
        return db.Delete(id);
    })
    .Destructive();

app.UseMcpServer();
return app.Run(args);

myapp mcp serve                    # starts MCP stdio server
myapp                              # still works as a CLI / interactive REPL

One command graph. CLI, REPL, remote sessions, and AI agents — all from the same code.

What agents see

Commands become MCP tools with typed JSON Schema derived from route constraints and handler parameters. Annotations map directly to MCP hints that agents use for safety decisions:

Repl API	MCP effect
.ReadOnly()	readOnlyHint: true, destructiveHint: false — agent calls autonomously
.Destructive()	destructiveHint: true — agent asks for confirmation
.Idempotent()	idempotentHint: true — agent retries on failure
.OpenWorld()	openWorldHint: true — agent expects latency
.AutomationHidden()	excluded from tool list entirely
.AsResource()	exposed as MCP resource with URI template (e.g. repl://config/{env})
.AsPrompt()	exposed as MCP prompt template
.WithDetails(md)	enriches MCP tool description with extended markdown

Route constraints ({id:guid}, {email:email}, {when:date}) produce proper JSON Schema formats. Parameterized resources (e.g. config {env}) are exposed as URI templates — agents read repl://config/production and the parameters flow through the command pipeline.

Runtime interaction in MCP mode

Commands that prompt users at runtime (AskConfirmationAsync, AskChoiceAsync, etc.) degrade gracefully across four tiers:

1. Prefill — values from tool arguments (answer:confirm=yes)
2. Elicitation — structured form request to the user through the agent client
3. Sampling — LLM answers on behalf of the user
4. Default/Fail — use explicit default value or fail with descriptive error

AskConfirmationAsync accepts bool? defaultValue = null — explicit defaults are returned before mode checks (consistent with AskChoiceAsync and AskTextAsync). AskSecretAsync is always prefill-only (security). WriteProgressAsync maps to real-time MCP progress notifications. WriteStatusAsync maps to MCP log messages.

Custom transports & HTTP

The server supports three integration patterns:

• Stdio (default) — myapp mcp serve for standard MCP clients
• Stdio-over-anything — TransportFactory option for WebSocket, named pipes, SSH, etc.
• MCP-over-HTTP — BuildMcpServerOptions() builds the MCP collections for use with ASP.NET Core or any HTTP host

Multi-session is supported in all patterns via AsyncLocal session isolation (same mechanism as hosted sessions). See docs/mcp-advanced.md for recipes.

// Custom transport via mcp serve
app.UseMcpServer(o => o.TransportFactory = (name, io) =>
    new StreamServerTransport(wsInput, wsOutput, name));

// Standalone options for HTTP integration
var mcpOptions = app.Core.BuildMcpServerOptions();
var server = McpServer.Create(httpTransport, mcpOptions);

Architecture

The design splits into two layers:

• Core enrichment (Repl.Core) — CommandAnnotations, WithDetails, AsResource, AsPrompt, ReplRuntimeChannel.Programmatic, public CreateDocumentationModel. Useful independently of MCP.
• Repl.Mcp package — opt-in, references ModelContextProtocol SDK. Reads the documentation model, generates JSON Schema, registers MCP tools/resources/prompts, dispatches tool calls through the existing Repl pipeline, and captures output.

Tool calls execute through CoreReplApp.RunWithServicesAsync — the same pipeline as CLI and interactive mode. No parallel code path.

Reliability & performance

• Debounced routing invalidation — multiple rapid Map() calls coalesce into a single rebuild (100ms debounce via injectable TimeProvider)
• Optimistic concurrency — route rebuilds use a temporary adapter; existing routes stay live until the atomic swap
• Timer crash resilience — unhandled exceptions in rebuild callbacks are caught; server continues with stale routes
• IsProgrammatic AsyncLocal — properly saved/restored across all execution paths
• Concurrent sessions — tested with parallel MCP sessions sharing the same app instance

Configuration

app.UseMcpServer(o =>
{
    o.ServerName = "MyApp";
    o.ServerVersion = "1.0.0";
    o.ResourceUriScheme = "myapp";                              // myapp://status instead of repl://status
    o.TransportFactory = (name, io) => customTransport;         // custom transport
    o.InteractivityMode = InteractivityMode.PrefillThenFail;
    o.ResourceFallbackToTools = true;                           // resources also appear as tools
    o.PromptFallbackToTools = true;                             // prompts also appear as tools
    o.CommandFilter = cmd => true;
});

Test plan

• 736 tests pass (dotnet test --solution src/Repl.slnx)
• End-to-end tests via real MCP client/server over in-process pipes
• Concurrent session isolation tested
• Debounce tested with FakeTimeProvider (deterministic, sync)
• Parameterized resource read tested
• Interaction error paths tested (ParseBool, prefix matching, min/max multi-choice)
• Timer crash resilience tested
• Custom transport factory tested