sh-mcp/servers/sh-mcp-ops

sh-mcp-ops

Operations-tier Sea Haven MCP server. Exposes the ops tool registry (internal-data, knowledge-base, google-maps, gmail, calendar, tasks, reminders — see docs/design.md §3) over two universal interfaces backed by one shared dispatch path:

• MCP (Streamable HTTP) at POST /mcp — via @modelcontextprotocol/sdk.
• OpenAPI 3.1 — full document at GET /openapi.json, plus one POST /tools/{tool-name} endpoint per tool.

All scope enforcement, audience binding, input validation, rate limiting, and audit logging live in @sh-mcp/shared (executeTool) and are identical across both interfaces (docs/design.md §2.5).

Run locally (no AWS, no Cognito)

# from the repo root
npm install
npm run build            # or: npx tsc -b

SH_MCP_ENV=local PORT=8081 npm run start -w @sh-mcp/server-ops
# or live-reload:  SH_MCP_ENV=local npm run dev -w @sh-mcp/server-ops

SH_MCP_ENV=local wires in-memory dev clients (seeded fake data, no network) and the LocalAuthProvider, which maps dev bearer tokens to identities. The local provider refuses to construct unless SH_MCP_ENV=local.

Endpoints

Method	Path	Auth	Notes
GET	/healthz	no	{ "status": "ok" }
GET	/openapi.json	no	full OpenAPI 3.1 document
POST	/mcp (+GET/DELETE)	yes	MCP Streamable HTTP
POST	/tools/:name	yes	one-shot tool call, JSON in / JSON out

Dev bearer tokens (local only)

Token	Identity	Scopes
dev-ops-only	ops-only@seahavenind.com	ops:read, ops:tasks
dev-assistant	lauren@seahavenind.com	+ gmail:self, calendar:self
dev-ops-admin	adam@seahavenind.com	ops:read, ops:tasks, gmail/calendar self

Tokens minted for a different tier (e.g. dev-finance) are rejected by this server (audience binding).

Sample curl

TOKEN=dev-ops-only

curl -s localhost:8081/healthz
curl -s localhost:8081/openapi.json | jq '.openapi, (.paths | keys | length)'

curl -s -X POST localhost:8081/tools/lookup_work_order \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"workOrderId":"WO-1001"}' | jq

# tool-hiding is convenience; the boundary is server-side — a forced call to a
# tool you lack scope for is still 403:
curl -s -o /dev/null -w '%{http_code}\n' -X POST localhost:8081/tools/search_inbox \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"query":"invoice"}'   # → 403 (needs gmail:self)

MCP Inspector

Point the MCP Inspector at http://localhost:8081/mcp (transport: Streamable HTTP) and set an Authorization: Bearer dev-assistant header. tools/list reflects only the tools your token's scopes permit.

Environment

Var	Mode	Purpose
SH_MCP_ENV	both	local (dev clients) or aws (real/Cognito)
PORT	both	listen port (default 8081)
AWS_REGION	aws	Cognito region
COGNITO_USER_POOL_ID	aws	issuer / JWKS source
COGNITO_ALLOWED_CLIENT_IDS	aws	comma-list; the audience boundary
GOOGLE_MAPS_API_KEY	aws	maps client
REMINDER_TARGET_ARN etc.	aws	scheduler wiring

aws mode is not runtime-exercised in Phase 1 (real external clients are deferred stubs; Cognito infra is out of scope — see docs/build-plan-phase-1.md).

CDK

cdk/app.ts is a synth-only placeholder (npm run synth -w @sh-mcp/server-ops) so the CI cdk synth gate has a valid app. It provisions no real IAM, Cognito, API Gateway, or WAF — those land in a later phase behind the mandatory IAM cross-review.