From de256b625e756a233c14a75738a940f059061644 Mon Sep 17 00:00:00 2001
From: Stephen von Takach <steve@place.technology>
Date: Tue, 20 Oct 2026 16:32:07 +1100
Subject: [PATCH] feat(mcp): module state and logs as MCP resources

Uses the resource templates, subscriptions and long running routes from
action-controller 9.3 to bring the module debugging features of the
control websocket to MCP clients.

- resource templates: `placeos://modules/{id}/state`,
  `placeos://modules/{id}/state/{key}`, `placeos://systems/{sys_id}/{module_slug}/{key}`
  and `placeos://modules/{id}/logs{?seconds,level}`
- the two state value templates can be subscribed to. Watchers use the
  websocket's redis subscriptions, so any instance can serve a client, and
  clients re-read the resource when notified
- GET /modules/:id/state/:key/value returns the stored JSON as is, for MCP
  reads. `state_lookup` is unchanged
- GET /modules/:id/logs captures a module's debug output for `seconds`
  (30s default, 36h max) at or above `level`, streamed over HTTP and spooled
  to disk for MCP clients, capped at 3 MiB with a truncation marker
- module logs need support or admin users, or support subsystem Operate and
  Read (or Manage) on the module's zones. The websocket `debug` command now
  requires the same
- requires action-controller >= 9.3.0, which no longer issues Mcp-Session-Id

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 OPENAPI_DOC.yml                               | 230 +++++++++++++++++-
 shard.lock                                    |   2 +-
 shard.yml                                     |   2 +-
 spec/controllers/modules_spec.cr              |  89 +++++++
 spec/mcp_resources_spec.cr                    | 203 ++++++++++++++++
 spec/module_logs_spec.cr                      |  72 ++++++
 spec/websocket/session_spec.cr                |  21 ++
 src/placeos-rest-api/controllers/modules.cr   |  78 +++++-
 src/placeos-rest-api/controllers/systems.cr   |   4 +-
 src/placeos-rest-api/mcp.cr                   |  25 ++
 .../utilities/group_permissions.cr            |  20 ++
 src/placeos-rest-api/utilities/module_logs.cr | 142 +++++++++++
 src/placeos-rest-api/websocket/session.cr     |  55 ++---
 13 files changed, 902 insertions(+), 41 deletions(-)
 create mode 100644 spec/mcp_resources_spec.cr
 create mode 100644 spec/module_logs_spec.cr
 create mode 100644 src/placeos-rest-api/utilities/module_logs.cr

diff --git a/OPENAPI_DOC.yml b/OPENAPI_DOC.yml
index c9138e9f..dc62340d 100644
--- a/OPENAPI_DOC.yml
+++ b/OPENAPI_DOC.yml
@@ -12823,6 +12823,113 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/PlaceOS.Api.Application.ContentError'
+  /api/engine/v2/modules/{id}/state/{key}/value:
+    summary: Modules, running instances of drivers that control individual devices
+      and services
+    get:
+      summary: Returns the value of the requested status variable as JSON, `null`
+        when it isn't set.
+      description: 'Returns the value of the requested status variable as JSON, `null`
+        when it isn''t set.
+
+        Subscribe to the resource to be notified when the value changes'
+      tags:
+      - Modules
+      operationId: PlaceOS::Api::Modules_state_value
+      parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+      - name: key
+        in: path
+        description: the name of the status variable
+        example: power
+        required: true
+        schema:
+          type: string
+      responses:
+        "200":
+          description: OK
+        "409":
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.CommonError'
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.CommonError'
+        "503":
+          description: Service Unavailable
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.ImageGenError'
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.ImageGenError'
+        "404":
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.CommonError'
+        "429":
+          description: Too Many Requests
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.ImageGenError'
+        "422":
+          description: Unprocessable Entity
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.ParameterError'
+        "502":
+          description: Bad Gateway
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.CommonError'
+        "504":
+          description: Gateway Timeout
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.CommonError'
+        "406":
+          description: Not Acceptable
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.ContentError'
+        "408":
+          description: Request Timeout
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.CommonError'
+        "400":
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.ParameterError'
+        "415":
+          description: Unsupported Media Type
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.ContentError'
   /api/engine/v2/modules/{id}/state/{key}:
     summary: Modules, running instances of drivers that control individual devices
       and services
@@ -12928,6 +13035,124 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/PlaceOS.Api.Application.ContentError'
+  /api/engine/v2/modules/{id}/logs:
+    summary: Modules, running instances of drivers that control individual devices
+      and services
+    get:
+      summary: Captures the module's debug output for a period of time, as lines of
+      description: 'Captures the module''s debug output for a period of time, as lines
+        of
+
+        `<time> <LEVEL> <message>`. Over HTTP the lines are streamed as they arrive.
+
+        MCP clients receive them once the capture ends, so capturing for more than
+        a
+
+        minute may not work with all clients. The output is limited to 3 MiB.'
+      tags:
+      - Modules
+      operationId: PlaceOS::Api::Modules_logs
+      parameters:
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+      - name: seconds
+        in: query
+        description: how long to capture logs for, in seconds, up to 129600 (36 hours)
+        example: 30
+        schema:
+          type: integer
+          format: Int32
+      - name: level
+        in: query
+        description: 'the minimum level of the lines captured: trace, debug, info,
+          notice, warn, error or fatal'
+        example: info
+        schema:
+          type: string
+      responses:
+        "200":
+          description: OK
+        "409":
+          description: Conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.CommonError'
+        "401":
+          description: Unauthorized
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.CommonError'
+        "503":
+          description: Service Unavailable
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.ImageGenError'
+        "403":
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.ImageGenError'
+        "404":
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.CommonError'
+        "429":
+          description: Too Many Requests
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.ImageGenError'
+        "422":
+          description: Unprocessable Entity
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.ParameterError'
+        "502":
+          description: Bad Gateway
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.CommonError'
+        "504":
+          description: Gateway Timeout
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.CommonError'
+        "406":
+          description: Not Acceptable
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.ContentError'
+        "408":
+          description: Request Timeout
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.CommonError'
+        "400":
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.ParameterError'
+        "415":
+          description: Unsupported Media Type
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PlaceOS.Api.Application.ContentError'
   /api/engine/v2/modules/{id}/ping:
     summary: Modules, running instances of drivers that control individual devices
       and services
