Google MCP Router

# BUILD_START.md — Handoff Instructions for Engineer/Agent > Purpose: a precise, low‑ambiguity starting guide to implement the **Google‑only MCP Router** from scratch using the specs in `PLANNING.md`, `CONTEXT.md`, and `SYSTEM_DESIGN.md`. ## 0) Audience & Success Criteria **Audience:** a software engineer or capable AI agent with Node.js/TypeScript experience. **Success Criteria (MVP):** - All **5 tools** implemented and passing contract tests: `calendar.find_free_slots`, `calendar.create_event`, `calendar.cancel_event`, `email.send`, `time.resolve`. - Policy enforced server‑side: working hours, calendar allowlist, idempotency, overlap prevention. - OAuth (Google) flow working with encrypted token store. - Basic observability: JSON logs, Prometheus metrics, request tracing. - Staging runbook validated: happy‑path booking + cancel + confirmation email. ## 1) Read This First (Doc Order) 1. `SYSTEM_DESIGN.md` → architecture, stack, schemas, flows. 2. `PLANNING.md` → milestones, repository structure, test plan. 3. `CONTEXT.md` → policy, costs, error model, security. ## 2) Tooling & Versions - Node.js **≥ 20**; TypeScript **≥ 5.5**. - Fastify, AJV, openid-client, googleapis, luxon, pino, prom‑client, opentelemetry, vitest, nock, Redis (or SQLite for MVP). ## 3) Environment & Secrets (Staging) Create a **Google Cloud** project and enable **Calendar API** and **Gmail API**. - OAuth app (type: Web) with redirect URI: `https://<host>/oauth/google/callback` (or `http://localhost:8080/oauth/google/callback` for local). - Scopes: `https://www.googleapis.com/auth/calendar.events`, `https://www.googleapis.com/auth/gmail.send`. - Prepare `.env.staging` (or equivalent secret store) with keys below (prod uses KMS/Vault): ``` NODE_ENV=staging APP_PORT=8080 DEFAULT_TZ=America/Chicago DEFAULT_MEETING_MIN=30 ALLOWLIST_CALENDAR_IDS=primary WORK_HOURS_START=08:00 WORK_HOURS_END=18:00 WORK_DAYS=Mon,Tue,Wed,Thu,Fri GOOGLE_CLIENT_ID=... GOOGLE_CLIENT_SECRET=... GOOGLE_REDIRECT_URI=http://localhost:8080/oauth/google/callback TOKEN_ENC_KEY=base64:... REDIS_URL=redis://localhost:6379 LOG_LEVEL=info GMAIL_SENDER_EMAIL=assistant@yourdomain.com GMAIL_SENDER_NAME=Thinh’s Assistant ``` ## 4) Repository Bootstrap (Scaffold) Create the repo **exactly** as in `SYSTEM_DESIGN.md` §3. Key directories: ``` src/ server.ts mcp/{index.ts, tools/*, schemas/*} adapters/{google-calendar.ts, gmail-send.ts} policy/{calendars.json, rules.ts} auth/{oauth.ts, token-store.ts} templates/{meeting_confirm.hbs, cancel_confirm.hbs} util/{time.ts, errors.ts, idempotency.ts} ``` Include CI (lint, type‑check, tests, SBOM). ## 5) Implementation Order (Do Not Reorder) 1. **Schemas** — Define JSON Schemas for requests/responses (see `SYSTEM_DESIGN.md` §11). Add AJV validators. 2. **Errors** — Implement unified error types + provider mapping (`errors.ts`). 3. **Time** — Implement `util/time.ts` (IANA TZ, ISO helpers, clamp to work hours). 4. **Auth** — Implement OAuth (PKCE) + token store (AES‑GCM encrypt/decrypt) + refresh. 5. **Adapters** — - `google-calendar.ts`: freebusy, events.list, events.insert, events.delete. - `gmail-send.ts`: send MIME from Handlebars templates. 6. **Policy** — `policy/rules.ts`: working hours, overlap prevention, allowlist enforcement. 7. **Idempotency** — `util/idempotency.ts`: `(key,fingerprint)→outcome` TTL=24h. 8. **Tools** — Implement handlers in this exact order: - `time.resolve` - `calendar.find_free_slots` - `calendar.create_event` - `calendar.cancel_event` - `email.send` 9. **Server** — Wire Fastify routes (if any) + MCP registry + OpenTelemetry + metrics. 10. **Templates** — `meeting_confirm.hbs`, `cancel_confirm.hbs` (no untrusted HTML). ## 6) Definition of Done (per Tool) - **Validation:** request passes AJV; bad inputs return `INVALID_ARGUMENT` with clear path. - **Policy:** rejects off‑hours and non‑allowlisted calendars (`FORBIDDEN`). - **Idempotency:** replays with same `idempotency_key` return identical outcome. - **Observability:** logs include `{tool, request_id, latency_ms, code}`; metrics incremented. - **Tests:** unit + contract tests green; nock mocks for Google happy/edge cases. ## 7) Tests You Must Implement ### Contract Tests - Round‑trip validation for all schemas (req/resp). ### Policy Tests - Off‑hours clamp → `FORBIDDEN`. - Overlap → `CONFLICT`. - Duration bounds (min/max). ### Adapter Tests - Calendar freebusy OK + rateLimitExceeded + 5xx. - Gmail send OK + 401 with refresh + malformed template vars. ### Idempotency Tests - `create_event` replay returns `UPDATED` or cached result (as specified). ### Time Resolve Tests - Deterministic with `now_iso`; DST boundaries. ## 8) Local Run & Manual QA - Start Redis (or SQLite fallback). Run server on `:8080`. - Complete OAuth via `/oauth/google/login` → `/oauth/google/callback`. - Call tools via MCP client or HTTP shim: - `time.resolve`: "next Tue 3pm" → ISO. - `calendar.find_free_slots`: next week window → list slots. - `calendar.create_event`: book 30m slot → returns `event_id`. - `email.send`: MEETING_CONFIRM to your test address. - Verify logs/metrics; no PII beyond masked emails. ## 9) Staging Checklist - Separate Google project & calendars for staging. - DKIM/SPF configured for sender domain (or use Gmail default for testing). - Alerting thresholds: error rate >1%, p95 latency budget breaches, OAuth refresh failures. - Synthetic check: every 15 min, schedule+cancel in staging calendar. ## 11) Security Gates (must pass) - Dependency scan clean; no critical vulns. - Secrets only from env/secret store; no tokens in code or logs. - Egress filtered to `googleapis.com`. - Scopes limited to `calendar.events` & `gmail.send`. ## 12) Deliverables for Acceptance - Git repo with code, tests, and CI. - Metrics dashboard screenshots (latency/error SLIs). - Staging demo video (happy path + cancel path). - README with quickstart; this `BUILD_START.md` checked off. ## 13) Out‑of‑Scope (MVP) - Slack/Discord notifications; SMS; inbox reads; reschedule assistant; ICS in email (can be Week 3). ## 14) Escalation & Ownership - If Google quotas block progress → reduce concurrency, open a console request, or stub with mocks to continue feature work. - Security issues → pause rollout; rotate keys; audit logs; file incident doc. --- **You are expected to follow this order and check off each section.** For any ambiguity, prefer server‑side guardrails over longer prompts, and keep schemas terse to minimize LLM token load.