EcommerceSearch

A clean-architecture ASP.NET Core 8 Web API for searching an ecommerce product catalog, with a companion Model Context Protocol (MCP) server, integration tests, and BenchmarkDotNet benchmarks.

Projects

Architecture

Client
  └─▶ ProductsController          (ASP.NET Core Controller)
        └─▶ IProductService       (Service abstraction)
              ├─▶ IProductRepository            (EF Core reads — AsNoTracking)
              └─▶ IDapperProductReadRepository  (Dapper raw SQL reads)
                    └─▶ ProductDbContext / SQLite

Entities never leave the service layer — controllers only receive ProductDto.

Tech Stack

• .NET 8 / ASP.NET Core 8
• Entity Framework Core 8 with SQLite driver — all reads use AsNoTracking()
• Dapper 2 with Microsoft.Data.Sqlite for alternative read endpoints
• xUnit 2 + Microsoft.AspNetCore.Mvc.Testing for integration tests
• FluentAssertions for expressive test assertions
• BenchmarkDotNet for micro-benchmarks
• ModelContextProtocol SDK for the MCP server

Domain

Product
{
    string  Id          // "p1" … "p100"
    string  Name
    string  Brand
    string  Description
    decimal Price
    string  Category    // electronics | clothing | furniture | sports | books
}

100 products are seeded at startup across 5 categories (20 each).

Getting Started

Prerequisites

• .NET 8 SDK

Build

dotnet build EcommerceSearch.sln

Run the API

cd EcommerceSearch.Api
dotnet run

The API starts at http://localhost:5000 (HTTP) / https://localhost:5001 (HTTPS). Swagger UI is available at http://localhost:5000/swagger in Development mode.

The SQLite database (ecommerce.db) is created and seeded automatically on first run.

Run the MCP Server

The MCP server reads the REST API base URL from appsettings.json:

{ "ApiBaseUrl": "http://localhost:5000/" }

Start the API first, then:

cd EcommerceSearch.McpServer
dotnet run

The server communicates over stdio (standard MCP transport).

Run Tests

dotnet test EcommerceSearch.Tests

Tests use an isolated in-memory SQLite database — no file is written to disk.

Run Benchmarks

cd EcommerceSearch.Benchmarks
dotnet run -c Release

API Endpoint Reference

GET /api/products/{id}

Fetch a single product by its ID.

Responses

Example

curl http://localhost:5000/api/products/p1

GET /api/products

Paginated product list via EF Core.

Response — PagedResult<ProductDto>

Example

curl "http://localhost:5000/api/products?category=electronics&page=1&pageSize=10"

GET /api/products/dapper

Same paginated list but executed with raw SQL via Dapper.

Example

curl "http://localhost:5000/api/products/dapper?category=clothing&page=2&pageSize=5"

POST /api/products/search

Natural language product search — parses a free-text query into structured filters.

Request body

{
  "query": "show me electronics under 500",
  "page": 1,
  "pageSize": 20
}

Response — PagedResult<ProductDto>

Supported filter patterns

Filters combine: only products matching all parsed filters are returned.

Natural Language Search Examples

# Electronics under $500
curl -X POST http://localhost:5000/api/products/search \
  -H "Content-Type: application/json" \
  -d '{"query": "show me electronics under 500", "page": 1, "pageSize": 20}'

# Nike shoes below $200
curl -X POST http://localhost:5000/api/products/search \
  -H "Content-Type: application/json" \
  -d '{"query": "Nike shoes below 200"}'

# Similar to MacBook Pro
curl -X POST http://localhost:5000/api/products/search \
  -H "Content-Type: application/json" \
  -d '{"query": "similar to MacBook Pro"}'

# Samsung furniture
curl -X POST http://localhost:5000/api/products/search \
  -H "Content-Type: application/json" \
  -d '{"query": "Samsung furniture"}'

# Cheap books
curl -X POST http://localhost:5000/api/products/search \
  -H "Content-Type: application/json" \
  -d '{"query": "books under 20"}'

Rate Limiting

Per-IP fixed-window rate limiting:

Requests that exceed the limit and queue receive 429 Too Many Requests.

Configure in appsettings.json:

{
  "RateLimit": {
    "PermitLimit": 30,
    "WindowSeconds": 60,
    "QueueLimit": 5
  }
}

MCP Tools

The EcommerceSearch.McpServer exposes three tools to AI agents:

The MCP server never accesses the database directly — it calls the REST API over HTTP.

Project Structure

EcommerceSearch/
├── EcommerceSearch.Api/
│   ├── Controllers/
│   │   └── ProductsController.cs       # GET /{id}, GET /, GET /dapper, POST /search
│   ├── Services/
│   │   ├── IProductService.cs
│   │   └── ProductService.cs           # NL query parser + business logic
│   ├── Data/
│   │   ├── ProductDbContext.cs
│   │   ├── IProductRepository.cs
│   │   ├── EfProductRepository.cs      # EF Core + AsNoTracking
│   │   ├── IDapperProductReadRepository.cs
│   │   ├── DapperProductReadRepository.cs
│   │   └── ProductSeeder.cs            # 100 seed products
│   ├── Contracts/
│   │   ├── ProductDto.cs
│   │   ├── PagedResult.cs
│   │   ├── ProductSearchFilters.cs
│   │   └── SearchProductsRequest.cs
│   ├── Models/
│   │   └── Product.cs
│   ├── Filters/
│   │   ├── GlobalActionLoggerAsync.cs          # Request/response timing
│   │   └── GlobalExceptionHandlingFilter.cs    # ProblemDetails error responses
│   ├── Options/
│   │   └── RateLimitOptions.cs
│   └── Program.cs
├── EcommerceSearch.McpServer/
│   ├── Clients/
│   │   └── ProductApiClient.cs         # Typed HTTP client for the REST API
│   ├── Models/
│   │   ├── ProductDto.cs
│   │   └── PagedResult.cs
│   ├── Tools/
│   │   └── ProductTools.cs             # MCP tool definitions
│   └── Program.cs
├── EcommerceSearch.Tests/
│   ├── CustomWebApplicationFactory.cs  # In-memory SQLite, no file I/O
│   ├── ProductsControllerTests.cs
│   ├── ProductDapperTests.cs
│   ├── NaturalLanguageSearchTests.cs
│   ├── RateLimitingTests.cs
│   └── GlobalExceptionHandlingFilterTests.cs
├── EcommerceSearch.Benchmarks/
│   ├── ProductCategoryQueryBenchmark.cs
│   └── Program.cs
└── EcommerceSearch.sln

Coding Conventions

• All identifiers and comments in English
• Interfaces prefixed with I (e.g. IProductService)
• EF Core implementations suffixed with Ef (e.g. EfProductRepository)
• Controllers are plural (ProductsController)
• DTOs suffixed with Dto (ProductDto)
• Raw entities never leave the service layer — always mapped to DTOs
• Exception handling centralised in GlobalExceptionHandlingFilter
• Logging centralised in GlobalActionLoggerAsync