smartguy05/empty-mcp

MCP Server Starter (.NET)

A .NET implementation of the Model Context Protocol (MCP) server that provides a foundation for building MCP-compliant servers with JSON-RPC 2.0 support.

Features

• JSON-RPC 2.0 Compliance: Full support for JSON-RPC 2.0 specification
• Namespace-based Routing: Methods organized by namespace (e.g., tools/list, test/echo)
• Standard MCP Error Codes: All MCP-specified error codes implemented
• Extensible Architecture: Easy to add new namespaces and operations
• Built-in Test Endpoints: Test functionality for validation

Project Structure

Api/
├── Controllers/
│   └── JsonRpcController.cs       # Main HTTP endpoint handler
├── Services/
│   ├── RpcDispatcher.cs           # Routes JSON-RPC requests to handlers
│   └── McpTestService.cs          # Test namespace implementation
├── Models/
│   ├── RpcRequest.cs              # JSON-RPC request model
│   ├── RpcResponse.cs             # JSON-RPC response model
│   ├── RpcError.cs                # JSON-RPC error model
│   └── RpcErrorCodes.cs           # MCP standard error codes
├── MCPNamespaces/
│   ├── ToolsNamespace.cs          # Tools namespace stub
│   ├── ResourcesNamespace.cs     # Resources namespace stub
│   └── PromptsNamespace.cs       # Prompts namespace stub
└── test-requests.http             # HTTP test requests

Getting Started

1. Build and run the project:

   cd Api
   dotnet build
   dotnet run
   

2. The server will start on:

   • HTTP: http://localhost:5000
   • HTTPS: https://localhost:5001

3. Test the server:

   • Swagger UI: Navigate to https://localhost:5001/swagger for interactive API testing
   • HTTP files: Use the provided test-requests.http file
   • Direct requests: Send POST requests to /api/jsonrpc

Swagger UI Features

The integrated Swagger UI provides:

• Interactive Testing: Execute JSON-RPC requests directly from the browser
• Request Examples: Pre-filled examples for common MCP operations
• Schema Documentation: Detailed parameter and response documentation
• Error Code Reference: Complete list of MCP and JSON-RPC error codes

Access Swagger UI at: https://localhost:5001/swagger (when running in development mode)

Example Requests

Test Echo

POST /api/jsonrpc
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "test/echo",
  "params": {
    "message": "Hello, MCP Server!"
  }
}

Initialize Connection

POST /api/jsonrpc
{
  "jsonrpc": "2.0",
  "id": "2", 
  "method": "initialize/initialize",
  "params": {
    "protocolVersion": "1.0.0",
    "capabilities": {
      "tools": true,
      "resources": true,
      "prompts": true
    },
    "clientInfo": {
      "name": "Test Client",
      "version": "1.0.0"
    }
  }
}

Implemented Namespaces

test - Testing Functions

• test/echo - Echo back a message with timestamp
• test/ping - Simple ping/pong functionality

initialize - Connection Setup

• initialize/initialize - MCP initialization handshake

Stub Namespaces (Not Yet Implemented)

• tools/* - Tool discovery and execution
• resources/* - Resource access and management
• prompts/* - Prompt template management

Error Codes

The server implements all standard JSON-RPC 2.0 and MCP error codes:

Extending the Server

Adding a New Namespace

1. Create a new class in MCPNamespaces/ folder

2. Implement the handler pattern:

   public class MyNamespace
   {
       public Task<object> HandleAsync(string operation, JObject? parameters)
       {
           return operation.ToLowerInvariant() switch
           {
               "myoperation" => HandleMyOperationAsync(parameters),
               _ => Task.FromResult<object>(CreateErrorResult(
                   RpcErrorCodes.MethodNotFound, 
                   $"Unknown operation: {operation}"))
           };
       }
   }
   

3. Register the service in Program.cs:

   builder.Services.AddSingleton<MyNamespace>();
   

4. Add routing in RpcDispatcher.cs:

   case "mynamespace":
       var myService = _services.GetService<MyNamespace>();
       response.Result = await myService.HandleAsync(operation, request.Params);
       break;
   

Adding Tools

Implement the tools/list and tools/call operations in ToolsNamespace.cs to register and execute tools according to the MCP specification.

Adding Resources

Implement the resources/list and resources/read operations in ResourcesNamespace.cs to provide access to external resources.

Dependencies

• .NET 9.0 - Target framework
• Newtonsoft.Json - JSON serialization
• Microsoft.AspNetCore.Mvc.NewtonsoftJson - JSON support for ASP.NET Core
• Microsoft.AspNetCore.OpenApi - OpenAPI support

License

This is a starter template for building MCP servers in .NET.