Lokale Entwicklung

Betrieb der MCP (Model Context Protocol) Services aus dem Quellcode gegen einen lokalen OctoMesh-Stack auf Ihrem eigenen Rechner.

Voraussetzungen

• .NET 10 SDK
• Die lokal laufenden OctoMesh-Backend-Services — siehe Developer Guide → Erste Schritte und Developer PowerShell für den Start-Octo-Workflow
• Erreichbares MongoDB (die Standard-Infrastruktur von Start-Octo stellt es unter localhost:27017 bereit)
• Verfügbares octo-cli — wird beim einmaligen Tenant-Bootstrap und als Referenzverhalten für neue Tools genutzt

Zuerst die Backend-Services starten

Die MCP Services rufen Identity / Asset / Communication / Bot / Reporting über HTTP auf. Das PowerShell-Cmdlet Start-Octo startet sie nativ auf dem Entwicklungsrechner:

Start-Octo -nonInteractive $true

Die Ports, an die sich die einzelnen Services lokal binden (verwendet von den Standardwerten in appsettings.json — siehe Konfiguration):

Service	HTTPS
Asset	https://localhost:5001/
Identity	https://localhost:5003/
Communication	https://localhost:5005/
Bot	https://localhost:5007/
Reporting	https://localhost:5009/

Beenden Sie sie mit Stop-Octo, wenn Sie fertig sind.

Die MCP Services aus dem Quellcode betreiben

cd octo-mcp-service/src/McpServices
dotnet run --environment Development

Im Development-Modus liest der Server appsettings.json + appsettings.Development.json und stellt beide Transporte bereit:

Transport	URL
HTTP	http://localhost:5016/mcp
HTTPS	https://localhost:5017/mcp

Der HTTPS-Port verwendet das lokale Dev-Zertifikat (dotnet dev-certs https --trust, falls Ihr Betriebssystem ihm noch nicht vertraut).

Der Dev-Server zählt beim Start rund 187 Tool-Methoden auf. Verfolgen Sie die Ausgabe, um einen sauberen Start zu bestätigen — Startfehler tauchen als geloggte Exceptions auf, bevor der Host zu lauschen beginnt.

Ihren lokalen Server bei Claude Code registrieren

# HTTP (most common — no cert hassle)
claude mcp add --transport http --scope local octomesh-local http://localhost:5016/mcp

# HTTPS (only if your dev profile binds HTTPS and you trust the dev cert)
claude mcp add --transport http --scope local octomesh-local https://localhost:5017/mcp

// Claude Desktop — claude_desktop_config.json
{
  "mcpServers": {
    "octomesh-local": {
      "type": "http",
      "url": "http://localhost:5016/mcp"
    }
  }
}

Überprüfen:

claude mcp list
# octomesh-local: http://localhost:5016/mcp (HTTP) - ✓ Connected

Starten Sie Claude Code neu, damit der Tool-Katalog aufgezählt wird. Authentifizieren Sie sich über interaktives OAuth (/mcp → wählen Sie den Server; siehe unten für den Hinweis zum Dev-Zertifikat) oder mit dem in-band-Device-Flow authenticate(tenantId="<your local tenant>").

Legacy stdio bridge

Frühere Versionen lieferten src/mcp-bridge.js aus, einen Node-basierten stdio→HTTPS-Shim, der von älteren Claude-Code-Releases benötigt wurde. Dieser Shim wurde entfernt. Die direkte HTTP-Registrierung ist einfacher und unterstützt das Tenant-Routing pro Aufruf.

Interaktives OAuth und das lokale Dev-Zertifikat

Der interaktive OAuth-Flow (Dynamic Client Registration + Authorization Code + PKCE) bringt Claude Code selbst dazu, den lokalen Identity Service unter https://localhost:5003 aufzurufen — Registrierung, Discovery und Token-Anfragen laufen alle innerhalb des Claude-Code-Prozesses, nicht in Ihrem Browser.

Das schlägt out of the box mit unable to verify the first certificate fehl: Claude Code ist ein Bun-kompiliertes Binary mit eingefrorenem CA-Store. Es ignoriert NODE_EXTRA_CA_CERTS für selbstsignierte Leaf-Zertifikate (das ASP.NET-Dev-Zertifikat ist ein Leaf, keine CA) und es liest auch nicht den Trust-Store des Betriebssystems — daher helfen weder dotnet dev-certs https --trust noch das Hinzufügen des Zertifikats zum macOS-Schlüsselbund.

Der einzige funktionierende Workaround für die lokale Entwicklung ist das Deaktivieren der TLS-Verifikation für den Claude-Code-Prozess, z. B. über ~/.claude/settings.json:

{
  "env": {
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}

Dev machines only

NODE_TLS_REJECT_UNAUTHORIZED=0 deaktiviert die Zertifikatsverifikation für alle TLS-Verbindungen des Prozesses. Verwenden Sie es nur auf einem lokalen Entwicklungsrechner gegen localhost-Services — niemals gegen geteilte oder Produktions-Endpunkte (diese haben echte Zertifikate und benötigen keinen Workaround).

Der Device-Flow (Tool authenticate) benötigt dies nicht: Der Browser übernimmt die Anmeldung (und kann dem Dev-Zertifikat normal vertrauen), und die Token-Aufrufe laufen innerhalb des .NET-Prozesses des MCP-Servers, der den Trust-Store der Maschine verwendet.

Die Test-Suite ausführen

# Full suite (~400 tests, ~250 ms)
dotnet test Octo.McpServices.sln -c DebugL

# Filter to a single tool class
dotnet test --filter "FullyQualifiedName~TenantManagementToolsTests"

# CI parity (uses Release + private NuGet feed)
dotnet test Octo.McpServices.sln -c Release

Der CI-Build läuft im Release-Modus gegen den privaten NuGet-Feed ($(nugetPrivateServer)), nicht DebugL. Bilden Sie dies lokal nach, wenn Sie einen konfigurationsabhängigen Fehler vermuten.

Fallstricke bei der lokalen Entwicklung

• Das CkTypeId-Format ist Name-VersionUint, nicht SemVer. new CkTypeId("MyType-1") funktioniert; new CkTypeId("MyType-1.0.0") wirft eine Exception, weil das SDK die Version als uint parst.
• OctoObjectId muss eine 24-stellige Hex-Zeichenkette sein. Verwenden Sie in Tests realistische Werte wie "507f1f77bcf86cd799439011".
• Verwenden Sie SDK-Clients nicht über Requests hinweg erneut. Die SDK-Clients cachen ServiceUri beim ersten Gebrauch; wird ein Client über Tenants hinweg geteilt, wird der zweite Aufruf zum falschen Tenant geroutet. Gehen Sie immer über IOctoServiceClientFactory.Create*Client(tenantId, accessToken) — die *ClientContext.TryBuild-Helfer erledigen das für Sie.
• TreatWarningsAsErrors ist aktiviert. Fehlende XML-Doku an einem öffentlichen Member (CS1591) bricht den Build.

Den vollständigen Katalog der Konventionen (Response-Envelope, optimistisches Locking, File-Transfer-Architektur, Aggregation-Mapper) finden Sie in CLAUDE.md im Repository.