Skip to main content
Glama
renaisanci

mcp-clean-architecture

by renaisanci

FastMCP Clean Architecture – MCP-App-UI-Vorlage

Eine produktionsreife Vorlage zum Erstellen von MCP-Servern und MCP-Apps mit Python und FastMCP, die Clean Architecture, Dependency Inversion, Trennung von Zuständigkeiten und moderne Python-Praktiken umsetzt.

Das Projekt dient auch als Lernreferenz für Entwickler, die aus C# / .NET kommen.

Das Ziel ist nicht nur, einen MCP-Server zu bauen, der funktioniert, sondern einen, der wartbar, testbar, erweiterbar und unabhängig von externen Frameworks und Diensten bleibt.


Ziele

Diese Vorlage zeigt, wie man eine MCP-Anwendung mit Folgendem erstellt:

  • Python

  • FastMCP

  • Streamable-HTTP-Transport

  • Zustandsloses HTTP

  • MCP-Tools

  • MCP-Ressourcen

  • MCP-Prompts

  • MCP-Apps / App-UI

  • Clean Architecture

  • Dependency Inversion

  • Repository-Muster

  • Anwendungsfälle

  • Pydantic-Modelle

  • Integration externer REST-APIs

  • Umgebungsbasierte Konfiguration

  • Asynchrone HTTP-Kommunikation

  • Dependency Injection / Komposition

  • Zentralisierte Fehlerbehandlung

  • Strukturierte Anwendungsfehler

  • Protokollierung

  • Unit-Tests

  • Integrationstests

Die Beispieldomäne ist eine E-Commerce-Anwendung.

Produkte werden über eine öffentliche externe API abgerufen und über MCP bereitgestellt.

Die Anwendung wird sich weiterentwickeln, um Aktionen wie folgende zu unterstützen:

  • Produkte suchen

  • Produktdetails anzeigen

  • Produkte zum Warenkorb hinzufügen

  • Warenkorb anzeigen

  • Produkte aus dem Warenkorb entfernen

Eine MCP-App-UI wird ein interaktives Erlebnis in kompatiblen MCP-Hosts bieten.


Related MCP server: NitroStack

Architektur

Das Projekt folgt den Prinzipien der Clean Architecture.

                         MCP HOST
                   Claude / Copilot / etc.
                              |
                              | MCP over HTTP
                              v
+---------------------------------------------------------+
|                    PRESENTATION                         |
|                                                         |
|  FastMCP Server                                         |
|  MCP Tools                                              |
|  MCP Resources                                          |
|  MCP Prompts                                            |
|  MCP App UI                                             |
|  Error Boundary                                         |
+---------------------------+-----------------------------+
                            |
                            v
+---------------------------------------------------------+
|                    APPLICATION                          |
|                                                         |
|  Use Cases                                              |
|                                                         |
|  GetProductUseCase                                      |
|  SearchProductsUseCase                                  |
|  AddProductToCartUseCase                                |
|  GetCartUseCase                                         |
+---------------------------+-----------------------------+
                            |
                            v
+---------------------------------------------------------+
|                       DOMAIN                            |
|                                                         |
|  Entities / Models                                      |
|                                                         |
|  Product                                                |
|  Cart                                                   |
|                                                         |
|  Repository Contracts                                   |
|                                                         |
|  ProductRepository                                      |
|  CartRepository                                         |
|                                                         |
|  Domain Errors                                          |
+---------------------------+-----------------------------+
                            ^
                            |
+---------------------------+-----------------------------+
|                   INFRASTRUCTURE                        |
|                                                         |
|  External API implementations                           |
|  HTTP clients                                           |
|  Configuration                                          |
|  Persistence adapters                                   |
|                                                         |
|  DummyJsonProductRepository                             |
|  DummyJsonCartRepository                                |
+---------------------------+-----------------------------+
                            |
                            v
                     External REST API

Abhängigkeitsregel

Die wichtigste Regel ist:

Presentation  ---> Application ---> Domain
                         ^
                         |
Infrastructure ----------+

Abhängigkeiten zeigen auf den Kern der Anwendung.

Die Domäne darf niemals abhängen von:

FastMCP
HTTP libraries
Uvicorn
DummyJSON
Claude
Copilot
databases
environment variables
MCP App UI

