kbb-mcp-relay

MCP server for InfoRapid KnowledgeBase Builder. It allows an AI assistant to control a running instance of the web application — creating nodes and relations, reading the graph, and switching views or layouts.

The relay handles the MCP protocol and forwards commands via WebSocket on 127.0.0.1 to the running application. An execution layer in the frontend runs each command, ensuring that undo grouping and redrawing work identically to manual user interactions.

Prerequisites

• Node 20 or later
• A running instance of KnowledgeBase Builder with the built-in bridge (mcpbridge.js and corresponding kmap.js)

Starting

npx -y kbb-mcp-relay --allow-origin http://localhost:8080

| Option | Description | |---|---| | --port <n> | WebSocket port, default 8765 | | --host <address> | Default 127.0.0.1 | | --allow-origin <url> | Allowed origin (can be specified multiple times). If omitted, any origin is accepted — always set in production. | | --insecure-no-pairing | Skip pairing. For testing only. |

Pairing

On startup, the relay prints a 4-digit pairing code to stderr. When connecting for the first time, the application displays a pairing dialog where the user enters this code. The application stores a persistent token so subsequent connections connect automatically.

The assistant can retrieve the pairing code via the kbb_status tool.

Tools

57 task-oriented tools rather than a 1:1 mapping of backend actions:

• Read — kbb_status, kbb_get_stats, kbb_get_selected, kbb_search_nodes, kbb_get_node, kbb_get_neighborhood, kbb_get_categories, kbb_get_category_items, kbb_get_attachments, kbb_get_whiteboards, kbb_list_bookmarks, kbb_list_databases, kbb_get_ui_state
• Write — kbb_create_node, kbb_create_subgraph, kbb_update_node, kbb_link, kbb_delete, kbb_set_style, kbb_set_diagram, kbb_create_category, kbb_update_category, kbb_add_attachment, kbb_detach_attachment, kbb_delete_attachment, kbb_set_node_position, kbb_create_whiteboard, kbb_move_kanban_card, kbb_batch, kbb_undo
• Databases — kbb_create_database, kbb_open_database, kbb_delete_database
• Import / Export — kbb_export_database, kbb_import_database, kbb_import_pseudocode
• View — kbb_focus_node, kbb_select_nodes, kbb_set_display_mode, kbb_set_layout, kbb_adjust_view, kbb_save_bookmark, kbb_restore_bookmark, kbb_set_camera_3d, kbb_toggle_ui_panel
• Screenplay — kbb_run_screenplay, kbb_animate_cursor_move, kbb_animate_click, kbb_animate_drag, kbb_animate_type_text, kbb_narrate_speech, kbb_show_overlay_panel, kbb_present_node
• Events — kbb_get_events, kbb_wait_for_event

kbb_create_subgraph is the primary workhorse: it creates multiple nodes and their connections in a single server call and a single undo step.

Every write operation creates exactly one undo step with the prefix AI: — any changes made by the assistant can be reverted with one click. Tools that declare dryRun report what they would do without touching the database; the smoke test pins that list so the flag cannot drift away from the executor.

Two tools are registered but always answer NOT_SUPPORTED: kbb_import_wikipedia and kbb_import_wikidata. Both run through app dialogs that the bridge cannot drive reliably — their descriptions point to kbb_create_subgraph as the way to build the same graph.

Deleting a database cannot be undone by kbb_undo, and kbb_delete_database opens the named database first, because the backend always deletes the one currently open.

Security

The relay listens exclusively on the loopback address, validates the Origin header, and enforces pairing via a code entered by the user in the web application. WebSockets do not have same-origin policies by default — pairing ensures that other local processes or open web pages cannot manipulate the knowledge base.

Tests

npm test

The smoke test runs standalone without requiring a live web application instance: it mocks the browser endpoint to verify the MCP handshake, the complete tool list by name, per-tool schema details, the dryRun allowlist, the timeout classes, the pairing flow, command forwarding, error propagation, progress reporting, parameter schema validation, and event buffers.