Skip to main content
Glama
ostapondo

plonk-mcp

by ostapondo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

set_awake

Prevent Mac sleep and keep chat apps from marking you Away by holding a power assertion and resetting the idle timer.

Instructions

Keep the Mac from sleeping, and optionally keep the user shown as available in chat apps. One session with two levels, called Pulse in the app. 'available' picks the level. Left off, Plonk holds a power assertion: the Mac does not sleep, but Slack and Teams still slide the user to Away, because those read the system idle timer and an assertion does not touch it. Turned on, Plonk also resets that idle timer with a Shift keypress every two minutes, which is what keeps a chat status green — and which postpones sleep by itself, so being available always includes being awake. Use it whenever the point is how the user looks to other people rather than whether a job finishes. Three ways to end the session, in order of preference: 'pid' ends it the moment that process exits — best by far when something is running, because a build or a render knows when it is finished and nothing is left holding the machine awake afterwards; 'until' ends it at a wall-clock time ('17:00', or an ISO-8601 timestamp); 'minutes' ends it after a countdown. Give none of them and it runs until switched off, or until the user's configured default timeout expires. Switching it by hand overrides the schedule until the schedule itself next changes, so turning it off during scheduled hours lasts until those hours end rather than being undone on the next tick. Sessions Plonk starts on its own — a recurring schedule of hours and weekdays, a list of apps whose being open arms it, or the charger being plugged in — are settings on the Pulse page rather than parameters here; get_state reports all of them under 'awake_details'. Behavior also follows those settings: a session may pause on battery, so the returned 'status' is what actually happened, 'awake' is whether an assertion is held right now, and 'available' is whether a keypress is actually being posted. Those differ from what was asked for when Plonk has no Accessibility permission (nothing can be posted, though the Mac still stays awake) or when the user disallowed running on battery and the Mac is unplugged; neither is an error, since the request was understood. The menu bar cube glows while a session holds. A process-bound session is deliberately not restored if Plonk restarts, since the pid would mean nothing by then. Errors come back for a pid that is not running or a time that has already passed.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
onYes
pidNoEnd when this process exits. Use the pid of the long job being waited on; get_state lists a pid for every open window
untilNoEnd at a time of day, e.g. '17:00' (the next such moment — tomorrow if today's has passed), or an ISO-8601 timestamp like '2026-08-08T17:00:00Z'
minutesNoEnd the session after this many minutes
availableNoAlso reset the idle timer, so chat apps go on showing the user as available instead of Away. This is the user's stored level rather than a property of one session: later sessions run at it too, until it is changed again. Omit to leave it as the user set it

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.4.3
    • addedInput schema / properties / available
      Added value: +{
+  "description": "Also reset the idle timer, so chat apps go on showing the user as available instead of Away. This is the user's stored level rather than a property of one session: later sessions run at it too, until it is changed again. Omit to leave it as the user set it",
+  "type": "boolean"
+}
  2. Changed3 schema fields changedv0.3.0
    • removedInput schema / additionalProperties
      Removed value: -false
    • addedInput schema / properties / minutes / maximum
      Added value: +9007199254740991
    • addedInput schema / properties / pid / maximum
      Added value: +9007199254740991
  3. Changed3 schema fields changedv0.2.2
    • changedInput schema / properties / minutes / description
      Previous value: -"Auto-off after this many minutes"New value: +"End the session after this many minutes"
    • addedInput schema / properties / pid
      Added value: +{
+  "description": "End when this process exits. Use the pid of the long job being waited on; get_state lists a pid for every open window",
+  "minimum": 1,
+  "type": "integer"
+}
    • addedInput schema / properties / until
      Added value: +{
+  "description": "End at a time of day, e.g. '17:00' (the next such moment — tomorrow if today's has passed), or an ISO-8601 timestamp like '2026-08-08T17:00:00Z'",
+  "type": "string"
+}
  4. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and this description goes beyond the schema substantially: it discloses the Shift keypress every two minutes, Accessibility-permission limitations, battery behavior, session restoration semantics, menu bar glow, and the fact that returned fields reflect actual behavior rather than requested behavior. It also states that certain outcomes are deliberate design choices and not errors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is long, but the tool is complex and there is no output schema or annotations to carry behavioral details. The description is front-loaded with the core purpose and then layers end-condition, persistence, and failure semantics; while some sentences are dense, they all earn their place given the absence of other structured context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and no annotations, the description unusually covers the important missing pieces: what the returned status fields mean, when they can diverge from requested behavior, error conditions, restart behavior, and how manual overrides interact with schedules. An agent can predict side effects and interpret results without further tool metadata.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is high at 80%, so the schema already documents parameter syntax. The description adds valuable selection logic, especially the order of preference for pid vs until vs minutes, and clarifies what happens when no end condition is given. This extra guidance lifts it above the high-coverage baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific, actionable purpose: 'Keep the Mac from sleeping, and optionally keep the user shown as available in chat apps.' It goes on to define the two 'levels' and explicitly distinguishes the tool's session concept from persistent Pulse-page settings, and even points to get_state for those settings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit contextual guidance: 'Use it whenever the point is how the user looks to other people rather than whether a job finishes,' plus guidance on choosing pid vs until vs minutes. It does not explicitly name a 'do not use this tool' case or a sibling alternative, but no sibling overlaps functionally, so the guidance is clear if not exhaustive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools