MCP Architecture - Agentic AI Service

A clean, SOLID, object-oriented architecture for implementing Model Context Protocol (MCP) with an Agentic AI service built on .NET 8.0.

Architecture Overview

This solution follows Clean Architecture principles with clear separation of concerns:

• Domain Layer: Core models, interfaces, and business logic
• Application Layer: Use cases and application services
• Infrastructure Layer: External service implementations (HTTP clients, data access)
• API Layer: ASP.NET Core Web API with REST endpoints

Project Structure

McpArchitecture/
├── McpArchitecture.Domain/          # Core domain models and interfaces
├── McpArchitecture.Application/     # Application services and use cases
├── McpArchitecture.Infrastructure/  # Infrastructure implementations
├── McpArchitecture.Api/             # ASP.NET Core Web API
├── scripts/                         # PowerShell setup scripts
└── README.md

Prerequisites

• .NET 8.0 SDK or later
• Visual Studio 2022 (or later)
• PowerShell 5.1 or later

Setup Instructions

Option 1: Using PowerShell Scripts (Recommended)

1. Open PowerShell in the project root directory

2. Run the setup script:

   .\scripts\Setup-Project.ps1
   

3. Add NuGet packages:

   .\scripts\Add-Packages.ps1
   

Option 2: Manual Setup

1. Create the solution:

   dotnet new sln -n McpArchitecture
   

2. Create projects:

   dotnet new classlib -n McpArchitecture.Domain
   dotnet new classlib -n McpArchitecture.Application
   dotnet new classlib -n McpArchitecture.Infrastructure
   dotnet new webapi -n McpArchitecture.Api
   

3. Add projects to solution:

   dotnet sln add McpArchitecture.Domain/McpArchitecture.Domain.csproj
   dotnet sln add McpArchitecture.Application/McpArchitecture.Application.csproj
   dotnet sln add McpArchitecture.Infrastructure/McpArchitecture.Infrastructure.csproj
   dotnet sln add McpArchitecture.Api/McpArchitecture.Api.csproj
   

4. Add project references (see Setup-Project.ps1 for reference structure)

Running the Application

Option 1: Using the Start Script (Recommended)

Windows (PowerShell):

.\start.ps1

Linux/Mac (Bash):

chmod +x start.sh
./start.sh

With custom options:

# Run in Production environment
.\start.ps1 -Environment Production

# Run on custom port
.\start.ps1 -Port 5002

# Show help
.\start.ps1 -Help

Option 2: Using Visual Studio 2022

1. Open the solution in Visual Studio 2022
2. Set McpArchitecture.Api as the startup project
3. Press F5 to run

Option 3: Using .NET CLI

cd McpArchitecture.Api
dotnet run

Access the API

Once started, navigate to:

• Swagger UI: https://localhost:5001/swagger
• API Base: https://localhost:5001

API Endpoints

Standard MCP Endpoints

• POST /api/mcp/request - Process an MCP request
• POST /api/mcp/message - Process an MCP message
• GET /api/mcp/resources - Get all available resources
• GET /api/mcp/resources/{id} - Get a specific resource
• POST /api/mcp/resources - Register a new resource

FileServer MCP (JSON-RPC 2.0)

• POST /api/mcp/json - Process JSON-RPC 2.0 MCP requests
  • filesystem/list_files - List files and directories
  • filesystem/read_file - Read file contents
  • filesystem/write_file - Write file contents
  • filesystem/get_file_info - Get file/directory information
  • filesystem/create_directory - Create a directory
  • filesystem/delete_file - Delete a file or directory

Testing with MCP Inspector

Use the MCP Inspector to interactively test the API:

.\test-mcp\start-inspector.ps1

This will launch a web-based inspector tool. See test-mcp/README.md for details.

Design Principles

This project follows SOLID principles:

• Single Responsibility: Each class has one reason to change
• Open/Closed: Open for extension, closed for modification
• Liskov Substitution: Interfaces can be swapped without breaking functionality
• Interface Segregation: Small, focused interfaces
• Dependency Inversion: Depend on abstractions, not concretions

Features

• ✅ Clean Architecture with layered separation
• ✅ Dependency Injection throughout
• ✅ Structured logging with Serilog
• ✅ Swagger/OpenAPI documentation
• ✅ RESTful API design
• ✅ Resource management system
• ✅ MCP protocol implementation
• ✅ Visual Studio 2022 compatible

Configuration

Edit appsettings.json to configure:

• MCP base URL
• Timeout settings
• Logging levels

Testing

To add tests, create a test project:

dotnet new xunit -n McpArchitecture.Tests
dotnet add reference ../McpArchitecture.Domain/McpArchitecture.Domain.csproj

Contributing

This is a clean architecture template. Extend it based on your specific requirements while maintaining the SOLID principles and clean architecture boundaries.

License

This project is provided as-is for educational and commercial use.