@@ -15034,7 +15259,10 @@ paths:
     summary: Systems are typically rooms or spaces, they can represent digital signage
       endpoints and are a collection of modules (devices) placed in zones
     get:
-      summary: Returns the state lookup for a given key on a module
+      summary: Returns the state lookup for a given key on a module.
+      description: 'Returns the state lookup for a given key on a module.
+
+        Subscribe to the resource to be notified when the value changes'
       tags:
       - Systems
       operationId: PlaceOS::Api::Systems_state_lookup
diff --git a/shard.lock b/shard.lock
index efbcdba2..6cb09f67 100644
--- a/shard.lock
+++ b/shard.lock
@@ -7,7 +7,7 @@ shards:
 
   action-controller:
     git: https://github.com/spider-gazelle/action-controller.git
-    version: 9.2.0
+    version: 9.3.0
 
   active-model:
     git: https://github.com/spider-gazelle/active-model.git
diff --git a/shard.yml b/shard.yml
index d87454b7..cbe7de95 100644
--- a/shard.yml
+++ b/shard.yml
@@ -10,7 +10,7 @@ dependencies:
   # Server framework
   action-controller:
     github: spider-gazelle/action-controller
-    version: ">= 8.3.1"
+    version: ">= 9.3.0"
 
   # Data validation library
   active-model:
diff --git a/spec/controllers/modules_spec.cr b/spec/controllers/modules_spec.cr
index f69f44c7..2acc6473 100644
--- a/spec/controllers/modules_spec.cr
+++ b/spec/controllers/modules_spec.cr
@@ -978,6 +978,95 @@ module PlaceOS::Api
         zone.destroy
       end
 
+      it "gates GET state value on the Read bit, returning the stored JSON as is" do
+        authority = Model::Authority.find_by_domain("localhost").not_nil!
+        user, headers = Spec::Authentication.authentication(sys_admin: false, support: false)
+
+        zone = Model::Generator.zone.save!
+        mod = support_setup.call(zone)
+        state_path = File.join(Modules.base_route, mod.id.as(String), "state")
+        PlaceOS::Driver::RedisStorage.new(mod.id.as(String))["power"] = %({"on":true,"level":2})
+
+        group = Model::Generator.group(authority: authority, subsystems: ["support"]).save!
+        gu = Model::Generator.group_user(user: user, group: group, permissions: Model::Permissions::Update).save!
+        gz = Model::Generator.group_zone(group: group, zone: zone, permissions: Model::Permissions::Update).save!
+
+        client.get(path: File.join(state_path, "power", "value"), headers: headers).status_code.should eq 403
+
+        gu.permissions = Model::Permissions::Read.to_i
+        gu.save!
+        gz.permissions = Model::Permissions::Read.to_i
+        gz.save!
+
+        result = client.get(path: File.join(state_path, "power", "value"), headers: headers)
+        result.status_code.should eq 200
+        result.headers["Content-Type"].should start_with "application/json"
+        JSON.parse(result.body).should eq JSON.parse(%({"on":true,"level":2}))
+
+        # the existing lookup still returns the value encoded as a string
+        String.from_json(client.get(path: File.join(state_path, "power"), headers: headers).body).should eq %({"on":true,"level":2})
+
+        missing = client.get(path: File.join(state_path, "missing", "value"), headers: headers)
+        missing.status_code.should eq 200
+        missing.body.should eq "null"
+
+        mod.destroy
+        zone.destroy
+      end
+
+      it "gates GET logs on the Operate and Read bits" do
+        authority = Model::Authority.find_by_domain("localhost").not_nil!
+        user, headers = Spec::Authentication.authentication(sys_admin: false, support: false)
+
+        zone = Model::Generator.zone.save!
+        mod = support_setup.call(zone)
+        logs_path = File.join(Modules.base_route, mod.id.as(String), "logs?seconds=1")
+
+        group = Model::Generator.group(authority: authority, subsystems: ["support"]).save!
+        gu = Model::Generator.group_user(user: user, group: group, permissions: Model::Permissions::Read).save!
+        gz = Model::Generator.group_zone(group: group, zone: zone, permissions: Model::Permissions::Read).save!
+
+        # Read alone is not enough
+        client.get(path: logs_path, headers: headers).status_code.should eq 403
+
+        # nor is Operate alone
+        gu.permissions = Model::Permissions::Operate.to_i
+        gu.save!
+        gz.permissions = Model::Permissions::Operate.to_i
+        gz.save!
+        client.get(path: logs_path, headers: headers).status_code.should eq 403
+
+        # Operate and Read => past the auth gate. Only the auth outcome is asserted,
+        # as core may not be running the module
+        both = (Model::Permissions::Operate | Model::Permissions::Read).to_i
+        gu.permissions = both
+        gu.save!
+        gz.permissions = both
+        gz.save!
+        client.get(path: logs_path, headers: headers).status_code.should_not eq 403
+
+        # support users can always capture logs
+        client.get(path: logs_path, headers: Spec::Authentication.headers(sys_admin: false, support: true)).status_code.should_not eq 403
+
+        mod.destroy
+        zone.destroy
+      end
+
+      it "validates the GET logs params" do
+        zone = Model::Generator.zone.save!
+        mod = support_setup.call(zone)
+        logs_path = File.join(Modules.base_route, mod.id.as(String), "logs")
+        headers = Spec::Authentication.headers
+
+        client.get(path: "#{logs_path}?seconds=0", headers: headers).status_code.should eq 400
+        client.get(path: "#{logs_path}?seconds=#{Modules::LOGS_MAX_SECONDS + 1}", headers: headers).status_code.should eq 400
+        client.get(path: "#{logs_path}?seconds=1&level=loud", headers: headers).status_code.should eq 400
+        client.get(path: "#{logs_path}?seconds=1&level=none", headers: headers).status_code.should eq 400
+
+        mod.destroy
+        zone.destroy
+      end
+
       it "keeps GET error support-JWT only, even for Manage grants" do
         authority = Model::Authority.find_by_domain("localhost").not_nil!
         user, headers = Spec::Authentication.authentication(sys_admin: false, support: false)
