# Photon iMessage MCP

A separate MCP server for Photon Advanced iMessage features. It does not modify
or replace Hermes' native Photon bridge. Version `0.1.0` focuses on shared Find
My locations because those are not part of Spectrum's ordinary message stream.

The server reuses the Photon project already connected to Hermes. It exchanges
the project ID and secret for short-lived Advanced iMessage credentials, selects
the shared or dedicated route, and refreshes credentials without another login.

## Tools

- `photon_location_list` — list allowed shared locations
- `photon_location_get` — fetch one allowed location
- `photon_location_request` — send a visible Find My request card
- `photon_location_watch_start` / `photon_location_watch_stop` — control the
  live gRPC location stream
- `photon_location_watch_status` — inspect watcher health
- `photon_location_latest` — read the last in-memory live update

Locations are never persisted or logged. `PHOTON_ALLOWED_ADDRESSES` is required
and enforced inside the service. Visible requests are disabled unless
`PHOTON_ALLOW_MUTATIONS=true`, and the tool call must also include
`confirm=true`.

## Authentication

This server uses Photon's current `@photon-ai/advanced-imessage` gRPC SDK. The
recommended configuration reuses the project credentials already held by the
Hermes Photon bridge:

```dotenv
PHOTON_PROJECT_ID=11111111-1111-4111-8111-111111111111
PHOTON_PROJECT_SECRET=replace-at-runtime
PHOTON_ALLOWED_ADDRESSES=+14155550123
PHOTON_LOCATION_STALE_AFTER_SECONDS=300
PHOTON_ALLOW_MUTATIONS=false
```

For a dedicated project with multiple lines, set `PHOTON_IMESSAGE_PHONE` to the
line that should own the MCP connection. Explicit endpoint/token configuration
remains available for self-hosted Advanced iMessage servers.

## Install into Hermes

Clone a pinned release into Hermes' persistent data volume and run the included
installer from inside the Hermes container:

```bash
mkdir -p /opt/data/mcps
git clone --depth 1 --branch v0.1.0 \
  https://github.com/nathanielangafor/photon-mcp.git \
  /opt/data/mcps/photon-mcp
cd /opt/data/mcps/photon-mcp
./install-hermes.sh
```

The installer:

- confirms the existing Photon variables are present without printing them;
- builds pinned dependencies from `package-lock.json`;
- references the existing secrets in `config.yaml` instead of copying values;
- derives the MCP location allowlist from `PHOTON_ALLOWED_USERS`;
- preserves an existing MCP tool filter; and
- enables the server with mutations disabled.

It is safe to run the installer again from the same checkout. Start a new
Hermes session after installation so the new MCP tools are discovered.

## Build and test

Requires Node.js 20 or later.

```bash
npm ci
npm run check
npm test
npm run build
```

Run the MCP server over stdio:

```bash
npm start
```

The service writes MCP protocol frames only to stdout. Operational messages go
to stderr, and Photon payloads and credentials are not logged.

## Hermes configuration

Build the server, place this directory somewhere readable by the Hermes
container, and add the following to `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  photon-imessage:
    command: node
    args:
      - /opt/photon-mcp/dist/index.js
    env:
      PHOTON_PROJECT_ID: "${PHOTON_PROJECT_ID}"
      PHOTON_PROJECT_SECRET: "${PHOTON_PROJECT_SECRET}"
      PHOTON_ALLOWED_ADDRESSES: "${PHOTON_ALLOWED_USERS}"
      PHOTON_LOCATION_STALE_AFTER_SECONDS: "300"
      PHOTON_ALLOW_MUTATIONS: "false"
```

Hermes intentionally passes only configured environment variables to stdio MCP
children. Do not commit the token or place it directly in this repository.

## Current limitation

The live watcher is process-local and does not persist coordinates. A Hermes or
MCP restart stops the watcher; call `photon_location_watch_start` again. Find My
availability on Photon shared-pool lines still needs a live read-only probe.