nanoFramework.WebServer.FileSystem 1.2.147

.NET nanoFramework WebServer with Model Context Protocol (MCP) and Skills Discovery

Build status

Component	Build Status	NuGet Package
nanoFramework.WebServer
nanoFramework.WebServer.FileSystem
nanoFramework.WebServer.Mcp
nanoFramework.WebServer.Skills

Overview

This library provides a lightweight, multi-threaded HTTP/HTTPS WebServer for .NET nanoFramework with comprehensive Model Context Protocol (MCP) support and AI Agent Skills Discovery (A2A-compatible) for AI agent integration.

Key Features

• Multi-threaded request handling
• Static file serving with FileSystem support
• RESTful API support with parameter handling
• Route-based controllers with attribute decoration
• Authentication support (Basic, API Key)
• HTTPS/SSL support with certificates
• Model Context Protocol (MCP) for AI agent integration
• AI Agent Skills Discovery with A2A-compatible Agent Card
• Automatic tool discovery and JSON-RPC 2.0 compliance

Quick Start

Basic Event Based WebServer

Using the Web Server is very straight forward and supports event based calls.

// You need to be connected to a Wi-Fi or ethernet connection with a proper IP Address
// Optionally you can pass a parameter with the IP address for the server to bind to

using (WebServer server = new WebServer(80, HttpProtocol.Http))
{
    server.CommandReceived += ServerCommandReceived;
    server.Start();
    Thread.Sleep(Timeout.Infinite);
}

private static void ServerCommandReceived(object source, WebServerEventArgs e)
{
    if (e.Context.Request.RawUrl.ToLower() == "/hello")
    {
        WebServer.OutputAsStream(e.Context.Response, "Hello from nanoFramework!");
    }
    else
    {
        WebServer.OutputHttpCode(e.Context.Response, HttpStatusCode.NotFound);
    }
}

Controller-Based WebServer

Controllers are supported including with parametarized routes like 'api/led/{id}/dosomething/{order}'.

using (WebServer server = new WebServer(80, HttpProtocol.Http, new Type[] { typeof(MyController) }))
{
    server.Start();
    Thread.Sleep(Timeout.Infinite);
}

public class MyController
{
    [Route("api/hello")]
    [Method("GET")]
    public void Hello(WebServerEventArgs e)
    {
        WebServer.OutputAsStream(e.Context.Response, "Hello from Controller!");
    }

    [Route("api/led/{id}")]
    [Method("GET")]
    public void LedState(WebServerEventArgs e)
    {
        string ledId = e.GetRouteParameter("id");
        WebServer.OutputAsStream(e.Context.Response, $"You selected Led {ledId}!");
    }
}

Model Context Protocol (MCP) Support

Enable AI agents to interact with your embedded devices through standardized tools and JSON-RPC 2.0 protocol.

Defining MCP Tools

public class IoTTools
{
    [McpServerTool("read_sensor", "Reads temperature from sensor")]
    public static string ReadTemperature()
    {
        // Your sensor reading code
        return "23.5°C";
    }

    [McpServerTool("control_led", "Controls device LED", "Output the status of the LED")]
    public static string ControlLed(LedCommand command)
    {
        // Your LED control code
        return $"LED set to {command.State}";
    }
}

public class LedCommand
{
    public string State
    {
        [Description("LED state: on, off, or blink")]
        get;
        set;
    }
}

Defining MCP Prompts

You can define reusable, high-level prompts for AI agents using the McpServerPrompt attribute. Prompts encapsulate multi-step instructions or workflows that can be invoked by agents.

Here's a simple example:

using nanoFramework.WebServer.Mcp;

public class McpPrompts
{
    [McpServerPrompt("echo_sanity_check", "Echo test prompt")]
    public static PromptMessage[] EchoSanityCheck()
    {
        return new PromptMessage[]
        {
            new PromptMessage("Call Echo with the string 'Hello MCP world!' and return the response.")
        };
    }
}

Prompts can be discovered and invoked by AI agents in the same way as tools. You can also define prompts with parameters using the McpPromptParameter attribute.

Setting Up MCP Server

