RalfHuesing.Mcp.Observability 1.0.0

RalfHuesing.Mcp.Observability

A NuGet package that adds unified JSONL tool-call logging and a structured agent feedback channel to any MCP server built on the official ModelContextProtocol SDK.

Why

MCP servers run as stdio processes — they have no built-in logging that survives a binary update. When an LLM agent misbehaves or a tool returns unexpected results, there is usually no trace of what happened.

This package solves that with a single call:

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly()
    .WithObservability();          // ← one line

From that point on:

• Every tools/call is logged to a JSONL file that survives server reinstalls.
• Agents can report issues and feature requests via report_observability_feedback.

What it does

Requirements

• .NET 10 or later
• ModelContextProtocol SDK 2.x (stable)

Installation

dotnet add package RalfHuesing.Mcp.Observability

Quick Start

// Program.cs
var builder = Host.CreateApplicationBuilder(args);

// Optional: read options from appsettings.json
var obsOptions = builder.Configuration
    .GetSection("McpObservability")
    .Get<McpObservabilityOptions>()
    ?? new McpObservabilityOptions();   // all defaults = enabled

builder.Services
    .AddMcpServer(options =>
    {
        options.ServerInfo = new() { Name = "MyServer", Version = "1.0.0" };
    })
    .WithStdioServerTransport()
    .WithToolsFromAssembly()
    .WithObservability(obsOptions);

await builder.Build().RunAsync();

Configuration

All settings are optional. Without configuration, everything is enabled and logs go to %LOCALAPPDATA%\RalfHuesing\McpObservability\.

{
  "McpObservability": {
    "Enabled": true,
    "EnableToolCallLogging": true,
    "EnableFeedbackTool": true
    // "LogDirectory": "D:\\Logs\\Mcp"
  }
}

Log file location

%LOCALAPPDATA%\RalfHuesing\McpObservability\
└── {ServerName}\
    └── {yyyy-MM-dd}\
        └── {ServerName}_{ProcessId}_{InstanceId}.jsonl

Example: AiNetLinter\2026-08-17\AiNetLinter_18432_a1b2c3d4e5f67890.jsonl

JSONL record format

Each line is a self-contained JSON object. All records share these fields:

{
  "schemaVersion": 1,
  "timestamp": "2026-08-17T17:22:01.123Z",
  "recordType": "tool_call",
  "serverName": "AiNetLinter",
  "serverVersion": "1.4.2",
  "processId": 18432,
  "instanceId": "a1b2c3d4e5f67890"
}

tool_call additional fields

{
  "toolName": "analyze_code",
  "arguments": { "filePath": "src/Foo.cs" },
  "durationMs": 142,
  "success": true,
  "isErrorResult": false,
  "errorMessage": null
}

feedback additional fields

{
  "feedbackType": "issue",
  "title": "False positive on nullable reference",
  "description": "When analyzing … the tool reported …",
  "relatedTool": "analyze_code",
  "severity": "medium",
  "expectedBehavior": "…",
  "actualBehavior": "…",
  "additionalContext": "…"
}

The feedback tool

report_observability_feedback is automatically registered when EnableFeedbackTool = true. Agents see it as a regular MCP tool.

Report an issue or a feature request about this MCP server. Use this tool whenever something is wrong (bugs, false positives, unexpected results, confusing output) or when a needed capability is missing. After reporting, continue with the best available workaround.

License

MIT — see LICENSE.