@coffeerunhobby/mcp-ha-connect 2.2.1 → 2.4.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 (293) hide show
  1. package/.env.example +1 -1
  2. package/README.md +24 -2
  3. package/dist/omadaClient/accessControl.d.ts +290 -0
  4. package/dist/omadaClient/accessControl.js +509 -0
  5. package/dist/omadaClient/accessControl.js.map +1 -0
  6. package/dist/omadaClient/client.d.ts +6 -1
  7. package/dist/omadaClient/client.js +12 -1
  8. package/dist/omadaClient/client.js.map +1 -1
  9. package/dist/omadaClient/diagnose.d.ts +68 -0
  10. package/dist/omadaClient/diagnose.js +164 -0
  11. package/dist/omadaClient/diagnose.js.map +1 -0
  12. package/dist/omadaClient/index.d.ts +9 -0
  13. package/dist/omadaClient/index.js +19 -0
  14. package/dist/omadaClient/index.js.map +1 -1
  15. package/dist/omadaClient/macGroups.d.ts +58 -0
  16. package/dist/omadaClient/macGroups.js +110 -0
  17. package/dist/omadaClient/macGroups.js.map +1 -0
  18. package/dist/omadaClient/serialize.d.ts +13 -0
  19. package/dist/omadaClient/serialize.js +29 -0
  20. package/dist/omadaClient/serialize.js.map +1 -0
  21. package/dist/omadaClient/timeRange.d.ts +41 -0
  22. package/dist/omadaClient/timeRange.js +109 -0
  23. package/dist/omadaClient/timeRange.js.map +1 -0
  24. package/dist/tools/infra/actions.d.ts +1 -1
  25. package/dist/tools/infra/actions.js +1 -1
  26. package/dist/tools/omada/accessControl.d.ts +151 -0
  27. package/dist/tools/omada/accessControl.js +158 -0
  28. package/dist/tools/omada/accessControl.js.map +1 -0
  29. package/dist/tools/omada/index.js +9 -0
  30. package/dist/tools/omada/index.js.map +1 -1
  31. package/dist/tools/omada/macGroups.d.ts +19 -0
  32. package/dist/tools/omada/macGroups.js +77 -0
  33. package/dist/tools/omada/macGroups.js.map +1 -0
  34. package/dist/tools/omada/namespace.js +16 -0
  35. package/dist/tools/omada/namespace.js.map +1 -1
  36. package/dist/version.d.ts +1 -1
  37. package/dist/version.js +1 -1
  38. package/package.json +5 -1
  39. package/.codex/review-rules.md +0 -16
  40. package/.dockerignore +0 -8
  41. package/.gitattributes +0 -30
  42. package/.github/workflows/ci.yml +0 -193
  43. package/AGENTS.md +0 -389
  44. package/Dockerfile +0 -50
  45. package/docker-compose.yml +0 -23
  46. package/docs/CHANGELOG.md +0 -341
  47. package/docs/COVERAGE.md +0 -219
  48. package/docs/QUICK_START.md +0 -240
  49. package/eslint.config.js +0 -33
  50. package/n8n/ai-agent-safety-monitor.json +0 -355
  51. package/openapi.json +0 -1259
  52. package/scripts/check-version-sync.mjs +0 -69
  53. package/scripts/generate-jwt.ts +0 -121
  54. package/src/config.ts +0 -440
  55. package/src/haClient/automations.ts +0 -261
  56. package/src/haClient/calendars.ts +0 -94
  57. package/src/haClient/config.ts +0 -52
  58. package/src/haClient/devices.ts +0 -653
  59. package/src/haClient/entities.ts +0 -128
  60. package/src/haClient/events.ts +0 -689
  61. package/src/haClient/history.ts +0 -73
  62. package/src/haClient/index.ts +0 -336
  63. package/src/haClient/request.ts +0 -142
  64. package/src/haClient/services.ts +0 -45
  65. package/src/haClient/states.ts +0 -60
  66. package/src/haClient/updates.ts +0 -58
  67. package/src/haClient/wsCommand.ts +0 -44
  68. package/src/index.ts +0 -164
  69. package/src/localAI/index.ts +0 -88
  70. package/src/localAI/prompts.ts +0 -50
  71. package/src/localAI/providers/base.ts +0 -120
  72. package/src/localAI/providers/ollama.ts +0 -78
  73. package/src/localAI/providers/openai.ts +0 -86
  74. package/src/localAI/types.ts +0 -67
  75. package/src/omadaClient/auth.ts +0 -178
  76. package/src/omadaClient/client.ts +0 -337
  77. package/src/omadaClient/device.ts +0 -118
  78. package/src/omadaClient/index.ts +0 -310
  79. package/src/omadaClient/network.ts +0 -284
  80. package/src/omadaClient/request.ts +0 -365
  81. package/src/omadaClient/security.ts +0 -51
  82. package/src/omadaClient/site.ts +0 -344
  83. package/src/ownerQuestions/service.ts +0 -536
  84. package/src/permissions/index.ts +0 -143
  85. package/src/resources/index.ts +0 -213
  86. package/src/server/auth.ts +0 -175
  87. package/src/server/chatFace.ts +0 -789
  88. package/src/server/chatSlice.ts +0 -57
  89. package/src/server/common.ts +0 -170
  90. package/src/server/eventSubscription.ts +0 -343
  91. package/src/server/http.ts +0 -626
  92. package/src/server/instructions.ts +0 -97
  93. package/src/server/rateLimiter.ts +0 -227
  94. package/src/server/stdio.ts +0 -41
  95. package/src/server/stream.ts +0 -205
  96. package/src/tools/ai/analyzeSensors.ts +0 -33
  97. package/src/tools/ai/index.ts +0 -20
  98. package/src/tools/common.ts +0 -442
  99. package/src/tools/homeassistant/askOwner.ts +0 -133
  100. package/src/tools/homeassistant/automationControls.ts +0 -66
  101. package/src/tools/homeassistant/calendar.ts +0 -97
  102. package/src/tools/homeassistant/callService.ts +0 -25
  103. package/src/tools/homeassistant/controlClimate.ts +0 -68
  104. package/src/tools/homeassistant/controlCover.ts +0 -48
  105. package/src/tools/homeassistant/controlFan.ts +0 -44
  106. package/src/tools/homeassistant/controlLight.ts +0 -38
  107. package/src/tools/homeassistant/controlMediaPlayer.ts +0 -50
  108. package/src/tools/homeassistant/createAutomation.ts +0 -35
  109. package/src/tools/homeassistant/deleteAutomation.ts +0 -24
  110. package/src/tools/homeassistant/entityAction.ts +0 -35
  111. package/src/tools/homeassistant/entityGuard.ts +0 -28
  112. package/src/tools/homeassistant/getAllSensors.ts +0 -46
  113. package/src/tools/homeassistant/getAutomationTrace.ts +0 -30
  114. package/src/tools/homeassistant/getDomainSummary.ts +0 -29
  115. package/src/tools/homeassistant/getEntitiesByDomain.ts +0 -56
  116. package/src/tools/homeassistant/getHistory.ts +0 -24
  117. package/src/tools/homeassistant/getState.ts +0 -24
  118. package/src/tools/homeassistant/getStates.ts +0 -46
  119. package/src/tools/homeassistant/getVersion.ts +0 -21
  120. package/src/tools/homeassistant/index.ts +0 -121
  121. package/src/tools/homeassistant/listAutomations.ts +0 -35
  122. package/src/tools/homeassistant/listEntities.ts +0 -44
  123. package/src/tools/homeassistant/listPersons.ts +0 -46
  124. package/src/tools/homeassistant/sceneAndScript.ts +0 -53
  125. package/src/tools/homeassistant/searchEntities.ts +0 -58
  126. package/src/tools/homeassistant/sendNotification.ts +0 -179
  127. package/src/tools/homeassistant/systemTools.ts +0 -52
  128. package/src/tools/homeassistant/triggerAutomation.ts +0 -24
  129. package/src/tools/index.ts +0 -78
  130. package/src/tools/infra/actions.ts +0 -95
  131. package/src/tools/infra/index.ts +0 -138
  132. package/src/tools/omada/blockClient.ts +0 -28
  133. package/src/tools/omada/cyclePoePort.ts +0 -32
  134. package/src/tools/omada/deleteClient.ts +0 -27
  135. package/src/tools/omada/disableClientRateLimit.ts +0 -23
  136. package/src/tools/omada/getClient.ts +0 -14
  137. package/src/tools/omada/getDevice.ts +0 -14
  138. package/src/tools/omada/getFirewallSetting.ts +0 -14
  139. package/src/tools/omada/getInternetInfo.ts +0 -14
  140. package/src/tools/omada/getLanNetworkList.ts +0 -14
  141. package/src/tools/omada/getLanProfileList.ts +0 -14
  142. package/src/tools/omada/getPortForwardingStatus.ts +0 -26
  143. package/src/tools/omada/getRateLimitProfiles.ts +0 -14
  144. package/src/tools/omada/getSiteNtpStatus.ts +0 -14
  145. package/src/tools/omada/getSsidDetail.ts +0 -22
  146. package/src/tools/omada/getSsidList.ts +0 -21
  147. package/src/tools/omada/getSwitchStackDetail.ts +0 -14
  148. package/src/tools/omada/getThreatList.ts +0 -42
  149. package/src/tools/omada/getWlanGroupList.ts +0 -14
  150. package/src/tools/omada/graph.ts +0 -187
  151. package/src/tools/omada/index.ts +0 -153
  152. package/src/tools/omada/listBlockedClients.ts +0 -17
  153. package/src/tools/omada/listClients.ts +0 -14
  154. package/src/tools/omada/listClientsActivity.ts +0 -25
  155. package/src/tools/omada/listClientsPastConnections.ts +0 -44
  156. package/src/tools/omada/listDevices.ts +0 -14
  157. package/src/tools/omada/listDevicesStats.ts +0 -41
  158. package/src/tools/omada/listMostActiveClients.ts +0 -14
  159. package/src/tools/omada/listSites.ts +0 -18
  160. package/src/tools/omada/namespace.ts +0 -1164
  161. package/src/tools/omada/searchDevices.ts +0 -20
  162. package/src/tools/omada/setClientRateLimit.ts +0 -26
  163. package/src/tools/omada/setClientRateLimitProfile.ts +0 -25
  164. package/src/tools/omada/setSiteNtpServers.ts +0 -36
  165. package/src/tools/omada/setSsidEnabled.ts +0 -38
  166. package/src/tools/omada/unblockClient.ts +0 -26
  167. package/src/tools/types.ts +0 -11
  168. package/src/tools/utils/pagination-schema.ts +0 -27
  169. package/src/types/ai/index.ts +0 -11
  170. package/src/types/ai/types.ts +0 -67
  171. package/src/types/homeassistant/automations.ts +0 -43
  172. package/src/types/homeassistant/calendars.ts +0 -26
  173. package/src/types/homeassistant/config.ts +0 -14
  174. package/src/types/homeassistant/entities.ts +0 -14
  175. package/src/types/homeassistant/errors.ts +0 -33
  176. package/src/types/homeassistant/haConfig.ts +0 -7
  177. package/src/types/homeassistant/history.ts +0 -13
  178. package/src/types/homeassistant/index.ts +0 -46
  179. package/src/types/homeassistant/request.ts +0 -6
  180. package/src/types/homeassistant/serviceCall.ts +0 -18
  181. package/src/types/homeassistant/states.ts +0 -58
  182. package/src/types/homeassistant/updates.ts +0 -28
  183. package/src/types/index.ts +0 -12
  184. package/src/types/omada/activeClientInfo.ts +0 -17
  185. package/src/types/omada/clientActivity.ts +0 -32
  186. package/src/types/omada/clientBlockStatus.ts +0 -11
  187. package/src/types/omada/clientPastConnection.ts +0 -82
  188. package/src/types/omada/index.ts +0 -14
  189. package/src/types/omada/omadaApiResponse.ts +0 -5
  190. package/src/types/omada/omadaClientInfo.ts +0 -11
  191. package/src/types/omada/omadaDeviceInfo.ts +0 -11
  192. package/src/types/omada/omadaDeviceStats.ts +0 -31
  193. package/src/types/omada/omadaSiteSummary.ts +0 -5
  194. package/src/types/omada/oswStackDetail.ts +0 -11
  195. package/src/types/omada/paginatedResult.ts +0 -6
  196. package/src/types/omada/rateLimitProfile.ts +0 -58
  197. package/src/types/omada/threatInfo.ts +0 -38
  198. package/src/types/omada/tokenResult.ts +0 -6
  199. package/src/types.ts +0 -2
  200. package/src/utils/config-validations.ts +0 -68
  201. package/src/utils/jwt.ts +0 -112
  202. package/src/utils/logger.ts +0 -121
  203. package/src/utils/plainText.ts +0 -48
  204. package/src/utils/redact.ts +0 -59
  205. package/src/utils/sanitizeError.ts +0 -18
  206. package/src/utils/tlsDispatcher.ts +0 -69
  207. package/src/version.ts +0 -5
  208. package/tests/bdd/automation-creation.spec.ts +0 -214
  209. package/tests/bdd/automation-management.spec.ts +0 -267
  210. package/tests/bdd/calendar.spec.ts +0 -190
  211. package/tests/bdd/configuration.spec.ts +0 -283
  212. package/tests/bdd/device-control.spec.ts +0 -344
  213. package/tests/bdd/entity-listing.spec.ts +0 -208
  214. package/tests/bdd/entity-search.spec.ts +0 -183
  215. package/tests/bdd/history-retrieval.spec.ts +0 -195
  216. package/tests/bdd/notifications.spec.ts +0 -238
  217. package/tests/bdd/service-calls.spec.ts +0 -144
  218. package/tests/bdd/state-retrieval.spec.ts +0 -204
  219. package/tests/bench/hotpaths.bench.ts +0 -68
  220. package/tests/config.test.ts +0 -355
  221. package/tests/features/automation-creation.feature +0 -36
  222. package/tests/features/automation-management.feature +0 -54
  223. package/tests/features/calendar.feature +0 -37
  224. package/tests/features/configuration.feature +0 -70
  225. package/tests/features/device-control.feature +0 -100
  226. package/tests/features/entity-listing.feature +0 -51
  227. package/tests/features/entity-search.feature +0 -44
  228. package/tests/features/history-retrieval.feature +0 -38
  229. package/tests/features/notifications.feature +0 -37
  230. package/tests/features/service-calls.feature +0 -35
  231. package/tests/features/state-retrieval.feature +0 -37
  232. package/tests/fixtures/openapi-default-slice.json +0 -290
  233. package/tests/haClient/automationTrace.test.ts +0 -59
  234. package/tests/haClient/automations.test.ts +0 -149
  235. package/tests/haClient/config.test.ts +0 -117
  236. package/tests/haClient/entities.test.ts +0 -188
  237. package/tests/haClient/events.test.ts +0 -455
  238. package/tests/haClient/eventsTls.test.ts +0 -52
  239. package/tests/haClient/history.test.ts +0 -228
  240. package/tests/haClient/index.test.ts +0 -243
  241. package/tests/haClient/request.test.ts +0 -217
  242. package/tests/haClient/services.test.ts +0 -120
  243. package/tests/haClient/states.test.ts +0 -119
  244. package/tests/haClient/updates.test.ts +0 -193
  245. package/tests/index.test.ts +0 -160
  246. package/tests/integration/homeassistant.test.ts +0 -144
  247. package/tests/integration/omada.test.ts +0 -167
  248. package/tests/integration/server.test.ts +0 -151
  249. package/tests/localAI/index.test.ts +0 -177
  250. package/tests/localAI/ollama.test.ts +0 -187
  251. package/tests/localAI/openai.test.ts +0 -257
  252. package/tests/omadaClient/actions.test.ts +0 -161
  253. package/tests/omadaClient/clientBlocks.test.ts +0 -170
  254. package/tests/omadaClient/ntp.test.ts +0 -381
  255. package/tests/omadaClient/site.test.ts +0 -37
  256. package/tests/ownerQuestions/service.test.ts +0 -499
  257. package/tests/ownerQuestions/tools.test.ts +0 -186
  258. package/tests/permissions/index.test.ts +0 -217
  259. package/tests/resources/index.test.ts +0 -288
  260. package/tests/scripts/generateJwt.test.ts +0 -44
  261. package/tests/security/accessControl.test.ts +0 -223
  262. package/tests/security/authentication.test.ts +0 -117
  263. package/tests/security/configuration.test.ts +0 -170
  264. package/tests/security/cryptoTransport.test.ts +0 -172
  265. package/tests/security/dependencies.test.ts +0 -152
  266. package/tests/security/injection.test.ts +0 -117
  267. package/tests/security/insecureDesign.test.ts +0 -121
  268. package/tests/security/logging.test.ts +0 -131
  269. package/tests/security/resourceConsumption.test.ts +0 -142
  270. package/tests/server/auth.test.ts +0 -249
  271. package/tests/server/chatFace.test.ts +0 -320
  272. package/tests/server/common.test.ts +0 -84
  273. package/tests/server/http.test.ts +0 -561
  274. package/tests/server/instructions.test.ts +0 -152
  275. package/tests/server/memoizeJsonSchema.test.ts +0 -71
  276. package/tests/server/stdio.test.ts +0 -99
  277. package/tests/server/stream.test.ts +0 -285
  278. package/tests/server/toolVisibility.http.test.ts +0 -111
  279. package/tests/server/toolVisibility.test.ts +0 -129
  280. package/tests/tools/ai/analyzeSensors.test.ts +0 -227
  281. package/tests/tools/common.test.ts +0 -123
  282. package/tests/tools/homeassistant/handlers.test.ts +0 -872
  283. package/tests/tools/infra/invokeAction.test.ts +0 -280
  284. package/tests/tools/omada/graph.test.ts +0 -385
  285. package/tests/tools/omada/handlers.test.ts +0 -897
  286. package/tests/tools/omada/namespace.test.ts +0 -483
  287. package/tests/tools/registry.test.ts +0 -168
  288. package/tests/utils/config-validations.test.ts +0 -352
  289. package/tests/utils/jwt.test.ts +0 -115
  290. package/tests/utils/logger.test.ts +0 -327
  291. package/tests/utils/redact.test.ts +0 -105
  292. package/tsconfig.json +0 -24
  293. package/vitest.config.ts +0 -38
