MCP Connector (oco_mcp) #

oco_mcp macht aus einer owncloud.online-Instanz einen MCP-Server (Model Context Protocol). KI-Assistenten wie Claude (Desktop/Code), Editoren oder eigene Agenten verbinden sich damit und arbeiten mit den Dateien, Freigaben, Tags und Kommentaren des angemeldeten Nutzers — mit exakt dessen Berechtigungen, standardmäßig nur lesend.

English? See the app's README for the English version. Quellcode: apps/oco_mcp/ im Server-Repository.

Inhalt #

1. Was ist MCP?
2. Schnellstart
3. Wie es funktioniert (Protokoll)
4. Authentifizierung
5. Rechte-Modell
6. Werkzeug-Referenz (Tools)
7. Ressourcen (Dateien als Kontext)
8. KI-Dokumentensuche ai_ask (optional)
9. Clients anbinden
10. Konfiguration
11. Sicherheit
12. Fehlerbehebung
13. Eigene Tools ergänzen

1. Was ist MCP? #

Das Model Context Protocol ist ein offener Standard, über den KI-Modelle mit externen Systemen sprechen. Ein MCP-Server bietet dem Modell drei Dinge an:

• Tools — aufrufbare Funktionen („liste meine Dateien", „lege einen öffentlichen Link an").
• Ressourcen — Inhalte, die der Client als Kontext anhängen kann (hier: die Dateien des Nutzers).
• Sitzungen — der Client initialisiert einmal und ruft dann beliebig viele Tools in dieser Sitzung auf.

oco_mcp implementiert die MCP-Transportvariante Streamable HTTP (JSON-RPC 2.0 über POST). Das Modell sieht dadurch die Cloud des Nutzers wie einen Werkzeugkasten: es kann suchen, lesen, (falls freigeschaltet) schreiben und teilen — aber niemals mehr, als der Nutzer selbst dürfte.

2. Schnellstart #

# 1. App installieren (Ordner nach apps-external/ bzw. apps/ legen) und aktivieren
occ app:enable oco_mcp

# 2. Optional: Schreib- und Verwaltungs-Tools freischalten (Standard: nur lesen)
occ config:app:set oco_mcp enable_write --value=yes

# 3. In owncloud.online ein App-Passwort erzeugen:
#    Einstellungen -> Sicherheit -> App-Passwörter

Endpoint: POST https://<server>/apps/oco_mcp/mcp (ohne Rewrite-Regeln: https://<server>/index.php/apps/oco_mcp/mcp)

3. Wie es funktioniert (Protokoll) #

Eine MCP-Sitzung besteht aus drei Schritten:

Schritt 1 — initialize: Der Client stellt sich vor, der Server antwortet mit seinen Fähigkeiten und vergibt eine Session-ID im Antwort-Header Mcp-Session-Id.

curl -u "benutzer:app-passwort" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -D - \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2025-11-25","capabilities":{},
        "clientInfo":{"name":"mein-client","version":"1.0"}}}' \
  https://cloud.example.com/apps/oco_mcp/mcp

Antwort (gekürzt) — die Session-ID steht im Header:

Mcp-Session-Id: f1fff858-70bc-49ed-bdfc-bed963d5b57b

{"jsonrpc":"2.0","id":1,"result":{
  "protocolVersion":"2025-11-25",
  "serverInfo":{"name":"owncloud.online","version":"1.0.3"},
  "instructions":"You are connected to an owncloud.online instance as user \"…\" …"}}

Schritt 2 — Tools auflisten/aufrufen: Jede weitere Anfrage schickt die Session-ID im Header Mcp-Session-Id mit:

curl -u "benutzer:app-passwort" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: f1fff858-…" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  https://cloud.example.com/apps/oco_mcp/mcp

Tool-Aufruf:

  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
        "name":"files_list","arguments":{"path":"/"}}}'

Schritt 3 — Sitzung beenden (optional): DELETE auf den Endpoint mit der Session-ID beendet die Sitzung. Sitzungen verfallen sonst automatisch nach einer Stunde Inaktivität (dateibasierter Session-Store im Datenverzeichnis des Servers).

Fertige MCP-Clients (Claude, mcp-remote, MCP-SDKs) erledigen all das automatisch — die curl-Beispiele zeigen nur, was unter der Haube passiert.

4. Authentifizierung #

Der Endpoint akzeptiert ausschließlich:

• Basic-Auth mit App-Passwort (empfohlen): Authorization: Basic base64("benutzer:app-passwort"). App-Passwörter erzeugt jeder Nutzer selbst unter Einstellungen → Sicherheit → App-Passwörter.

Die Basic-Zugangsdaten werden bei jeder Anfrage neu validiert. Reine Browser-Cookie-Sitzungen, Bearer-Header und beliebige Platzhalter-Header werden abgelehnt. Dadurch kann keine im Browser mitgeschickte Session heimlich MCP-Aufrufe auslösen.

Das normale Kontopasswort wird ebenfalls abgelehnt. Nur ein widerrufbares App-Passwort ist zulässig; dadurch bleibt eine aktive Zwei-Faktor-Pflicht erhalten.

5. Rechte-Modell #

Fehler erscheinen als reguläre MCP-Tool-Fehler, die das Modell lesen und dem Nutzer erklären kann — kein stiller Abbruch.

