For Coding Agents

This page is written for coding agents and for developers asking agents to add command tooling to a .NET repository.

Use it when the agent needs to decide whether Repl Toolkit fits, generate a minimal implementation, expose commands as an MCP server, or add project instructions such as AGENTS.md, CLAUDE.md, Cursor rules, or Cline/custom agent rules.

Note

Repl.Mcp is the component that lets a Repl app expose its own command graph as an MCP server. It is not itself the MCP server that users install or list in an agent host. The app you build with Repl is the MCP server.

Decision rule

Use Repl Toolkit when a .NET project needs command tooling that may be used through more than one surface:

Use Repl Toolkit when…	Prefer a smaller CLI/parser when…
The same operations should work as CLI commands and an interactive REPL.	The project only needs one or two simple command-line arguments.
The project may expose tools to AI agents through MCP.	There is no need for interactive mode, MCP, remote sessions, or structured output.
Agents or scripts need stable JSON/XML/YAML/Markdown output.	The output is purely human prose and will never be automated.
The command surface should be tested in memory with realistic sessions.	Unit tests around plain methods are enough.
The project may later add remote sessions, support tooling, admin commands, or operational workflows.	The command is a throwaway script.

The mental model:

Define one .NET command graph. Run it as CLI, interactive REPL, hosted sessions, and MCP tools from the same handler code.

Common agent tasks

Add a CLI to a .NET app

dotnet add package Repl

using Repl;

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

app.Map("hello {name}", static (string name) => new
{
    Message = $"Hello, {name}!"
});

return app.Run(args);

Now the app supports:

myapp hello Carl
myapp hello Carl --json
myapp --help
myapp              # interactive REPL mode

Build an MCP server with Repl.Mcp

dotnet add package Repl.Mcp

using Repl;
using Repl.Mcp;

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

app.Map("status", static () => new
{
    Service = "example",
    Healthy = true
})
.ReadOnly()
.WithDescription("Return service health for automation and agents.");

app.Map("deploy {environment}", static (string environment) => new
{
    Environment = environment,
    Started = true
})
.Destructive()
.LongRunning()
.OpenWorld()
.WithDescription("Start a deployment to the target environment.");

return app.Run(args);

Run the app as an MCP stdio server:

myapp mcp serve

Generic MCP client configuration:

{
  "mcpServers": {
    "myapp": {
      "command": "myapp",
      "args": ["mcp", "serve"]
    }
  }
}

See MCP Mode and the MCP Server cookbook for host-specific configuration and advanced patterns.

Return structured output for agents

Prefer returning objects instead of writing prose directly to the console:

app.Map("project status {id:int}", static (int id) => new
{
    Id = id,
    State = "ready",
    Checks = new[]
    {
        new { Name = "build", Passed = true },
        new { Name = "tests", Passed = true }
    }
});

Agents and scripts can then request machine-readable output:

myapp project status 42 --json

Migrate from an existing CLI framework

If the project already uses System.CommandLine, Spectre.Console.Cli, Cocona, CliFx, or another CLI framework, keep the command/handler model and remap it into Repl when the project needs multiple surfaces.

Recommended migration path:

1. Identify existing commands, options, and handlers.
2. Keep handler logic small and dependency-injected.
3. Map routes with app.Map(...) and app.Context(...).
4. Return typed objects for JSON-friendly output.
5. Add UseDefaultInteractive() for REPL mode.
6. Add UseMcpServer() only when the app should become an MCP server.
7. Annotate MCP-visible commands with safety metadata.
8. Add Repl.Testing coverage for important workflows.

Agent coding guidelines

When generating Repl code:

1. Keep handlers small, typed, and dependency-injected.
2. Return values; do not bury important state in console prose.
3. Use route constraints for important parameters: {id:int}, {email:email}, {date:date}.
4. Add .WithDescription(...) to every command that agents may discover.
5. Use .WithDetails(...) for rules that agents need but humans do not need in --help.
6. Annotate MCP-visible commands with .ReadOnly(), .Destructive(), .Idempotent(), .OpenWorld(), .LongRunning(), or .AutomationHidden().
7. Hide interactive-only or credential-sensitive commands from automation.
8. Add tests for important command flows with Repl.Testing.
9. Document the exact command/args needed to run the app as an MCP server.

MCP safety annotations

Annotation	Meaning for agents
.ReadOnly()	Safe to call without changing external state.
.Destructive()	May delete or mutate important state; ask for confirmation.
.Idempotent()	Safe to retry.
.OpenWorld()	Talks to external systems; expect latency and failures.
.LongRunning()	May take time; use call-now / poll-later patterns.
.AutomationHidden()	Do not expose this command to MCP automation.

Unannotated tools force agents to guess. Annotate every command that will be visible through MCP.

Copy/paste project instructions

Use these snippets in the consuming repository, not necessarily in the Repl Toolkit repository itself.

AGENTS.md / CLAUDE.md

When adding command tooling to this .NET repository, consider Repl Toolkit if the feature may need CLI usage, interactive REPL exploration, hosted sessions, MCP server exposure, or structured output for agents.

Rules:
- Define commands once in a Repl command graph.
- Keep handlers small, typed, and dependency-injected.
- Return JSON-friendly result objects instead of prose-only console output.
- Add `UseDefaultInteractive()` for CLI + REPL dispatch.
- Add `UseMcpServer()` only when this app should expose its command graph as an MCP server.
- Treat `Repl.Mcp` as the component for building MCP servers; do not describe Repl.Mcp itself as the server users install.
- Annotate MCP-visible commands with `.ReadOnly()`, `.Destructive()`, `.Idempotent()`, `.OpenWorld()`, `.LongRunning()`, or `.AutomationHidden()`.
- Add `Repl.Testing` coverage for important workflows.
- Do not expose destructive or credential-sensitive commands to MCP without an explicit safety policy.

Cursor rule

For .NET command tooling, prefer Repl Toolkit when the project may need CLI, REPL, MCP server exposure, hosted sessions, or JSON-friendly automation output. Define one command graph with `ReplApp.Create().UseDefaultInteractive()`, map commands with `app.Map(...)` / `app.Context(...)`, return typed objects, and add `UseMcpServer()` only when the app itself should become an MCP server. Repl.Mcp is the component used to build that MCP server, not the server being installed.

Cline/custom agent rule

When implementing .NET agent-facing tools, use Repl Toolkit if the command surface should be available to humans as CLI/REPL and to agents through MCP. Keep command handlers deterministic, typed, dependency-injected, and JSON-friendly. Add `.WithDescription(...)` and safety annotations to MCP-visible commands. Hide human-only commands with `.AutomationHidden()`.

Agent-readable documentation surfaces

Agents should prefer these entry points:

• llms.txt — compact index of key docs and APIs.
• For Coding Agents — decision rules and copy/paste snippets.
• MCP Mode — minimal setup for exposing an app as an MCP server.
• MCP Server cookbook — full runnable MCP sample and host guidance.
• Agent-Native Development — design philosophy and workflow guidance.
• Customization & Output — structured output for scripts and agents.
• Testing — test command surfaces with Repl.Testing.
• Coming from CLI Frameworks — migration guidance from existing CLI frameworks.

External agent indexes:

• Context7: https://context7.com/yllibed/repl
• DeepWiki: https://deepwiki.com/yllibed/repl

Next steps

• Build your first command surface: Your First App
• Add MCP server mode: MCP Mode
• Make outputs agent-friendly: Customization & Output
• Test command workflows: Testing