Zum Beispiel:

MCP Tool
   |
   v
GetProductUseCase
   |
   v
ProductRepository
   ^
   |
DummyJsonProductRepository
   |
   v
DummyJSON REST API

GetProductUseCase kennt die ProductRepository-Abstraktion.

Es weiß nicht, dass Produkte über HTTP oder DummyJSON abgerufen werden.

Dies ermöglicht:

DummyJSON

später ersetzt zu werden durch:

SQL Server
PostgreSQL
MongoDB
another REST API
mock repository

ohne den Anwendungsfall zu ändern.


Projektstruktur

Das Projekt wird sich hin zu der folgenden Struktur entwickeln:

mcp-clean-architecture/
|
|-- src/
|   |
|   |-- domain/
|   |   |
|   |   |-- entities/
|   |   |   |-- __init__.py
|   |   |   |-- product.py
|   |   |   `-- cart.py
|   |   |
|   |   |-- repositories/
|   |   |   |-- __init__.py
|   |   |   |-- product_repository.py
|   |   |   `-- cart_repository.py
|   |   |
|   |   `-- errors/
|   |       |-- __init__.py
|   |       `-- domain_errors.py
|   |
|   |-- application/
|   |   |
|   |   |-- use_cases/
|   |   |   |-- __init__.py
|   |   |   |-- get_product.py
|   |   |   |-- search_products.py
|   |   |   |-- add_product_to_cart.py
|   |   |   `-- get_cart.py
|   |   |
|   |   `-- errors/
|   |       |-- __init__.py
|   |       `-- application_errors.py
|   |
|   |-- infrastructure/
|   |   |
|   |   |-- config/
|   |   |   |-- __init__.py
|   |   |   `-- environment.py
|   |   |
|   |   |-- http/
|   |   |
|   |   |-- repositories/
|   |   |   |-- __init__.py
|   |   |   |-- dummy_json_product_repository.py
|   |   |   `-- dummy_json_cart_repository.py
|   |   |
|   |   `-- errors/
|   |       |-- __init__.py
|   |       `-- infrastructure_errors.py
|   |
|   `-- presentation/
|       |
|       `-- mcp/
|           |-- __init__.py
|           |-- server.py
|           |
|           |-- tools/
|           |
|           |-- resources/
|           |
|           |-- prompts/
|           |
|           `-- apps/
|
|-- tests/
|   |
|   |-- unit/
|   `-- integration/
|
|-- .env.example
|-- .gitignore
|-- .python-version
|-- pyproject.toml
|-- uv.lock
`-- README.md

Ordner sollten eingeführt werden, wenn sie eine echte Verantwortung haben.

Die Vorlage sollte keine Abstraktionen nur um der Abstraktionen willen erstellen.


Verantwortlichkeiten der Ebenen

Domäne

Enthält die zentralen Geschäftskonzepte und Verträge.

Beispiele:

Product
Cart

ProductRepository
CartRepository

ProductNotFoundError
CartError

Die Domäne sollte Geschäftskonzepte enthalten, ohne zu wissen, wie die Außenwelt mit der Anwendung kommuniziert.


Anwendung

Enthält anwendungsspezifische Arbeitsabläufe und Anwendungsfälle.

Beispiele:

GetProductUseCase
SearchProductsUseCase
AddProductToCartUseCase
GetCartUseCase

Ein Anwendungsfall koordiniert Domänenabstraktionen.

Er sollte keine externe API direkt aufrufen.

Schlecht

class GetProductUseCase:

    def execute(self, product_id: int):
        requests.get(
            f"https://external-api/products/{product_id}"
        )

Der Anwendungsfall weiß jetzt:

  • dass HTTP existiert

  • welche HTTP-Bibliothek verwendet wird

  • welcher externe Anbieter verwendet wird

  • wie die Anbieter-URL funktioniert

Bevorzugt

class GetProductUseCase:

    def __init__(self, repository: ProductRepository):
        self.repository = repository

    def execute(self, product_id: int) -> Product:
        return self.repository.get_by_id(product_id)

Jetzt kennt der Anwendungsfall nur noch den Vertrag:

ProductRepository

Infrastruktur

Enthält Implementierungen für externe technische Belange.

