Voltaic.JsonRpc

Voltaic

Modern, lightweight JSON-RPC 2.0 and MCP implementations for .NET 8.0

Voltaic provides client and server implementations for JSON-RPC 2.0 and the Model Context Protocol (MCP). Whether you're building microservices, AI integrations, or distributed systems—Voltaic gives you the tools to communicate clearly and reliably.

---

What's Inside

Voltaic consists of two focused libraries, available separately or together:

Voltaic.JsonRpc

A complete JSON-RPC 2.0 implementation with TCP-based client and server. Perfect for building RPC-based APIs, microservices, and distributed applications.

Features:

• Full JSON-RPC 2.0 specification compliance
• TCP-based transport with LSP-style message framing (Content-Length headers)
• Async/await throughout for modern .NET performance
• Support for requests, responses, notifications, and broadcasts
• Type-safe method registration and invocation
• Connection management with graceful shutdown
• Thread-safe concurrent request handling

Voltaic.Mcp

Client and server implementations for Anthropic's Model Context Protocol (MCP), supporting multiple transport options.

Features:

• Stdio transport: Subprocess-based MCP servers (standard MCP pattern)
• TCP transport: Network-based MCP communication with LSP-style framing
• HTTP transport: HTTP-based MCP communication with Server-Sent Events (SSE) for notifications
• WebSocket transport: Full-duplex bidirectional communication
• Implements JSON-RPC 2.0 protocol across all transports
• Process lifecycle management for subprocess servers
• Event-driven notification handling
• Compatible with MCP server ecosystem

Important

Voltaic currently does not support authorization, which is listed as OPTIONAL in the spec.

---

Who Is This For?

Voltaic is designed for developers who need:

• Microservice Communication: Build services that talk to each other using a standard RPC protocol
• AI Tool Integration: Connect to MCP servers for AI assistant integrations (Claude, etc.)
• Custom RPC APIs: Implement your own remote procedure call interfaces
• Subprocess Orchestration: Launch and communicate with child processes using stdio transport
• Language Server Protocols: Build LSP-style applications that use Content-Length framing
• Real-time Systems: Low-latency RPC communication over TCP sockets
• Web-based Integration: HTTP and WebSocket transports for browser-compatible communication
• Flexible Transport Options: Choose the right transport for your architecture

If you're building .NET applications that need structured, bidirectional communication, Voltaic has you covered.

---

Getting Started

Installation

# Install the full Voltaic package (includes both JsonRpc and Mcp)
dotnet add package Voltaic

Quick Start: JSON-RPC Server (TCP)

using System.Text.Json;
using Voltaic.JsonRpc;

JsonRpcServer server = new JsonRpcServer(8080);

// Register custom methods
server.RegisterMethod("greet", (JsonElement? args) =>
{
    string? name = args?.TryGetProperty("name", out JsonElement nameEl) == true
        ? nameEl.GetString()
        : "World";
    return $"Hello, {name}!";
});

// Start the server
await server.StartAsync();
Console.WriteLine("Server running on port 8080");

// Keep it running
await Task.Delay(Timeout.Infinite, server.TokenSource.Token);

Quick Start: JSON-RPC Client (TCP)

using Voltaic.JsonRpc;

JsonRpcClient client = new JsonRpcClient();
await client.ConnectAsync("localhost", 8080);

// Call a method with typed response
JsonRpcResponse response = await client.CallAsync("greet", new { name = "Developer" });
Console.WriteLine(response.Result); // "Hello, Developer!"

// Send a notification (no response expected)
await client.NotifyAsync("logEvent", new { level = "info", message = "User logged in" });

Quick Start: MCP Server (stdio)

using System.Text.Json;
using Voltaic.Mcp;

McpServer server = new McpServer();

// Register MCP methods
server.RegisterMethod("tools/list", (JsonElement? args) =>
{
    return new
    {
        tools = new[]
        {
            new { name = "calculator", description = "Performs calculations" }
        }
    };
});

// Run the server (reads from stdin, writes to stdout)
await server.RunAsync();

Quick Start: MCP Client (stdio)

using Voltaic.Mcp;

McpClient client = new McpClient();

