PositionGuard MCP server

positionguard-mcp

An MCP server that lets an AI assistant ask about PositionGuard presence: is Earl at the skatepark, who is at home, how many people are at the club. It answers only what each member has agreed to share with assistants, and says unknown when they haven't.

The server is a deterministic client of the public REST API. It holds one API key, calls three read-only endpoints, and maps what comes back into a small, explicit vocabulary. There is no model inside it and no privileged access: every guarantee is enforced at api.positionguardai.com, where the key is checked and the consent gate runs. This server cannot widen what the API returns. It can only ask.

What it asks for, and what it doesn't

This server gives the assistant less than it could, on purpose, and you can read exactly what.

groups:read. Do not grant areas:read: it unlocks /groups/{id}/areas, which returns area center coordinates, and this server never calls it. Area names and IDs come from /area-counts, which is coordinate-free by design. The client refuses to fetch /areas even if a future edit asked it to, and a test checks the refusal.

• Three scopes, not four. Grant presence:read, counts:read and

developer portal with type Assistant. Members are visible to an Assistant key only if they have turned on Let AI agents see whether I'm at an area; otherwise the key gets unknown. An Integration key works mechanically, and bypasses that consent gate. That is the key holder's choice to make; the reference configuration does not demonstrate it.

• An Assistant key, not an Integration key. Create the key in the

statuses, item counts, durations, tool names and the status a tool returned. The key appears once at startup, as its first 16 characters, the same prefix the portal shows.

• Never log a body, a key, or a name. Log lines carry paths, HTTP

global Ghost, who paused sharing, or whose phone has not reported in a while all look identical on the wire, and all map to unknown; the first three are captured in test/fixtures/ and asserted identical. The same holds per area: a member who is at an area but has hidden that one area from assistants is simply not listed there, and that absence is unknown too, never "not there". A member who joined a public group in Ghost mode is not on that roster at all, and one who joined anonymously is listed as "Anonymous"; the API does that before this server sees the roster. The tool descriptions tell the model, in so many words, that unknown means it doesn't know. A stale last-known position is never returned as a current location: it is unknown, or lastknownat_area with its age (below); counts include stale members and say so.

• unknown is not "away". A member who has not opted in, who is in

second place for a withdrawn consent to lag.

• No caching. The API caches for 15 seconds. A second cache would be a

Every tool is annotated readOnlyHint.

• Read-only. No write tools, no coordinates, no messages, no history.

Tools

Every answer is JSON with a status field. ok means the question was answered. unknown means it was not, and reason says why in one word. API failures are MCP tool errors carrying the HTTP status in one sentence, and are never retried.

Shortened. The full README is on GitHub.