Smithery

Publishing to Smithery, the @modelcontextprotocol/sdk-based build, and the local playground.

---

Smithery is a public registry of MCP servers. Users install with one click from a Smithery-aware client. The server is published at @jango-blockchained/advanced-homeassistant-mcp.

What Smithery wants

Smithery scans the running server and asks for its tool manifest. To play nice with the scanner, the server:

1. Skips HASS_TOKEN validation when SMITHERY_SCAN=true is set. The scanner doesn’t have your HA credentials.
2. Exposes the same tools/list response as the other entry points.
3. Speaks the standard MCP protocol over the configured transport (HTTP for the production build, STDIO for local development).

The src/config/app.config.ts validation function already handles SMITHERY_SCAN. Nothing else needs to be configured for the server to be Smithery-compatible.

The build

The Smithery entry point lives at src/smithery-sdk.ts and uses the official @modelcontextprotocol/sdk. The build script:

bun run smithery:build

This produces dist/smithery.js, a single-file bundle that Smithery’s container can run. Externals are kept inline (the bundle is self-contained for the Smithery sandbox).

The container image is built from Dockerfile.smithery, which:

• Uses oven/bun:1-slim as the base
• Copies the prebuilt dist/smithery.js
• Exposes the port from PORT (default 7123)
• Sets HOST=0.0.0.0
• HEALTHCHECK calls GET /health on the local port

The full container path on the registry is dist/smithery.js inside Dockerfile.smithery. The published image is the one Smithery deploys to their infrastructure when a user clicks install.

Local debug

Before publishing, you can run the server in a local Smithery-style playground:

npx @smithery/cli playground-stdio -- npm run start:stdio

This opens a Smithery-aware REPL that talks to your local STDIO server. You can:

• List the tools Smithery will see (tools/list).
• Call any tool with arguments.
• See the exact JSON-RPC envelopes the scanner would record.

It’s the fastest way to confirm a change hasn’t broken the manifest.

Publishing

The repo’s .github/workflows/release.yml (not the docs deploy) handles the version bump + npm + Docker + Smithery release flow. The short version:

1. Open the repo on GitHub, go to Actions → Version Bump and Release → Run workflow.
2. Pick patch / minor / major.
3. The workflow:
   • Bumps the version in package.json.
   • Creates a GitHub release with the new tag.
   • Publishes the npm package.
   • Builds and pushes the Docker image with the new version tag (and latest if it was a minor or major).
   • Updates the Smithery registry.

You don’t need to do anything Smithery-specific by hand.

Configuration Smithery exposes to users

When a user installs the server from Smithery, the install flow asks for:

• Home Assistant URL (e.g. http://192.168.1.50:8123) — passed as HASS_HOST.
• Long-lived access token — passed as HASS_TOKEN.
• Optional: a port (default 7123), a debug toggle.

Smithery injects these as env vars before the server starts. The server reads them via the standard config pipeline, so the rest of the codebase is unchanged.

Differences from the custom HTTP stack

Concern	Smithery build	Custom HTTP
Auth	None (Smithery handles per-user isolation)	JWT, login endpoint, rate limit
Transport	@modelcontextprotocol/sdk HTTP	Express + custom MCPServer
Rate limiting	None (Smithery rate-limits at the registry)	100 req / 15 min per IP
WebSocket	No (HTTP only)	Yes (/mcp/ws)
Container size	Smaller (Smithery-only deps)	Larger (bespoke middleware)

Pick the Smithery build if you want the registry install UX and don’t need the WebSocket streaming. Pick the custom HTTP build if you’re self-hosting and want the full middleware suite.

Next

• HTTP+WS — the full custom stack.
• STDIO — editor integrations.