diff --git a/spec/mcp_resources_spec.cr b/spec/mcp_resources_spec.cr
new file mode 100644
index 00000000..8b005219
--- /dev/null
+++ b/spec/mcp_resources_spec.cr
@@ -0,0 +1,203 @@
+require "./helper"
+
+MCP_RESOURCES_PORT = 6_131
+
+# a 2026-07-28 MCP client, subscriptions need a real server as they're streamed
+class MCPResourcesClient
+  VERSION = "2026-07-28"
+  META    = JSON.parse(%({"io.modelcontextprotocol/protocolVersion":"#{VERSION}","io.modelcontextprotocol/clientCapabilities":{}}))
+
+  @headers : HTTP::Headers
+
+  def initialize(credentials : HTTP::Headers)
+    @headers = credentials.dup
+    @headers["Content-Type"] = "application/json"
+    @headers["Accept"] = "application/json, text/event-stream"
+    @headers["Host"] = "localhost"
+    @headers["MCP-Protocol-Version"] = VERSION
+  end
+
+  def prepare(id : Int32, method : String, params : Hash(String, JSON::Any)) : Tuple(HTTP::Headers, String)
+    params = params.merge({"_meta" => META})
+    headers = @headers.dup
+    headers["Mcp-Method"] = method
+    if method == "resources/read"
+      headers["Mcp-Name"] = params["uri"].as_s
+    end
+    {headers, {jsonrpc: "2.0", id: id, method: method, params: params}.to_json}
+  end
+
+  # the final JSON-RPC message of the response
+  def request(method : String, params = {} of String => JSON::Any) : JSON::Any
+    headers, body = prepare(1, method, params)
+    response = HTTP::Client.post("http://127.0.0.1:#{MCP_RESOURCES_PORT}#{PlaceOS::Api::MCP::PATH}", headers: headers, body: body)
+    response.status_code.should eq 200
+    return JSON.parse(response.body) unless response.content_type == "text/event-stream"
+    events = response.body.split("\n\n").compact_map do |event|
+      event.lines.find(&.starts_with?("data: ")).try { |data| JSON.parse(data.lchop("data: ")) }
+    end
+    events.last
+  end
+
+  def read(uri : String) : JSON::Any
+    request("resources/read", {"uri" => JSON::Any.new(uri)})
+  end
+
+  # posts on a raw socket so the response can be read as it streams
+  def stream(method : String, params : Hash(String, JSON::Any), &)
+    headers, body = prepare(1, method, params)
+    socket = TCPSocket.new("127.0.0.1", MCP_RESOURCES_PORT)
+    socket.read_timeout = 2.seconds
+    begin
+      HTTP::Request.new("POST", PlaceOS::Api::MCP::PATH, headers, body).to_io(socket)
+      socket.flush
+      HTTP::Client::Response.from_io(socket) { |response| yield response.body_io }
+    ensure
+      socket.close
+    end
+  end
+
+  # the next JSON-RPC message on an event stream, skipping keep-alive comments
+  def self.next_event(io : IO) : JSON::Any?
+    data = nil
+    while line = io.gets(chomp: true)
+      if line.empty?
+        return JSON.parse(data) if data
+        next
+      end
+      data = line.lchop("data: ") if line.starts_with?("data: ")
+    end
+  end
+end
+
+module PlaceOS::Api
+  describe "MCP resources" do
+    server = ActionController::Server.new(MCP_RESOURCES_PORT, "127.0.0.1")
+    MCP.mount(server)
+
+    before_all do
+      bound = Channel(Nil).new
+      spawn { server.run { bound.send nil } }
+      bound.receive
+    end
+
+    after_all { server.close }
+
+    it "lists the module state and logs resource templates" do
+      client = MCPResourcesClient.new(Spec::Authentication.headers)
+      result = client.request("resources/templates/list")["result"]
+      templates = result["resourceTemplates"].as_a.map(&.["uriTemplate"].as_s)
+      templates.should contain "placeos://modules/{id}/state"
+      templates.should contain "placeos://modules/{id}/state/{key}"
+      templates.should contain "placeos://systems/{sys_id}/{module_slug}/{key}"
+      templates.should contain "placeos://modules/{id}/logs{?seconds,level}"
+
+      discovered = client.request("server/discover")["result"]
+      discovered["capabilities"]["resources"]["subscribe"].should be_true
+    end
+
+    it "reads module state by module and by system" do
+      mod = Model::Generator.module.save!
+      module_id = mod.id.as(String)
+      control_system = Model::Generator.control_system
+      control_system.modules = [module_id]
+      control_system.save!
+      wait_for_module_lookups(control_system.id.as(String), {"#{mod.resolved_name}/1" => module_id})
+      PlaceOS::Driver::RedisStorage.new(module_id)["power"] = %({"on":true})
+
+      client = MCPResourcesClient.new(Spec::Authentication.headers)
+      uri = "placeos://modules/#{module_id}/state/power"
+      contents = client.read(uri)["result"]["contents"][0]
+      contents["uri"].should eq uri
+      contents["mimeType"].should eq "application/json"
+      JSON.parse(contents["text"].as_s).should eq JSON.parse(%({"on":true}))
+
+      state = client.read("placeos://modules/#{module_id}/state")["result"]["contents"][0]
+      JSON.parse(state["text"].as_s)["power"].should eq %({"on":true})
+
+      by_system = client.read("placeos://systems/#{control_system.id}/#{mod.resolved_name}_1/power")["result"]["contents"][0]
+      JSON.parse(by_system["text"].as_s).should eq JSON.parse(%({"on":true}))
+
+      control_system.destroy
+      mod.destroy
+    end
+
+    it "doesn't read module state without access" do
+      mod = Model::Generator.module.save!
+      client = MCPResourcesClient.new(Spec::Authentication.headers(sys_admin: false, support: false))
+      error = client.read("placeos://modules/#{mod.id}/state/power")["error"]
+      error["code"].should eq -32602
+      error["message"].as_s.should start_with "403"
+      mod.destroy
+    end
+
+    it "notifies subscribers when module state changes" do
+      mod = Model::Generator.module.save!
+      module_id = mod.id.as(String)
+      storage = PlaceOS::Driver::RedisStorage.new(module_id)
+      uri = "placeos://modules/#{module_id}/state/power"
+      client = MCPResourcesClient.new(Spec::Authentication.headers)
+
+      params = {"notifications" => JSON.parse({resourceSubscriptions: [uri, "placeos://modules/#{module_id}/logs"]}.to_json)}
+      client.stream("subscriptions/listen", params) do |body|
+        ack = MCPResourcesClient.next_event(body).should_not be_nil
+        ack["method"].should eq "notifications/subscriptions/acknowledged"
+        # logs can't be subscribed to
+        ack["params"]["notifications"]["resourceSubscriptions"].should eq JSON.parse([uri].to_json)
+
+        # redis pub/sub has no replay, so publish until the update arrives
+        update = nil
+        5.times do |attempt|
+          storage["power"] = attempt
+          update = MCPResourcesClient.next_event(body)
+          break if update
+        rescue IO::TimeoutError
+        end
+        update = update.should_not be_nil
+        update["method"].should eq "notifications/resources/updated"
+        update["params"]["uri"].should eq uri
+        update["params"]["_meta"]["io.modelcontextprotocol/subscriptionId"].should eq 1
+      end
+
+      mod.destroy
+    end
+
+    it "doesn't subscribe to module state without access" do
+      mod = Model::Generator.module.save!
+      client = MCPResourcesClient.new(Spec::Authentication.headers(sys_admin: false, support: false))
+      params = {"notifications" => JSON.parse({resourceSubscriptions: ["placeos://modules/#{mod.id}/state/power"]}.to_json)}
+      client.stream("subscriptions/listen", params) do |body|
+        ack = MCPResourcesClient.next_event(body).should_not be_nil
+        ack["params"]["notifications"].should eq JSON.parse("{}")
+        # with nothing to watch the subscription completes
+        MCPResourcesClient.next_event(body).should_not(be_nil)["result"]["resultType"].should eq "complete"
+      end
+      mod.destroy
+    end
+
+    it "captures module logs" do
+      mod = Model::Generator.module.save!
+      client = MCPResourcesClient.new(Spec::Authentication.headers)
+      uri = "placeos://modules/#{mod.id}/logs?seconds=1&level=info"
+      response = client.read(uri)
+      # core may not be running the module, so either the capture or a debugger failure
+      if result = response["result"]?
+        contents = result["contents"][0]
+        contents["uri"].should eq uri
+        contents["mimeType"].should eq "text/plain"
+        contents["text"].as_s.should be_a(String)
+      else
+        response["error"]["message"].as_s.should start_with "502"
+      end
+      mod.destroy
+    end
+
+    it "doesn't capture module logs without access" do
+      mod = Model::Generator.module.save!
+      client = MCPResourcesClient.new(Spec::Authentication.headers(sys_admin: false, support: false))
+      error = client.read("placeos://modules/#{mod.id}/logs?seconds=1")["error"]
+      error["message"].as_s.should start_with "403"
+      mod.destroy
+    end
+  end
+end
diff --git a/spec/module_logs_spec.cr b/spec/module_logs_spec.cr
new file mode 100644
index 00000000..2a25f788
--- /dev/null
+++ b/spec/module_logs_spec.cr
@@ -0,0 +1,72 @@
+require "./helper"
+
+module PlaceOS::Api
+  describe Utils::ModuleLogCapture do
+    it "writes lines at or above the level" do
+      output = IO::Memory.new
+      capture = Utils::ModuleLogCapture.new(output, ::Log::Severity::Info)
+      capture.write(::Log::Severity::Debug, "ignored")
+      capture.write(::Log::Severity::Info, "connected")
+      capture.write(::Log::Severity::Error, "failed")
+
+      lines = output.to_s.lines
+      lines.size.should eq 2
+      lines[0].should match /^\d{4}-\d\d-\d\dT[\d:.]+Z INFO connected$/
+      lines[1].should end_with "ERROR failed"
+      capture.bytes_written.should eq output.size
+    end
+
+    it "stops at the byte limit, noting the truncation" do
+      output = IO::Memory.new
+      capture = Utils::ModuleLogCapture.new(output, max_bytes: 200_i64)
+      10.times { |index| capture.write(::Log::Severity::Info, "message #{index}") }
+
+      output.to_s.should end_with Utils::ModuleLogCapture::TRUNCATED
+      output.size.should be <= 200
+      capture.finished?.should be_true
+
+      # the capture ends straight away
+      elapsed = Time.measure { capture.wait(5.seconds) }
+      elapsed.should be < 1.second
+    end
+
+    it "stops when the output fails" do
+      reader, writer = IO.pipe
+      reader.close
+      capture = Utils::ModuleLogCapture.new(writer)
+      capture.write(::Log::Severity::Info, "client gone")
+      capture.finished?.should be_true
+      Time.measure { capture.wait(5.seconds) }.should be < 1.second
+    ensure
+      writer.try &.close
+    end
+
+    it "waits for the period, reporting progress" do
+      context = ActionController::MCPServer::RequestContext.new(JSON::Any.new("token"))
+      capture = Utils::ModuleLogCapture.new(IO::Memory.new)
+      elapsed = Time.measure { capture.wait(300.milliseconds, context) }
+      elapsed.should be >= 300.milliseconds
+      elapsed.should be < 2.seconds
+      capture.finished?.should be_true
+    end
+
+    it "ends when the MCP request is cancelled" do
+      context = ActionController::MCPServer::RequestContext.new
+      capture = Utils::ModuleLogCapture.new(IO::Memory.new)
+      spawn do
+        sleep 100.milliseconds
+        context.cancel
+      end
+      Time.measure { capture.wait(5.seconds, context) }.should be < 2.seconds
+    end
+
+    it "ends when stopped, i.e. core closed the debug socket" do
+      capture = Utils::ModuleLogCapture.new(IO::Memory.new)
+      spawn do
+        sleep 100.milliseconds
+        capture.stop
+      end
+      Time.measure { capture.wait(5.seconds) }.should be < 2.seconds
+    end
+  end
+end
diff --git a/spec/websocket/session_spec.cr b/spec/websocket/session_spec.cr
index 62d252dd..b3721418 100644
--- a/spec/websocket/session_spec.cr
+++ b/spec/websocket/session_spec.cr
@@ -140,6 +140,27 @@ module PlaceOS::Api::WebSocket
         updates.shift.type.should eq Session::Response::Type::Success
       end
 
