@kody-bot/connector-kit

Shared protocol helpers and types for Kody remote connectors.

This package is intentionally small. It exists to hold stable connector boundaries that are shared by Kody and independently shipped connector repos.

Install

npm install @kody-bot/connector-kit

Exports

• @kody-bot/connector-kit/protocol — connector WebSocket message types, parsers, serializers, and JSON-RPC helpers.
• @kody-bot/connector-kit/urls — connector route, session key, and WebSocket URL helpers.
• @kody-bot/connector-kit/schema — Kody JSON Schema metadata helpers.
• @kody-bot/connector-kit — all public exports.

Protocol

Remote connectors open an outbound WebSocket to Kody and exchange JSON messages:

• connector to Kody: connector.hello, connector.heartbeat, connector.jsonrpc
• Kody to connector: server.ping, server.ack, server.error

The connector is expected to answer MCP-style JSON-RPC requests such as tools/list and tools/call inside connector.jsonrpc envelopes.

Connector URLs

Production connector ingress URLs are username-scoped:

userScopedConnectorWebSocketUrl({
	workerBaseUrl: 'https://heykody.dev',
	username: 'kentcdodds',
	instanceId: 'home',
})
// wss://heykody.dev/@kentcdodds/connectors/home

Connector names must match ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$. Use normalizeRemoteConnectorInstanceId and isValidRemoteConnectorName from @kody-bot/connector-kit/urls to normalize and validate names before connecting.

The connector.hello message requires connectorId (trimmed and lowercased to match the URL path) and sharedSecret. connectorKind is optional and ignored by Kody.