Add MCP client roots support and dynamic tool compatibility fallback

[carldebilly]

Summary

This PR adds two MCP-focused capabilities to Repl:

• support for session-scoped MCP client roots through a dedicated injectable service
• an opt-in compatibility layer for clients that do not handle dynamic tool list refreshes well

It also restructures the MCP documentation to better separate:

• how to use the features
• how the underlying behavior works

In addition, this PR aligns MCP-specific public APIs under the Repl.Mcp namespace.

What changed

MCP client roots

Added a new MCP-only abstraction:

• IMcpClientRoots
• McpClientRoot

This allows MCP handlers and module presence predicates to access client workspace roots when the connected client supports them.

The service also supports session-scoped fallback roots ("soft roots") for clients that do not implement native MCP roots.

Dynamic tool compatibility fallback

Added a new opt-in option:

• DynamicToolCompatibilityMode
• ReplMcpServerOptions.DynamicToolCompatibility

When DiscoverAndCallShim is enabled, the server:

1. returns discover_tools and call_tool on the first tools/list
2. emits notifications/tools/list_changed
3. returns the real tool list on later tools/list

This is intended for applications with genuinely dynamic tool graphs, especially when targeting clients that ignore or mishandle tools/list_changed.

Session-aware MCP generation

The MCP server now builds tools, resources, and prompts dynamically per session, using the MCP session service provider. This allows session-scoped services such as IMcpClientRoots to influence:

• module presence
• tools
• resources
• prompts

MCP namespace alignment

Public MCP-specific APIs are now exposed from Repl.Mcp instead of the root Repl namespace, including:

• IMcpClientRoots
• McpClientRoot
• DynamicToolCompatibilityMode
• InteractivityMode
• ToolNamingSeparator
• ReplMcpServerOptions
• McpReplExtensions

This keeps MCP concepts grouped under the package namespace instead of making MCP-only abstractions appear as core Repl primitives.

Documentation

The MCP docs were reorganized into:

• docs/mcp-server.md for the main guide and basic troubleshooting
• docs/mcp-advanced.md for advanced usage patterns
• docs/mcp-internals.md for concepts and under-the-hood behavior
• docs/mcp-transports.md for transport and HTTP hosting scenarios

The docs now also include:

• native roots usage
• soft roots fallback patterns
• dynamic tool troubleshooting
• workspace resolution guidance for MCP-only and workspace-aware commands
• a clearer separation between practical guidance and internal behavior

Why

Some MCP scenarios require session-aware behavior:

• tools that appear only after initialization or authentication
• tools that depend on workspace context
• clients that do not support native roots
• clients that do not refresh dynamic tools correctly

This PR provides a structured way to support those cases without affecting the default behavior for static MCP servers.

Validation

Validated with:

• dotnet build src/Repl.McpTests/Repl.McpTests.csproj --no-restore -p:NuGetAudit=false
• dotnet test --project src/Repl.McpTests/Repl.McpTests.csproj --no-build --output Normal --no-progress

Result:

• 109 tests passed

Notes

• The dynamic tool compatibility shim is intentionally opt-in.
• Static tool graphs continue to use the normal MCP behavior without extra compatibility indirection.
• Soft roots automatically invalidate routing for the current MCP session when set or cleared.
• This PR also includes a namespace alignment for MCP-specific public APIs, which is intentionally breaking while this feature surface is still new.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.