[mcp] Initial Contribution

[digitaldan]

The openHAB MCP add-on lets AI assistants — Claude Desktop, Claude Code, ChatGPT, and other Model Context Protocol (MCP) clients — read and control your openHAB smart home.

Once you've connected a client, you can say things like:

• "What's the status of my home?"
• "Dim the office to 30%."
• "Turn on the porch light every day at sunset."
• "Let me know if the garage door opens while we're talking."
• "Turn off the kitchen light at 10pm tonight."

The assistant uses your home's semantic model (rooms, equipment, devices) along with fuzzy matching logic to understand which items you mean to monitor or control without having to use the exact item name.

Other notable aspects:

• Uses the official io.modelcontextprotocol.sdk library and the libraries that it pulls in, so adds a little weight to the jar, but i would not want to try and implement that spec by hand, its grown remarkably complex in the last few months, so worth the extra imports IMHO.
• Like the Twilio binding, this optionally uses a webhook to support clients like ChatGPT who can only access MCP servers that are globally routable, but the binding does requires auth for ALL requests (see next point)
• Requests require either A) openHAB API Token or B) oAuth initiated login to get a session token using the standard openHAB user login. Either works through the webhook as well.
• There are some really cool features that are described in the README, so i would suggest starting there.

tldr;
(copied from the readme)

Tool Calls

Items

Tool	What it does
get_semantic_model	Returns the home layout: Locations → Equipment → Points. The assistant usually calls this first to orient itself.
search_items	Fuzzy search across names, labels, and synonyms. Tolerates typos and word reordering.
get_item	Current state and details for one or more items by exact name.
create_item	Create a new item (Switch, Dimmer, Number, Group, etc.) with label, tags, and group memberships.
update_item	Modify an item's label, category, tags, or group memberships.
delete_item	Permanently remove an item.
send_command	Turn things on/off, set dimmer/colour values, etc.
update_state	Directly set the state of a virtual item (bypasses the device handler).
get_home_status	A single snapshot: security (open doors/windows), active lights, climate, energy, device health.
get_system_info	openHAB version, item/thing/rule counts, installed bindings.

Things & links

Tool	What it does
get_things	Lists Things with online/offline status.
get_thing_details	Channels, configuration, and linked items for one Thing.
get_links	List item-channel links, filtered by item name or channel UID.
create_link	Wire an item to a thing's channel.
delete_link	Remove an item-channel link.

Rules

Tool	What it does
get_rules	Lists automation rules. tag='MCP' scopes the list to rules the assistant created.
create_rule	Creates a rule. Triggers supported: time_of_day, cron, item_state_change, item_command, and datetime (one-shot; auto-deletes after firing).
update_rule	Modify a rule's name, description, tags, or actions without recreating it.
manage_rule	Enable, disable, manually trigger, or delete a rule.

Watching for changes

Tool	What it does
watch_items	Start tracking the given items for state changes in this session.
get_events	Return any state changes buffered since the last call and drain the buffer.
unwatch_items	Stop watching (omit the item list to unwatch everything).

Full REST API access (optional)

Tool	What it does
list_api_endpoints	Enumerate every REST endpoint from openHAB's live OpenAPI spec. Filter by tag (items, rules, …) or method.
describe_api_endpoint	Return the schema fragment for one endpoint so the assistant knows what parameters to pass.
call_api	Invoke any endpoint. Supports every HTTP method.

[Copilot]

Pull request overview

Adds a new openHAB MCP (Model Context Protocol) Server IO add-on (org.openhab.io.mcp) so MCP-capable AI clients can discover the semantic model, read/control items/things/rules, and receive updates via MCP resources or tool-polled watch sessions.

Changes:

• Registers a new org.openhab.io.mcp bundle/module (plus BOM + CODEOWNERS + feature metadata) with config + i18n.
• Implements MCP server transport, OAuth discovery/DCR/token proxy endpoints, authentication, and resource/tool providers.
• Adds a comprehensive unit-test suite for core utilities and tool handlers.

Reviewed changes