Beispiele:

HTTP clients
REST APIs
repositories
databases
cache
environment configuration
external service adapters

Zum Beispiel:

ProductRepository
        ^
        |
DummyJsonProductRepository

Die Infrastruktur implementiert Domänenabstraktionen.

Die Domäne hängt nicht von der Infrastruktur ab.


Präsentation

Enthält MCP-spezifische Einstiegspunkte.

Beispiele:

FastMCP Server
MCP Tools
MCP Resources
MCP Prompts
MCP Apps

Ein MCP-Tool sollte schlank bleiben.

Seine Hauptverantwortung ist:

MCP Request
     |
     v
Validate / map input
     |
     v
Use Case
     |
     v
Map result
     |
     v
MCP Response

Geschäftslogik sollte nicht in MCP-Dekoratoren leben.


MCP-Architektur

MCP und FastMCP sind unterschiedliche Konzepte.

MCP
 |
 `-- Protocol


FastMCP
 |
 `-- Python framework implementing MCP

Die Anwendung verwendet MCP über Streamable HTTP.

MCP Host
   |
   | Streamable HTTP
   v
http://localhost:8000/mcp
   |
   v
FastMCP Server

Der Server ist standardmäßig so konfiguriert, dass er zustandsloses HTTP ausführt.


MCP-Komponenten

Tools

Aktionen, die das Modell ausführen kann.

Beispiele:

get_product
search_products
add_product_to_cart
get_cart
remove_product_from_cart

Konzeptionell:

LLM
 |
 | tool call
 v
MCP Tool
 |
 v
Use Case

Ressourcen

Ressourcen stellen Daten oder Kontext bereit, die ein MCP-Host lesen kann.

Sie sollten keinen Ersatz für die Geschäftslogik der Anwendung darstellen.


Prompts

Prompts stellen wiederverwendbare Prompt-Vorlagen über MCP bereit.

Sie gehören zur MCP-/Präsentationsgrenze.


MCP-App-UI

MCP-Apps ermöglichen kompatiblen MCP-Hosts, interaktive Benutzeroberflächen im Zusammenhang mit der MCP-Funktionalität anzuzeigen.

Unser E-Commerce-Beispiel wird schließlich etwas konzeptionell Ähnliches rendern wie:

+--------------------------------+
| Product                        |
|                                |
| Smartphone                     |
|                                |
| $799.99                        |
|                                |
|       [ Add to cart ]          |
+---------------+----------------+
                |
                v
          MCP Tool Call
                |
                v
     AddProductToCartUseCase
                |
                v
          CartRepository

Die wichtige Architekturregel lautet:

Die MCP-App-UI ist ein Präsentationsbelang.

Die Benutzeroberfläche sollte keine Geschäftsregeln implementieren.

Zum Beispiel, wenn man klickt auf:

[ Add to cart ]

sollte das Ergebnis sein:

MCP App UI
     |
     v
MCP Tool
     |
     v
AddProductToCartUseCase
     |
     v
CartRepository

Die Benutzeroberfläche manipuliert die Infrastruktur nicht direkt.


Umgebungskonfiguration

Die Laufzeitkonfiguration muss aus Umgebungsvariablen stammen und nicht hartcodiert sein.

Aktuelle Variablen:

MCP_SERVER_TRANSPORT
MCP_SERVER_HOST
MCP_SERVER_PORT
MCP_STATELESS_HTTP

Beispiel:

$env:MCP_SERVER_PORT="9000"

Der Konfigurationsfluss ist:

Operating System / Container
           |
           | Environment Variables
           v
EnvironmentSettings
           |
           v
server.py
           |
           v
FastMCP

Dies ermöglicht, dass derselbe Anwendungscode ausgeführt wird in:

Local
Development
Test
Staging
Production
Docker
Kubernetes
Cloud environments

mit unterschiedlicher Konfiguration.

Geheimnisse dürfen niemals in Git committet werden.


Python-Paketkonventionen

__init__.py kann verwendet werden, um die öffentliche API eines Python-Pakets zu definieren.

Zum Beispiel:

from infrastructure.config.environment import EnvironmentSettings

__all__ = [
    "EnvironmentSettings",
]

Verbraucher können dann verwenden:

