@coffeerunhobby/mcp-ha-connect 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (294) hide show
  1. package/.dockerignore +8 -0
  2. package/.env.example +149 -0
  3. package/.gitattributes +30 -0
  4. package/Dockerfile +33 -0
  5. package/LICENSE +21 -0
  6. package/README.md +394 -0
  7. package/dist/config.d.ts +33 -0
  8. package/dist/config.d.ts.map +1 -0
  9. package/dist/config.js +183 -0
  10. package/dist/config.js.map +1 -0
  11. package/dist/haClient/automations.d.ts +67 -0
  12. package/dist/haClient/automations.d.ts.map +1 -0
  13. package/dist/haClient/automations.js +181 -0
  14. package/dist/haClient/automations.js.map +1 -0
  15. package/dist/haClient/config.d.ts +28 -0
  16. package/dist/haClient/config.d.ts.map +1 -0
  17. package/dist/haClient/config.js +38 -0
  18. package/dist/haClient/config.js.map +1 -0
  19. package/dist/haClient/devices.d.ts +219 -0
  20. package/dist/haClient/devices.d.ts.map +1 -0
  21. package/dist/haClient/devices.js +506 -0
  22. package/dist/haClient/devices.js.map +1 -0
  23. package/dist/haClient/entities.d.ts +35 -0
  24. package/dist/haClient/entities.d.ts.map +1 -0
  25. package/dist/haClient/entities.js +97 -0
  26. package/dist/haClient/entities.js.map +1 -0
  27. package/dist/haClient/events.d.ts +138 -0
  28. package/dist/haClient/events.d.ts.map +1 -0
  29. package/dist/haClient/events.js +344 -0
  30. package/dist/haClient/events.js.map +1 -0
  31. package/dist/haClient/history.d.ts +26 -0
  32. package/dist/haClient/history.d.ts.map +1 -0
  33. package/dist/haClient/history.js +54 -0
  34. package/dist/haClient/history.js.map +1 -0
  35. package/dist/haClient/index.d.ts +153 -0
  36. package/dist/haClient/index.d.ts.map +1 -0
  37. package/dist/haClient/index.js +223 -0
  38. package/dist/haClient/index.js.map +1 -0
  39. package/dist/haClient/request.d.ts +34 -0
  40. package/dist/haClient/request.d.ts.map +1 -0
  41. package/dist/haClient/request.js +93 -0
  42. package/dist/haClient/request.js.map +1 -0
  43. package/dist/haClient/services.d.ts +22 -0
  44. package/dist/haClient/services.d.ts.map +1 -0
  45. package/dist/haClient/services.js +39 -0
  46. package/dist/haClient/services.js.map +1 -0
  47. package/dist/haClient/states.d.ts +26 -0
  48. package/dist/haClient/states.d.ts.map +1 -0
  49. package/dist/haClient/states.js +53 -0
  50. package/dist/haClient/states.js.map +1 -0
  51. package/dist/haClient/updates.d.ts +22 -0
  52. package/dist/haClient/updates.d.ts.map +1 -0
  53. package/dist/haClient/updates.js +48 -0
  54. package/dist/haClient/updates.js.map +1 -0
  55. package/dist/haClient.d.ts +97 -0
  56. package/dist/haClient.d.ts.map +1 -0
  57. package/dist/haClient.js +344 -0
  58. package/dist/haClient.js.map +1 -0
  59. package/dist/index.d.ts +8 -0
  60. package/dist/index.d.ts.map +1 -0
  61. package/dist/index.js +92 -0
  62. package/dist/index.js.map +1 -0
  63. package/dist/localAI/index.d.ts +37 -0
  64. package/dist/localAI/index.d.ts.map +1 -0
  65. package/dist/localAI/index.js +73 -0
  66. package/dist/localAI/index.js.map +1 -0
  67. package/dist/localAI/prompts.d.ts +20 -0
  68. package/dist/localAI/prompts.d.ts.map +1 -0
  69. package/dist/localAI/prompts.js +48 -0
  70. package/dist/localAI/prompts.js.map +1 -0
  71. package/dist/localAI/providers/base.d.ts +51 -0
  72. package/dist/localAI/providers/base.d.ts.map +1 -0
  73. package/dist/localAI/providers/base.js +80 -0
  74. package/dist/localAI/providers/base.js.map +1 -0
  75. package/dist/localAI/providers/ollama.d.ts +22 -0
  76. package/dist/localAI/providers/ollama.d.ts.map +1 -0
  77. package/dist/localAI/providers/ollama.js +63 -0
  78. package/dist/localAI/providers/ollama.js.map +1 -0
  79. package/dist/localAI/providers/openai.d.ts +23 -0
  80. package/dist/localAI/providers/openai.d.ts.map +1 -0
  81. package/dist/localAI/providers/openai.js +63 -0
  82. package/dist/localAI/providers/openai.js.map +1 -0
  83. package/dist/localAI/types.d.ts +61 -0
  84. package/dist/localAI/types.d.ts.map +1 -0
  85. package/dist/localAI/types.js +6 -0
  86. package/dist/localAI/types.js.map +1 -0
  87. package/dist/ollamaClient.d.ts +37 -0
  88. package/dist/ollamaClient.d.ts.map +1 -0
  89. package/dist/ollamaClient.js +110 -0
  90. package/dist/ollamaClient.js.map +1 -0
  91. package/dist/resources/index.d.ts +11 -0
  92. package/dist/resources/index.d.ts.map +1 -0
  93. package/dist/resources/index.js +238 -0
  94. package/dist/resources/index.js.map +1 -0
  95. package/dist/server/common.d.ts +9 -0
  96. package/dist/server/common.d.ts.map +1 -0
  97. package/dist/server/common.js +27 -0
  98. package/dist/server/common.js.map +1 -0
  99. package/dist/server/eventSubscription.d.ts +53 -0
  100. package/dist/server/eventSubscription.d.ts.map +1 -0
  101. package/dist/server/eventSubscription.js +257 -0
  102. package/dist/server/eventSubscription.js.map +1 -0
  103. package/dist/server/http.d.ts +12 -0
  104. package/dist/server/http.d.ts.map +1 -0
  105. package/dist/server/http.js +491 -0
  106. package/dist/server/http.js.map +1 -0
  107. package/dist/server/rateLimiter.d.ts +70 -0
  108. package/dist/server/rateLimiter.d.ts.map +1 -0
  109. package/dist/server/rateLimiter.js +156 -0
  110. package/dist/server/rateLimiter.js.map +1 -0
  111. package/dist/server/sse.d.ts +32 -0
  112. package/dist/server/sse.d.ts.map +1 -0
  113. package/dist/server/sse.js +76 -0
  114. package/dist/server/sse.js.map +1 -0
  115. package/dist/server/stdio.d.ts +8 -0
  116. package/dist/server/stdio.d.ts.map +1 -0
  117. package/dist/server/stdio.js +16 -0
  118. package/dist/server/stdio.js.map +1 -0
  119. package/dist/server/stream.d.ts +26 -0
  120. package/dist/server/stream.d.ts.map +1 -0
  121. package/dist/server/stream.js +81 -0
  122. package/dist/server/stream.js.map +1 -0
  123. package/dist/server.d.ts +8 -0
  124. package/dist/server.d.ts.map +1 -0
  125. package/dist/server.js +30 -0
  126. package/dist/server.js.map +1 -0
  127. package/dist/tools/callService.d.ts +8 -0
  128. package/dist/tools/callService.d.ts.map +1 -0
  129. package/dist/tools/callService.js +100 -0
  130. package/dist/tools/callService.js.map +1 -0
  131. package/dist/tools/getClient.d.ts +8 -0
  132. package/dist/tools/getClient.d.ts.map +1 -0
  133. package/dist/tools/getClient.js +94 -0
  134. package/dist/tools/getClient.js.map +1 -0
  135. package/dist/tools/getDevice.d.ts +8 -0
  136. package/dist/tools/getDevice.d.ts.map +1 -0
  137. package/dist/tools/getDevice.js +94 -0
  138. package/dist/tools/getDevice.js.map +1 -0
  139. package/dist/tools/getEntitiesByDomain.d.ts +8 -0
  140. package/dist/tools/getEntitiesByDomain.d.ts.map +1 -0
  141. package/dist/tools/getEntitiesByDomain.js +80 -0
  142. package/dist/tools/getEntitiesByDomain.js.map +1 -0
  143. package/dist/tools/getState.d.ts +8 -0
  144. package/dist/tools/getState.d.ts.map +1 -0
  145. package/dist/tools/getState.js +90 -0
  146. package/dist/tools/getState.js.map +1 -0
  147. package/dist/tools/getStates.d.ts +8 -0
  148. package/dist/tools/getStates.d.ts.map +1 -0
  149. package/dist/tools/getStates.js +70 -0
  150. package/dist/tools/getStates.js.map +1 -0
  151. package/dist/tools/index.d.ts +9 -0
  152. package/dist/tools/index.d.ts.map +1 -0
  153. package/dist/tools/index.js +9 -0
  154. package/dist/tools/index.js.map +1 -0
  155. package/dist/tools/listClients.d.ts +8 -0
  156. package/dist/tools/listClients.d.ts.map +1 -0
  157. package/dist/tools/listClients.js +73 -0
  158. package/dist/tools/listClients.js.map +1 -0
  159. package/dist/tools/listDevices.d.ts +8 -0
  160. package/dist/tools/listDevices.d.ts.map +1 -0
  161. package/dist/tools/listDevices.js +73 -0
  162. package/dist/tools/listDevices.js.map +1 -0
  163. package/dist/tools/listSites.d.ts +8 -0
  164. package/dist/tools/listSites.d.ts.map +1 -0
  165. package/dist/tools/listSites.js +67 -0
  166. package/dist/tools/listSites.js.map +1 -0
  167. package/dist/tools/registry.d.ts +9 -0
  168. package/dist/tools/registry.d.ts.map +1 -0
  169. package/dist/tools/registry.js +1382 -0
  170. package/dist/tools/registry.js.map +1 -0
  171. package/dist/tools/searchDevices.d.ts +8 -0
  172. package/dist/tools/searchDevices.d.ts.map +1 -0
  173. package/dist/tools/searchDevices.js +84 -0
  174. package/dist/tools/searchDevices.js.map +1 -0
  175. package/dist/tools/searchEntities.d.ts +8 -0
  176. package/dist/tools/searchEntities.d.ts.map +1 -0
  177. package/dist/tools/searchEntities.js +80 -0
  178. package/dist/tools/searchEntities.js.map +1 -0
  179. package/dist/types/entity.d.ts +98 -0
  180. package/dist/types/entity.d.ts.map +1 -0
  181. package/dist/types/entity.js +2 -0
  182. package/dist/types/entity.js.map +1 -0
  183. package/dist/types/errors.d.ts +16 -0
  184. package/dist/types/errors.d.ts.map +1 -0
  185. package/dist/types/errors.js +32 -0
  186. package/dist/types/errors.js.map +1 -0
  187. package/dist/types/haConfig.d.ts +8 -0
  188. package/dist/types/haConfig.d.ts.map +1 -0
  189. package/dist/types/haConfig.js +2 -0
  190. package/dist/types/haConfig.js.map +1 -0
  191. package/dist/types/index.d.ts +6 -0
  192. package/dist/types/index.d.ts.map +1 -0
  193. package/dist/types/index.js +2 -0
  194. package/dist/types/index.js.map +1 -0
  195. package/dist/types/request.d.ts +7 -0
  196. package/dist/types/request.d.ts.map +1 -0
  197. package/dist/types/request.js +2 -0
  198. package/dist/types/request.js.map +1 -0
  199. package/dist/types/serviceCall.d.ts +18 -0
  200. package/dist/types/serviceCall.d.ts.map +1 -0
  201. package/dist/types/serviceCall.js +2 -0
  202. package/dist/types/serviceCall.js.map +1 -0
  203. package/dist/types.d.ts +2 -0
  204. package/dist/types.d.ts.map +1 -0
  205. package/dist/types.js +3 -0
  206. package/dist/types.js.map +1 -0
  207. package/dist/utils/config-validations.d.ts +12 -0
  208. package/dist/utils/config-validations.d.ts.map +1 -0
  209. package/dist/utils/config-validations.js +43 -0
  210. package/dist/utils/config-validations.js.map +1 -0
  211. package/dist/utils/logger.d.ts +24 -0
  212. package/dist/utils/logger.d.ts.map +1 -0
  213. package/dist/utils/logger.js +94 -0
  214. package/dist/utils/logger.js.map +1 -0
  215. package/dist/wrapper.d.ts +8 -0
  216. package/dist/wrapper.d.ts.map +1 -0
  217. package/dist/wrapper.js +301 -0
  218. package/dist/wrapper.js.map +1 -0
  219. package/docker-compose.yml +17 -0
  220. package/docs/CHANGELOG.md +86 -0
  221. package/docs/LOCAL_CLIENT.md +268 -0
  222. package/docs/SSE_API.md +341 -0
  223. package/eslint.config.js +33 -0
  224. package/n8n/ai-agent-safety-monitor.json +355 -0
  225. package/openapi.json +166 -0
  226. package/package.json +51 -0
  227. package/src/config.ts +260 -0
  228. package/src/haClient/automations.ts +217 -0
  229. package/src/haClient/config.ts +41 -0
  230. package/src/haClient/devices.ts +653 -0
  231. package/src/haClient/entities.ts +128 -0
  232. package/src/haClient/events.ts +456 -0
  233. package/src/haClient/history.ts +68 -0
  234. package/src/haClient/index.ts +287 -0
  235. package/src/haClient/request.ts +127 -0
  236. package/src/haClient/services.ts +45 -0
  237. package/src/haClient/states.ts +60 -0
  238. package/src/haClient/updates.ts +58 -0
  239. package/src/index.ts +99 -0
  240. package/src/localAI/index.ts +88 -0
  241. package/src/localAI/prompts.ts +50 -0
  242. package/src/localAI/providers/base.ts +120 -0
  243. package/src/localAI/providers/ollama.ts +78 -0
  244. package/src/localAI/providers/openai.ts +86 -0
  245. package/src/localAI/types.ts +67 -0
  246. package/src/resources/index.ts +266 -0
  247. package/src/server/common.ts +38 -0
  248. package/src/server/eventSubscription.ts +318 -0
  249. package/src/server/http.ts +546 -0
  250. package/src/server/rateLimiter.ts +195 -0
  251. package/src/server/sse.ts +120 -0
  252. package/src/server/stdio.ts +22 -0
  253. package/src/server/stream.ts +113 -0
  254. package/src/tools/callService.ts +114 -0
  255. package/src/tools/getEntitiesByDomain.ts +92 -0
  256. package/src/tools/getState.ts +103 -0
  257. package/src/tools/getStates.ts +80 -0
  258. package/src/tools/index.ts +9 -0
  259. package/src/tools/registry.ts +1521 -0
  260. package/src/tools/searchEntities.ts +92 -0
  261. package/src/types/entity.ts +110 -0
  262. package/src/types/errors.ts +33 -0
  263. package/src/types/haConfig.ts +7 -0
  264. package/src/types/index.ts +5 -0
  265. package/src/types/request.ts +6 -0
  266. package/src/types/serviceCall.ts +18 -0
  267. package/src/types.ts +2 -0
  268. package/src/utils/config-validations.ts +46 -0
  269. package/src/utils/logger.ts +114 -0
  270. package/src/wrapper.ts +340 -0
  271. package/tests/config.test.ts +332 -0
  272. package/tests/haClient/automations.test.ts +133 -0
  273. package/tests/haClient/config.test.ts +96 -0
  274. package/tests/haClient/entities.test.ts +188 -0
  275. package/tests/haClient/history.test.ts +170 -0
  276. package/tests/haClient/index.test.ts +221 -0
  277. package/tests/haClient/request.test.ts +217 -0
  278. package/tests/haClient/services.test.ts +120 -0
  279. package/tests/haClient/states.test.ts +119 -0
  280. package/tests/haClient/updates.test.ts +193 -0
  281. package/tests/index.test.ts +164 -0
  282. package/tests/localAI/index.test.ts +168 -0
  283. package/tests/localAI/ollama.test.ts +187 -0
  284. package/tests/localAI/openai.test.ts +257 -0
  285. package/tests/server/common.test.ts +64 -0
  286. package/tests/server/http.test.ts +326 -0
  287. package/tests/server/sse.test.ts +240 -0
  288. package/tests/server/stdio.test.ts +102 -0
  289. package/tests/server/stream.test.ts +287 -0
  290. package/tests/tools/registry.test.ts +355 -0
  291. package/tests/utils/config-validations.test.ts +289 -0
  292. package/tests/utils/logger.test.ts +327 -0
  293. package/tsconfig.json +25 -0
  294. package/vitest.config.ts +26 -0
