Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -190,6 +190,29 @@ The agent then sees all tools from the Puppeteer server alongside the built-in F

---

## Servers provided by the launcher

A program that starts fuseraft can give it MCP servers of its own through the `FUSERAFT_MCP_SERVERS`
environment variable: a JSON array of the `McpServerConfig` fields above. fuseraft-web uses this for the
MCP servers an admin adds on its MCP servers page, which reach every account's chats and runs.

```sh
export SQL_MCP_TOKEN=...
export FUSERAFT_MCP_SERVERS='[{"Name":"Sql","Transport":"http","Url":"http://localhost:8080/mcp",
"TransportMode":"streamable-http","Headers":{"Authorization":"Bearer ${SQL_MCP_TOKEN}"}}]'
```

Keep secrets in their own variables and refer to them with `${NAME}`, as above. Values of variables whose
names look like secrets (`..._TOKEN`, `..._KEY`) are masked in tool output; `FUSERAFT_MCP_SERVERS` itself isn't.

- **REPL**: each one connects at startup along with your saved servers, and `/mcp list` marks it *provided by
the launcher*. A saved server with the same name is used instead. `/mcp remove` drops it for the session only.
- **Orchestration**: one connects only if an agent names it in `Plugins` and the config's own `McpServers`
doesn't use the name. If it can't connect, the run logs a warning and carries on without its tools, rather
than failing as a server in `McpServers` would.

---

## Building your own MCP server

Any MCP-compliant server works. For .NET, use the `ModelContextProtocol` NuGet package.
Expand Down
5 changes: 4 additions & 1 deletion src/Cli/Commands/Repl/ReplCommand.cs
Original file line number Diff line number Diff line change
Expand Up @@ -660,7 +660,10 @@ private async Task<int> RunAsync(
activePlugins.Add(p);
}

foreach (var server in ReplMcpServerStore.Load())
var managedMcp = ManagedMcpServers.Load(out var managedMcpError);
if (managedMcpError is not null)
AnsiConsole.MarkupLine($"[yellow]⚠ {Markup.Escape(managedMcpError)}[/]");
foreach (var server in ManagedMcpServers.Merge(ReplMcpServerStore.Load(), managedMcp))
{
try
{
Expand Down
34 changes: 26 additions & 8 deletions src/Cli/Commands/Repl/ReplCommands.Mcp.cs
Original file line number Diff line number Diff line change
Expand Up @@ -84,13 +84,19 @@ private static CommandResult CmdMcpList(ReplSessionContext ctx)
var name = category[McpCategoryPrefix.Length..];
var stopped = ctx.McpManager?.IsRunning(name) == false;
AnsiConsole.MarkupLine($" [bold cyan]{Markup.Escape(name)}[/] [dim]({tools.Count} tool(s))[/]" +
(IsManagedOnly(name) ? " [dim]· provided by the launcher[/]" : "") +
(stopped ? $" [yellow]not running[/] [dim]— /mcp reconnect {Markup.Escape(name)}[/]" : ""));
foreach (var t in tools)
AnsiConsole.MarkupLine($" [dim]·[/] {Markup.Escape(t.Name)}");
}
return CommandResult.Continue;
}

// Came from whatever launched fuseraft (FUSERAFT_MCP_SERVERS), with no saved server of the name standing in front of it.
private static bool IsManagedOnly(string name) =>
ManagedMcpServers.Load(out _).Any(s => s.Name.Equals(name, StringComparison.OrdinalIgnoreCase))
&& !ReplMcpServerStore.Load().Any(s => s.Name.Equals(name, StringComparison.OrdinalIgnoreCase));