from infrastructure.config import EnvironmentSettings

anstatt:

from infrastructure.config.environment import EnvironmentSettings

Dies reduziert die Kopplung an die interne Dateistruktur.

Konzeptionell ähnelt dies einem TypeScript:

index.ts

das als Barrel-Export verwendet wird.

__all__ definiert die beabsichtigte öffentliche API.

Es ist kein Zugriffsmodifikator wie public oder private in C#.


Python-/C#-Referenz

Dieses Projekt ist auch als Lernhilfe für .NET-Entwickler gedacht.

Python

C#-Konzept

str

string

int

int

float

double

bool

bool

None

null

list[T]

List<T>

dict[K, V]

Dictionary<K, V>

tuple[T1, T2]

ungefähr (T1, T2) / Tupel

self

this

ABC

abstract class

@abstractmethod

abstract method

Repository ABC

wird oft ähnlich wie IRepository verwendet

Product | None

ungefähr Product?

Exception

Exception

raise

throw

try / except

try / catch

__init__

Konstruktor

__init__.py

Paketinitialisierung / ähnlicher Zweck wie Barrel-Exports

Pydantic BaseModel

typisiertes Modell + Validierung/Serialisierung

@decorator

konzeptionell ähnlich zu Attributen/Middleware-Verhalten, je nach Verwendung

Wenn neue Python-Konzepte eingeführt werden, sollten ihre C#-Entsprechungen dokumentiert werden, wenn dies nützlich ist.


Domänenmodelle

Strukturierte Modelle verwenden Pydantic, wo Validierung und Serialisierung nützlich sind.

Beispiel:

from typing import Annotated

from pydantic import BaseModel


class Product(BaseModel):
    id: Annotated[int, "Product identifier"]
    title: Annotated[str, "Product title"]
    description: Annotated[str, "Product description"]
    price: Annotated[float, "Product price"]
    thumbnail: Annotated[str, "Product thumbnail URL"]

Pydantic bietet:

validation
type coercion
serialization
JSON-compatible output
JSON Schema generation

Repository-Muster

Repositories stellen Abstraktionen über Daten oder externe Systeme dar.

Beispiel:

from abc import ABC, abstractmethod

from domain.entities import Product


class ProductRepository(ABC):

    @abstractmethod
    def get_by_id(self, product_id: int) -> Product:
        pass

Für einen C#-Entwickler ist dies konzeptionell ähnlich zu:

public interface IProductRepository
{
    Product GetById(int productId);
}

Eine konkrete Infrastrukturimplementierung kann dann das tatsächliche Verhalten bereitstellen:

ProductRepository
        ^
        |
DummyJsonProductRepository

Externe APIs

Auf externe APIs muss von der Infrastruktur aus zugegriffen werden.

Die erste Implementierung verwendet die öffentliche DummyJSON-API für das E-Commerce-Beispiel.

Die Architektur verhindert, dass Anwendungsfälle direkt von DummyJSON abhängen.

Application
    |
    v
ProductRepository
    ^
    |
Infrastructure implementation
    |
    v
DummyJSON

Dies ermöglicht, den externen Anbieter später zu ersetzen, ohne die Anwendungs- oder Domänenschicht neu schreiben zu müssen.


Fehlerbehandlungsstrategie

Das Projekt verwendet eine zentralisierte Ausnahmehierarchie, die von Clean Architecture und gängigen .NET-Fehlerbehandlungsmustern inspiriert ist.

Das Ziel ist es, zu unterscheiden:

expected business failures
          vs
technical/infrastructure failures

während ein gemeinsamer strukturierter Fehlervertrag bereitgestellt wird.


Ausnahmehierarchie