package/.dockerignore ADDED
@@ -0,0 +1,8 @@
1
+ node_modules
2
+ dist
3
+ .git
4
+ .vscode
5
+ .env
6
+ .env.*
7
+ Dockerfile
8
+ npm-debug.log*
package/.env.example ADDED
@@ -0,0 +1,149 @@
1
+ # =============================================================================
2
+ # Home Assistant MCP Server Configuration
3
+ # =============================================================================
4
+
5
+ # -----------------------------------------------------------------------------
6
+ # Home Assistant Connection (Required)
7
+ # -----------------------------------------------------------------------------
8
+
9
+ # Your Home Assistant URL (must include http:// or https://)
10
+ HA_URL=http://homeassistant.10.0.0.19.nip.io:8123
11
+
12
+ # Long-lived access token from Home Assistant
13
+ # Get from: Profile -> Long-Lived Access Tokens
14
+ HA_TOKEN=your_long_lived_access_token_here
15
+
16
+ # Validate SSL certificates (set to false for self-signed certs or HTTP)
17
+ # Default: true
18
+ HA_STRICT_SSL=false
19
+
20
+ # Request timeout in milliseconds
21
+ # Default: 30000 (30 seconds)
22
+ HA_TIMEOUT=30000
23
+
24
+ # -----------------------------------------------------------------------------
25
+ # AI Provider Configuration (Optional)
26
+ # -----------------------------------------------------------------------------
27
+
28
+ # Provider type: ollama, openai (for OpenAI-compatible APIs), or none (disabled)
29
+ AI_PROVIDER=none
30
+
31
+ # Provider URL
32
+ AI_URL=http://ollama.10.0.0.17.nip.io:11434
33
+
34
+ # Model name
35
+ AI_MODEL=qwen3:14b
36
+
37
+ # Request timeout in milliseconds
38
+ AI_TIMEOUT=60000
39
+
40
+ # API key (optional, for authenticated providers)
41
+ # AI_API_KEY=your_api_key_here
42
+
43
+ # -----------------------------------------------------------------------------
44
+ # MCP Server Configuration
45
+ # -----------------------------------------------------------------------------
46
+
47
+ # Log level: debug, info, warn, error
48
+ # Default: info
49
+ MCP_SERVER_LOG_LEVEL=info
50
+
51
+ # Log format: plain, json, gcp-json
52
+ # - plain: Human-readable format
53
+ # - json: Structured JSON logs
54
+ # - gcp-json: Google Cloud Platform compatible JSON
55
+ # Default: plain
56
+ MCP_SERVER_LOG_FORMAT=plain
57
+
58
+ # Enable HTTP server mode (set to true for web/API access)
59
+ # When false, uses stdio mode for Claude Desktop
60
+ # Default: false
61
+ MCP_SERVER_USE_HTTP=false
62
+
63
+ # Enable stateful sessions (only for HTTP mode)
64
+ # When true, maintains session state across requests
65
+ # Default: false
66
+ MCP_SERVER_STATEFUL=false
67
+
68
+ # -----------------------------------------------------------------------------
69
+ # HTTP Server Configuration (only when MCP_SERVER_USE_HTTP=true)
70
+ # -----------------------------------------------------------------------------
71
+
72
+ # Port to listen on
73
+ # Default: 3000
74
+ MCP_HTTP_PORT=3000
75
+
76
+ # Transport protocol: stream or sse
77
+ # - stream: Modern MCP protocol (recommended)
78
+ # - sse: Legacy MCP protocol with Server-Sent Events
79
+ # Default: stream
80
+ MCP_HTTP_TRANSPORT=stream
81
+
82
+ # Bind address (use 0.0.0.0 to listen on all interfaces)
83
+ # Default: 127.0.0.1 (localhost only)
84
+ MCP_HTTP_BIND_ADDR=127.0.0.1
85
+
86
+ # MCP endpoint path
87
+ # Default: /mcp for stream, /sse for SSE
88
+ MCP_HTTP_PATH=/mcp
89
+
90
+ # Enable health check endpoint
91
+ # Default: true
92
+ MCP_HTTP_ENABLE_HEALTHCHECK=true
93
+
94
+ # Health check endpoint path
95
+ # Default: /health
96
+ MCP_HTTP_HEALTHCHECK_PATH=/health
97
+
98
+ # Enable CORS (Cross-Origin Resource Sharing)
99
+ # Default: true
100
+ MCP_HTTP_ALLOW_CORS=true
101
+
102
+ # Allowed origins (comma-separated)
103
+ # Use * for all origins (development only!)
104
+ # Default: 127.0.0.1,localhost
105
+ MCP_HTTP_ALLOWED_ORIGINS=127.0.0.1,localhost,http://mcpserver.10.0.0.18.nip.io:3000
106
+
107
+ # =============================================================================
108
+ # Usage Examples
109
+ # =============================================================================
110
+
111
+ # Example 1: Claude Desktop (Stdio Mode)
112
+ # ----------------------------------------
113
+ # MCP_SERVER_USE_HTTP=false
114
+ # MCP_SERVER_LOG_LEVEL=info
115
+ # Then configure claude_desktop_config.json to run: node dist/index.js
116
+
117
+ # Example 2: HTTP Server with Stream Transport (Recommended)
118
+ # -----------------------------------------------------------
119
+ # MCP_SERVER_USE_HTTP=true
120
+ # MCP_HTTP_TRANSPORT=stream
121
+ # MCP_HTTP_PORT=3000
122
+ # MCP_HTTP_BIND_ADDR=127.0.0.1
123
+ # Access at: http://mcpserver.10.0.0.18.nip.io:3000/mcp
124
+
125
+ # Example 3: HTTP Server with SSE (Legacy Clients)
126
+ # -------------------------------------------------
127
+ # MCP_SERVER_USE_HTTP=true
128
+ # MCP_HTTP_TRANSPORT=sse
129
+ # MCP_HTTP_PORT=3000
130
+ # Access at: http://mcpserver.10.0.0.18.nip.io:3000/sse
131
+
132
+ # Example 4: Production HTTP Server
133
+ # ----------------------------------
134
+ # MCP_SERVER_USE_HTTP=true
135
+ # MCP_SERVER_LOG_FORMAT=json
136
+ # MCP_HTTP_TRANSPORT=stream
137
+ # MCP_HTTP_PORT=3000
138
+ # MCP_HTTP_BIND_ADDR=0.0.0.0
139
+ # MCP_HTTP_ALLOWED_ORIGINS=https://your-app.com
140
+ # MCP_SERVER_STATEFUL=true
141
+
142
+ # =============================================================================
143
+ # Security Notes
144
+ # =============================================================================
145
+ # - Never commit this file with real credentials
146
+ # - Use HA_STRICT_SSL=true in production with HTTPS
147
+ # - Restrict MCP_HTTP_ALLOWED_ORIGINS to trusted domains
148
+ # - Use MCP_HTTP_BIND_ADDR=127.0.0.1 for local-only access
149
+ # - Rotate your Home Assistant tokens periodically
package/.gitattributes ADDED
@@ -0,0 +1,30 @@
1
+ # Set default behavior to automatically normalize line endings to LF
2
+ * text=auto eol=lf
3
+
4
+ # Explicitly declare text files you want to always be normalized and converted to native line endings on checkout
5
+ *.ts text eol=lf
6
+ *.js text eol=lf
7
+ *.mjs text eol=lf
8
+ *.json text eol=lf
9
+ *.md text eol=lf
10
+ *.yml text eol=lf
11
+ *.yaml text eol=lf
12
+ *.toml text eol=lf
13
+ *.sh text eol=lf
14
+
15
+ # Declare files that will always have LF line endings on checkout
16
+ *.env.example text eol=lf
17
+ .gitignore text eol=lf
18
+ .gitattributes text eol=lf
19
+
20
+ # Denote all files that are truly binary and should not be modified
21
+ *.png binary
22
+ *.jpg binary
23
+ *.jpeg binary
24
+ *.gif binary
25
+ *.ico binary
26
+ *.pdf binary
27
+ *.woff binary
28
+ *.woff2 binary
29
+ *.ttf binary
30
+ *.eot binary
package/Dockerfile ADDED
@@ -0,0 +1,33 @@
1
+ # syntax=docker/dockerfile:1.7
2
+
3
+ FROM node:24-bookworm-slim AS deps
4
+ WORKDIR /app
5
+ COPY package*.json ./
6
+ RUN npm install
7
+
8
+ FROM node:24-bookworm-slim AS build
9
+ WORKDIR /app
10
+ COPY --from=deps /app/node_modules ./node_modules
11
+ COPY . .
12
+ RUN npm run build
13
+
14
+ FROM node:24-bookworm-slim AS runtime
15
+
16
+ # OCI metadata labels
17
+ LABEL org.opencontainers.image.title="Smart HomeAssistant MCP Server"
18
+ LABEL org.opencontainers.image.description="Smart home MCP server for Home Assistant plus Local AI integration"
19
+ LABEL org.opencontainers.image.authors="Coffee Run Hobby"
20
+ LABEL org.opencontainers.image.url="https://github.com/coffeerunhobby/mcp-ha-connect"
21
+ LABEL org.opencontainers.image.source="https://github.com/coffeerunhobby/mcp-ha-connect"
22
+ LABEL org.opencontainers.image.documentation="https://github.com/coffeerunhobby/mcp-ha-connect#readme"
23
+ LABEL org.opencontainers.image.licenses="MIT"
24
+
25
+ WORKDIR /app
26
+ ENV NODE_ENV=production
27
+ RUN apt-get update \
28
+ && apt-get install -y --no-install-recommends curl \
29
+ && rm -rf /var/lib/apt/lists/*
30
+ COPY package*.json ./
31
+ RUN npm install --omit=dev
32
+ COPY --from=build /app/dist ./dist
33
+ CMD ["node", "dist/index.js"]
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 João Miguel Tabosa Vaz Marques Silva
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,394 @@
1
+ # MCP-HA-Connect
2
+
3
+ A production-ready Model Context Protocol (MCP) server for Home Assistant integration with AI assistants like Claude.
4
+
5
+ ## Version 0.5.0 Features
6
+
7
+ - **Real-time Updates**: Get instant updates through Server-Sent Events (SSE) - subscribe to state changes, automations, and service calls
8
+ - **Device Control**: Control any Home Assistant device through natural language with advanced options
9
+ - **Automation Management**: Create, update, delete, trigger, and manage automations programmatically
10
+ - **State Monitoring**: Track and query device states in real-time
11
+ - **Rate Limiting**: Built-in rate limiting to protect your Home Assistant instance
12
+ - **Secure**: Token-based authentication and configurable rate limits
13
+ - **Mobile Ready**: Works with any HTTP-capable client
14
+
15
+ ## Real-time Updates with SSE
16
+
17
+ The server includes a powerful Server-Sent Events (SSE) system that provides real-time updates from your Home Assistant instance:
18
+
19
+ - **Get instant state changes** for any device
20
+ - **Monitor automation triggers** and executions
21
+ - **Subscribe to specific domains** or entities
22
+ - **Track service calls** and script executions
23
+
24
+ ### Quick SSE Example
25
+
26
+ ```javascript
27
+ const eventSource = new EventSource(
28
+ 'http://mcpserver.10.0.0.18.nip.io:3000/subscribe_events?domain=light'
29
+ );
30
+
31
+ eventSource.onmessage = (event) => {
32
+ const data = JSON.parse(event.data);
33
+ console.log('Update received:', data);
34
+ };
35
+ ```
36
+
37
+ See [docs/SSE_API.md](docs/SSE_API.md) for complete documentation of the SSE system.
38
+
39
+ ## Key Features
40
+
41
+ ### Core Functionality
42
+
43
+ - **Smart Device Control**
44
+ - Lights: Brightness, color temperature, RGB color, transitions
45
+ - Climate: Temperature, HVAC modes, fan modes, humidity
46
+ - Covers: Position and tilt control
47
+ - Switches: On/off control
48
+ - Sensors & Contacts: State monitoring
49
+ - Media Players: Playback control, volume, source selection
50
+ - Fans: Speed, oscillation, direction
51
+ - Locks: Lock/unlock control
52
+ - Vacuums: Start, stop, return to base
53
+ - Cameras: Motion detection, snapshots
54
+
55
+ ### Automation Management
56
+
57
+ - List all automations with status
58
+ - Trigger automations manually with variables
59
+ - Enable/disable/toggle automations
60
+ - Create new automations via API
61
+ - Delete automations
62
+ - View automation execution traces
63
+ - Reload automations from configuration
64
+
65
+ ### System Features
66
+
67
+ - Direct Home Assistant API integration
68
+ - Long-lived access token authentication
69
+ - Entity state management
70
+ - Service call support
71
+ - Advanced entity search
72
+ - AI-powered sensor analysis with Ollama
73
+ - Multiple transport modes (stdio, SSE, Streamable HTTP)
74
+ - HTTP server with health checks
75
+ - CORS support for browser-based clients
76
+ - Structured logging with pino (plain, JSON, GCP-JSON formats)
77
+ - Comprehensive configuration validation with Zod
78
+ - Full type safety with TypeScript
79
+ - Stateful and stateless session support
80
+
81
+ ## Available Tools (33 Total)
82
+
83
+ ### State & Entity Tools
84
+
85
+ | Tool | Description |
86
+ |------|-------------|
87
+ | `getStates` | Get all entity states from Home Assistant |
88
+ | `getState` | Get the state of a specific entity by entity_id |
89
+ | `getEntitiesByDomain` | Get all entities for a specific domain |
90
+ | `searchEntities` | Search for entities by name or entity_id |
91
+ | `getAllSensors` | Get all sensor and binary_sensor entities |
92
+ | `listEntities` | List entities with filtering (domain, state, search, limit) |
93
+ | `getDomainSummary` | Get summary statistics for a domain |
94
+ | `getHistory` | Get historical data for an entity |
95
+
96
+ ### Service & Control Tools
97
+
98
+ | Tool | Description |
99
+ |------|-------------|
100
+ | `callService` | Call any Home Assistant service |
101
+ | `entityAction` | Simple turn_on/turn_off/toggle actions |
102
+
103
+ ### Device Control Tools
104
+
105
+ | Tool | Description |
106
+ |------|-------------|
107
+ | `controlLight` | Control lights with brightness, color, temperature |
108
+ | `controlClimate` | Control thermostats with temperature, HVAC mode |
109
+ | `controlMediaPlayer` | Control media players with playback, volume |
110
+ | `controlCover` | Control covers/blinds with position, tilt |
111
+ | `controlFan` | Control fans with speed, oscillation, direction |
112
+ | `activateScene` | Activate a Home Assistant scene |
113
+ | `runScript` | Run a Home Assistant script |
114
+ | `sendNotification` | Send notifications through Home Assistant |
115
+
116
+ ### Automation Tools
117
+
118
+ | Tool | Description |
119
+ |------|-------------|
120
+ | `listAutomations` | List all automations with status |
121
+ | `triggerAutomation` | Manually trigger an automation |
122
+ | `enableAutomation` | Enable a disabled automation |
123
+ | `disableAutomation` | Disable an automation |
124
+ | `toggleAutomation` | Toggle automation state |
125
+ | `reloadAutomations` | Reload automations from config |
126
+ | `createAutomation` | Create a new automation |
127
+ | `deleteAutomation` | Delete an automation |
128
+ | `getAutomationTrace` | Get automation execution history |
129
+
130
+ ### System Tools
131
+
132
+ | Tool | Description |
133
+ |------|-------------|
134
+ | `getVersion` | Get Home Assistant version and config info |
135
+ | `restartHomeAssistant` | Restart the Home Assistant server |
136
+ | `getSystemLog` | Get system log entries from logbook |
137
+ | `checkUpdates` | Check for available updates |
138
+ | `analyzeSensors` | AI-powered sensor analysis using Ollama |
139
+
140
+ ### MCP Resources
141
+
142
+ | Resource URI | Description |
143
+ |--------------|-------------|
144
+ | `hass://entities` | List all entities grouped by domain |
145
+ | `hass://entities/{entity_id}` | Get state of a specific entity |
146
+ | `hass://entities/{entity_id}/detailed` | Get detailed entity info with all attributes |
147
+ | `hass://entities/domain/{domain}` | Get all entities for a domain |
148
+ | `hass://search/{query}/{limit}` | Search entities with result limit |
149
+
150
+ ## Prerequisites
151
+
152
+ - **Node.js 20+** (tested with v20.19.6)
153
+ - **npm 10.8+** (tested with v10.8.2)
154
+ - Home Assistant instance with long-lived access token
155
+ - Network access to your Home Assistant instance
156
+ - (Optional) Ollama for AI-powered analysis
157
+ - (Optional) Docker for containerized deployment
158
+
159
+ ## Configuration
160
+
161
+ ### Getting Long-Lived Access Token
162
+
163
+ 1. Log into your Home Assistant
164
+ 2. Click on your profile (bottom left)
165
+ 3. Scroll down to "Long-Lived Access Tokens"
166
+ 4. Click "Create Token"
167
+ 5. Give it a name (e.g., "MCP Server")
168
+ 6. Copy the token (shown only once!)
169
+
170
+ ### Environment Variables
171
+
172
+ Copy `.env.example` to `.env` and configure:
173
+
174
+ ```bash
175
+ # Home Assistant Connection
176
+ HA_URL=http://homeassistant.10.0.0.19.nip.io:8123
177
+ HA_TOKEN=your_long_lived_access_token_here
178
+ HA_STRICT_SSL=false
179
+ HA_TIMEOUT=30000
180
+
181
+ # MCP Server Configuration
182
+ MCP_SERVER_LOG_LEVEL=info # debug, info, warn, error
183
+ MCP_SERVER_LOG_FORMAT=plain # plain, json, gcp-json
184
+ MCP_SERVER_USE_HTTP=false # true for HTTP mode, false for stdio
185
+ MCP_SERVER_STATEFUL=false # Enable stateful sessions in HTTP mode
186
+
187
+ # HTTP Configuration (when MCP_SERVER_USE_HTTP=true)
188
+ MCP_HTTP_PORT=3000
189
+ MCP_HTTP_TRANSPORT=stream # stream or sse
190
+ MCP_HTTP_BIND_ADDR=127.0.0.1
191
+ MCP_HTTP_PATH=/mcp # /mcp for stream, /sse for SSE
192
+ MCP_HTTP_ENABLE_HEALTHCHECK=true
193
+ MCP_HTTP_HEALTHCHECK_PATH=/health
194
+ MCP_HTTP_ALLOW_CORS=true
195
+ MCP_HTTP_ALLOWED_ORIGINS=127.0.0.1,localhost
196
+
197
+ # SSE Event Subscription (real-time updates)
198
+ MCP_SSE_EVENTS_ENABLED=true # Enable SSE event subscription
199
+ MCP_SSE_EVENTS_PATH=/subscribe_events # SSE endpoint path
200
+
201
+ # Rate Limiting
202
+ MCP_RATE_LIMIT_ENABLED=true # Enable rate limiting
203
+ MCP_RATE_LIMIT_WINDOW_MS=60000 # Time window in ms (default: 1 minute)
204
+ MCP_RATE_LIMIT_MAX_REQUESTS=100 # Max requests per window
205
+
206
+ # AI Configuration (optional)
207
+ AI_PROVIDER=ollama # ollama or openai
208
+ AI_URL=http://ollama.10.0.0.17.nip.io:11434
209
+ AI_MODEL=phi4:14b
210
+ AI_TIMEOUT=60000
211
+ ```
212
+
213
+ ## Usage
214
+
215
+ ### Mode 1: Claude Desktop (Stdio Transport)
216
+
217
+ [`docs/LOCAL_CLIENT.md`](docs/LOCAL_CLIENT.md)
218
+
219
+ ### Mode 2: HTTP Server
220
+
221
+ ```bash
222
+ # Start HTTP server
223
+ MCP_SERVER_USE_HTTP=true npm start
224
+ ```
225
+
226
+ #### Streamable HTTP Transport (Recommended)
227
+
228
+ Configure your MCP client to use:
229
+ - **URL:** `http://mcpserver.10.0.0.18.nip.io:3000/mcp`
230
+ - **Transport:** Streamable HTTP (MCP 2025-03-26)
231
+
232
+ #### SSE Event Subscription
233
+
234
+ Subscribe to real-time events:
235
+ - **URL:** `http://mcpserver.10.0.0.18.nip.io:3000/subscribe_events`
236
+ - **Method:** GET
237
+ - **Query params:** `domain`, `entity_id`, `event_types`
238
+
239
+ ### Mode 3: Docker
240
+
241
+ ```bash
242
+ # Build image
243
+ docker build -t mcp-ha-connect .
244
+
245
+ # Run container
246
+ docker run -d --name mcp-ha-connect \
247
+ -e HA_URL=http://homeassistant.10.0.0.19.nip.io:8123 \
248
+ -e HA_TOKEN=your_token \
249
+ -e MCP_SERVER_USE_HTTP=true \
250
+ -p 3000:3000 \
251
+ mcp-ha-connect
252
+ ```
253
+
254
+ ## Development
255
+
256
+ ### Running Tests
257
+
258
+ ```bash
259
+ npm test # Run all tests
260
+ npm run test:watch # Watch mode
261
+ npm run test:coverage # Coverage report
262
+ ```
263
+
264
+ ### Type Checking
265
+
266
+ ```bash
267
+ npm run type-check
268
+ ```
269
+
270
+ ### Linting
271
+
272
+ ```bash
273
+ npm run lint
274
+ ```
275
+
276
+ ### Building
277
+
278
+ ```bash
279
+ npm run build
280
+ ```
281
+
282
+ ## Integration Examples
283
+
284
+ ### With Claude Desktop
285
+
286
+ Once configured, you can ask Claude:
287
+
288
+ - "Show me all lights in my house"
289
+ - "Turn on the kitchen lights to 50% brightness"
290
+ - "Set the living room temperature to 72 degrees"
291
+ - "Create an automation that turns off all lights at midnight"
292
+ - "What automations are currently enabled?"
293
+ - "Trigger the morning routine automation"
294
+ - "Search for entities with 'bedroom' in their name"
295
+ - "Get all climate entities"
296
+ - "Analyze my sensors for any issues" (requires Ollama)
297
+ - "Check the history of my thermostat"
298
+
299
+ ### With n8n Workflows
300
+
301
+ The server can be integrated with n8n for automated home monitoring. Pre-built workflows are available in the `n8n/` directory:
302
+
303
+ 1. **ai-agent-safety-monitor** - Critical safety monitoring every 5 minutes
304
+
305
+ #### Importing Workflows
306
+
307
+ **Method 1: n8n UI**
308
+ 1. Open n8n: `http://127.0.0.1:5678`
309
+ 2. Click **Workflows** → **Import from File**
310
+ 3. Select JSON file from `n8n-files/`
311
+ 4. Activate the workflow
312
+
313
+ **Method 2: Docker CLI**
314
+ ```bash
315
+ # Copy workflow to n8n container
316
+ docker cp "n8n-files/AI Agent Safety Monitor - Updated.json" n8n:/files/workflow.json
317
+
318
+ # Import using n8n CLI
319
+ docker exec -it n8n n8n import:workflow --input=/files/workflow.json
320
+
321
+ # Verify import
322
+ docker exec -it n8n n8n list:workflow
323
+ ```
324
+
325
+ ### With Web Applications
326
+
327
+ Use the HTTP transport with your MCP-compatible web client:
328
+
329
+ 1. Configure client to use `http://mcpserver.10.0.0.18.nip.io:3000/mcp`
330
+ 2. Set transport to Streamable HTTP (MCP 2025-03-26)
331
+ 3. Enable CORS by adding your origin to `MCP_HTTP_ALLOWED_ORIGINS`
332
+
333
+ ### With Stateful Sessions
334
+
335
+ Enable session persistence:
336
+
337
+ ```bash
338
+ MCP_SERVER_STATEFUL=true
339
+ ```
340
+
341
+ Your MCP client should:
342
+ 1. Include `Mcp-Session-Id` header in requests
343
+ 2. Reuse the same session ID for related requests
344
+ 3. Session state is maintained server-side
345
+
346
+ Connect to SSE for real-time updates
347
+
348
+ ```javascript
349
+ const eventSource = new EventSource(
350
+ 'http://mcpserver.10.0.0.18.nip.io:3000/subscribe_events?domain=light'
351
+ );
352
+
353
+ eventSource.addEventListener('state_changed', (event) => {
354
+ const data = JSON.parse(event.data);
355
+ updateUI(data.entity_id, data.new_state);
356
+ });
357
+ ```
358
+
359
+ ## Security
360
+
361
+ ### Network Security
362
+
363
+ **Network Segmentation:**
364
+ - Run MCP server on private LAN only (192.168.0.0/24)
365
+ - Use Docker networks for container isolation
366
+ - Consider VLAN for IoT devices
367
+ - Never expose MCP server directly to internet
368
+
369
+ ### Best Practices
370
+
371
+ - Store `.env` securely (contains access token)
372
+ - Never commit `.env` to version control
373
+ - Set `.env` permissions: `chmod 600 .env`
374
+ - Use `HA_STRICT_SSL=true` for HTTPS in production
375
+ - Rotate access tokens periodically
376
+ - Restrict `MCP_HTTP_ALLOWED_ORIGINS` (avoid wildcard)
377
+ - Bind to `127.0.0.1` for local-only access
378
+ - Enable rate limiting in production
379
+
380
+ ## License
381
+
382
+ MIT
383
+
384
+ ## Author
385
+
386
+ Coffee Run Hobby (github.com/coffeerunhobby)
387
+
388
+ ## Version
389
+
390
+ 0.5.0
391
+
392
+ ## Changelog
393
+
394
+ [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
@@ -0,0 +1,33 @@
1
+ import type { AIProviderType } from './localAI/types.js';
2
+ export interface EnvironmentConfig {
3
+ baseUrl: string;
4
+ token: string;
5
+ strictSsl: boolean;
6
+ timeout: number;
7
+ aiProvider: AIProviderType;
8
+ aiUrl: string;
9
+ aiModel: string;
10
+ aiTimeout: number;
11
+ aiApiKey?: string;
12
+ logLevel: 'debug' | 'info' | 'warn' | 'error';
13
+ logFormat: 'plain' | 'json' | 'gcp-json';
14
+ useHttp: boolean;
15
+ stateful: boolean;
16
+ httpPort?: number;
17
+ httpTransport: 'stream' | 'sse';
18
+ httpBindAddr?: string;
19
+ httpPath?: string;
20
+ httpEnableHealthcheck: boolean;
21
+ httpHealthcheckPath?: string;
22
+ httpAllowCors: boolean;
23
+ httpAllowedOrigins?: string[];
24
+ sseEventsEnabled: boolean;
25
+ sseEventsPath: string;
26
+ rateLimitEnabled: boolean;
27
+ rateLimitWindowMs: number;
28
+ rateLimitMaxRequests: number;
29
+ }
30
+ export declare function loadConfig(env?: NodeJS.ProcessEnv): EnvironmentConfig;
31
+ export declare function validateConfig(config: EnvironmentConfig): void;
32
+ export declare function loadConfigFromEnv(): EnvironmentConfig;
33
+ //# sourceMappingURL=config.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAyGzD,MAAM,WAAW,iBAAiB;IAEhC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAGhB,UAAU,EAAE,cAAc,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC9C,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAGlB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,QAAQ,GAAG,KAAK,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,aAAa,EAAE,OAAO,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAG9B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IAGtB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,iBAAiB,CAmGlF;AAGD,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAK9D;AAED,wBAAgB,iBAAiB,IAAI,iBAAiB,CAErD"}