Roadmap & Known Issues
Active tech debt, known issues, and planned work. Source: architecture session notes (2026-04-20) and graph/ files.
This page documents the honest state of sheets-mcp: what is known to be incomplete, what is actively planned, and what constraints affect current behavior. All items are sourced from the architecture session notes in graph/des.md committed to the repo.
Known issues
Build OOM on next build
The next build bundling step sometimes exceeds the available memory budget on CI-grade machines. This is a pre-existing infrastructure issue, not related to any specific feature. Workaround: run NODE_OPTIONS=--max-old-space-size=4096 next build locally.
Status: Parked — needs infra fix before CI/CD pipeline can be automated.
Hardcoded OIDC discovery in middleware
The OIDC discovery endpoint (/.well-known/oauth-authorization-server) is referenced by hardcoded URL in middleware. If the deployment URL changes, OIDC discovery silently breaks for MCP clients.
Status: Known. Fix: read BETTER_AUTH_URL env var at runtime instead of hardcoding.
Proactive token refresh adds latency
lib/mcp-google.ts refreshes the Google OAuth token on every tool call if the accessTokenExpiresAt is within 5 minutes of expiry. This is correctness-first but adds an extra DB write + Google token endpoint call on every invocation near token expiry.
Status: Known tradeoff. Lazy refresh (let Sheets API return 401, then refresh) would reduce latency but add a retry round-trip. Not yet changed.
Three pg.Pool instances
The codebase currently has two pg.Pool instances — one in lib/db.ts (used by MCP tools and schema cache) and one inside lib/auth.ts (used by better-auth). A third pool may be created by @supabase/ssr in some code paths.
Status: Consolidation is the next planned refactor. Impact: unnecessary connection slots consumed in Supabase.
Planned work
Rate limiting
Rate limiting is explicitly disabled (rateLimit: { enabled: false } in lib/auth.ts). No per-user or per-IP limits exist on any endpoint. This is intentional pre-launch — the implementation is ready to enable but needs configuration of limits before any public user traffic.
Target: Before first external user.
HMAC token rotation for Apps Script runner
The Apps Script runner (not yet publicly exposed) uses BETTER_AUTH_SECRET as the HMAC key to sign per-user runner tokens. A single secret leak would permanently compromise all runner tokens for all users.
Target: Before Apps Script runner is exposed. Planned fix: per-user HMAC keys or a separate signing secret.
pg.Pool consolidation
Merge the two (possibly three) pg.Pool instances into a single shared pool exported from lib/db.ts.
Target: Next refactor pass.
Apps Script runner (unreleased)
A per-user Google Apps Script web app runner is architected and committed but not publicly exposed. It evaluates arbitrary JS in the user's Google Workspace context — enabling UI automation (custom menus, sidebars, dialogs) that the Sheets REST API cannot do.
Status: Architecture complete, HMAC security needs hardening before release.
Security notes
These are not vulnerabilities — they are acknowledged constraints:
| Item | Status |
|---|---|
| No rate limiting on any endpoint | Pre-launch intentional — must be enabled before public traffic |
BETTER_AUTH_SECRET used for runner HMAC | Single-secret design — rotation planned |
debug_auth tool was previously exposed | Removed |
| Apps Script runner not publicly accessible | Withheld pending HMAC hardening |
Architecture constraints (by design)
These are deliberate decisions, not bugs:
| Constraint | Why |
|---|---|
transform_range never uses cache | Stale data + write-back = data corruption. Intentional. |
valueInputOption: RAW on transform_range writes | Prevents SQL output strings starting with = from being evaluated as formulas |
maxDuration: 60 on the transport route | Vercel serverless function limit. Long SQL queries or large sheet fetches may time out on very large datasets |
| Vercel CLI deploy only (no GitHub integration) | Deliberate — prevents accidental deploys from unreviewed pushes |
ConsoleSpanExporter for OTel | Stdout-only traces for agent log visibility. No OTLP HTTP endpoint configured yet |