GopherMcp 0.1.2.3

GopherMcp C# SDK

C# SDK for GopherMcp, providing AI agent orchestration with native C++ performance through P/Invoke bindings.

Features

• .NET Standard 2.0 compatibility (works with .NET Core 2.0+, .NET 5+, .NET Framework 4.6.1+)
• P/Invoke FFI bindings to native gopher-orch library
• GopherAgent class with builder pattern configuration
• IDisposable support for automatic resource cleanup
• Typed exceptions (AgentException, ApiKeyException, ConnectionException, TimeoutException)
• OAuth 2.0 authentication support with RFC 8414/9728 metadata types
• xUnit tests

Installation

NuGet Package Manager

Install-Package GopherMcp

.NET CLI

dotnet add package GopherMcp

PackageReference

<PackageReference Include="GopherMcp" Version="0.1.2.2" />

Requirements

• .NET SDK 6.0 or later (for building)
• Native gopher-orch library (see Building)

Quick Start

Basic Usage

using GopherMcp;

// Create an agent with API key
using var agent = GopherAgent.Create(
    GopherAgentConfig.CreateBuilder()
        .WithProvider("AnthropicProvider")
        .WithModel("claude-3-haiku-20240307")
        .WithApiKey("your-api-key")
        .Build()
);

// Run a query
string answer = agent.Run("What time is it in Tokyo?");
Console.WriteLine(answer);

Using JSON Server Configuration

using GopherMcp;

string serverConfig = @"{
    ""succeeded"": true,
    ""code"": 200000000,
    ""message"": ""success"",
    ""data"": {
        ""servers"": [
            {
                ""version"": ""2025-01-09"",
                ""serverId"": ""1"",
                ""name"": ""server1"",
                ""transport"": ""http_sse"",
                ""config"": {""url"": ""http://127.0.0.1:3001/mcp"", ""headers"": {}},
                ""connectTimeout"": 5000,
                ""requestTimeout"": 30000
            }
        ]
    }
}";

using var agent = GopherAgent.CreateWithServerConfig(
    "AnthropicProvider",
    "claude-3-haiku-20240307",
    serverConfig
);

string answer = agent.Run("What tools are available?");
Console.WriteLine(answer);

Authentication Support

The SDK includes OAuth 2.0 types for building authenticated MCP servers and clients.

AuthContext

Authentication context for holding user/token information:

using GopherMcp.Auth;

// Check if user has required scope
if (authContext.IsAuthenticated && authContext.HasScope("weather:read"))
{
    // Allow access to weather tools
}

// Create anonymous context for development
var devContext = AuthContext.Anonymous("weather:read weather:write");

OAuth 2.0 Metadata Types

RFC-compliant metadata types for OAuth discovery:

using GopherMcp.Auth.OAuth;

// RFC 8414 - Authorization Server Metadata
var authServerMeta = new AuthorizationServerMetadata
{
    Issuer = "https://auth.example.com",
    AuthorizationEndpoint = "https://auth.example.com/oauth/authorize",
    TokenEndpoint = "https://auth.example.com/oauth/token",
    ScopesSupported = new[] { "weather:read", "weather:write" },
    ResponseTypesSupported = new[] { "code" },
    GrantTypesSupported = new[] { "authorization_code" },
    CodeChallengeMethodsSupported = new[] { "S256" }
};

// RFC 9728 - Protected Resource Metadata
var resourceMeta = new ProtectedResourceMetadata
{
    Resource = "https://api.example.com",
    AuthorizationServers = new[] { "https://auth.example.com" },
    ScopesSupported = new[] { "weather:read", "weather:write" },
    BearerMethodsSupported = new[] { "header" }
};

API Reference

GopherAgent

Main entry point for agent operations.

// Create with config
var agent = GopherAgent.Create(config);

// Create with API key
var agent = GopherAgent.Create(provider, model, apiKey);

// Create with server config
var agent = GopherAgent.CreateWithServerConfig(provider, model, serverConfig);

// Run query
string response = agent.Run("your query");

// Run with timeout
string response = agent.Run("your query", timeoutMs: 30000);

// Run with detailed result
AgentResult result = agent.RunDetailed("your query");

// Cleanup
agent.Dispose();

GopherAgentConfig

Configuration builder for agent creation.

var config = GopherAgentConfig.CreateBuilder()
    .WithProvider("AnthropicProvider")
    .WithModel("claude-3-haiku-20240307")
    .WithApiKey("your-api-key")      // OR
    .WithServerConfig(jsonConfig)     // Use one or the other
    .Build();

AgentResult

Detailed result from query execution.

AgentResult result = agent.RunDetailed("query");

Console.WriteLine(result.Response);
Console.WriteLine(result.Status);        // Success, Error, Timeout
Console.WriteLine(result.IsSuccess);
Console.WriteLine(result.IterationCount);
Console.WriteLine(result.TokensUsed);

Exceptions

• AgentException - Base exception for agent operations
• ApiKeyException - API key related errors
• ConnectionException - Connection related errors
• TimeoutException - Timeout related errors

Building

# Build everything (native library + C# SDK)
./build.sh

# Or build manually:
dotnet build
dotnet test

Code Formatting

# Format code
dotnet format

# Check formatting without making changes
dotnet format --verify-no-changes

Examples

The examples/ directory contains runnable examples:

JSON Server Config Example

# Run the JSON server config example
./examples/client_example_json_run.sh

This starts two MCP servers and runs a client that queries them.

Auth MCP Server Example

A complete OAuth-protected MCP server implementation:

cd examples/auth/AuthMcpServer
dotnet run

Features:

• OAuth 2.0 discovery endpoints (.well-known/oauth-*)
• JWT token validation with scope-based access control
• MCP protocol support with weather tools
• CORS middleware for browser clients
• Development mode with auth disabled

Project Structure

gopher-mcp-csharp/
├── GopherMcp.sln              # Solution file
├── build.sh                   # Build script
├── src/
│   └── GopherMcp/             # Main library
│       ├── GopherMcp.csproj
│       ├── GopherAgent.cs
│       ├── GopherAgentConfig.cs
│       ├── AgentResult.cs
│       ├── Auth/
│       │   ├── AuthContext.cs
│       │   └── OAuth/
│       │       ├── AuthorizationServerMetadata.cs
│       │       ├── ProtectedResourceMetadata.cs
│       │       ├── ClientRegistrationResponse.cs
│       │       └── OpenIdConfiguration.cs
│       ├── Errors/
│       │   ├── AgentException.cs
│       │   ├── ApiKeyException.cs
│       │   ├── ConnectionException.cs
│       │   └── TimeoutException.cs
│       └── Ffi/
│           └── GopherMcpLibrary.cs
├── tests/
│   └── GopherMcp.Tests/       # Unit tests
├── examples/
│   ├── client_example_json_run.sh
│   ├── ClientExampleJson/
│   ├── auth/                  # Auth MCP server example
│   │   ├── AuthMcpServer/
│   │   └── AuthMcpServer.Tests/
│   ├── server3001/
│   └── server3002/
├── third_party/
│   └── gopher-orch/           # Native library (git submodule)
└── native/                    # Built native libraries (generated)

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright 2024 Gopher Security

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.