Copilot reviewed 49 out of 49 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
bundles/pom.xml	Adds the new org.openhab.io.mcp module to the build reactor.
bom/openhab-addons/pom.xml	Adds org.openhab.io.mcp to the add-ons BOM.
CODEOWNERS	Assigns ownership for the new MCP bundle.
bundles/org.openhab.io.mcp/pom.xml	Declares MCP SDK + supporting dependencies and bnd configuration.
bundles/org.openhab.io.mcp/src/main/feature/feature.xml	Provides a Karaf feature for installing the MCP add-on.
bundles/org.openhab.io.mcp/src/main/resources/OH-INF/addon/addon.xml	Declares the add-on metadata + config reference.
bundles/org.openhab.io.mcp/src/main/resources/OH-INF/config/config.xml	Defines addon configuration parameters.
bundles/org.openhab.io.mcp/src/main/resources/OH-INF/i18n/mcp.properties	Provides i18n labels/descriptions for addon + config.
bundles/org.openhab.io.mcp/README.md	Documents installation, auth, client setup, tools, and usage.
bundles/org.openhab.io.mcp/NOTICE	Declares third-party notices for included dependencies.
bundles/org.openhab.io.mcp/META-INF/MANIFEST.MF	Adds a manifest file (currently appears to be from a dependency).
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/McpService.java	Main OSGi component wiring: servlet registration, tool/resource setup, cloud webhook registration.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/McpConfiguration.java	Config DTO for the MCP service.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/McpCloudWebhookService.java	Integrates with openHAB Cloud WebhookService via reflection + refresh scheduling.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/auth/McpAuthenticator.java	Validates oh.* tokens via UserRegistry and JWTs via REST probe.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/servlet/JavaxStreamableServerTransportProvider.java	Streamable HTTP transport implementation on javax.servlet for HTTP whiteboard.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/servlet/OAuthMetadataServlet.java	Serves OAuth discovery documents under /mcp/.well-known/*.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/servlet/OAuthRegisterServlet.java	Minimal Dynamic Client Registration endpoint for MCP clients.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/servlet/OAuthTokenProxyServlet.java	Proxies /mcp/oauth/token to core /rest/auth/token.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/tools/ResourceProvider.java	Exposes items/things/rules + semantic model as MCP resources/templates.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/tools/SemanticTools.java	Tool to return semantic model JSON.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/tools/SystemTools.java	Tools for system info + aggregated home status snapshot.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/tools/ThingTools.java	Tools for listing things + retrieving thing details.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/tools/LinkTools.java	Tools for listing/creating/deleting item-channel links.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/tools/WatchTools.java	Tools for watch/unwatch + polling buffered change events.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/tools/McpToolUtils.java	Shared helper utilities for tool argument parsing + JSON responses.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/util/SemanticModelBuilder.java	Builds hierarchical semantic model (Locations → Equipment → Points).
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/util/SubscriptionManager.java	Tracks per-session watched items + buffered change events.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/util/McpEventBridge.java	Translates openHAB events into MCP resources/updated notifications (+ watch buffer recording).
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/util/FuzzyItemMatcher.java	Fuzzy scoring for item matching using tokenization + Jaro-Winkler.
bundles/org.openhab.io.mcp/src/main/java/org/openhab/io/mcp/internal/util/ItemStateFormatter.java	Formats states into human/LLM-friendly strings.
bundles/org.openhab.io.mcp/src/test/java/org/openhab/io/mcp/internal/McpTestHelper.java	Shared test helpers for MCP tool-result parsing/assertions.
bundles/org.openhab.io.mcp/src/test/java/org/openhab/io/mcp/internal/auth/McpAuthenticatorTest.java	Tests for token extraction and auth flows.
bundles/org.openhab.io.mcp/src/test/java/org/openhab/io/mcp/internal/tools/McpToolUtilsTest.java	Tests for argument parsing and response helpers.
bundles/org.openhab.io.mcp/src/test/java/org/openhab/io/mcp/internal/tools/SemanticToolsTest.java	Tests semantic model tool output.
bundles/org.openhab.io.mcp/src/test/java/org/openhab/io/mcp/internal/tools/SystemToolsTest.java	Tests system info + home status aggregation.
bundles/org.openhab.io.mcp/src/test/java/org/openhab/io/mcp/internal/tools/ThingToolsTest.java	Tests thing listing/detail behavior.
bundles/org.openhab.io.mcp/src/test/java/org/openhab/io/mcp/internal/tools/LinkToolsTest.java	Tests link listing/creation/deletion.
bundles/org.openhab.io.mcp/src/test/java/org/openhab/io/mcp/internal/tools/WatchToolsTest.java	Tests watch/get_events/unwatch flows and session isolation.
bundles/org.openhab.io.mcp/src/test/java/org/openhab/io/mcp/internal/util/SemanticModelBuilderTest.java	Tests semantic model builder behavior.
bundles/org.openhab.io.mcp/src/test/java/org/openhab/io/mcp/internal/util/SubscriptionManagerTest.java	Tests subscription/event buffering semantics.
bundles/org.openhab.io.mcp/src/test/java/org/openhab/io/mcp/internal/util/McpEventBridgeTest.java	Tests event translation, coalescing, and buffering.
bundles/org.openhab.io.mcp/src/test/java/org/openhab/io/mcp/internal/util/FuzzyItemMatcherTest.java	Tests fuzzy scoring across name/label/synonyms.
bundles/org.openhab.io.mcp/src/test/java/org/openhab/io/mcp/internal/util/ItemStateFormatterTest.java	Tests state formatting for common types.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[lsiepel]

This looks promising! Need to take a deep dive and invest many hours to get familiair with this.

[Copilot]

Pull request overview

Copilot reviewed 48 out of 48 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.