GnOuGo.Mcp.Core 0.20.0

GnOuGo.Mcp.Core

GnOuGo-owned MCP servers use stable ModelContextProtocol 2.2.0 and leave protocol selection unpinned. The SDK prefers discovery-first 2026-07-28 (GnOuGoMcpProtocol.PreferredRevision) and accepts stable 2025-11-25 initialization as a compatibility fallback. RequiredRevision remains an obsolete source-compatible alias for the preferred revision.

Shared helpers for GnOuGo MCP servers.

Artifact metadata contract

MCP tools can describe reusable, externally materialized artifacts through tools/list metadata at _meta.gnougo.artifacts. Version 1 supports produces entries with kind, structured-output instance pointer, and mode: materialize, plus consumes entries with kind, input instance pointer, and required. McpArtifactContractParser validates those pointers against the advertised input/output schemas. workspace.directory is the standard kind for a validated workspace-relative working directory.

The metadata is planning information, not authorization. Producing and consuming MCP tools must still validate paths and policies at execution time.

Capability composition metadata

High-level tools can advertise _meta.gnougo.composition version 1 with kind: complete_operation and an encapsulates array of same-server { kind, method } capabilities. McpCapabilityCompositionParser validates the bounded contract. Flow consumers use it to prefer a complete wrapper over its start/analyse/finish primitives and prevent redundant mixed-level plans. The metadata describes orchestration semantics only; it does not grant tool authorization.

MCP protocol compatibility

The library targets the stable C# MCP SDK 2.2.0 and is shared by both MCP 2026-07-28 servers and down-level connections negotiated by the SDK. It does not add Tasks, MCP Apps, Roots, Sampling, or MCP Logging dependencies.

Composed HTTP tool groups

McpServerToolGroupAttribute is an AOT-safe class-level marker for hosts that compose several independently packaged tool sets into one stateless HTTP transport. Each MCP package marks its tool classes with its logical server name. A composing host can read that metadata in the SDK's request-local ConfigureSessionOptions callback and replace McpServerOptions.ToolCollection with the matching group.

[McpServerToolType]
[McpServerToolGroup("GnOuGo.Example.Mcp")]
public sealed class ExampleTools
{
    // MCP tools
}

The marker only declares group membership. Route mapping, exact server identity, and fail-closed selection remain the composing host's responsibility.

Build

dotnet build src/GnOuGo.Mcp.Core/GnOuGo.Mcp.Core.csproj

Test

dotnet test tests/GnOuGo.Mcp.Core.Tests/GnOuGo.Mcp.Core.Tests.csproj

Usage

Register the GnOuGo tool-error normalizer in an MCP server options block:

services
    .AddMcpServer(options =>
    {
        options.ServerInfo = new Implementation
        {
            Name = "GnOuGo.Example.Mcp",
            Version = "1.0.0"
        };
        options.AddGnOuGoToolErrorNormalizer();
    });

The normalizer marks a CallToolResult as IsError = true when the returned payload has a clear structured failure envelope, such as success: false, ok: false, status: "error", error_code, error_message, or a compact { code, message } error object. Plain text diagnostics are not treated as errors.

Artifact producers may declare encoding: "json_array" for string fields containing exact JSON arrays. This additive metadata authorizes the native planner to concatenate original page records without changing their contents. Unknown encodings are rejected. Missing metadata never implies a collection format.