# Notion Local Ops Operator

> Use when working inside notion-local-ops-mcp on macOS startup, launchd keepalive, rolling reload, cloudflared tunnel status, or /mcp connection failures from Notion.

- Skill: `tomevault-io/notion-local-ops-operator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/notion-local-ops-operator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/notion-local-ops-operator/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/notion-local-ops-operator

---


# notion-local-ops operator

## Overview

This project has two runtime modes on macOS:

- `./scripts/dev-tunnel.sh` for foreground dev sessions
- launchd-managed services for long-lived local MCP + cloudflared keepalive

Prefer launchd when the goal is “stay up even if a shell/tmux pane dies”.

## Quick reference

- Install persistent services: `./scripts/install-launchd.sh`
- Check service + endpoint status: `./scripts/launchd-status.sh`
- Reload Python code without dropping the tunnel: `./scripts/launchd-reload.sh`
- Force restart after dependency/config changes: `./scripts/launchd-restart.sh all`
- Remove launchd services: `./scripts/uninstall-launchd.sh`

## Operational rules

- Keep the MCP supervisor and `cloudflared` as separate launchd services.
- Treat `launchd-reload.sh` as the default code-update path; it sends `HUP` to the supervisor so a fresh child server becomes ready before the old one drains.
- Use `launchd-restart.sh mcp` after `.venv` / dependency changes.
- Use `launchd-restart.sh cloudflared` after tunnel config changes.
- If install fails because the port is already bound, stop manual `dev-tunnel.sh` processes first.

## Debug order

1. `./scripts/launchd-status.sh`
2. Check local `http://127.0.0.1:8766/mcp`
3. Check public `https://<hostname>/mcp` if the tunnel config has a hostname
4. Inspect logs under `~/Library/Logs/notion-local-ops-mcp/`

## Common traps

- `dev-tunnel.sh` is not a durable keepalive service; closing the wrapper shell can still take everything down.
- launchd plists live under `~/Library/LaunchAgents/`; do not commit installed plist artifacts back into the repo.
- launchd gets a minimal environment. Always set runtime env vars through `.env` or the install-time render path, not by assuming your interactive shell exports them.

---
> Source: [catoncat/notion-local-ops-mcp](https://github.com/catoncat/notion-local-ops-mcp) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-19 -->