Initial local macOS MCP service

2026-05-26 21:54:57 -04:00
commit ad3bac91ae
18 changed files with 1937 additions and 0 deletions
@@ -0,0 +1,102 @@
+# MacMini MCP
+
+A local Model Context Protocol server that exposes selected macOS app actions to
+an AI harness. It uses Apple's scripting interfaces through `/usr/bin/osascript`
+and stays on the local machine.
+
+## Available tools
+
+| Tool | Action |
+| --- | --- |
+| `notes_list` | Search note titles and plaintext previews |
+| `notes_read` | Read a note by the ID returned by `notes_list` |
+| `notes_create` | Create a plaintext-backed note |
+| `calendar_list_calendars` | List calendars and write capability |
+| `calendar_list_events` | List events in an ISO-8601 time window |
+| `calendar_create_event` | Create an event on a named writable calendar |
+| `reminders_list_lists` | List reminder lists |
+| `reminders_list` | List reminders |
+| `reminders_create` | Create a reminder |
+
+There are no destructive tools in the initial server.
+
+## Setup
+
+Requires macOS and Node.js 20 or newer.
+
+```sh
+npm install
+npm run check
+npm run service:install
+```
+
+The service endpoint is:
+
+```text
+http://127.0.0.1:7331/mcp
+```
+
+Health check:
+
+```sh
+curl -s http://127.0.0.1:7331/health
+```
+
+`launchd` runs `node --watch src/http.js`, so edits to the server or imported
+modules cause it to restart automatically while the agent remains installed.
+After changing installed dependencies or service configuration, run:
+
+```sh
+npm install
+npm run service:install
+```
+
+Operational commands:
+
+```sh
+npm run service:status
+npm run service:restart
+npm run service:uninstall
+```
+
+Service logs are stored in `.logs/`.
+
+## Harness configuration
+
+For a harness that supports Streamable HTTP, configure the local MCP URL as
+`http://127.0.0.1:7331/mcp`.
+
+For a harness that launches stdio servers, use:
+
+```json
+{
+  "mcpServers": {
+    "macmini": {
+      "command": "/Users/adolforeyna/.nvm/versions/node/v22.22.0/bin/node",
+      "args": ["/Users/adolforeyna/Projects/MacMiniMCP/src/stdio.js"]
+    }
+  }
+}
+```
+
+## Permissions and security
+
+On first use of a Notes, Calendar, or Reminders tool, macOS may ask for
+Automation access for Node. Permit only the applications you want the server
+to control under **System Settings > Privacy & Security > Automation**.
+
+The HTTP service binds to `127.0.0.1` by default. To require bearer
+authentication even locally, create `.env` from `.env.example` and set
+`MACMINI_MCP_TOKEN`; clients must then send `Authorization: Bearer <token>`.
+Do not bind to a non-loopback address without enabling authentication and
+reviewing the tools first.
+
+## Development
+
+```sh
+npm run check
+npm run dev
+```
+
+The MCP transport follows the official TypeScript SDK Streamable HTTP server
+approach: [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).