API: mcp-business-tools

Ort: work7_laendletech/docs/api/api-mcp-business-tools.md

Überblick

• Base-URL / Prefix: /mcp
• Auth: JSON-RPC mit Work7-Kontext-Headern
• Format: JSON-RPC 2.0
• Source of truth: mcp/src/central-mcp-server/contracts/work7-tools.v1.md

Endpoint(s)

tools/list

Zweck:

Liefert die verfguebaren Business-Tools im MCP-Server.

tools/call mit customers.*

Zweck:

Werkzeuge fuer Kundenverwaltung.

Bekannte Tools

• customers.list
• customers.search
• customers.get
• customers.count
• customers.create
• customers.update
• customers.delete

tools/call mit projects.*

Zweck:

Werkzeuge fuer Projektverwaltung.

Bekannte Tools

• projects.list
• projects.get
• projects.create
• projects.update

tools/call mit rapports.*

Zweck:

Werkzeuge fuer Rapporte, Eintraege, Materialien und Versand.

Bekannte Tools

• rapports.list
• rapports.get
• rapports.create
• rapports.add_entry
• rapports.add_material
• rapports.complete

tools/call mit offers.*

Zweck:

Werkzeuge fuer Angebotsprozesse.

Bekannte Tools

• offers.list
• offers.get
• offers.create
• offers.update
• offers.add_item
• offers.get_pdf_link
• offers.accept
• offers.send

tools/call mit invoices.*

Zweck:

Werkzeuge fuer Rechnungsprozesse inklusive Umwandlung aus Angeboten/Rapporten.

Bekannte Tools

• invoices.list
• invoices.get
• invoices.create
• invoices.update
• invoices.add_item
• invoices.get_pdf_link
• invoices.mark_paid
• invoices.send

tools/call mit work7.meta

Zweck:

Liefert Work7-Vertragsmetadaten wie toolsVersion, Tool-Inventar und Entitaeten.

Standard Request-Schema

Feld	Typ	Pflicht	Beschreibung
jsonrpc	string	ja	2.0
id	string	ja	Request-ID
method	string	ja	tools/call
params.name	string	ja	z. B. offers.create
params.arguments	object	nein	Tool-spezifische Parameter

Standard Response 200

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": [
      {
        "type": "json",
        "json": {
          "success": true,
          "data": {}
        }
      }
    ]
  }
}

Fehler

HTTP	Bedeutung	Body-Hinweis
400	Toolname/Argumente ungültig	JSON-RPC error
401	Auth fehlt	JSON-RPC error
403	Rollen-/Firmenkontext unzulässig	JSON-RPC error
500	Toolfehler	JSON-RPC error oder result.isError

Rate Limiting / Limits

• Max Requests: Nicht separat dokumentiert
• Timeout: Remote-Aufruf in Agent-Service standardmaessig 15s
• Max Payload: Abhaengig vom Tool; ueblicherweise kleine bis mittlere Argumentobjekte

Breaking Changes / Versionierung

• Tool-Namen und Semantik sind Vertragsbestandteile.
• Statuswert- und Feldumbauten in offers.*, invoices.*, rapports.* sind fuer Agenten breaking.

Beispiel (curl)

curl -sS -X POST "{{mcp_base_url}}/mcp" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {{mcp_api_key}}" \
  -H "X-Work7-User-Id: 18" \
  -H "X-Work7-User-Role: 1" \
  -H "X-Work7-Company-Id: mueller-bau-de" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "customers.list",
      "arguments": {}
    }
  }'

Verwandte Notes

• Feature-Spec: work7
• OpenAPI/Schema: MCP JSON-RPC

Follow-ups

• [ ] Postman Collection prüfen: passt es in bestehende Collection? Sonst neu anlegen → work7_laendletech/src/postman/ 📅 2026-04-16
• [ ] In Feature-Spec verlinken falls zugehörig 📅 2026-04-16