mcp-safari: Instructions file for Claude Code

Project Instructions

A MCP (Model Context Protocol) server bridging Safari with Claude agents. Published to npm as @axivo/mcp-safari and consumed by MCP-capable hosts (Claude Code, Claude Desktop) via stdio transport.

Collaborator

• Name: Floren Munteanu
• Work: Engineering

Personal Preferences

I'm a site reliability engineer specialized in:

• Advanced GitHub actions based on JS code
• Helm charts
• IaC for Kubernetes clusters
• Next.js/Nextra static websites

Architecture

A small TypeScript server that translates MCP tool calls into Safari automation. There is no daemon, no listening socket, no HTTP server - the host (e.g., Claude Code) spawns the server as a child process, communicates over stdio, and tears it down when the host exits. The server controls the user's actual Safari session through Apple Events (AppleScript and JXA), so cookies, login state, and browsing history are preserved across calls.

The server's job is small and focused: accept a tool call from the host, drive Safari to perform it, return a structured response. No state is persisted across server restarts. There is no authentication layer between host and server because there is no transport-level access - whoever controls the MCP client controls the server entirely. Security relies on the host enforcing tool boundaries and on the user trusting the MCP client they configure.

Directory Tree

.
├── package.json                          npm metadata, runtime deps: @modelcontextprotocol/sdk, sharp, zod
├── tsconfig.json                         strict TypeScript, ES2022 target, NodeNext modules, DOM lib for browser-side scripts
├── CHANGELOG.md                          Keep a Changelog format, semver
├── README.md                             user-facing install + tool reference
├── SECURITY.md                           threat model, supply-chain integrity policy
├── LICENSE                               BSD-3-Clause
├── .github/
│   ├── workflows/package.yml             trusted-publish to npm on `v*` tag push (no PAT, OIDC provenance)
│   ├── renovate.json5                    dependency dashboard config
│   └── pull_request_template.md
├── .vscode/
│   ├── settings.json                     editor formatting, 2-space indent, format-on-save
│   └── extensions.json                   recommended extensions
└── src/
    ├── index.ts                          entry point - stdio transport + Mcp class instantiation, EPIPE handling
    ├── server/
    │   ├── mcp.ts                        Mcp class - registers tools via McpServer.registerTool, owns dispatch
    │   ├── tool.ts                       McpTool class - tool definitions (Zod input/output schemas, _meta.usage, annotations)
    │   └── client.ts                     Client class - working tab capture, act/observe target dispatch, AppleScript/JXA invocation, response normalization
    └── lib/
        ├── automation.ts                 Automation class - AppleScript template strings parsed into a Map at construction
        └── browser.ts                    Browser class - JavaScript scripts (function bodies serialized via fn.toString()) for `do JavaScript` execution