mcp-typescript-sdk

This MCP server library provides a TypeScript-based API for implementing MCP over MQTT, with automatic environment detection for browser and Node.js runtimes. It exposes a clean, constructor-based API (McpMqttServer) to register tools and resources that clients can call or read, and Auto Discovery to surface servers over MQTT topics. Use the server to define tools (callable actions) and resources (readable data) that clients can discover, list, and interact with via the MCP protocol. The examples show creating a server, registering a login greeting tool and a configuration resource, then starting the server so clients can discover and interact with it. The SDK handles type safety via TypeScript types and Zod-based validation for MCP payloads, and it works over MQTT using either WebSocket (browser) or TCP (Node.js) transports.

To use it in your project, install the package, create an instance of McpMqttServer with your MQTT connection details and server metadata, then register tools and resources. Clients will discover the server on the MQTT network, retrieve the list of available tools and resources, and invoke tools or read resources as needed. The API supports lifecycle management (start/stop), topic inspection, and optional access control via rbac if required.

Prerequisites:\n- Node.js >= 18\n- npm (or yarn)\n\n1) Install the package:\nbash\nnpm install @emqx-ai/mcp-mqtt-sdk\n\n2) Set up your TypeScript project (if using TS): ensure tsconfig.json targets a modern module system and includes lib types for DOM (if browser support is needed) and Node.\n3) Build/run your MCP server as part of your application code. For browser environments, use the universal transport provided by the SDK; for Node.js, MQTT TCP transport is used by default.\n4) If you plan to publish a runnable example, compile TypeScript to JavaScript (tsc) and run with Node.js, or use a bundler for browser environments.\n\nNotes:\n- Ensure MQTT broker is reachable from both server and client components.\n- Enable TLS/secure transport in production as needed.\n- Consider enabling rbac for production deployments to constrain tool/resource access.

Tips and common issues:\n- Environment detection may default to browser or Node.js in hybrid setups; verify your runtime environment so MQTT transport uses the intended protocol.\n- Validate input schemas with the provided TypeScript types to catch mismatches early.\n- If you expose resources with listChanged: true, clients may poll or subscribe for updates; adjust subscribe settings accordingly.\n- When deploying, consider bundling the server code for browsers if you plan to run a UI-driven MCP client that also serves MCP logic.\n- Use the example serverId and serverName conventions to ensure hierarchical naming and conflict-free discovery on MQTT topics.