svrnty-mcp-server/docs/api/README.md

Svrnty.MCP.Server - API Reference

Version: 1.0.0 Last Updated: 2025-10-19 Status: Production-Ready

---

Table of Contents

• Core Abstractions
  • IMcpServer
  • IMcpTool
• Infrastructure
  • McpServer
  • HttpTransport
• Models
  • McpToolSchema
  • McpToolResult
• ASP.NET Core Integration
  • Service Extensions
  • Endpoint Mapping

---

Core Abstractions

IMcpServer

Namespace: Svrnty.MCP.Core.Abstractions

Interface defining the core MCP server contract.

Methods

ExecuteToolAsync

Task<McpToolResult> ExecuteToolAsync(
    string toolName,
    Dictionary<string, object> parameters,
    CancellationToken cancellationToken = default)

Executes a tool by name with the given parameters.

Parameters:

• toolName (string): The name of the tool to execute
• parameters (Dictionary<string, object>): Tool input parameters
• cancellationToken (CancellationToken): Optional cancellation token

Returns: Task<McpToolResult> - The result of the tool execution

Throws:

• ToolNotFoundException - If the tool doesn't exist
• InvalidParametersException - If parameters don't match schema
• OperationCanceledException - If cancelled

Example:

var result = await server.ExecuteToolAsync(
    "search_documents",
    new Dictionary<string, object>
    {
        ["query"] = "architecture patterns",
        ["maxResults"] = 10
    }
);

ListToolsAsync

Task<IEnumerable<McpToolInfo>> ListToolsAsync(
    CancellationToken cancellationToken = default)

Lists all available tools.

Returns: Task<IEnumerable<McpToolInfo>> - Collection of tool metadata

Example:

var tools = await server.ListToolsAsync();
foreach (var tool in tools)
{
    Console.WriteLine($"{tool.Name}: {tool.Description}");
}

---

IMcpTool

Namespace: Svrnty.MCP.Core.Abstractions

Interface for implementing MCP tools.

Properties

Name

string Name { get; }

Unique identifier for the tool (e.g., "search_documents").

Requirements:

• Must be lowercase
• Use underscores for word separation
• No spaces or special characters

Description

string Description { get; }

Human-readable description of what the tool does.

Schema

McpToolSchema Schema { get; }

JSON Schema defining the tool's input parameters.

Methods

ExecuteAsync

Task<McpToolResult> ExecuteAsync(
    Dictionary<string, object> parameters,
    CancellationToken cancellationToken = default)

Executes the tool with validated parameters.

Parameters:

• parameters (Dictionary<string, object>): Validated input parameters
• cancellationToken (CancellationToken): Cancellation support

Returns: Task<McpToolResult> - Success or error result

Example Implementation:

public class SearchTool : IMcpTool
{
    public string Name => "search_documents";
    public string Description => "Search documents by query";

    public McpToolSchema Schema => new()
    {
        Type = "object",
        Properties = new Dictionary<string, McpProperty>
        {
            ["query"] = new()
            {
                Type = "string",
                Description = "Search query",
                Required = true
            }
        }
    };

    public async Task<McpToolResult> ExecuteAsync(
        Dictionary<string, object> parameters,
        CancellationToken ct = default)
    {
        var query = parameters["query"].ToString();
        var results = await SearchAsync(query, ct);
        return McpToolResult.Success(results);
    }
}

---

Infrastructure

McpServer

Namespace: Svrnty.MCP.Infrastructure

Default implementation of IMcpServer.

Constructor

public McpServer(ToolRegistry toolRegistry)

Parameters:

• toolRegistry (ToolRegistry): Registry containing all available tools

Example:

var registry = new ToolRegistry();
registry.AddTool(new SearchTool());
registry.AddTool(new GetDocumentTool());

var server = new McpServer(registry);

Methods

StartAsync

Task StartAsync(CancellationToken cancellationToken = default)

Starts the MCP server (initializes transport).

StopAsync

Task StopAsync(CancellationToken cancellationToken = default)

Gracefully stops the server.

---

HttpTransport

Namespace: Svrnty.MCP.AspNetCore.Extensions

HTTP transport implementation for MCP protocol.

Configuration

{
  "Mcp": {
    "Transport": {
      "Type": "Http",
      "Port": 5050
    }
  }
}

Endpoints

POST /mcp/invoke

Invokes MCP methods via JSON-RPC 2.0.

Request:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "search_documents",
    "arguments": {
      "query": "test"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": "Search results...",
    "isSuccess": true
  }
}

GET /health

Health check endpoint.

Response:

{
  "status": "Healthy",
  "timestamp": "2025-10-19T12:00:00Z"
}

---

Models

McpToolSchema

Namespace: Svrnty.MCP.Core.Models

JSON Schema representation for tool parameters.

Properties

public class McpToolSchema
{
    public string Type { get; set; }  // "object"
    public Dictionary<string, McpProperty> Properties { get; set; }
    public List<string> Required { get; set; }
}

public class McpProperty
{
    public string Type { get; set; }  // "string", "number", "boolean", "array", "object"
    public string Description { get; set; }
    public bool Required { get; set; }
    public object Default { get; set; }
}

Example

var schema = new McpToolSchema
{
    Type = "object",
    Properties = new Dictionary<string, McpProperty>
    {
        ["query"] = new()
        {
            Type = "string",
            Description = "Search query",
            Required = true
        },
        ["maxResults"] = new()
        {
            Type = "number",
            Description = "Maximum number of results",
            Required = false,
            Default = 10
        }
    }
};

---

McpToolResult

Namespace: Svrnty.MCP.Core.Models

Represents the result of a tool execution.

Properties

public class McpToolResult
{
    public bool IsSuccess { get; set; }
    public string Content { get; set; }
    public string ErrorMessage { get; set; }
    public int? ErrorCode { get; set; }
}

Static Factory Methods

Success

public static McpToolResult Success(object content)

Creates a successful result.

Example:

return McpToolResult.Success(new
{
    results = documents,
    count = documents.Count
});

Error

public static McpToolResult Error(string message, int? code = null)

Creates an error result.

Example:

return McpToolResult.Error("Document not found", 404);

---

ASP.NET Core Integration

Service Extensions

Namespace: Svrnty.MCP.AspNetCore

AddMcpServer

public static IServiceCollection AddMcpServer(
    this IServiceCollection services,
    McpServer server)

Registers MCP server and dependencies.

Example:

var registry = new ToolRegistry();
registry.AddTool(new SearchTool());

var server = new McpServer(registry);
builder.Services.AddMcpServer(server);

---

Endpoint Mapping

MapMcpEndpoints

public static IEndpointRouteBuilder MapMcpEndpoints(
    this IEndpointRouteBuilder endpoints,
    McpServer server)

Maps HTTP endpoints for MCP protocol.

Example:

var app = builder.Build();
app.MapMcpEndpoints(server);

Mapped Endpoints:

• POST /mcp/invoke - JSON-RPC 2.0 method invocation
• GET /health - Health check

---

JSON-RPC 2.0 Methods

tools/list

Lists all available tools.

Request:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "tools": [
      {
        "name": "search_documents",
        "description": "Search documents by query",
        "inputSchema": { ... }
      }
    ]
  }
}

tools/call

Executes a tool.

Request:

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "search_documents",
    "arguments": {
      "query": "test",
      "maxResults": 10
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "content": { "results": [...] },
    "isSuccess": true
  }
}

---

Error Handling

Error Codes

Code	Meaning
-32700	Parse error (invalid JSON)
-32600	Invalid request
-32601	Method not found
-32602	Invalid params
-32603	Internal error

Error Response

{
  "jsonrpc": "2.0",
  "id": "1",
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": {
      "method": "invalid_method"
    }
  }
}

---

Complete Example

Creating an MCP Server

using Svrnty.MCP.Core;
using Svrnty.MCP.Core.Abstractions;
using Microsoft.AspNetCore.Builder;

// 1. Create tools
public class SearchTool : IMcpTool
{
    public string Name => "search_documents";
    public string Description => "Search documents";

    public McpToolSchema Schema => new()
    {
        Type = "object",
        Properties = new Dictionary<string, McpProperty>
        {
            ["query"] = new() { Type = "string", Required = true }
        }
    };

    public async Task<McpToolResult> ExecuteAsync(
        Dictionary<string, object> parameters,
        CancellationToken ct = default)
    {
        var query = parameters["query"].ToString();
        // Implementation here
        return McpToolResult.Success($"Results for: {query}");
    }
}

// 2. Set up server
var builder = WebApplication.CreateBuilder(args);

var registry = new ToolRegistry();
registry.AddTool(new SearchTool());

var server = new McpServer(registry);
builder.Services.AddMcpServer(server);

builder.WebHost.ConfigureKestrel(options =>
{
    options.ListenLocalhost(5050);
});

var app = builder.Build();

// 3. Map endpoints
app.MapMcpEndpoints(server);
app.MapHealthChecks("/health");

// 4. Start server
await app.RunAsync();

Calling from Client

curl -X POST http://localhost:5050/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "search_documents",
      "arguments": {
        "query": "test"
      }
    }
  }'

---

See Also

• Server Architecture
• Configuration Guide
• Security Guide
• TDD Guide

---

Document Type: API Reference Version: 1.0.0 Last Updated: 2025-10-19 Maintained By: Svrnty Development Team