private static async Task<CommandResult> CmdMcpAddAsync(
ReplSessionContext ctx, string arg, CancellationToken cancellationToken)
{
Expand Down Expand Up @@ -274,7 +280,8 @@ private static async Task<CommandResult> CmdMcpReconnectAsync(
return CommandResult.Continue;
}

var config = ctx.McpManager?.ConfigOf(name) ?? ReplMcpServerStore.Load()
// One that failed at startup isn't in the manager, so it's looked up where it came from.
var config = ctx.McpManager?.ConfigOf(name) ?? ManagedMcpServers.Merge(ReplMcpServerStore.Load(), ManagedMcpServers.Load(out _))
.FirstOrDefault(s => s.Name.Equals(name, StringComparison.OrdinalIgnoreCase));
if (config is null)
{
Expand Down Expand Up @@ -471,17 +478,24 @@ private static async Task<CommandResult> CmdMcpRemoveAsync(ReplSessionContext ct
}

var category = $"{McpCategoryPrefix}{name}";
if (!ctx.ToolsByCategory.Remove(category))
var managedOnly = IsManagedOnly(name);
var saved = ReplMcpServerStore.Load();
var removed = saved.Where(s => s.Name.Equals(name, StringComparison.OrdinalIgnoreCase)).ToList();

// A saved server that couldn't connect this session is still one to forget.
var connected = ctx.ToolsByCategory.Remove(category);
if (!connected && removed.Count == 0)
{
AnsiConsole.MarkupLine($"[yellow]No connected MCP server named '{Markup.Escape(name)}'.[/]");
AnsiConsole.MarkupLine($"[yellow]No MCP server named '{Markup.Escape(name)}' is connected or saved.[/]");
return CommandResult.Continue;
}

ctx.DisabledCategories.Remove(category);
ctx.ChatOptions = ctx.BuildChatOptions();
if (connected)
{
ctx.DisabledCategories.Remove(category);
ctx.ChatOptions = ctx.BuildChatOptions();
}

var saved = ReplMcpServerStore.Load();
var removed = saved.Where(s => s.Name.Equals(name, StringComparison.OrdinalIgnoreCase)).ToList();
if (removed.Count > 0)
{
saved.RemoveAll(s => s.Name.Equals(name, StringComparison.OrdinalIgnoreCase));
Expand Down Expand Up @@ -510,7 +524,11 @@ private static async Task<CommandResult> CmdMcpRemoveAsync(ReplSessionContext ct

AnsiConsole.MarkupLine(disconnected
? $"[green]Removed '{Markup.Escape(name)}'[/] [dim]and closed its connection.[/]"
: $"[green]Removed '{Markup.Escape(name)}'.[/] [dim]Its tools are no longer offered to the model.[/]");
: connected
? $"[green]Removed '{Markup.Escape(name)}'.[/] [dim]Its tools are no longer offered to the model.[/]"
: $"[green]Removed '{Markup.Escape(name)}'[/] [dim]from your saved servers.[/]");
if (managedOnly)
AnsiConsole.MarkupLine("[dim]Whatever launched fuseraft provides it, so it's back in your next session.[/]");
return CommandResult.Continue;
}
}
28 changes: 28 additions & 0 deletions src/Cli/OrchestratorBuilder.cs
Original file line number Diff line number Diff line change
Expand Up @@ -333,6 +333,30 @@ private sealed record InfrastructureResult(
string? ReadCachePath,
Action<string?> RebindSessionScopedState);

// A server-provided MCP server serves every run on the machine, so it's connected only for a config whose agents
// name it in Plugins, and one that's down costs that agent its tools rather than failing the run.
internal static async Task ConnectManagedMcpServersAsync(OrchestrationConfig config, IReadOnlyList<McpServerConfig> managed,
McpSessionManager mcpManager, PluginRegistry pluginRegistry, ILogger logger, CancellationToken cancellationToken)
{
var wanted = ManagedMcpServers.ReferencedBy(managed, config.McpServers, config.Agents.SelectMany(a => a.Plugins));
foreach (var server in wanted)
{
try
{
var (_, tools) = await mcpManager.ConnectSingleAsync(server, cancellationToken);
pluginRegistry.RegisterAIFunctions(server.Name, tools);
logger.LogInformation("Connected server-provided MCP server '{Name}' ({Count} tool(s)).", server.Name, tools.Count);
}
catch (Exception ex) when (ex is not OperationCanceledException || !cancellationToken.IsCancellationRequested)
{
// Registered empty, so an agent that lists it still builds instead of failing on an unknown plugin.
pluginRegistry.RegisterAIFunctions(server.Name, []);
logger.LogWarning("Could not connect server-provided MCP server '{Name}': {Error}. Agents that list it run without its tools.",
server.Name, ex.Message);
}
}
}

private static async Task<InfrastructureResult> InitInfrastructure(
OrchestrationConfig config,
PluginRegistry pluginRegistry,
Expand All @@ -349,6 +373,10 @@ private static async Task<InfrastructureResult> InitInfrastructure(
var mcpManager = new McpSessionManager(loggerFactory);
if (config.McpServers.Count > 0)
await mcpManager.InitializeAsync(config.McpServers, pluginRegistry, cancellationToken);
var mcpLogger = loggerFactory.CreateLogger("fuseraft.Mcp");
var managedMcp = ManagedMcpServers.Load(out var managedMcpError);
if (managedMcpError is not null) mcpLogger.LogWarning("{Error}", managedMcpError);
await ConnectManagedMcpServersAsync(config, managedMcp, mcpManager, pluginRegistry, mcpLogger, cancellationToken);

EventEmitter? eventEmitter = config.Events is { } evtCfg
? new EventEmitter(evtCfg.Path, loggerFactory.CreateLogger<EventEmitter>())
Expand Down
60 changes: 60 additions & 0 deletions src/Infrastructure/Storage/ManagedMcpServers.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
using System.Text.Json;
using fuseraft.Core.Models.Config;

namespace fuseraft.Infrastructure.Storage;

/// <summary>
/// MCP servers handed to fuseraft by whatever launched it (fuseraft-web's server-wide MCP servers) through the
/// <c>FUSERAFT_MCP_SERVERS</c> environment variable: a JSON array of <see cref="McpServerConfig"/>. They join the
/// REPL's saved servers and an orchestration config's <c>McpServers</c>, and are never written to either.
/// </summary>
public static class ManagedMcpServers
{
public const string EnvVar = "FUSERAFT_MCP_SERVERS";

private static readonly JsonSerializerOptions Json = new() { PropertyNameCaseInsensitive = true };

/// <summary>The servers in <see cref="EnvVar"/>; <paramref name="error"/> says why it couldn't be read.</summary>
public static List<McpServerConfig> Load(out string? error) =>
Parse(Environment.GetEnvironmentVariable(EnvVar), out error);

internal static List<McpServerConfig> Parse(string? json, out string? error)
{
error = null;
if (string.IsNullOrWhiteSpace(json)) return [];
try
{
var servers = JsonSerializer.Deserialize<List<McpServerConfig?>>(json, Json) ?? [];
var named = servers.OfType<McpServerConfig>().Where(s => !string.IsNullOrWhiteSpace(s.Name)).ToList();
if (named.Count < servers.Count)
error = $"{EnvVar} has {servers.Count - named.Count} server(s) without a Name; they were skipped.";
return named;
}
catch (JsonException ex)
{
error = $"{EnvVar} isn't a JSON array of MCP servers ({ex.Message}); none of its servers were connected.";
return [];
}
}

/// <summary>
/// <paramref name="own"/> followed by the managed servers whose names it doesn't already use, so a config or a
/// user's saved server keeps a name it chose.
/// </summary>
public static List<McpServerConfig> Merge(IEnumerable<McpServerConfig> own, IEnumerable<McpServerConfig> managed)
{
var result = own.ToList();
var names = new HashSet<string>(result.Select(s => s.Name), StringComparer.OrdinalIgnoreCase);
result.AddRange(managed.Where(s => names.Add(s.Name)));
return result;
}

/// <summary>The managed servers an orchestration's agents name in <c>Plugins</c>, unless its own <c>McpServers</c> uses the name.</summary>
public static List<McpServerConfig> ReferencedBy(IEnumerable<McpServerConfig> managed,
IEnumerable<McpServerConfig> own, IEnumerable<string> plugins)
{
var used = new HashSet<string>(plugins, StringComparer.OrdinalIgnoreCase);
var taken = new HashSet<string>(own.Select(s => s.Name), StringComparer.OrdinalIgnoreCase);
return [.. managed.Where(s => used.Contains(s.Name) && taken.Add(s.Name))];
}
}
82 changes: 82 additions & 0 deletions tests/FuseraftCli.Tests/ManagedMcpServersTests.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
using fuseraft.Core.Models.Config;
using fuseraft.Infrastructure.Storage;

namespace FuseraftCli.Tests;

public class ManagedMcpServersTests
{
[Fact]
public void Parse_ReadsHttpServerWithHeaders()
{
var servers = ManagedMcpServers.Parse("""
[{"name":"Sql","transport":"http","url":"http://localhost:8080/mcp","transportMode":"streamable-http",
"headers":{"Authorization":"Bearer ${FUSERAFT_WEB_MCP_1_TOKEN}"}}]
""", out var error);

Assert.Null(error);
var s = Assert.Single(servers);
Assert.Equal("Sql", s.Name);
Assert.Equal("http", s.Transport);
Assert.Equal("streamable-http", s.TransportMode);
Assert.Equal("Bearer ${FUSERAFT_WEB_MCP_1_TOKEN}", s.Headers["Authorization"]);
}

[Theory]
[InlineData(null)]
[InlineData("")]
[InlineData(" ")]
public void Parse_UnsetIsEmptyWithoutError(string? json)
{
Assert.Empty(ManagedMcpServers.Parse(json, out var error));
Assert.Null(error);
}

[Fact]
public void Parse_InvalidJsonIsEmptyWithError()
{
Assert.Empty(ManagedMcpServers.Parse("{not json", out var error));
Assert.Contains("isn't a JSON array", error);
}

[Fact]
public void Parse_SkipsServersWithoutAName()
{
var servers = ManagedMcpServers.Parse("""[{"url":"http://a/mcp"},{"name":"B","transport":"http","url":"http://b/mcp"}]""", out var error);

Assert.Equal("B", Assert.Single(servers).Name);
Assert.Contains("without a Name", error);
}

// fuseraft-web passes each server's token as FUSERAFT_WEB_MCP_<n>_TOKEN and relies on its value being masked.
[Fact]
public void LauncherTokenVariables_AreMaskedAsSecrets() =>
Assert.True(fuseraft.Infrastructure.Plugins.EnvSecretMasker.IsSensitiveName("FUSERAFT_WEB_MCP_1_TOKEN"));

[Fact]
public void Merge_KeepsOwnServerOfTheSameName()
{
var own = new McpServerConfig { Name = "sql", Url = "http://mine/mcp" };
var managed = new[] { new McpServerConfig { Name = "Sql", Url = "http://server/mcp" }, new McpServerConfig { Name = "Docs" } };

var merged = ManagedMcpServers.Merge([own], managed);

Assert.Equal(["sql", "Docs"], merged.Select(s => s.Name));
Assert.Equal("http://mine/mcp", merged[0].Url);
}

[Fact]
public void ReferencedBy_OnlyServersAnAgentNamesAndTheConfigDoesNotDeclare()
{
var managed = new[]
{
new McpServerConfig { Name = "Sql" },
new McpServerConfig { Name = "Docs" },
new McpServerConfig { Name = "Jira" },
};
var own = new[] { new McpServerConfig { Name = "docs" } };

var wanted = ManagedMcpServers.ReferencedBy(managed, own, ["FileSystem", "sql", "Docs"]);

Assert.Equal("Sql", Assert.Single(wanted).Name);
}
}
44 changes: 44 additions & 0 deletions tests/FuseraftCli.Tests/OrchestratorBuilderManagedMcpTests.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
using fuseraft.Cli;
using fuseraft.Core.Models;
using fuseraft.Core.Models.Config;
using fuseraft.Infrastructure.Mcp;
using fuseraft.Infrastructure.Plugins;
using Microsoft.Extensions.Logging.Abstractions;

namespace FuseraftCli.Tests;

public sealed class OrchestratorBuilderManagedMcpTests
{
[Fact]
public async Task UnreachableServer_IsRegisteredWithNoTools_SoTheAgentStillBuilds()
{
var config = new OrchestrationConfig
{
Agents = [new AgentConfig { Name = "Analyst", Plugins = ["Sql"] }],
};
// Port 1 on loopback refuses at once.
var managed = new[] { new McpServerConfig { Name = "Sql", Transport = "http", Url = "http://127.0.0.1:1/mcp", TransportMode = "streamable-http" } };
var registry = new PluginRegistry();
await using var manager = new McpSessionManager();

await OrchestratorBuilder.ConnectManagedMcpServersAsync(config, managed, manager, registry,
NullLogger.Instance, CancellationToken.None);

Assert.True(registry.TryGetAIFunctions("Sql", out var tools));
Assert.Empty(tools);
}

[Fact]
public async Task ServerNoAgentNames_IsNotConnected()
{
var config = new OrchestrationConfig { Agents = [new AgentConfig { Name = "Dev", Plugins = ["FileSystem"] }] };
var managed = new[] { new McpServerConfig { Name = "Sql", Transport = "http", Url = "http://127.0.0.1:1/mcp" } };
var registry = new PluginRegistry();
await using var manager = new McpSessionManager();

await OrchestratorBuilder.ConnectManagedMcpServersAsync(config, managed, manager, registry,
NullLogger.Instance, CancellationToken.None);

Assert.False(registry.TryGetAIFunctions("Sql", out _));
}
}
Loading
Loading