skylight-mcp

skylight_link_apple_calendar

Destructive

Link an Apple/iCloud calendar to the Skylight frame to sync events. Uses a server-side app password and asks for user confirmation before granting access.

Instructions

Link an Apple/iCloud calendar to the frame. The app-specific password is read from the server's SKYLIGHT_APPLE_APP_PASSWORD environment variable — it is never a tool argument, so it never passes through the model or the transcript. Linking hands Skylight persistent access to that iCloud account's calendars, so it asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE). The preview names the Apple ID and frame and fingerprints (never shows) the password.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "skylight_link_apple_calendar"
  }
}

Input Schema

Name	Required	Description
`email`	No	Apple ID email. Defaults to SKYLIGHT_APPLE_ID from the server's environment.
`frameId`	No
`confirmToken`	No	ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 "confirmation-required" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.3.0Sep 25, 2026

removedInput schema / properties / app_specific_password

Removed value: -{
-  "description": "An app-specific password generated at appleid.apple.com (NOT your normal Apple password).",
-  "type": "string"
-}

addedInput schema / properties / confirmToken

Added value: +{
+  "description": "ONLY for the two-step confirmation fallback (a client without MCP elicitation). The confirmToken from this same tool's phase-1 \"confirmation-required\" response, passed back ONLY after the user has seen that preview and explicitly approved it in chat — never on the first call, never invented, never reused. Call again with the same arguments. Ignored when the client supports elicitation.",
+  "type": "string"
+}

changedInput schema / properties / email / description

Previous value: -"Apple ID email."New value: +"Apple ID email. Defaults to SKYLIGHT_APPLE_ID from the server's environment."

removedInput schema / required

Removed value: -[
-  "email",
-  "app_specific_password"
-]

Changed1 schema field changedv1.0.1Sep 19, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

First observedv0.4.6Jul 30, 2026

TDQS

A3.9/5.0

Behavior5/5

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

Annotations only flag a destructive, open-world mutation; the description adds substantial context beyond them: the credential is sourced from a server env var and never transits the model or transcript, linking grants persistent access to the iCloud calendars, and a confirmation step is enforced with a concrete fallback flow. The preview contract (names Apple ID and frame, fingerprints but never shows the password) is exactly the kind of behavioral detail annotations cannot carry.

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?

Front-loads the action in the first sentence, then spends the remainder on security and confirmation mechanics that genuinely matter for invocation. The confirmToken explanation overlaps the schema's own text, which is modest redundancy, but nothing is padding.

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

Completeness4/5

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

For a destructive, credential-touching mutation with no output schema, the description covers the safety-critical surface: secrets handling, persistent-access implications, and the two-phase confirm path. It omits what a successful link returns or how failures surface, a minor gap given no output schema exists to cover it.

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

Parameters3/5

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

Schema coverage is 67%, and the schema already documents email's env-var default and confirmToken's fallback-only, never-reuse semantics in detail. The description largely restates that behavior rather than adding new per-parameter meaning, so it lands at the mid-coverage baseline.

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

Purpose4/5

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

States a specific verb and resource ('Link an Apple/iCloud calendar to the frame'), which is unambiguous on its own. It does not, however, name or contrast with the closest siblings (skylight_add_webcal, skylight_create_source_calendar), so an agent choosing among calendar-attachment tools gets no explicit routing signal.

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

Usage Guidelines3/5

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

The description gives clear procedural guidance on the two-step confirmation path (when confirmToken applies, when it is ignored), which is useful. It stops short of saying when to prefer this tool over alternative calendar-linking siblings, so the usage context is implied by the resource name rather than stated.

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

Deploy Server