public static void Main()
{
    // Connect to WiFi first
    var connected = WifiNetworkHelper.ConnectDhcp(Ssid, Password, requiresDateTime: true);
    
    // Discover and register MCP tools
    McpToolRegistry.DiscoverTools(new Type[] { typeof(IoTTools) });

    // Discover and register MCP prompts
    McpPromptRegistry.DiscoverPrompts(new Type[] { typeof(McpPrompts) });
    
    // Start WebServer with MCP support
    using (var server = new WebServer(80, HttpProtocol.Http, new Type[] { typeof(McpServerController) }))
    {
        // Optional customization
        McpServerController.ServerName = "MyIoTDevice";
        McpServerController.Instructions = "IoT device with sensor and LED control capabilities.";
        
        server.Start();
        Thread.Sleep(Timeout.Infinite);
    }
}

AI Agent Integration

Once running, AI agents can discover and invoke your tools:

// Tool discovery
POST /mcp
{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
}

// Tool invocation
POST /mcp
{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
        "name": "control_led",
        "arguments": {"State": "on"}
    },
    "id": 2
}

AI Agent Skills Discovery

Expose device capabilities as discoverable skills for AI agents using the A2A (Agent2Agent) protocol conventions.

Defining Skills

using nanoFramework.WebServer.Skills;

[Skill("climate", "Climate Control", "HVAC management for building zones")]
[SkillTag("temperature")]
[SkillTag("hvac")]
[SkillExample("What is the current temperature?")]
public class ClimateSkill
{
    [SkillAction("GetTemperature", "Reads current room temperature")]
    public static double GetTemperature()
    {
        return 22.5;
    }

    [SkillAction("SetTarget", "Sets the target temperature")]
    public static bool SetTarget(TargetInput input)
    {
        return true;
    }
}

public class TargetInput
{
    public double Temperature
    {
        [Description("Target temperature in Celsius")]
        get;
        set;
    }
}

Setting Up Skills Server

public static void Main()
{
    // Connect to WiFi first
    var connected = WifiNetworkHelper.ConnectDhcp(Ssid, Password, requiresDateTime: true);

    // Discover and register skills
    SkillRegistry.DiscoverSkills(new Type[] { typeof(ClimateSkill) });

    // Start WebServer with Skills Discovery support
    using (var server = new WebServer(80, HttpProtocol.Http, new Type[] { typeof(SkillDiscoveryController) }))
    {
        // Optional customization
        SkillDiscoveryController.AgentName = "SmartThermostat";
        SkillDiscoveryController.AgentDescription = "Embedded HVAC controller with sensor capabilities";

        server.Start();
        Thread.Sleep(Timeout.Infinite);
    }
}

AI Agent Integration

Once running, AI agents can discover and invoke your skills:

GET /.well-known/agent-card.json

{
  "name": "SmartThermostat",
  "description": "Embedded HVAC controller with sensor capabilities",
  "version": "1.0.0",
  "skills": [
    {
      "id": "climate",
      "name": "Climate Control",
      "tags": ["temperature", "hvac"],
      "actions": [
        { "name": "GetTemperature", "description": "Reads current room temperature" },
        { "name": "SetTarget", "description": "Sets the target temperature" }
      ]
    }
  ]
}

POST /skills/invoke
Content-Type: application/json

{ "skill": "climate", "action": "GetTemperature", "arguments": {} }

Documentation

Limitations

• No compression support in request/response streams
• MCP implementation supports server features only (no notifications or SSE)
• No or single parameter limitation for MCP tools and Skills actions (use complex objects for multiple parameters)
• Prompt parameters, when declared, are always mandatory.
• Skills Discovery implements A2A discovery and invocation only (no task lifecycle)

Installation

Install 'nanoFramework.WebServer' for the Web Server without File System support. Install 'nanoFramework.WebServer.FileSystem' for file serving, so with devices supporting File System. Install 'nanoFramework.WebServer.Mcp' for MCP support. It does contains the full 'nanoFramework.WebServer' but does not include native file serving. You can add this feature fairly easilly by reusing the code function serving it. Install 'nanoFramework.WebServer.Skills' for A2A-compatible AI Agent Skills Discovery. Like MCP, it includes the core 'nanoFramework.WebServer' and can be used alongside MCP.

Contributing

For documentation, feedback, issues and contributions, please refer to the Home repo.

Join our Discord community here.

Credits

The list of contributors to this project can be found at CONTRIBUTORS.

License

Licensed under the MIT license.

Code of Conduct

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behaviour in our community. For more information see the .NET Foundation Code of Conduct.

.NET Foundation

This project is supported by the .NET Foundation.