https://github.com/diomonogatari/mcp-server-factory
Provides an in-memory test harness for .NET MCP servers, similar to WebApplicationFactory<T> for Web APIs.
https://github.com/diomonogatari/mcp-server-factory
dotnet integration-testing mcp mcp-server model-context-protocol nuget test-harness testing
Last synced: 10 days ago
JSON representation
Provides an in-memory test harness for .NET MCP servers, similar to WebApplicationFactory<T> for Web APIs.
- Host: GitHub
- URL: https://github.com/diomonogatari/mcp-server-factory
- Owner: diomonogatari
- License: mit
- Created: 2026-02-13T12:48:25.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-13T17:27:39.000Z (4 months ago)
- Last Synced: 2026-02-14T00:00:15.068Z (4 months ago)
- Topics: dotnet, integration-testing, mcp, mcp-server, model-context-protocol, nuget, test-harness, testing
- Language: C#
- Homepage:
- Size: 35.2 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# McpServerFactory
[](https://www.nuget.org/packages/McpServerFactory)
[](https://www.nuget.org/packages/McpServerFactory)
[](https://github.com/diomonogatari/mcp-server-factory/actions/workflows/ci.yml)
[](https://codecov.io/gh/diomonogatari/mcp-server-factory)
[](https://github.com/diomonogatari/mcp-server-factory/blob/main/LICENSE)
In-memory integration **test harness** for .NET Model Context Protocol (MCP) servers.
**Your MCP server's real contract isn't with your code — it's with the model.** The tool names
and JSON schemas, the descriptions the agent reads, the error text it sees, the sampling
round-trips it triggers. McpServerFactory boots your server **in-process** and connects a *real*
`McpClient` over in-memory pipes, so you can assert on that contract in a plain unit test:
breakpoints on both sides, dependencies swapped for fakes, no subprocess, no ports, no Docker,
no live model.
Think `WebApplicationFactory` — but for MCP.
```csharp
// one process: a real client ⇄ your real server, over in-memory pipes
McpTestClient client = await factory.CreateTestClientAsync();
Assert.Equal("hello", await client.CallToolForTextAsync(
"echo", new Dictionary { ["message"] = "hello" }));
```
## What you can actually verify
- A tool **exists**, and its input schema/description are what you think (`GetToolAsync`, `McpAssert.ToolExistsAsync`).
- A tool returns the right **text** or **typed JSON** (`CallToolForTextAsync`, `CallToolForJsonAsync`).
- A tool **fails the way you intend** — `IsError` results throw instead of quietly passing a test (`CallToolExpectingErrorAsync`).
- **Server-initiated sampling** does the right thing, answered by a fake model you control (`FakeSamplingHandler`).
- The expected **notifications** fire — logging, progress, list-changed (`NotificationRecorder`).
- Your **real DI graph** wires up, with the slow/external bits mocked (`configureServices` / `ConfigureHost`).
> **Scope:** by default the factory hosts the **tool/resource/prompt classes you register**
> over an in-memory transport. It does not auto-run your server's `Program.cs`. To exercise
> your real composition root (configuration, options, hosted services), use the
> [`ConfigureHost`](#testing-your-real-composition-root) hook.
## Installation
```bash
dotnet add package McpServerFactory
```
## Template-based scaffolding
Install the template pack to bootstrap an MCP integration test project:
```bash
dotnet new install McpServerFactory.Templates
dotnet new mcp-itest -n MyServer.Tests
```
The `mcp-itest` template accepts `--McpServerFactoryVersion` to override the
`McpServerFactory` package version; the default tracks the version of the
template pack you installed.
## Quick start
```csharp
using McpServerFactory.Testing;
using Microsoft.Extensions.DependencyInjection;
using ModelContextProtocol.Server;
using Xunit;
[McpServerToolType]
public sealed class EchoTools
{
[McpServerTool(Name = "echo")]
public string Echo(string message) => message;
}
public class EchoTests
{
[Fact]
public async Task Echo_ReturnsInput()
{
await using McpServerIntegrationFactory factory = new(
configureMcpServer: builder => builder.WithTools());
// The factory owns the client; you do not dispose it yourself.
McpTestClient client = await factory.CreateTestClientAsync();
string text = await client.CallToolForTextAsync(
"echo",
new Dictionary { ["message"] = "hello" });
Assert.Equal("hello", text);
}
}
```
Using xUnit? The companion [`McpServerFactory.Xunit`](#boot-once-per-class-with-xunit) package
boots the server once per test class via `IClassFixture`.
## Why use this library
- **Fast and in-process** — no subprocess, ports, Docker, or stdio plumbing.
- **Real protocol flow** — a real `McpClient` over a real (in-memory) transport: `tools/list`,
`tools/call`, resources, prompts, and server-initiated sampling all run end-to-end.
- **Easy dependency overrides** — substitute services via `configureServices`.
- **Debuggable** — set breakpoints on both sides; it's all one process.
- **Framework-agnostic core** — works with xUnit, NUnit, and MSTest.
## How it compares
| Approach | Speed | No process/port | Breakpoints both sides | DI substitution | Exercises real `Program.cs` |
| --- | --- | --- | --- | --- | --- |
| **McpServerFactory** | fast | ✅ | ✅ | ✅ | via `ConfigureHost` |
| stdio subprocess + `McpClient` | slow | ❌ | server only | ❌ | ✅ |
| raw pipes + `StreamClientTransport` | fast | ✅ | ✅ | ✅ (manual) | ❌ |
| MCP Inspector (manual) | n/a | ❌ | ❌ | ❌ | ✅ |
**Use it when** you want fast, automated, in-process tests of your tools/resources/prompts and
handlers with dependency substitution. **Reach for a stdio subprocess instead** when you must
validate the actual published binary, its real transport configuration, or process-level startup.
## Used in the wild
[`stash-mcp`](https://github.com/diomonogatari/stash-mcp) — a 40-tool MCP server for Bitbucket
Server — tests its tools with McpServerFactory. It subclasses the factory, registers its real tool
assembly, and swaps the live Bitbucket client, cache, and resilience services for fakes, so the
whole tool surface is exercised in-process without ever touching a Bitbucket instance:
```csharp
public sealed class StashMcpTestFactory(Action? configureMocks = null)
: McpServerFactory.Testing.McpServerFactory
{
public IBitbucketClient BitbucketClient { get; } = Substitute.For();
protected override void ConfigureMcpServer(IMcpServerBuilder builder) =>
builder.WithToolsFromAssembly(typeof(ProjectTools).Assembly);
protected override void ConfigureServices(IServiceCollection services) =>
services.AddSingleton(BitbucketClient); // ...plus cache, settings, resilience fakes
}
```
## Testing tools, resources, prompts, and structured output
`McpTestClient` wraps a real `McpClient` with test-shaped helpers (all pagination-safe):
```csharp
McpTestClient client = await factory.CreateTestClientAsync();
string[] tools = await client.GetToolNamesAsync();
string greeting = await client.CallToolForTextAsync("greet");
MyDto result = await client.CallToolForJsonAsync("compute", args); // structured or JSON-text
string contents = await client.ReadResourceTextAsync("resource://config");
string[] prompts = await client.GetPromptNamesAsync();
```
Tool failures (`IsError`) no longer pass silently: `CallToolForTextAsync` throws
`McpToolCallException`, and `CallToolExpectingErrorAsync` asserts the negative path. The
framework-agnostic `McpAssert` helpers (`ToolExistsAsync`, `Succeeded`, `IsError`, `TextEquals`)
work under any test framework.
## Testing server-initiated sampling
If your server calls the model (server-initiated sampling), wire a deterministic fake so tests
never need a real LLM:
```csharp
FakeSamplingHandler sampling = FakeSamplingHandler.Returning("42");
await using McpServerIntegrationFactory factory = new(
configureMcpServer: builder => builder.WithTools(),
options: new McpServerFactoryOptions
{
ConfigureClient = client => client.UseSamplingHandler(sampling),
});
McpTestClient client = await factory.CreateTestClientAsync();
string answer = await client.CallToolForTextAsync(
"ask", new Dictionary { ["question"] = "..." });
Assert.Single(sampling.ReceivedRequests); // assert what the server asked the model
```
`ConfigureClient` exposes the full `McpClientOptions`, so you can also declare elicitation, roots,
or notification handlers. Capture server-sent notifications (logging, progress, list-changed) with
`NotificationRecorder.Attach(client.Inner)` and `await recorder.WaitForMethodAsync(...)`.
## Testing your real composition root
By default the factory hosts the classes you register. To exercise the same registration your
server's `Program.cs` uses — real configuration binding, options, and hosted services — supply
`ConfigureHost`. The factory always owns the MCP server registration and the in-memory transport,
so configure everything **except** the transport; register tools/resources/prompts via
`configureMcpServer`:
```csharp
await using McpServerIntegrationFactory factory = new(
configureMcpServer: builder => builder.WithTools(),
options: new McpServerFactoryOptions
{
ConfigureHost = builder =>
{
builder.Configuration.AddInMemoryCollection(/* test config */);
builder.Services.AddMyDomainServices(); // your real registration, minus the transport
},
});
```
## Boot once per class with xUnit
Install the companion package and derive a fixture:
```bash
dotnet add package McpServerFactory.Xunit
```
```csharp
using McpServerFactory.Testing.Xunit;
public sealed class EchoFixture : McpServerFixture
{
protected override void ConfigureMcpServer(IMcpServerBuilder builder) => builder.WithTools();
}
public sealed class EchoTests(EchoFixture fixture) : IClassFixture
{
[Fact]
public async Task Echoes() =>
Assert.Equal("hi", await fixture.TestClient.CallToolForTextAsync(
"echo", new Dictionary { ["message"] = "hi" }));
}
```
## Behavioral guarantees
- `CreateClientAsync` / `CreateTestClientAsync` are thread-safe and idempotent per factory instance.
- Concurrent calls return the same connected client; **the factory owns and disposes it** — you do
not need to dispose the returned client yourself.
- Startup failures do not leak the temporary host instance or its pipes.
- `DisposeAsync` is safe to call multiple times and is bounded by `ShutdownTimeout` (it will not hang
teardown).
- `CreateClientAsync` throws `ObjectDisposedException` after disposal.
- Need independent server instances (isolation)? Create multiple factory instances — each owns its
own host. A single factory exposes one in-memory session.
## Compatibility and support
- Target frameworks: `net8.0`, `net9.0`, `net10.0`.
- MCP SDK dependency: `ModelContextProtocol` `1.4.0`.
- Compatibility promise: each package release is validated against the pinned MCP SDK version on all
target frameworks.
- Upgrade policy: MCP SDK bumps are explicit and called out in [CHANGELOG.md](CHANGELOG.md). Now that
the MCP SDK is stable, `McpServerFactory` follows [Semantic Versioning](https://semver.org/): an MCP
SDK change that breaks this library's public surface ships as a new major version.
| McpServerFactory | MCP SDK | Target frameworks |
| --- | --- | --- |
| 1.0.x | 1.4.0 | net8.0, net9.0, net10.0 |
| 0.2.x | 0.4.0-preview.3 | net8.0, net9.0, net10.0 |
| 0.1.x | 0.4.0-preview.3 | net10.0 |
## API overview
- `McpServerFactory` / `McpServerIntegrationFactory`
- Start an in-process server host; create a connected client via `CreateClientAsync()` or a
factory-owned wrapper via `CreateTestClientAsync()`.
- Expose `Services` for DI validation after startup.
- `McpServerFactoryOptions`
- Configure server identity, timeouts, instructions, logging, the client (`ConfigureClient`), and
the host composition root (`ConfigureHost`).
- `McpTestClient`
- Wrapper with tool, resource, prompt, structured-output, and server-metadata helpers.
- `FakeSamplingHandler` / `NotificationRecorder` / `McpAssert`
- Deterministic sampling, notification capture, and framework-agnostic assertions.
- `McpServerFactory.Xunit` (separate package)
- `McpServerFixture` for `IClassFixture` boot-once-per-class.
## Logging in test output
By default, host logging providers are suppressed to keep test output clean.
To enable custom logging during tests:
```csharp
using Microsoft.Extensions.Logging;
var options = new McpServerFactoryOptions
{
SuppressHostLogging = false,
ConfigureLogging = logging => logging.SetMinimumLevel(LogLevel.Debug),
};
```
## Release notes
See [CHANGELOG.md](CHANGELOG.md) for release history and upcoming changes.
## Samples
- Minimal runnable sample: [`samples/MinimalSmoke`](samples/MinimalSmoke)
## Repository layout
- `src/McpServerFactory` — reusable factory library (framework-agnostic core).
- `src/McpServerFactory.Xunit` — xUnit fixtures (`McpServerFixture`).
- `tests/McpServerFactory.Tests` — unit/integration-focused library tests.
- `templates/McpServerFactory.Templates` — `dotnet new` template pack.
- `samples/MinimalSmoke` — runnable sample console app.
- `docs` — architecture notes and usage guidance.