aspro-mcp

Ein Model Context Protocol-Server, der die Aspro.Cloud REST-API für LLM-Clients (Claude Desktop, Claude Code usw.) bereitstellt. Der Server wird mit der gebündelten OpenAPI-Spezifikation ausgeliefert, sodass das Modell Module, Entitäten und Methoden selbstständig entdecken und sicher aufrufen kann.

Funktionen

• Selbsterklärend. Das Modell durchsucht die API über aspro_list_modules → aspro_list_entities → aspro_list_methods → aspro_describe und führt erst dann aspro_call aus – Endpunkte müssen nicht auswendig gelernt werden.

• Teilstring-Suche über Modul / Entität / Methode / Pfad / Beschreibung / Tags.

• Form-urlencoded POSTs standardmäßig (der von Aspro erwartete Content-Type), mit Unterstützung für Arrays und verschachtelte Objekte.

• Pfadparameter-Ersetzung für /get/{id}, /update/{id}, /delete/{id} und ähnliche.

• Mandanten-spezifische Konfiguration über ASPRO_COMPANY (Subdomain) oder die vollständige ASPRO_BASE_URL.

Installation

git clone https://github.com/bssth/aspro-mcp.git
cd aspro-mcp
npm install
npm run build

Erfordert Node.js ≥ 18.

Konfiguration

Kopieren Sie die Beispiel-Umgebungsdatei und füllen Sie sie aus:

cp .env.example .env

ASPRO_COMPANY=your_company        # the {company} part of https://{company}.aspro.cloud
ASPRO_API_KEY=your_api_key_here   # passed as ?api_key=... on every request
# ASPRO_BASE_URL=...              # optional; overrides the URL built from ASPRO_COMPANY
# ASPRO_TIMEOUT_MS=30000          # optional; default 30s

Einen API-Schlüssel erhalten Sie in Ihrem Aspro.Cloud-Konto unter Einstellungen → Integrationen → API.

Mit einem Client verbinden

Claude Desktop / Claude Code

Fügen Sie den Server zu Ihrer MCP-Konfiguration hinzu:

{
  "mcpServers": {
    "aspro": {
      "command": "node",
      "args": ["/absolute/path/to/aspro-mcp/dist/index.js"]
    }
  }
}

Der Server liest seine .env-Datei aus dem Projektstammverzeichnis, unabhängig vom Arbeitsverzeichnis, aus dem der Client ihn startet.

Andere MCP-Clients

Jeder Client, der MCP über stdio unterstützt, kann node dist/index.js (oder npm start) ausführen.

Verfügbare Tools

Der empfohlene Ablauf ist search/list_* → describe → call.

Entwicklung

npm run dev      # tsc --watch
npm run build    # tsc
npm run smoke    # offline: exercises the spec indexer and URL builder

Der Smoke-Test greift nicht auf das Netzwerk zu – er prüft, ob die gebündelte OpenAPI-Spezifikation geparst werden kann, ob Operationen beschrieben werden können und ob der URL-Builder wohlgeformte URLs erzeugt.

Projektstruktur

src/
  index.ts    MCP server (tool registration + entry point)
  config.ts   .env loading and validation
  client.ts   HTTP client (URL building, form-urlencoded POSTs, timeouts)
  spec.ts    OpenAPI indexer (modules / entities / methods / search / describe)
  smoke.ts    offline smoke test
spec/
  openapi.json  bundled Aspro.Cloud OpenAPI spec

Sicherheitshinweise

• Der API-Schlüssel wird aus der Umgebung gelesen und an jede Anfrage als ?api_key=... angehängt. Committen Sie niemals die .env-Datei.

• Der Server verfügt über keine Whitelist – sobald er konfiguriert ist, kann er jeden Endpunkt aufrufen, den die Spezifikation beschreibt (einschließlich destruktiver Aktionen wie /delete/{id}). Verwenden Sie einen dedizierten API-Schlüssel mit den minimal erforderlichen Berechtigungen.

• Behandeln Sie Tool-Ausgaben als nicht vertrauenswürdig: Aspro-Entitäten (Werte benutzerdefinierter Felder, Beschreibungen usw.) können vom Benutzer bereitgestellte Inhalte enthalten.

Mitwirken

Issues und PRs sind willkommen. Bitte führen Sie npm run build && npm run smoke aus, bevor Sie etwas einreichen.

Lizenz

MIT – siehe LICENSE.

aspro-mcp ist ein inoffizieller Drittanbieter-Connector und steht in keiner Verbindung zu Aspro.Cloud.