csharp-utcp

using Utcp.Core;
using Utcp.Core.Models;
using Utcp.Http;

var client = await UtcpClientImplementation.CreateAsync(config: new UtcpClientConfig
{
    ToolRepository = new Utcp.Core.Repositories.InMemToolRepository(),
    ToolSearchStrategy = new Utcp.Core.Search.TagAndDescriptionWordMatchStrategy(),
    ManualCallTemplates = new []
    {
        (CallTemplate)new HttpCallTemplate
        {
            CallTemplateType = "http",
            Name = "openlibrary",
            Method = "GET",
            Url = new Uri("https://openlibrary.org/works/OL45883W.json"),
        }
    }
});

var result = await client.CallToolAsync("openlibrary", new Dictionary<string, object?>());
Console.WriteLine(result);

MCP (Model Context Protocol)

Multi-server configuration with OAuth2 and HTTP SSE streaming:

using Utcp.Mcp;
using Utcp.Core.Models;

var mcpTemplate = new McpCallTemplate
{
    CallTemplateType = "mcp",
    Name = "mcp",
    Config = new McpConfig
    {
        McpServers = new Dictionary<string, McpServerConfig>
        {
            ["stdioServer"] = new() { Command = "my-mcp-server" },
            ["httpServer"] = new() { Url = "http://localhost:7400/mcp", Headers = new Dictionary<string,string>{{"X-Client","Utcp"}} },
        }
    },
    Auth = new OAuth2Auth { AuthType = "oauth2", TokenUrl = "http://localhost:7400/token", ClientId = "id", ClientSecret = "secret" }
};

var register = await client.RegisterManualAsync(mcpTemplate);
var mcpResult = await client.CallToolAsync("echo", new Dictionary<string, object?>{ ["message"] = "hi" });
await foreach (var chunk in client.CallToolStreamingAsync("echo", new Dictionary<string, object?>{ ["message"] = "hi" }))
{
    Console.WriteLine(chunk);
}

Variable substitution

Namespaced variables are computed by:

• Take the namespace and replace every _ with __ (double underscores)
• Append _ and the variable key

In other words: {namespace with underscores doubled}_{KEY}.

Examples:

• variableNamespace = "manual_openlibrary", key = "API_KEY" → manual__openlibrary_API_KEY
• variableNamespace = "ns_with_many_parts", key = "TOKEN" → ns__with__many__parts_TOKEN

Variables are resolved first from UtcpClientConfig.Variables using the namespaced key, then from environment variables using the same namespaced key. Both $VAR and ${VAR} forms in strings are supported.

using Utcp.Core.Substitution;

var substitutor = new DefaultVariableSubstitutor();
var cfg = new UtcpClientConfig { ToolRepository = repo, ToolSearchStrategy = search, Variables = new(){ ["manual__openlibrary_API_KEY"] = "123" } };
var substituted = substitutor.Substitute(
    new Dictionary<string, object?> { ["auth"] = new Dictionary<string, object?>{ ["token"] = "${API_KEY}" } },
    cfg,
    "manual_openlibrary"
);

OpenAPI conversion

You can register an OpenAPI spec by passing its URL as an HttpCallTemplate to RegisterManualAsync. The HTTP protocol automatically fetches and converts JSON OpenAPI documents into a UTCP manual at registration time.

Example (automatic conversion on register):

using Utcp.Http;

var client = await UtcpClientImplementation.CreateAsync(config: new UtcpClientConfig
{
    ToolRepository = new Utcp.Core.Repositories.InMemToolRepository(),
    ToolSearchStrategy = new Utcp.Core.Search.TagAndDescriptionWordMatchStrategy(),
});

await client.RegisterManualAsync(new HttpCallTemplate
{
    CallTemplateType = "http",
    Name = "petstore",
    Url = new Uri("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json"),
});

var tools = await client.SearchToolsAsync("pet store", 5);

End-to-end conversion using OpenApiToUtcpConverter (manual control):

using Utcp.Http.OpenApi;
using System.Net.Http;

// Load an OpenAPI document
var http = new HttpClient();
var specUrl = "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.yaml";
var yaml = await http.GetStringAsync(specUrl);

// Convert (reader supports JSON/YAML via Microsoft.OpenApi.Readers)
var converter = new OpenApiToUtcpConverter();
var manual = converter.ConvertFromString(yaml, specUrl);

// Register the converted tools
var cfg = new UtcpClientConfig
{
    ToolRepository = new Utcp.Core.Repositories.InMemToolRepository(),
    ToolSearchStrategy = new Utcp.Core.Search.TagAndDescriptionWordMatchStrategy(),
    ManualCallTemplates = Array.Empty<CallTemplate>()
};
var client = await UtcpClientImplementation.CreateAsync(config: cfg);
await client.RegisterManualAsync(new HttpCallTemplate { CallTemplateType = "http", Name = manual.Tools.First().ToolCallTemplate.Name, Url = new Uri("http://example") });

// Call one of the converted tools (operationId)
var tools = await client.SearchToolsAsync("pet store", 5);
var anyTool = tools.First();
var output = await client.CallToolAsync(anyTool.Name, new Dictionary<string, object?>());
Console.WriteLine(output);

See also tests/Utcp.Http.Tests/OpenApiConverterTests.cs for focused examples.

Samples

• samples/ClientSample – demonstrates setup, HTTP + MCP configuration
• samples/ServerSample – minimal ASP.NET API with UTCP discovery endpoint

Full examples with expected outputs

CLI

Run a local command and capture stdout/stderr:

using Utcp.Cli;

var client = await UtcpClientImplementation.CreateAsync(config: new UtcpClientConfig
{
    ToolRepository = new Utcp.Core.Repositories.InMemToolRepository(),
    ToolSearchStrategy = new Utcp.Core.Search.TagAndDescriptionWordMatchStrategy(),
});

// Register a CLI tool (e.g., echo)
var template = new CliCallTemplate { CallTemplateType = "cli", Name = "local", Command = "/bin/echo" };
await client.RegisterManualAsync(template);

// Call it
var resp = await client.CallToolAsync("local", new Dictionary<string, object?> { ["args"] = new [] { "hello" } });
Console.WriteLine(resp); // expected: "hello\n"

Text

Read a file fully and as a stream of chunks:

using Utcp.Text;

var text = new TextCallTemplate { CallTemplateType = "text", Name = "docs", FilePath = "README.md" };
await client.RegisterManualAsync(text);

var all = await client.CallToolAsync("docs", new Dictionary<string, object?>());
Console.WriteLine(((string)all!).Length > 0); // expected: True

var streamed = client.CallToolStreamingAsync("docs", new Dictionary<string, object?>());
await foreach (var chunk in streamed)
{
    Console.WriteLine(chunk); // expected: lines (or chunks if ChunkSizeBytes set)
}

MCP

Echo via MCP HTTP and stdio with result shaping:

using Utcp.Mcp;

var mcp = new McpCallTemplate
{
    CallTemplateType = "mcp",
    Name = "mcp",
    Config = new McpConfig
    {
        McpServers = new Dictionary<string, McpServerConfig>
        {
            ["http"] = new() { Url = "http://localhost:7400/mcp" },
            ["stdio"] = new() { Command = "my-mcp-server" },
        }
    }
};
await client.RegisterManualAsync(mcp);

var r = await client.CallToolAsync("echo", new Dictionary<string, object?> { ["message"] = "test" });
Console.WriteLine(r); // expected: { reply = "you said: test" } or similar shaped object/string

await foreach (var s in client.CallToolStreamingAsync("echo", new Dictionary<string, object?> { ["message"] = "test" }))
{
    Console.WriteLine(s); // expected: streamed chunks/events if server uses SSE
}

Protocol registration

Protocols are registered in Utcp.Core.Protocols.ProtocolRegistry. Custom protocols can be added at runtime:

using Utcp.Core.Protocols;
ProtocolRegistry.Register("my-protocol", new MyProtocol());

Post-processing

Use post-processors to shape results. A simple filter example:

using Utcp.Core.PostProcessing;
var cfg = new UtcpClientConfig { ToolRepository = repo, ToolSearchStrategy = search, PostProcessing = new [] { new FilterDictPostProcessor(new []{"allowed"}) } };

Tool search

Default search TagAndDescriptionWordMatchStrategy ranks tools by tag hits and description term overlap:

var results = await client.SearchToolsAsync("weather forecast", limit: 5);

Concurrency and thread safety

InMemToolRepository uses async synchronization to support concurrent reads/writes safely. All client operations are async and accept CancellationToken.

Error handling

• Rich argument and state validation with specific exceptions
• HTTP paths use EnsureSuccessStatusCode and propagate details
• MCP stdio paths surface process start and JSON parsing errors

Parity with Python

• Data models map 1:1 (Auth, CallTemplate, Tool, UtcpManual, UtcpClientConfig, RegisterManualResult)
• MCP mirrors registration, calling, streaming, OAuth2 token flows, and result shaping
• OpenAPI converter maps security schemes and schemas similarly; see tests for parity
• Variable substitution supports namespacing and env resolution

CI & Packaging

• GitHub Actions builds/tests/packs on Windows, Linux, macOS (.github/workflows/build.yml)
• NuGet metadata via Directory.Build.props (packages per project)

License

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0). See LICENSE for details.