@@ -1,240 +0,0 @@
1
- # Quick Start Guide
2
-
3
- Get MCP-HA-Connect running in minutes. Choose your preferred installation method.
4
-
5
- ## Prerequisites
6
-
7
- - **Node.js 20+** - for npm/npx methods
8
- - **Docker** (optional) - for Docker method
9
- - Home Assistant instance with long-lived access token
10
-
11
- ## Getting Your Home Assistant Token
12
-
13
- 1. Log into your Home Assistant instance
14
- 2. Click on your profile (bottom left)
15
- 3. Scroll down to "Long-Lived Access Tokens"
16
- 4. Click "Create Token"
17
- 5. Give it a name (e.g., "MCP Server")
18
- 6. Copy the token (shown only once!)
19
-
20
- ## Installation Options
21
-
22
- ### Option 1: npx (Recommended - No Installation Required)
23
-
24
- ```json
25
- {
26
- "mcpServers": {
27
- "homeassistant": {
28
- "command": "npx",
29
- "args": ["-y", "@coffeerunhobby/mcp-ha-connect"],
30
- "env": {
31
- "HA_URL": "http://homeassistant.local:8123",
32
- "HA_TOKEN": "your_ha_long_lived_access_token"
33
- }
34
- }
35
- }
36
- }
37
- ```
38
-
39
- ### Option 2: Global npm Install
40
-
41
- ```bash
42
- npm install -g @coffeerunhobby/mcp-ha-connect
43
- ```
44
-
45
- ```json
46
- {
47
- "mcpServers": {
48
- "homeassistant": {
49
- "command": "mcp-ha-connect",
50
- "env": {
51
- "HA_URL": "http://homeassistant.local:8123",
52
- "HA_TOKEN": "your_ha_long_lived_access_token"
53
- }
54
- }
55
- }
56
- }
57
- ```
58
-
59
- ### Option 3: Docker
60
-
61
- ```json
62
- {
63
- "mcpServers": {
64
- "homeassistant": {
65
- "command": "docker",
66
- "args": [
67
- "run",
68
- "--rm",
69
- "-i",
70
- "-e", "HA_URL=http://host.docker.internal:8123",
71
- "-e", "HA_TOKEN=your_token",
72
- "ghcr.io/coffeerunhobby/mcp-ha-connect:latest"
73
- ]
74
- }
75
- }
76
- }
77
- ```
78
-
79
- ### Option 4: Local Development
80
-
81
- ```json
82
- {
83
- "mcpServers": {
84
- "homeassistant": {
85
- "command": "node",
86
- "args": ["/path/to/mcp-homeassistant/dist/index.js"],
87
- "env": {
88
- "HA_URL": "http://homeassistant.local:8123",
89
- "HA_TOKEN": "your_ha_long_lived_access_token"
90
- }
91
- }
92
- }
93
- }
94
- ```
95
-
96
- ### Option 5: Remote MCP Server (Claude Code on Windows)
97
-
98
- Connect to a remote HTTP MCP server without Docker or npx. Uses a Node.js one-liner as a stdio-to-HTTP bridge:
99
-
100
- ```json
101
- {
102
- "mcpServers": {
103
- "homeassistant": {
104
- "command": "node",
105
- "args": [
106
- "-e",
107
- "const http=require('http');const readline=require('readline');const rl=readline.createInterface({input:process.stdin,output:process.stdout,terminal:false});rl.on('line',(line)=>{const url=new URL(process.env.MCP_URL);const options={method:'POST',headers:{'Content-Type':'application/json','Accept':'application/json, text/event-stream','Authorization':'Bearer '+process.env.MCP_AUTH_TOKEN,'Content-Length':Buffer.byteLength(line)}};const req=http.request(url,options,(res)=>{let buffer='';const processLine=(l)=>{l=l.trim();if(l.startsWith('data: ')){const data=l.substring(6).trim();if(data&&data!=='[DONE]'){try{const json=JSON.parse(data);console.log(JSON.stringify(json));}catch(e){}}}};res.on('data',(chunk)=>{buffer+=chunk.toString();let newlineIndex;while((newlineIndex=buffer.indexOf('\\n'))!==-1){const line=buffer.substring(0,newlineIndex);buffer=buffer.substring(newlineIndex+1);processLine(line);}});res.on('end',()=>{if(buffer.trim()){processLine(buffer);}});});req.on('error',(e)=>console.error(JSON.stringify({jsonrpc:'2.0',error:{code:-1,message:e.message}})));req.write(line);req.end();});"
108
- ],
109
- "env": {
110
- "MCP_URL": "http://mcpserver.10.0.0.18.nip.io:3000/mcp",
111
- "MCP_AUTH_TOKEN": "your_bearer_auth_token_not_ha"
112
- }
113
- }
114
- }
115
- }
116
- ```
117
-
118
- This bridges stdio to your remote MCP HTTP server - useful when you can't run Docker or npx locally.
119
-
120
- ## Configuration File Locations
121
-
122
- ### Claude Desktop
123
- - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
124
- - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
125
- - **Linux:** `~/.config/Claude/claude_desktop_config.json`
126
-
127
- ### LM Studio
128
- - **Windows:** `%USERPROFILE%\.lmstudio\config.json`
129
- - **macOS:** `~/Library/Application Support/LM Studio/config.json`
130
- - **Linux:** `~/.config/lmstudio/config.json`
131
-
132
- ## HTTP Server Mode
133
-
134
- Start as standalone HTTP server for web applications or n8n:
135
-
136
- ```bash
137
- MCP_SERVER_USE_HTTP=true \
138
- MCP_HTTP_PORT=3000 \
139
- MCP_HTTP_BIND_ADDR=0.0.0.0 \
140
- HA_URL=http://homeassistant.local:8123 \
141
- HA_TOKEN=your_token \
142
- npx @coffeerunhobby/mcp-ha-connect
143
- ```
144
-
145
- ### Docker Compose
146
-
147
- ```yaml
148
- version: '3.8'
149
-
150
- services:
151
- mcp-ha-connect:
152
- image: ghcr.io/coffeerunhobby/mcp-ha-connect:latest
153
- container_name: mcp-ha-connect
154
- restart: unless-stopped
155
- ports:
156
- - "3000:3000"
157
- environment:
158
- - HA_URL=http://homeassistant.local:8123
159
- - HA_TOKEN=${HA_TOKEN}
160
- - MCP_SERVER_USE_HTTP=true
161
- - MCP_HTTP_BIND_ADDR=0.0.0.0
162
- ```
163
-
164
- ### With JWT Authentication
165
-
166
- ```yaml
167
- environment:
168
- - MCP_AUTH_METHOD=bearer
169
- - MCP_AUTH_SECRET=your_32_char_minimum_secret_key!
170
- - MCP_PERMISSIONS_CONFIG={"users":[{"sub":"admin","role":"admin"}],"defaultRole":"NONE"}
171
- ```
172
-
173
- Generate a JWT token with your secret using HS256 algorithm:
174
-
175
- ```bash
176
- # Example: Generate JWT with Node.js
177
- node -e "
178
- const crypto = require('crypto');
179
- const header = Buffer.from(JSON.stringify({alg:'HS256',typ:'JWT'})).toString('base64url');
180
- const payload = Buffer.from(JSON.stringify({sub:'admin',exp:Math.floor(Date.now()/1000)+86400})).toString('base64url');
181
- const signature = crypto.createHmac('sha256','your_32_char_minimum_secret_key!').update(header+'.'+payload).digest('base64url');
182
- console.log(header+'.'+payload+'.'+signature);
183
- "
184
- ```
185
-
186
- Then connect with:
187
- ```
188
- Authorization: Bearer <your-jwt-token>
189
- ```
190
-
191
- #### Available Roles
192
-
193
- | Role | Permissions |
194
- |------|-------------|
195
- | `READONLY` | Query entities and states |
196
- | `OPERATOR` | Query + Control devices + Notifications |
197
- | `CONTRIBUTOR` | Operator + Create/modify automations |
198
- | `ADMIN` | Full access except AI features |
199
- | `SUPERUSER` | All permissions |
200
-
201
- ## n8n Integration
202
-
203
- ![n8n MCP Client](n8n_mcp_client.png)
204
-
205
- 1. Add **MCP Client** node in n8n
206
- 2. Configure connection:
207
- - **SSE URL:** `http://your-server:3000/mcp`
208
- - **Authentication:** Bearer Token with JWT (if enabled)
209
- 3. Call tools like `getVersion`, `listEntities`, `getSystemLog`
210
-
211
- > **Note:** When using JWT authentication, generate a token with appropriate role permissions for your n8n workflows.
212
-
213
- ## Verify It's Working
214
-
215
- ### Test with curl
216
-
217
- ```bash
218
- # Health check
219
- curl http://localhost:3000/health
220
-
221
- # Call getVersion (with auth)
222
- curl -X POST http://localhost:3000/mcp \
223
- -H "Content-Type: application/json" \
224
- -H "Accept: application/json, text/event-stream" \
225
- -H "Authorization: Bearer your_token" \
226
- -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"getVersion","arguments":{}}}'
227
- ```
228
-
229
- ### Test with Claude Desktop
230
-
231
- Once configured, ask Claude:
232
- - "Show me all lights in my house"
233
- - "What's the temperature in the living room?"
234
- - "Who's home right now?"
235
-
236
- ## Next Steps
237
-
238
- - [Environment Variables](../README.md#environment-variables) - Full configuration reference
239
- - [Available Tools](../README.md#available-tools-60-total) - All 60 tools documented (35 Home Assistant + 24 Omada + 1 AI)
240
- - [Changelog](CHANGELOG.md) - Version history
package/eslint.config.js DELETED
@@ -1,33 +0,0 @@
1
- import eslint from '@eslint/js';
2
- import tseslint from 'typescript-eslint';
3
-
4
- export default tseslint.config(
5
- eslint.configs.recommended,
6
- ...tseslint.configs.recommended,
7
- {
8
- ignores: ['dist/**', 'node_modules/**', 'coverage/**', 'example/**'],
9
- },
10
- {
11
- files: ['src/**/*.ts'],
12
- languageOptions: {
13
- parserOptions: {
14
- projectService: true,
15
- tsconfigRootDir: import.meta.dirname,
16
- },
17
- },
18
- rules: {
19
- '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
20
- '@typescript-eslint/explicit-function-return-type': 'off',
21
- '@typescript-eslint/no-explicit-any': 'off',
22
- },
23
- },
24
- {
25
- files: ['tests/**/*.ts'],
26
- rules: {
27
- '@typescript-eslint/no-unused-vars': 'off',
28
- '@typescript-eslint/explicit-function-return-type': 'off',
29
- '@typescript-eslint/no-explicit-any': 'off',
30
- 'prefer-const': 'off',
31
- },
32
- }
33
- );
@@ -1,355 +0,0 @@
1
- {
2
- "name": "AI Agent Safety Monitor",
3
- "nodes": [
4
- {
5
- "parameters": {
6
- "rule": {
7
- "interval": [
8
- {
9
- "field": "minutes"
10
- }
11
- ]
12
- }
13
- },
14
- "type": "n8n-nodes-base.scheduleTrigger",
15
- "typeVersion": 1.2,
16
- "position": [
17
- 256,
18
- 304
19
- ],
20
- "id": "schedule",
21
- "name": "Every 5 Minutes"
22
- },
23
- {
24
- "parameters": {
25
- "method": "POST",
26
- "url": "http://mcpserver.10.0.0.18.nip.io:3000/mcp",
27
- "sendHeaders": true,
28
- "headerParameters": {
29
- "parameters": [
30
- {
31
- "name": "Accept",
32
- "value": "application/json, text/event-stream"
33
- }
34
- ]
35
- },
36
- "sendBody": true,
37
- "specifyBody": "json",
38
- "jsonBody": "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"getAllSensors\",\"arguments\":{}}}",
39
- "options": {}
40
- },
41
- "type": "n8n-nodes-base.httpRequest",
42
- "typeVersion": 4.2,
43
- "position": [
44
- 464,
45
- 304
46
- ],
47
- "id": "get-sensors",
48
- "name": "Get Sensors"
49
- },
50
- {
51
- "parameters": {
52
- "jsCode": "// Parse SSE response from MCP server\nlet rawResponse = $input.first().json;\nlet mcpResponse;\n\n// Handle SSE format (event: message\\ndata: {...})\nif (typeof rawResponse === 'string' || rawResponse.data) {\n const text = typeof rawResponse === 'string' ? rawResponse : rawResponse.data;\n const dataMatch = text.match(/^data:\\s*(.+)$/m);\n if (dataMatch) {\n mcpResponse = JSON.parse(dataMatch[1]);\n } else {\n throw new Error('No data line in SSE response');\n }\n} else {\n mcpResponse = rawResponse;\n}\n\nconst content = mcpResponse.result?.content?.[0]?.text;\nif (!content) throw new Error('No data from MCP');\nconst allSensors = JSON.parse(content);\n\nconst issues = [];\n\nfor (const sensor of allSensors) {\n const id = sensor.entity_id?.toLowerCase() || '';\n const state = String(sensor.state || '').toLowerCase();\n const stateClass = sensor.attributes?.state_class?.toLowerCase() || '';\n const deviceClass = sensor.attributes?.device_class?.toLowerCase() || '';\n const name = sensor.attributes?.friendly_name?.toLowerCase() || '';\n \n if (stateClass === 'total' || stateClass === 'total_increasing') continue;\n if (id.includes('cloud_connection') || id.includes('connectivity') || id.includes('_update') || id.includes('_connection')) continue;\n \n if (id.startsWith('binary_sensor.')) {\n if ((deviceClass === 'gas' || id.match(/\\bgas\\b/)) && state === 'on') {\n issues.push({sensor: sensor.entity_id, issue: 'GAS DETECTED', severity: 'critical', state, name: sensor.attributes?.friendly_name});\n }\n else if ((deviceClass === 'smoke' || id.includes('smoke')) && state === 'on') {\n issues.push({sensor: sensor.entity_id, issue: 'SMOKE DETECTED', severity: 'critical', state, name: sensor.attributes?.friendly_name});\n }\n else if ((deviceClass === 'carbon_monoxide' || id.match(/\\bco\\b/) || id.includes('carbon')) && state === 'on') {\n issues.push({sensor: sensor.entity_id, issue: 'CO DETECTED', severity: 'critical', state, name: sensor.attributes?.friendly_name});\n }\n else if ((deviceClass === 'moisture' || id.includes('leak') || id.includes('flood') || id.includes('water_') || name.includes('leak') || name.includes('moisture')) && state === 'on') {\n issues.push({sensor: sensor.entity_id, issue: 'Water detected', severity: 'critical', state, name: sensor.attributes?.friendly_name});\n }\n }\n else if (id.startsWith('sensor.')) {\n if ((id.includes('status') || id.includes('health')) && (state === 'attention' || state === 'warning' || state === 'error' || state === 'critical' || state === 'problem')) {\n issues.push({sensor: sensor.entity_id, issue: `Status: ${state}`, severity: 'high', state, name: sensor.attributes?.friendly_name});\n }\n else if (deviceClass === 'battery') {\n const batteryLevel = parseFloat(state);\n if (!isNaN(batteryLevel) && batteryLevel < 15) {\n issues.push({sensor: sensor.entity_id, issue: `Battery low: ${batteryLevel}%`, severity: batteryLevel < 5 ? 'high' : 'medium', state, name: sensor.attributes?.friendly_name});\n }\n }\n else if (deviceClass === 'temperature') {\n const temp = parseFloat(state);\n const unit = sensor.attributes?.unit_of_measurement;\n if (!isNaN(temp) && (unit === '°C' || unit === 'C')) {\n if (temp > 40) {\n issues.push({sensor: sensor.entity_id, issue: `Very high temp: ${temp}C`, severity: 'high', state, name: sensor.attributes?.friendly_name});\n } else if (temp < 0 && !name.includes('outdoor') && !name.includes('outside')) {\n issues.push({sensor: sensor.entity_id, issue: `Freezing temp: ${temp}C`, severity: 'medium', state, name: sensor.attributes?.friendly_name});\n }\n }\n }\n }\n}\n\nreturn [{json: {total_sensors: allSensors.length, issues_found: issues.length, issues: issues}}];"
53
- },
54
- "type": "n8n-nodes-base.code",
55
- "typeVersion": 2,
56
- "position": [
57
- 656,
58
- 304
59
- ],
60
- "id": "filter",
61
- "name": "Filter Issues"
62
- },
63
- {
64
- "parameters": {
65
- "jsCode": "const data = $input.first().json;\n\nif (data.issues_found === 0) {\n return [{json: {should_notify: false, notification: {title: 'All OK', message: `Monitored ${data.total_sensors} sensors - all normal`}, reasoning: 'No issues'}}];\n}\n\nconst criticalCount = data.issues.filter(i => i.severity === 'critical').length;\n\nconst prompt = `Home safety AI monitoring ${data.total_sensors} sensors.\n\nISSUES (${data.issues_found}):\n${JSON.stringify(data.issues, null, 2)}\n\nCritical: ${criticalCount}\n\nIMPORTANT: Create notification WITHOUT emojis or special characters. Plain text only.\n\nJSON:\n{\n \"should_notify\": true,\n \"notification\": {\n \"title\": \"${criticalCount > 0 ? 'CRITICAL ALERT' : 'System Notice'}\",\n \"message\": \"Plain text summary and actions needed\"\n },\n \"reasoning\": \"brief\"\n}`;\n\nreturn [{json: {model: 'phi4:14b', prompt: prompt, stream: false, issues: data.issues}}];\n"
66
- },
67
- "type": "n8n-nodes-base.code",
68
- "typeVersion": 2,
69
- "position": [
70
- 864,
71
- 304
72
- ],
73
- "id": "build",
74
- "name": "Build Prompt"
75
- },
76
- {
77
- "parameters": {
78
- "method": "POST",
79
- "url": "http://ollama.10.0.0.17.nip.io:11434/api/generate",
80
- "sendBody": true,
81
- "specifyBody": "json",
82
- "jsonBody": "={\"model\":\"ministral-3:14b\",\"prompt\":\"Home safety AI monitoring 278 sensors.\\n\\nISSUES (3):\\n[\\n {\\n \\\"sensor\\\": \\\"sensor.nas_station_s5_drive_1_temperature\\\",\\n \\\"issue\\\": \\\"Very high temp: 42C\\\",\\n \\\"severity\\\": \\\"high\\\",\\n \\\"state\\\": \\\"42\\\",\\n \\\"name\\\": \\\"nas-station-s5 (Drive 1) Temperature\\\"\\n },\\n {\\n \\\"sensor\\\": \\\"sensor.nas_station_s5_m_2_drive_2_temperature\\\",\\n \\\"issue\\\": \\\"Very high temp: 41C\\\",\\n \\\"severity\\\": \\\"high\\\",\\n \\\"state\\\": \\\"41\\\",\\n \\\"name\\\": \\\"nas-station-s5 (M.2 Drive 2) Temperature\\\"\\n },\\n {\\n \\\"sensor\\\": \\\"sensor.nas_station_s5_temperature\\\",\\n \\\"issue\\\": \\\"Very high temp: 60C\\\",\\n \\\"severity\\\": \\\"high\\\",\\n \\\"state\\\": \\\"60\\\",\\n \\\"name\\\": \\\"nas-station-s5 Temperature\\\"\\n }\\n]\\n\\nCritical: 0\\n\\nIMPORTANT: Create notification WITHOUT emojis or special characters. Plain text only.\\n\\nJSON:\\n{\\n \\\"should_notify\\\": true,\\n \\\"notification\\\": {\\n \\\"title\\\": \\\"System Notice\\\",\\n \\\"message\\\": \\\"Plain text summary and actions needed\\\"\\n },\\n \\\"reasoning\\\": \\\"brief\\\"\\n}\",\"stream\":false}",
83
- "options": {}
84
- },
85
- "type": "n8n-nodes-base.httpRequest",
86
- "typeVersion": 4.2,
87
- "position": [
88
- 1056,
89
- 304
90
- ],
91
- "id": "ollama",
92
- "name": "Ollama"
93
- },
94
- {
95
- "parameters": {
96
- "jsCode": "const ollamaResponse = $input.first().json;\nif (!ollamaResponse.response) {\n throw new Error('No response from Ollama');\n}\n\nlet responseText = ollamaResponse.response;\n\n// Remove markdown code fences\nresponseText = responseText.replace(/```json\\s*/g, '').replace(/```\\s*/g, '').trim();\n\n// Extract JSON (find first { to last })\nfunction extractJSON(text) {\n const firstBrace = text.indexOf('{');\n const lastBrace = text.lastIndexOf('}');\n \n if (firstBrace === -1 || lastBrace === -1 || firstBrace >= lastBrace) {\n throw new Error('No valid JSON object found in response');\n }\n \n return text.substring(firstBrace, lastBrace + 1);\n}\n\nlet jsonText = extractJSON(responseText);\n\n// DON'T escape newlines - JSON.parse() handles them fine\n// Just parse directly\nlet decision;\ntry {\n decision = JSON.parse(jsonText);\n} catch (e) {\n // If parse fails, try removing problematic characters\n jsonText = jsonText\n .replace(/[\\u0000-\\u001F]/g, '') // Remove control characters except newline/tab\n .replace(/,(\\s*[}\\]])/g, '$1'); // Remove trailing commas\n \n try {\n decision = JSON.parse(jsonText);\n } catch (e2) {\n throw new Error('JSON parse failed: ' + e2.message + '\\n\\nJSON text: ' + jsonText.substring(0, 500));\n }\n}\n\n// Clean up text helper\nfunction cleanText(text) {\n if (!text) return text;\n \n return text\n // Remove emojis\n .replace(/[\\u{1F600}-\\u{1F64F}]/gu, '')\n .replace(/[\\u{1F300}-\\u{1F5FF}]/gu, '')\n .replace(/[\\u{1F680}-\\u{1F6FF}]/gu, '')\n .replace(/[\\u{2600}-\\u{26FF}]/gu, '')\n .replace(/[\\u{2700}-\\u{27BF}]/gu, '')\n // Clean excessive whitespace\n .replace(/\\n{3,}/g, '\\n\\n')\n .trim();\n}\n\n// Clean notification fields\nif (decision.notification?.message) {\n decision.notification.message = cleanText(decision.notification.message);\n}\n\nif (decision.notification?.title) {\n decision.notification.title = cleanText(decision.notification.title);\n}\n\nreturn [{json: decision}];"
97
- },
98
- "type": "n8n-nodes-base.code",
99
- "typeVersion": 2,
100
- "position": [
101
- 1264,
102
- 304
103
- ],
104
- "id": "parse",
105
- "name": "Parse & Strip"
106
- },
107
- {
108
- "parameters": {
109
- "conditions": {
110
- "options": {
111
- "caseSensitive": true,
112
- "leftValue": "",
113
- "typeValidation": "strict",
114
- "version": 1
115
- },
116
- "conditions": [
117
- {
118
- "id": "notify",
119
- "leftValue": "={{ $json.should_notify }}",
120
- "rightValue": true,
121
- "operator": {
122
- "type": "boolean",
123
- "operation": "equals"
124
- }
125
- }
126
- ],
127
- "combinator": "or"
128
- },
129
- "options": {}
130
- },
131
- "type": "n8n-nodes-base.if",
132
- "typeVersion": 2,
133
- "position": [
134
- 1664,
135
- 304
136
- ],
137
- "id": "check",
138
- "name": "Notify?"
139
- },
140
- {
141
- "parameters": {
142
- "jsCode": "const message = $input.first().json.notification.message || 'Issue detected';\nconst title = $input.first().json.notification.title || 'Alert';\n\nconst mcpRequest = {\n jsonrpc: '2.0',\n id: 2,\n method: 'tools/call',\n params: {\n name: 'callService',\n arguments: {\n domain: 'notify',\n service: 'persistent_notification',\n service_data: {message, title}\n }\n }\n};\n\nreturn [{json: {mcpRequest}}];"
143
- },
144
- "type": "n8n-nodes-base.code",
145
- "typeVersion": 2,
146
- "position": [
147
- 1872,
148
- 208
149
- ],
150
- "id": "build-req",
151
- "name": "Build Request"
152
- },
153
- {
154
- "parameters": {
155
- "method": "POST",
156
- "url": "http://mcpserver.10.0.0.18.nip.io:3000/mcp",
157
- "sendHeaders": true,
158
- "headerParameters": {
159
- "parameters": [
160
- {
161
- "name": "Accept",
162
- "value": "application/json, text/event-stream"
163
- }
164
- ]
165
- },
166
- "sendBody": true,
167
- "specifyBody": "json",
168
- "jsonBody": "={{ JSON.stringify($json.mcpRequest) }}",
169
- "options": {}
170
- },
171
- "type": "n8n-nodes-base.httpRequest",
172
- "typeVersion": 4.2,
173
- "position": [
174
- 2064,
175
- 208
176
- ],
177
- "id": "notify",
178
- "name": "Send Alert"
179
- },
180
- {
181
- "parameters": {
182
- "jsCode": "return [{json: {result: 'Alert sent', issues: $('Build Prompt').item.json.issues}}];"
183
- },
184
- "type": "n8n-nodes-base.code",
185
- "typeVersion": 2,
186
- "position": [
187
- 2272,
188
- 208
189
- ],
190
- "id": "done-alert",
191
- "name": "Done Alert"
192
- },
193
- {
194
- "parameters": {
195
- "jsCode": "return [{json: {result: 'All OK'}}];"
196
- },
197
- "type": "n8n-nodes-base.code",
198
- "typeVersion": 2,
199
- "position": [
200
- 1872,
201
- 400
202
- ],
203
- "id": "done-ok",
204
- "name": "Done OK"
205
- },
206
- {
207
- "parameters": {
208
- "jsCode": "const notification = $input.first().json.notification;\nconst buildPromptData = $('Build Prompt').first().json;\nconst issues = buildPromptData.issues || [];\n\n// Create detailed alert log\nconst alertLog = {\n 'ALERT': notification.title,\n 'Message': notification.message,\n 'Issue Count': issues.length,\n 'Issues': issues.map(i => `${i.severity.toUpperCase()}: ${i.name} - ${i.issue}`),\n 'Time': new Date().toLocaleString()\n};\n\nconsole.log(JSON.stringify(alertLog, null, 2));\n\n// Pass data through unchanged\nreturn $input.all();"
209
- },
210
- "type": "n8n-nodes-base.code",
211
- "typeVersion": 2,
212
- "position": [
213
- 1472,
214
- 304
215
- ],
216
- "id": "code-in-javascript",
217
- "name": "Code in JavaScript"
218
- }
219
- ],
220
- "pinData": {},
221
- "connections": {
222
- "Every 5 Minutes": {
223
- "main": [
224
- [
225
- {
226
- "node": "Get Sensors",
227
- "type": "main",
228
- "index": 0
229
- }
230
- ]
231
- ]
232
- },
233
- "Get Sensors": {
234
- "main": [
235
- [
236
- {
237
- "node": "Filter Issues",
238
- "type": "main",
239
- "index": 0
240
- }
241
- ]
242
- ]
243
- },
244
- "Filter Issues": {
245
- "main": [
246
- [
247
- {
248
- "node": "Build Prompt",
249
- "type": "main",
250
- "index": 0
251
- }
252
- ]
253
- ]
254
- },
255
- "Build Prompt": {
256
- "main": [
257
- [
258
- {
259
- "node": "Ollama",
260
- "type": "main",
261
- "index": 0
262
- }
263
- ]
264
- ]
265
- },
266
- "Ollama": {
267
- "main": [
268
- [
269
- {
270
- "node": "Parse & Strip",
271
- "type": "main",
272
- "index": 0
273
- }
274
- ]
275
- ]
276
- },
277
- "Parse & Strip": {
278
- "main": [
279
- [
280
- {
281
- "node": "Code in JavaScript",
282
- "type": "main",
283
- "index": 0
284
- }
285
- ]
286
- ]
287
- },
288
- "Notify?": {
289
- "main": [
290
- [
291
- {
292
- "node": "Build Request",
293
- "type": "main",
294
- "index": 0
295
- }
296
- ],
297
- [
298
- {
299
- "node": "Done OK",
300
- "type": "main",
301
- "index": 0
302
- }
303
- ]
304
- ]
305
- },
306
- "Build Request": {
307
- "main": [
308
- [
309
- {
310
- "node": "Send Alert",
311
- "type": "main",
312
- "index": 0
313
- }
314
- ]
315
- ]
316
- },
317
- "Send Alert": {
318
- "main": [
319
- [
320
- {
321
- "node": "Done Alert",
322
- "type": "main",
323
- "index": 0
324
- }
325
- ]
326
- ]
327
- },
328
- "Done OK": {
329
- "main": [
330
- []
331
- ]
332
- },
333
- "Code in JavaScript": {
334
- "main": [
335
- [
336
- {
337
- "node": "Notify?",
338
- "type": "main",
339
- "index": 0
340
- }
341
- ]
342
- ]
343
- }
344
- },
345
- "active": false,
346
- "settings": {
347
- "executionOrder": "v1"
348
- },
349
- "versionId": "00000000-0000-0000-0000-000000000000",
350
- "meta": {
351
- "templateCredsSetupCompleted": true
352
- },
353
- "id": "1",
354
- "tags": []
355
- }