+      it "denies debug to users without access to the module" do
+        id = rand(10).to_i64
+        headers = Spec::Authentication.headers(sys_admin: false, support: false)
+        updates, _, _ = test_websocket_api(Systems.base_route, headers) do |ws, control_system, mod, ws_updates|
+          request = {
+            id:          id,
+            system_id:   control_system.id.as(String),
+            module_name: mod.id.as(String),
+            name:        "nugget",
+            command:     Session::Request::Command::Debug,
+          }
+          ws.send Session::Request.new(**request).to_json
+          wait_for_updates(ws_updates, 1)
+        end
+
+        updates.size.should eq 1
+        error = updates.shift
+        error.type.should eq Session::Response::Type::Error
+        error.error_code.should eq Session::Response::ErrorCode::AccessDenied
+      end
+
       it "ignore" do
         status_name = "nugget"
 
diff --git a/src/placeos-rest-api/controllers/modules.cr b/src/placeos-rest-api/controllers/modules.cr
index cdd5822a..fe2b687b 100644
--- a/src/placeos-rest-api/controllers/modules.cr
+++ b/src/placeos-rest-api/controllers/modules.cr
@@ -3,6 +3,7 @@ require "loki-client"
 require "placeos-driver/storage"
 require "placeos-driver/proxy/remote_driver"
 
