mcp-server-kilango

Operator MCP server for Kilango. It wraps Kilango's operator/control API (/v1 on the gateway) as MCP tools so an AI assistant can build and manage portals in a Kilango workspace: create/manage portals, pages, blocks and app widgets (including drag-and-drop reordering), install apps, and connect them to their backend systems.

Portal end-users only ever see widgets — Kilango holds the broad backend access. This server operates the studio/operator plane on the operator's behalf.

Auth & tenancy model

One host maps to one company's Kilango workspace (kilango.bos.mcp.borgels.com, kilango.spz…, kilango.one…), exactly like the e-conomic servers in the fleet. Access is gated by the Entra group SG-MCP-kilango-<company> at the borgels MCP gateway; the gateway forwards the verified user as X-MCP-User (recorded in the audit log). The server authenticates to Kilango with a single shared, workspace-bound API key (KILANGO_API_KEY, a hub_live_… key that self-scopes to that one workspace). Mint an ADMIN write key so full portal building (incl. deletes/publish) works. The key's own role/scopes are the real capability boundary — Kilango enforces them server-side.

Tools

Hybrid surface — curated golden-path tools plus a contract-driven escape hatch:

• Discovery — kilango_get_workspace, kilango_get_meta, kilango_get_vocabulary, kilango_search_operations, kilango_describe_operation.
• Portals — list/get/create/update, readiness, publish/unpublish/archive, preview, get/save navigation, delete.
• Pages & blocks — list/get pages, get blocks, create/update/delete page, save layout, add/update/delete content block, kilango_place_widget, kilango_update_widget, kilango_delete_widget, and drag-and-drop: kilango_move_block / kilango_reorder_blocks.
• Apps — catalog list/get, connectors, installations list/get, install/uninstall, list/activate/deactivate per portal, and kilango_connect_app (see below).
• Connections — list/get/health-check/delete.
• Escape hatch — kilango_call_operation(operationId, {path, query, body}) covers every operation in /v1/openapi.json not wrapped by a curated tool.

Whole-document writes (save layout, save navigation, reorder blocks) require an If-Match ETag; the client fetches and sends it automatically and retries once on a 412.

Connecting apps

kilango_connect_app(appKey, portalRef?):

• No credentials (native/scaffold apps) → installs (and activates if a portal is given).
• API-key apps (fynk, pipedrive, dalux, …) → returns a one-time browser URL (/kilango/connect-app) where the operator enters the secret. It goes straight to Kilango's encrypted vault via save_connection — never through the chat, never persisted or logged here. Then the app is installed, connected, activated (if a portal was given), and health-checked.
• OAuth apps (e.g. SharePoint) → returns a clear "not supported yet" message. Kilango's OAuth connect flow is a planned fast-follow (it currently returns 501 oauth_flow_not_implemented); once it ships, this tool switches to the redirect flow.

Configuration

See .env.example. Key vars: KILANGO_API_BASE_URL, KILANGO_PUBLIC_BASE_URL, KILANGO_API_KEY, KILANGO_ENABLE_WRITES (coarse kill-switch), KILANGO_AUDIT_LOG, MCP_HTTP_TOKEN (protects the loopback /mcp).

Develop

npm install
npm run typecheck
npm test
npm run dev        # stdio transport
npm run dev:http   # HTTP transport on :3000

Live smoke test against a real (dev) Kilango gateway — also cross-checks the curated tool paths against the live /v1/openapi.json:

KILANGO_API_BASE_URL=https://<dev-gateway> KILANGO_API_KEY=hub_test_... npm run smoke:live

Deploy

See deploy/ for the docker-compose service block, hosts.json entries, Caddy site blocks, and example env files to copy into ~/mcp on borgels-1 (mirrored in bos-server-config). The image publishes to ghcr.io/borgels/mcp-server-kilango:latest on push to main.