// Launch an MCP server as a subprocess
await client.LaunchServerAsync("dotnet", new[] { "run", "--project", "MyMcpServer" });

// Call methods on the server
JsonRpcResponse response = await client.CallAsync("tools/list");
Console.WriteLine(response.Result);

Quick Start: MCP Server (TCP)

using System.Text.Json;
using Voltaic.Mcp;

McpTcpServer server = new McpTcpServer(8080);

// Register MCP methods
server.RegisterMethod("tools/list", (JsonElement? args) =>
{
    return new
    {
        tools = new[]
        {
            new { name = "calculator", description = "Performs calculations" }
        }
    };
});

// Start the server
await server.StartAsync();
Console.WriteLine("MCP server running on port 8080");
await Task.Delay(Timeout.Infinite, server.TokenSource.Token);

Quick Start: MCP Client (TCP)

using Voltaic.Mcp;

McpTcpClient client = new McpTcpClient();

// Connect to the TCP server
await client.ConnectAsync("localhost", 8080);

// Call methods on the server
JsonRpcResponse response = await client.CallAsync("tools/list");
Console.WriteLine(response.Result);

Quick Start: MCP Server (HTTP)

using System.Text.Json;
using Voltaic.Mcp;

McpHttpServer server = new McpHttpServer(8080);

// Register MCP methods
server.RegisterMethod("tools/list", (JsonElement? args) =>
{
    return new
    {
        tools = new[]
        {
            new { name = "calculator", description = "Performs calculations" }
        }
    };
});

// Start the server
await server.StartAsync();
Console.WriteLine("MCP HTTP server running on http://localhost:8080");
await Task.Delay(Timeout.Infinite, server.TokenSource.Token);

Quick Start: MCP Client (HTTP)

using Voltaic.Mcp;

McpHttpClient client = new McpHttpClient();

// Connect to the HTTP server
await client.ConnectAsync("http://localhost:8080");

// Start SSE connection for server notifications
await client.StartSseAsync();

// Call methods on the server
object? result = await client.CallAsync<object>("tools/list");
Console.WriteLine(result);

Quick Start: MCP Server (WebSocket)

using System.Text.Json;
using Voltaic.Mcp;

McpWebsocketsServer server = new McpWebsocketsServer(8080);

// Register MCP methods
server.RegisterMethod("tools/list", (JsonElement? args) =>
{
    return new
    {
        tools = new[]
        {
            new { name = "calculator", description = "Performs calculations" }
        }
    };
});

// Start the server
await server.StartAsync();
Console.WriteLine("MCP WebSocket server running on ws://localhost:8080");
await Task.Delay(Timeout.Infinite, server.TokenSource.Token);

Quick Start: MCP Client (WebSocket)

using Voltaic.Mcp;

McpWebsocketsClient client = new McpWebsocketsClient();

// Connect to the WebSocket server
await client.ConnectAsync("ws://localhost:8080/mcp");

// Call methods on the server
object? result = await client.CallAsync<object>("tools/list");
Console.WriteLine(result);

// Send a notification
await client.NotifyAsync("log", new { message = "Hello from WebSocket client" });

---

When NOT to Use This

Voltaic might not be the right fit if you need:

• gRPC Features: If you need streaming, advanced load balancing, or language-agnostic service definitions, use gRPC
• REST Conventions: If you need resource-oriented APIs with standard HTTP verbs, use ASP.NET Core Web APIs
• Legacy .NET: Voltaic targets .NET 8.0+; older frameworks aren't supported
• High-level Abstractions: Voltaic is a protocol library, not a framework—you'll write your own business logic

---

Documentation

Voltaic.JsonRpc

Server API:

• JsonRpcServer(int port) - Create a server listening on the specified port
• RegisterMethod(string name, Func<JsonElement?, object> handler) - Register an RPC method
• Task StartAsync() - Start accepting connections
• Task BroadcastNotificationAsync(string method, object? parameters) - Send notifications to all clients
• void Stop() - Gracefully shut down the server

Client API:

• Task<bool> ConnectAsync(string host, int port) - Connect to a server
• Task<JsonRpcResponse> CallAsync(string method, object? parameters) - Make an RPC call and await response
• Task NotifyAsync(string method, object? parameters) - Send a notification (no response)
• NotificationReceived event - Handle notifications from the server
• void Disconnect() - Close the connection

Voltaic.Mcp

McpServer (stdio):

• void RegisterMethod(string name, Func<JsonElement?, object> handler) - Register an MCP method
• Task RunAsync(CancellationToken token = default) - Run the server (blocks until stdin closes)

McpClient (stdio):

• Task<bool> LaunchServerAsync(string executable, string[] args) - Launch subprocess server
• Task<JsonRpcResponse> CallAsync(string method, object? parameters) - Call server method
• NotificationReceived event - Handle server notifications

TCP Variants:

• McpTcpServer(int port) - TCP-based MCP server
• McpTcpClient() - TCP-based MCP client
• Same API as JsonRpcServer/JsonRpcClient

HTTP Variants:

• McpHttpServer(int port) - HTTP-based MCP server with SSE support
• McpHttpClient() - HTTP-based MCP client
• Additional methods:
  • Task<bool> ConnectAsync(string baseUrl) - Connect to HTTP server
  • Task<bool> StartSseAsync() - Start Server-Sent Events connection for notifications
  • void StopSse() - Stop SSE connection
  • string? SessionId property - Get session ID assigned by server

WebSocket Variants:

• McpWebsocketsServer(int port) - WebSocket-based MCP server
• McpWebsocketsClient() - WebSocket-based MCP client
• Same API as JsonRpcClient with bidirectional messaging

---

Examples

Check out the src/Test.* projects for working examples:

• Test.JsonRpcServer / Test.JsonRpcClient: Interactive JSON-RPC demos over TCP
• Test.McpServer / Test.McpClient: MCP stdio examples
• Test.McpHttpServer / Test.McpHttpClient: MCP HTTP with SSE examples
• Test.McpWebsocketsServer / Test.McpWebsocketsClient: MCP WebSocket examples
• Test.Automated: Comprehensive test suite showing various usage patterns

Run examples:

# JSON-RPC Server (TCP)
dotnet run --project src/Test.JsonRpcServer/Test.JsonRpcServer.csproj -- 8080

# JSON-RPC Client (TCP)
dotnet run --project src/Test.JsonRpcClient/Test.JsonRpcClient.csproj -- 8080

# MCP Stdio Client (launches server subprocess)
dotnet run --project src/Test.McpClient/Test.McpClient.csproj

# MCP HTTP Server
dotnet run --project src/Test.McpHttpServer/Test.McpHttpServer.csproj -- 8080

# MCP HTTP Client
dotnet run --project src/Test.McpHttpClient/Test.McpHttpClient.csproj -- 8080

# MCP WebSocket Server
dotnet run --project src/Test.McpWebsocketsServer/Test.McpWebsocketsServer.csproj -- 8080

# MCP WebSocket Client
dotnet run --project src/Test.McpWebsocketsClient/Test.McpWebsocketsClient.csproj -- 8080

---

Building

# Build everything
dotnet build src/Voltaic.sln

# Build specific library
dotnet build src/Voltaic.JsonRpc/Voltaic.JsonRpc.csproj
dotnet build src/Voltaic.Mcp/Voltaic.Mcp.csproj

# Run automated tests (all transports)
dotnet run --project src/Test.Automated/Test.Automated.csproj

# Run automated tests for specific transport
dotnet run --project src/Test.Automated/Test.Automated.csproj -- -stdio
dotnet run --project src/Test.Automated/Test.Automated.csproj -- -tcp
dotnet run --project src/Test.Automated/Test.Automated.csproj -- -http
dotnet run --project src/Test.Automated/Test.Automated.csproj -- -ws

# Run automated tests for multiple transports
dotnet run --project src/Test.Automated/Test.Automated.csproj -- -tcp -http -ws

---

License

Voltaic is released under the MIT License. Use it freely in your projects, commercial or otherwise.

---

Support

Need help or found a bug?

• Issues: Report bugs or request features at github.com/jchristn/voltaic/issues
• Discussions: Ask questions and share ideas at github.com/jchristn/voltaic/discussions