+require "../utilities/module_logs"
 require "./application"
 require "./drivers"
 require "./settings"
@@ -24,12 +25,12 @@ module PlaceOS::Api
 
     before_action :check_admin, except: [
       :index, :create, :update, :destroy, :show, :start, :stop,
-      :state, :state_lookup, :ping, :execute, :load, :settings,
+      :state, :state_lookup, :state_value, :ping, :execute, :load, :settings, :logs,
     ]
     # Everything absent from the check_admin list above is gated by a
     # support-subsystem permission on the module's zones instead:
-    # show/state/state_lookup → Read, start/stop/ping/execute/load → Operate,
-    # settings → Update, create/update/destroy → the verb's bit.
+    # show/state/state_lookup/state_value → Read, start/stop/ping/execute/load → Operate,
+    # settings → Update, logs → Operate and Read, create/update/destroy → the verb's bit.
     before_action :check_support, only: [:show_error]
 
     ###############################################################################################
@@ -72,7 +73,7 @@ module PlaceOS::Api
     # Reading a single module: admin/support JWT and the legacy org_zone path
     # bypass; otherwise a "support" subsystem user needs Read on the module's
     # zones. A module with no derivable zones stays admin/support only.
-    @[AC::Route::Filter(:before_action, only: [:show, :state, :state_lookup])]
+    @[AC::Route::Filter(:before_action, only: [:show, :state, :state_lookup, :state_value])]
     def check_show_permissions
       ensure_support_access!(zones_for_module(current_module), ::PlaceOS::Model::Permissions::Read)
     end
@@ -87,6 +88,13 @@ module PlaceOS::Api
     # Viewing collated settings exposes configuration, so it requires write
     # level access (Update) rather than Read; encrypted values are still
     # masked for non-support roles by `decrypt_for!`.