Pfade werden dabei strikt geprüft: . und .. sind in jedem Tool verboten (nicht aufgelöst, sondern abgelehnt), und zwar bevor der Server überhaupt auf den Speicher zugreift. Fehler aus angebundenen Backends — allen voran ai_ask — erreichen den Client nur als kurze, allgemeine Meldung; die vollständige Ursache steht ausschließlich im Serverprotokoll. So können weder Gateway-Adressen noch Datenbankfehler oder interne Dateipfade über einen MCP-Client abfließen.

6. Werkzeug-Referenz (Tools) #

Dateien (lesend):

Dateien (schreibend, benötigt enable_write):

Freigaben:

Tags & Kommentare:

Verwaltung (nur Administratoren):

Meta:

Die genauen Parameter jedes Tools liefert tools/list als JSON-Schema — MCP-Clients zeigen sie automatisch an.

7. Ressourcen (Dateien als Kontext) #

Zusätzlich zu Tools exponiert der Server die Nutzer-Dateien als MCP-Ressourcen, sodass Clients sie nativ durchstöbern und an den Kontext anhängen können:

• owncloud:/// — JSON-Auflistung des Wurzelordners; jeder Eintrag trägt eine uri, die direkt lesbar ist.
• owncloud:///{pfad} — beliebige Datei (Text oder binär) oder Ordnerliste per Pfad. Wichtig: Da URI-Template-Variablen nur ein Segment ohne Schrägstrich matchen, werden verschachtelte Pfade mit %2F statt / geschrieben (RFC 6570), z. B. owncloud:///Dokumente%2Fbericht.txt.

Binärdateien kommen als Base64, Text als UTF-8. Lesegrenze 5 MB, strikt auf den Speicher des angemeldeten Nutzers beschränkt.

8. KI-Dokumentensuche ai_ask (optional) #

Ist die optionale App ai_documents installiert und aktiv, erscheint zusätzlich das Tool ai_ask: Retrieval-Augmented Generation über die indizierten Dokumente des Nutzers (mit dessen Rechten), Antwort inklusive zitierter Quellen.

Parameter: question, scope (all | folder | selection), path (bei folder), file_ids (kommagetrennt, bei selection), mode (qa | summary | extract | report).

oco_mcp hat keine harte Abhängigkeit auf ai_documents — auf Servern ohne die App fehlt das Tool einfach (kein Fehler).

9. Clients anbinden #

Claude Desktop (über mcp-remote) #

claude_desktop_config.json:

{
  "mcpServers": {
    "owncloud": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://cloud.example.com/apps/oco_mcp/mcp",
        "--header", "Authorization: Basic <base64 von benutzer:app-passwort>",
        "--transport", "http-only"
      ]
    }
  }
}

--transport http-only passt zum Server: er antwortet mit Streamable-HTTP-JSON und hat bewusst keinen SSE-GET-Stream. End-to-end mit mcp-remote verifiziert (dieselbe Brücke, die Claude Desktop nutzt): initialize → notifications/initialized → tools/list → tools/call.

Claude Code (CLI) #

claude mcp add owncloud \
  --transport http \
  https://cloud.example.com/apps/oco_mcp/mcp \
  --header "Authorization: Basic <base64 von benutzer:app-passwort>"

Eigener Client / Skript #

Beliebige MCP-SDKs (TypeScript, Python, PHP, …) mit Transport „Streamable HTTP" funktionieren; alternativ direkt JSON-RPC per HTTP wie in Abschnitt 3.

Base64 für den Basic-Header erzeugen:

echo -n "benutzer:app-passwort" | base64

10. Konfiguration #

Mehr ist nicht zu konfigurieren — Authentifizierung und Rechte kommen vollständig aus owncloud.online selbst.

11. Sicherheit #

• Kein Cookie-Zugriff: Basic-Zugangsdaten werden pro Request geprüft; Browser-Sessions und beliebige Ersatz-Header werden abgelehnt → kein CSRF.
• App-Passwörter statt Login-Passwort: einzeln widerrufbar unter Einstellungen → Sicherheit.
• Read-only als Standard: Schreiben ist eine bewusste Admin-Entscheidung (enable_write).
• Nutzer-Scope: Jedes Tool läuft mit der Identität und den Rechten des authentifizierten Nutzers — niemals darüber hinaus.
• Vendor-Isolation: Die gebündelten Bibliotheken (MCP-SDK u. a.) werden lazy nur für MCP-Requests geladen und enthalten per composer-replace kein Guzzle und keine psr/*-Duplikate — sie können Core-Bibliotheken konstruktionsbedingt nicht überschatten.
• Limits: Lesegrenzen (1 MB Standard / 10 MB Maximum bei files_read, 5 MB bei Bildern und Ressourcen), Löschen geht bei aktiver Papierkorb-App in den Papierkorb, Sitzungen verfallen nach 1 Stunde.

12. Fehlerbehebung #

13. Eigene Tools ergänzen #

Zwei Schritte, kein Framework-Kleber — ausführlich (mit Codebeispiel) im englischen README:

1. Public-Methode in einer Klasse unter lib/Tools/ anlegen — Signatur + DocBlock werden automatisch zum Tool-Schema. Schreib-/Admin-Gating über $this->assertWrite() bzw. $this->assertAdmin($this->isAdmin).
2. In lib/Mcp/ServerFactory.php registrieren: $builder->addTool([FilesTool::class, 'countFiles'], 'files_count');

Für Tools, die eine optionale Fremd-App anbinden, zeigt AiDocumentsTool das Muster: Klassenname nur als String, class_exists- Guard, Registrierung nur bei aktivierter App.

Lizenz: AGPL-3.0-only · Autor: BW-Tech GmbH · Modified by BW-Tech GmbH for owncloud.online (PHP 8.4).