AppError
|
|-- DomainError
|   |
|   |-- ProductNotFoundError
|   `-- CartError
|
|-- ValidationError
|
`-- InfrastructureError
    |
    |-- ExternalAPIError
    `-- ExternalAPITimeoutError

Alle bekannten Anwendungsfehler leiten sich letztendlich ab von:

AppError

Basis-Anwendungsfehler

from typing import Any


class AppError(Exception):
    error_code: str = "UNKNOWN_ERROR"

    def __init__(
        self,
        message: str,
        details: dict[str, Any] | None = None,
    ):
        self.message = message
        self.details = details or {}

        super().__init__(message)

    def to_dict(self) -> dict:
        return {
            "error_code": self.error_code,
            "error_type": self.__class__.__name__,
            "message": self.message,
            "details": self.details,
        }

Konzeptionell ähnlich zu C#:

public abstract class AppException : Exception
{
    public string ErrorCode { get; }

    protected AppException(
        string message,
        string errorCode)
        : base(message)
    {
        ErrorCode = errorCode;
    }
}

Domänenfehler

Domänenfehler stellen erwartete geschäftliche Fehler dar.

Beispiele:

Product does not exist
Cart is empty
Product cannot be added to the cart
Requested quantity violates a business rule

Beispiel:

class DomainError(AppError):
    error_code = "DOMAIN_ERROR"


class ProductNotFoundError(DomainError):
    error_code = "PRODUCT_NOT_FOUND"

    def __init__(self, product_id: int):
        super().__init__(
            message=f"Product '{product_id}' was not found.",
            details={
                "product_id": product_id,
            },
        )

Konzeptionell ähnlich zu:

public class ProductNotFoundException : DomainException
{
    public int ProductId { get; }

    public ProductNotFoundException(int productId)
        : base($"Product '{productId}' was not found.")
    {
        ProductId = productId;
    }
}

Validierungsfehler

Validierungsfehler stellen ungültige Anwendungseingaben oder verletzte Einschränkungen dar.

Beispiele:

Invalid product ID
Quantity must be greater than zero
Missing required input
Invalid cart operation

Dies sind erwartete Fehler.

Sie sollten genügend strukturierte Informationen bereitstellen, damit der MCP-Host oder das LLM versteht, was korrigiert werden muss.


Infrastrukturfehler

Infrastrukturfehler stellen Fehler dar, die technische Abhängigkeiten betreffen.

Beispiele:

External API unavailable
HTTP timeout
Connection failure
Unexpected downstream response
Database unavailable

Zum Beispiel:

class InfrastructureError(AppError):
    error_code = "INFRASTRUCTURE_ERROR"


class ExternalAPIError(InfrastructureError):
    error_code = "EXTERNAL_API_ERROR"

Die Domäne darf nicht von Infrastrukturausnahmen abhängen.

Rohe Bibliotheksausnahmen sollten nicht durch die gesamte Anwendung leaken.

Zum Beispiel:

httpx.TimeoutException
        |
        v
ExternalAPITimeoutError
        |
        v
Application / Presentation

anstatt:

httpx.TimeoutException
        |
        +---------------------> MCP Host

Fehlerübersetzung

Die Infrastruktur ist dafür verantwortlich, technische Fehler auf niedriger Ebene bei Bedarf zu übersetzen.

Zum Beispiel:

HTTP 404 from product provider
          |
          v
ProductNotFoundError


HTTP timeout
          |
          v
ExternalAPITimeoutError


HTTP 500
          |
          v
ExternalAPIError

Dies verhindert, dass der Rest der Anwendung an eine bestimmte HTTP-Bibliothek gekoppelt wird.


Präsentations-Fehlergrenze

MCP-Tools sollten keine duplizierte Fehlerbehandlung enthalten.

Vermeiden Sie:

@mcp.tool
def tool_one():
    try:
        ...
    except AppError:
        ...


@mcp.tool
def tool_two():
    try:
        ...
    except AppError:
        ...


@mcp.tool
def tool_three():
    try:
        ...
    except AppError:
        ...

Die gewünschte Architektur ist:

MCP Host
   |
   v
Presentation Error Boundary
   |
   v
MCP Tool
   |
   v
Use Case
   |
   v
Domain / Repository

Bekannte Anwendungsfehler können in strukturierte MCP-freundliche Fehler umgewandelt werden.

Unerwartete Ausnahmen sollten:

logged
   |
   v
converted to generic internal error
   |
   v
returned without sensitive details

Dies ist konzeptionell ähnlich zu ASP.NET Core:

Python / MCP                 ASP.NET Core

AppError                     AppException
DomainError                  DomainException
InfrastructureError          InfrastructureException
central error boundary       IExceptionHandler / Middleware
raise                        throw
except                       catch

Strukturierte Fehler

Fehler sollten bei Bedarf strukturierte Informationen enthalten.

Beispiel:

{
  "error_code": "PRODUCT_NOT_FOUND",
  "error_type": "ProductNotFoundError",
  "message": "Product '123' was not found.",
  "details": {
    "product_id": 123
  }
}

Strukturierte Fehler verbessern:

  • das Verhalten von MCP-Clients

  • das Denken des LLM

  • die Protokollierung

  • die Beobachtbarkeit

  • automatisierte Tests

  • das Debugging


Regeln zur Fehlerbehandlung

  1. Setzen Sie rohe Infrastrukturausnahmen nicht direkt MCP-Clients aus.

  2. Duplizieren Sie keine try/except-Blöcke in jedem MCP-Tool.

  3. Verwenden Sie spezifische Domänenfehler für erwartete geschäftliche Fehler.

  4. Verwenden Sie Validierungsfehler für ungültige Eingaben und verletzte Einschränkungen.

  5. Übersetzen Sie externe technische Fehler in anwendungsspezifische Fehler.

  6. Bewahren Sie nützlichen strukturierten Kontext über details.

  7. Protokollieren Sie unerwartete Ausnahmen an der Anwendungsgrenze.

  8. Legen Sie niemals Geheimnisse, Token, Stack-Traces oder sensible Infrastrukturdaten gegenüber MCP-Clients offen.

  9. Halten Sie Fehlercodes stabil, damit Clients und automatisierte Tests sich darauf verlassen können.

  10. Die Präsentation ist dafür verantwortlich, Anwendungsfehler in MCP-freundliche Antworten zu übersetzen.


Dependency Injection und Komposition

Abhängigkeiten sollten explizit sein.

Zum Beispiel:

DummyJsonProductRepository
            |
            v
GetProductUseCase
            |
            v
MCP Tool

Die Kompositions-/Wurzelverdrahtung gehört in die Nähe des Anwendungseinstiegspunkts, nicht in die Domäne.

Das Projekt sollte versteckte globale Abhängigkeiten vermeiden, wo dies praktikabel ist.

Dies wird schrittweise eingeführt, wenn die Anwendung wächst.


Teststrategie

Die Architektur sollte es ermöglichen, Geschäftsverhalten zu testen, ohne:

starting FastMCP
calling DummyJSON
opening an HTTP port
running MCP App UI

Zum Beispiel:

Unit Test
   |
   v
GetProductUseCase
   |
   v
FakeProductRepository

Dies macht den Anwendungsfall unabhängig testbar.


Unit-Tests

Unit-Tests sollten sich konzentrieren auf:

Domain behavior
Use Cases
Validation
Error handling

unter Verwendung von Fake- oder Mock-Abhängigkeiten.


Integrationstests

Integrationstests können Grenzen separat validieren:

Infrastructure
      |
      v
DummyJSON API

und:

MCP Client
    |
    v
FastMCP Server

Diese Trennung verhindert, dass das Verhalten externer APIs jeden Geschäftstest unzuverlässig macht.


Entwicklungseinrichtung

Anforderungen:

Python 3.12+
uv

Abhängigkeiten installieren/synchronisieren:

uv sync

MCP-Server ausführen:

uv run python -m presentation.mcp.server

Standard-Endpunkt:

http://localhost:8000/mcp

Virtuelle Umgebung

Das Projekt verwendet:

.venv/

für isolierte Python-Abhängigkeiten.

uv verwaltet die Projektumgebung automatisch.

Befehle sollten im Allgemeinen folgendermaßen ausgeführt werden:

uv run ...

Zum Beispiel:

uv run python --version

Dadurch wird vermieden, sich auf global installierte Projektabhängigkeiten zu verlassen.


Entwicklungsprinzipien

Beim Erweitern dieser Vorlage:

  1. MCP-spezifischen Code in Presentation halten.

  2. Geschäftsworkflows in Application halten.

  3. Geschäftsmodelle und -verträge unabhängig von Frameworks halten, wo sinnvoll.

  4. Externe Integrationen in Infrastructure halten.

  5. Von Abstraktionen abhängen statt von konkreten Infrastructure-Implementierungen.

  6. MCP-Tools schlank halten.

  7. Umgebungsspezifische Konfiguration nicht hartkodieren.

  8. Keine Geheimnisse einchecken.

  9. Typisiertes Python bevorzugen.

  10. Externe Daten an Systemgrenzen validieren.

  11. Externe API-DTOs getrennt von Domain-Modellen halten, wenn ihre Strukturen voneinander abweichen.

  12. Use Cases unabhängig testbar machen.

  13. Explizite Abhängigkeiten verstecktem globalen Zustand vorziehen.

  14. Abstraktionen hinzufügen, wenn sie ein echtes architektonisches Problem lösen.

  15. Die Domain unabhängig von FastMCP halten.

  16. Infrastructure-Fehler übersetzen, bevor sie außerhalb ihrer Grenze offengelegt werden.

  17. Stabile strukturierte Fehlercodes verwenden.

  18. Die UI der MCP-App auf Präsentation und Interaktion fokussiert halten.

  19. Keine Geschäftslogik in MCP-Dekoratoren ablegen.

  20. Die externe API austauschbar halten.


Geplanter Lernablauf

Die Vorlage wird schrittweise aufgebaut.

FastMCP Server
      |
      v
HTTP Transport
      |
      v
Environment Configuration
      |
      v
Python Package Structure
      |
      v
Pydantic Models
      |
      v
Domain Entities
      |
      v
Repository Contracts
      |
      v
Error Hierarchy
      |
      v
Infrastructure / External API
      |
      v
Application Use Cases
      |
      v
MCP Tools
      |
      v
Dependency Composition
      |
      v
Centralized Error Handling
      |
      v
MCP Resources
      |
      v
MCP Prompts
      |
      v
MCP App UI
      |
      v
Interactive MCP Actions
      |
      v
Unit Tests
      |
      v
Integration Tests
      |
      v
Claude / Copilot integration

Endziel

Das finale Projekt sollte den vollständigen Ablauf demonstrieren:

Claude / Copilot
       |
       | MCP over HTTP
       v
FastMCP Server
       |
       v
MCP App UI
       |
       | user action
       v
MCP Tool
       |
       v
Application Use Case
       |
       v
Domain Contract
       |
       v
Infrastructure Adapter
       |
       | HTTP
       v
External Service

wobei Fehler sicher in die entgegengesetzte Richtung fließen:

External failure
       |
       v
Infrastructure Error
       |
       v
Application / Domain Error
       |
       v
Presentation Error Boundary
       |
       v
Structured MCP Error
       |
       v
Claude / Copilot

Zweck

Dieses Repository soll eine wiederverwendbare Vorlage und Lernreferenz für die Erstellung produktionsreifer FastMCP-Server und MCP-Apps mit Clean Architecture werden.

Das Projekt zeigt, wie MCP als Anwendungsgrenze behandelt werden kann, anstatt zuzulassen, dass sich MCP-spezifische Belange in der gesamten Codebasis ausbreiten.

Die zentrale Geschäftslogik sollte unabhängig bleiben von:

FastMCP
MCP transport
MCP App UI
Claude
Copilot
HTTP providers
databases
external APIs

Das macht die Anwendung einfacher zu:

maintain
test
extend
replace integrations
run in different environments
connect to different MCP hosts

wobei klare architektonische Grenzen erhalten bleiben.

F
license - not found
Not graded
quality - not tested
C
maintenance

Maintenance

Maintainers
Response time
Release cycle
Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol server that enables AI assistants to interact with a complete e-commerce application, providing authentication, product browsing, and shopping cart management through standardized MCP tools.
  • F
    license
    Not graded
    quality
    B
    maintenance
    A Python framework for building MCP servers with modular architecture, dependency injection, and built-in authentication. Enables creating scalable, testable MCP services with features like pipeline interceptors and background tasks.
    3
  • A
    license
    Not graded
    quality
    C
    maintenance
    A production-ready template for developing Model Context Protocol (MCP) servers using Python and FastMCP.
    Apache 2.0

View all related MCP servers

Related MCP Connectors

  • FastMCP commerce server starter: product catalog, search, and checkout. Deploy to Vercel in 5 min.

  • Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.

  • MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/renaisanci/mcp-clean-architecture'

If you have feedback or need assistance with the MCP directory API, please join our Discord server