+    # Debug output can include device traffic and credentials, see
+    # `GroupPermissions#module_debug_access?`
+    @[AC::Route::Filter(:before_action, only: [:logs])]
+    def check_debug_permissions
+      raise Error::Forbidden.new unless module_debug_access?(current_module.id.as(String))
+    end
+
     @[AC::Route::Filter(:before_action, only: [:settings])]
     def check_settings_permissions
       ensure_support_access!(zones_for_module(current_module), ::PlaceOS::Model::Permissions::Update)
@@ -463,11 +471,24 @@ module PlaceOS::Api
     end
 
     # Dumps the complete status state of the module, key values are serialised JSON
+    @[AC::MCP(resource: "placeos://modules/{id}/state", mime_type: "application/json", cache_ttl: 0)]
     @[AC::Route::GET("/:id/state")]
     def state : Hash(String, String)
       self.class.module_state(current_module).as(Hash(String, String))
     end
 
+    # Returns the value of the requested status variable as JSON, `null` when it isn't set.
+    # Subscribe to the resource to be notified when the value changes
+    @[AC::MCP(resource: "placeos://modules/{id}/state/{key}", mime_type: "application/json", subscribe: true, cache_ttl: 0)]
+    @[AC::Route::GET("/:id/state/:key/value")]
+    def state_value(
+      @[AC::Param::Info(description: "the name of the status variable", example: "power")]
+      key : String,
+    ) : Nil
+      # the value is stored as JSON, render it as is
+      render json: (Driver::RedisStorage.new(current_module.id.as(String))[key]? || "null")
+    end
+
     # Returns the value of the requested status variable
     @[AC::Route::GET("/:id/state/:key")]
     def state_lookup(
@@ -477,6 +498,55 @@ module PlaceOS::Api
       self.class.module_state(current_module, key).as(String)
     end
 
+    # the longest module logs capture, 36 hours
+    LOGS_MAX_SECONDS = 36 * 60 * 60
+
+    # Captures the module's debug output for a period of time, as lines of
+    # `<time> <LEVEL> <message>`. Over HTTP the lines are streamed as they arrive.
+    # MCP clients receive them once the capture ends, so capturing for more than a
+    # minute may not work with all clients. The output is limited to 3 MiB.
+    @[AC::MCP(resource: "placeos://modules/{id}/logs{?seconds,level}", mime_type: "text/plain", long_running: true, max_bytes: 3_145_728, cache_ttl: 0)]
+    @[AC::Route::GET("/:id/logs")]
+    def logs(
+      @[AC::Param::Info(description: "how long to capture logs for, in seconds, up to 129600 (36 hours)", example: "30")]
+      seconds : Int32 = 30,
+      # a String, as `Log::Severity` params don't resolve: `Log` is shadowed by the controller's logger
+      @[AC::Param::Info(description: "the minimum level of the lines captured: trace, debug, info, notice, warn, error or fatal", example: "info")]
+      level : String = "debug",
+    ) : Nil
+      unless 1 <= seconds <= LOGS_MAX_SECONDS
+        raise AC::Route::Param::ValueError.new("must be between 1 and #{LOGS_MAX_SECONDS}", "seconds")
+      end
+      severity = ::Log::Severity.parse?(level)
+      raise AC::Route::Param::ValueError.new("must be one of trace, debug, info, notice, warn, error or fatal", "level") if severity.nil? || severity.none?
+
+      capture = Utils::ModuleLogCapture.new(response, severity)
+      socket = begin
+        Utils::ModuleLogs.open(module_id: current_module.id.as(String), user_id: user_token.id, request_id: request_id) do |message_level, message|
+          capture.write(message_level, message)
+        end
+      rescue error
+        Log.warn(exception: error) { "failed to connect to the module debugger" }
+        raise Error::BadGateway.new("failed to connect to the module debugger: #{error.message}")
+      end
+
+      # stream the lines as they arrive
+      response.status = HTTP::Status::OK
+      response.content_type = "text/plain"
+      @__render_called__ = true
+      spawn(name: "module_logs_#{current_module.id}") do
+        socket.run
+      ensure
+        # core closed the socket
+        capture.stop
+      end
+      begin
+        capture.wait(seconds.seconds, mcp_context)
+      ensure
+        socket.close
+      end
+    end
+
     record PingResult, host : String, pingable : Bool?, warning : String?, exception : String? do
       include JSON::Serializable
     end
diff --git a/src/placeos-rest-api/controllers/systems.cr b/src/placeos-rest-api/controllers/systems.cr
index 8be90af1..462fb51f 100644
--- a/src/placeos-rest-api/controllers/systems.cr
+++ b/src/placeos-rest-api/controllers/systems.cr
@@ -575,7 +575,9 @@ module PlaceOS::Api
       self.class.module_state(sys_id, module_name, index) || {} of String => String
     end
 
-    # Returns the state lookup for a given key on a module
+    # Returns the state lookup for a given key on a module.
+    # Subscribe to the resource to be notified when the value changes
+    @[AC::MCP(resource: "placeos://systems/{sys_id}/{module_slug}/{key}", mime_type: "application/json", subscribe: true, cache_ttl: 0)]
     @[AC::Route::GET("/:sys_id/:module_slug/:key")]
     def state_lookup(
       sys_id : String,
diff --git a/src/placeos-rest-api/mcp.cr b/src/placeos-rest-api/mcp.cr
index c07e51ca..b37dd510 100644
--- a/src/placeos-rest-api/mcp.cr
+++ b/src/placeos-rest-api/mcp.cr
@@ -20,6 +20,11 @@ module PlaceOS::Api::MCP
     There is one toolbox per API resource. Every call is made as the signed in user,
     with their permissions. List results are paginated: follow the `Link` header (or use
     `X-Total-Count`) to fetch more.
+
+    Module state and debug logs are also resources (see resources/templates/list):
+    placeos://modules/{id}/state/{key} and placeos://systems/{sys_id}/{module_slug}/{key}
+    can be subscribed to for changes, placeos://modules/{id}/logs captures a module's
+    debug output for a number of seconds.
     TEXT
 
   # tokens are issued by auth.cr on the same host, its issuer is scheme + host
@@ -48,5 +53,25 @@ module PlaceOS::Api::MCP
     ActionController::MCPServer.mount(router, PATH)
   end
 
+  # Module state resources can be subscribed to. State changes are published on
+  # redis, so the instance holding a client's `subscriptions/listen` stream sees
+  # changes made anywhere. Access is checked by reading the resource first.
+  def self.watch_state : Nil
+    ActionController::MCPServer.watch("placeos://modules/{id}/state/{key}") do |variables, _request, changed|
+      subscriptions = WebSocket::Session.subscriptions
+      subscription = subscriptions.subscribe(variables["id"], variables["key"]) { |_, _| changed.call }
+      -> { subscriptions.unsubscribe(subscription); nil }
+    end
+
+    # follows the module if another is assigned to the system's module slot
+    ActionController::MCPServer.watch("placeos://systems/{sys_id}/{module_slug}/{key}") do |variables, _request, changed|
+      module_name, index = Driver::Proxy::RemoteDriver.get_parts(variables["module_slug"])
+      subscriptions = WebSocket::Session.subscriptions
+      subscription = subscriptions.subscribe(variables["sys_id"], module_name, index, variables["key"]) { |_, _| changed.call }
+      -> { subscriptions.unsubscribe(subscription); nil }
+    end
+  end
+
   configure
+  watch_state
 end
diff --git a/src/placeos-rest-api/utilities/group_permissions.cr b/src/placeos-rest-api/utilities/group_permissions.cr
index c947be13..ea84c2ed 100644
--- a/src/placeos-rest-api/utilities/group_permissions.cr
+++ b/src/placeos-rest-api/utilities/group_permissions.cr
@@ -414,6 +414,26 @@ module PlaceOS::Api
       zones.uniq
     end
 
+    # Debug output can include device traffic and credentials, so a "support"
+    # subsystem user needs both Operate and Read on the module's zones.
+    MODULE_DEBUG_PERMISSIONS = ::PlaceOS::Model::Permissions::Operate | ::PlaceOS::Model::Permissions::Read
+
+    # Whether the user can see a module's debug output (the websocket `debug`
+    # command and `GET /modules/:id/logs`): support/admin JWT, the legacy
+    # org_zone path, or the "support" subsystem granting Operate and Read (or
+    # Manage) on the module's zones. A module attached to no system has no
+    # derivable zones => support/admin only.
+    def module_debug_access?(module_id : String) : Bool
+      return true if user_support?
+      zones = module_zones(module_id)
+      return false if zones.empty?
+      return true if has_legacy_access?(zones)
+
+      perms_map = subsystem_zone_permissions(SUPPORT_SUBSYSTEM)
+      perms = zones.reduce(::PlaceOS::Model::Permissions::None) { |acc, zone| acc | (perms_map[zone]? || ::PlaceOS::Model::Permissions::None) }
+      perms.manage? || perms.includes?(MODULE_DEBUG_PERMISSIONS)
+    end
+
     # SQL subquery (single column: zone id) of the zones where the current
     # user holds `required` within any of `subsystems` — the zone-subtree
     # expansion runs in the database rather than materialising the zone set
diff --git a/src/placeos-rest-api/utilities/module_logs.cr b/src/placeos-rest-api/utilities/module_logs.cr
new file mode 100644
index 00000000..56fa1d70
--- /dev/null
+++ b/src/placeos-rest-api/utilities/module_logs.cr
@@ -0,0 +1,142 @@
+require "placeos-driver/proxy/remote_driver"
+
+require "./group_permissions"
+require "./permissions"
+
+module PlaceOS::Api
+  # A module's debug output, streamed from the core instance running it. Used by
+  # the websocket `debug` command and the `GET /modules/:id/logs` capture
+  module Utils::ModuleLogs
+    # Opens the module's debug socket on core, calling the block with each message.
+    # The socket isn't running, call `run` (it blocks until the socket closes) and
+    # `close` it when done
+    def self.open(
+      module_id : String,
+      user_id : String?,
+      sys_id : String = "",
+      request_id : String? = nil,
+      discovery : Clustering::Discovery = Driver::Proxy::RemoteDriver.default_discovery,
+      &block : ::Log::Severity, String -> Nil
+    ) : HTTP::WebSocket
+      driver = Driver::Proxy::RemoteDriver.new(
+        module_id: module_id,
+        sys_id: sys_id,
+        module_name: module_id,
+        discovery: discovery,
+        user_id: user_id,
+      ) { |id|
+        ::PlaceOS::Model::Module.find!(id).edge_id.as(String)
+      }
+
+      socket = driver.debug(request_id)
+      socket.on_message do |message|
+        level_value, text = Tuple(Int32, String).from_json(message)
+        block.call(::Log::Severity.from_value(level_value), text)
+      rescue error
+        Log.warn(exception: error) { "failed to forward debug message" }
+      end
+      socket
+    end
+  end
+
+  # Checks a websocket user's access to module debug output, see
+  # `GroupPermissions#module_debug_access?`. Created per check, so the
+  # permission memos never outlive it.
+  class Utils::ModuleDebugAccess
+    include Utils::Permissions
+    include Utils::GroupPermissions
+
+    def self.allowed?(user_token : ::PlaceOS::Model::UserJWT, module_id : String) : Bool
+      new(user_token).module_debug_access?(module_id)
+    end
+
+    def initialize(@user_token : ::PlaceOS::Model::UserJWT)
+    end
+
+    def user_support? : Bool
+      @user_token.is_support? || @user_token.is_admin?
+    end
+
+    getter current_user : ::PlaceOS::Model::User { ::PlaceOS::Model::User.find!(@user_token.id) }
+
+    getter current_authority : ::PlaceOS::Model::Authority? { ::PlaceOS::Model::Authority.find_by_domain(@user_token.domain) }
+  end
+
+  # Captures log lines, `<time> <LEVEL> <message>`, to an output for a period of
+  # time. Lines are written as they arrive, so nothing is held in memory: an HTTP
+  # response streams them and an MCP request spools them to disk.
+  #
+  # The capture ends when the period elapses, `max_bytes` is reached (a marker is
+  # written), the output fails (the client disconnected), the MCP request is
+  # cancelled or it's stopped
+  class Utils::ModuleLogCapture
+    MAX_BYTES = 3 * 1024 * 1024
+
+    TRUNCATED = "[truncated: the 3 MiB limit was reached]\n"
+
+    # how often progress is reported to MCP clients
+    PROGRESS_INTERVAL = 5.seconds
+
+    getter bytes_written : Int64 = 0_i64
+    getter? finished : Bool = false
+
+    @lock = Mutex.new
+    @stop = Channel(Nil).new(1)
+
+    def initialize(@output : IO, @level : ::Log::Severity = ::Log::Severity::Debug, @max_bytes : Int64 = MAX_BYTES.to_i64)
+    end
+
+    # writes the message, if it's at or above the level
+    def write(severity : ::Log::Severity, message : String) : Nil
+      return if severity < @level
+      line = "#{Time.utc.to_rfc3339(fraction_digits: 3)} #{severity.label} #{message}\n"
+      @lock.synchronize do
+        return if @finished
+        if @bytes_written + line.bytesize + TRUNCATED.bytesize > @max_bytes
+          @output << TRUNCATED
+          @output.flush
+          stop
+          return
+        end
+        @output << line
+        @output.flush
+        @bytes_written += line.bytesize
+      end
+    rescue IO::Error | HTTP::Server::ClientError
+      # the client disconnected
+      stop
+    end
+
+    # waits until the period elapses or the capture finishes, reporting progress
+    def wait(period : Time::Span, context : ActionController::MCPServer::RequestContext? = nil) : Nil
+      started = Time.instant
+      deadline = started + period
+      cancelled = context.try(&.done) || Channel(Nil).new
+
+      loop do
+        remaining = deadline - Time.instant
+        break if remaining <= Time::Span.zero
+
+        select
+        when @stop.receive
+          break
+        when cancelled.receive?
+          break
+        when timeout({remaining, PROGRESS_INTERVAL}.min)
+          context.try &.progress((Time.instant - started).total_seconds.to_i, period.total_seconds.to_i)
+        end
+      end
+      @lock.synchronize { @finished = true }
+    end
+
+    # ends the capture, i.e. when the debug socket closes
+    def stop : Nil
+      @finished = true
+      select
+      when @stop.send(nil)
+      else
+        # already stopping
+      end
+    end
+  end
+end
diff --git a/src/placeos-rest-api/websocket/session.cr b/src/placeos-rest-api/websocket/session.cr
index d852b9d8..dac001a2 100644
--- a/src/placeos-rest-api/websocket/session.cr
+++ b/src/placeos-rest-api/websocket/session.cr
@@ -4,6 +4,7 @@ require "placeos-driver/proxy/remote_driver"
 require "tasker"
 
 require "../error"
+require "../utilities/module_logs"
 require "../utilities/params"
 require "../utilities/permissions"
 
@@ -232,42 +233,30 @@ module PlaceOS::Api::WebSocket
     )
       # NOTE: In the interest of saving a redis lookup, the frontend passes
       #       the module_id, rather than name.
+      unless Utils::ModuleDebugAccess.allowed?(user, module_name)
+        Log.warn { {message: "websocket debug attempted without access", module_id: module_name} }
+        respond error_response(request_id, :access_denied, "attempted to debug a module without access", 403)
+        return
+      end
+
       existing_socket = debug_sessions[{system_id, module_name, index}]?
 
       if !existing_socket || existing_socket.closed?
-        driver = Driver::Proxy::RemoteDriver.new(
-          module_id: module_name,
-          sys_id: system_id,
-          module_name: module_name,
-          discovery: @discovery,
-          user_id: user.id,
-        ) { |module_id|
-          ::PlaceOS::Model::Module.find!(module_id).edge_id.as(String)
-        }
-
-        ws = driver.debug
-        ws.on_message do |message|
-          begin
-            level_value, message = Tuple(Int32, String).from_json(message)
-            level = ::Log::Severity.from_value(level_value)
-
-            respond(
-              Response.new(
-                id: request_id,
-                type: :debug,
-                module_id: module_name,
-                level: level,
-                message: message,
-                metadata: {
-                  sys:   system_id,
-                  mod:   module_name,
-                  index: index,
-                  name:  name,
-                },
-              ))
-          rescue e
-            Log.warn(exception: e) { "failed to forward debug message" }
-          end
+        ws = Utils::ModuleLogs.open(module_id: module_name, sys_id: system_id, user_id: user.id, discovery: @discovery) do |level, message|
+          respond(
+            Response.new(
+              id: request_id,
+              type: :debug,
+              module_id: module_name,
+              level: level,
+              message: message,
+              metadata: {
+                sys:   system_id,
+                mod:   module_name,
+                index: index,
+                name:  name,
+              },
+            ))
         end
 
         spawn { ws.run }