# SheetMaster Todo & Finance MCP

Remote MCP server for the unified SheetMaster Todo and personal finance REST API v3.

## Authentication

Remote MCP requests use OAuth 2.1 with Supabase as the authorization server.
Each ChatGPT user authorizes the MCP app once, and the resulting Bearer token
is forwarded to the REST API as that user's Supabase session. The MCP does not
store user tokens and does not require a shared user API key in Vercel.

The frontend's `/oauth/consent` page is the Supabase OAuth authorization path.
It shows the signed-in user what the MCP client is requesting, then approves or
denies the authorization. Access-token refresh is handled by the OAuth client
and Supabase token endpoint, so users do not log in for every action.

For local stdio usage only, set the SheetMaster REST API URL and API key in the
environment before starting Codex:

```bash
export SHEETMASTER_API_URL="https://todoappsapi.vercel.app/api"
export SHEETMASTER_API_KEY="sm_live_your_key"
```

Do not commit the key or put it in `.mcp.json`.

## Deploy to Vercel

1. Import this repository into Vercel.
2. Set these Vercel environment variables:

   - `SHEETMASTER_API_URL=https://todoappsapi.vercel.app/api`
   - `MCP_RESOURCE_URL=https://YOUR_PROJECT.vercel.app/api/mcp`
   - `MCP_PROTECTED_RESOURCE_METADATA_URL=https://YOUR_PROJECT.vercel.app/.well-known/oauth-protected-resource`
   - `SUPABASE_AUTH_ISSUER=https://YOUR_PROJECT_REF.supabase.co/auth/v1`

   `MCP_RESOURCE_URL` must exactly match the MCP URL that will be entered in
   ChatGPT. Do not set a shared `SHEETMASTER_API_KEY` for the remote OAuth flow.
3. In Supabase Dashboard → Authentication → OAuth Server, enable the OAuth
   server, set the Authorization Path to `/oauth/consent`, and enable Dynamic
   Client Registration if it is available for the ChatGPT client.
4. Deploy and use `https://YOUR_PROJECT.vercel.app/api/mcp` as the remote MCP URL.
5. In the ChatGPT app configuration, choose OAuth authentication. ChatGPT will
   discover the protected-resource metadata, redirect to the SheetMaster
   consent page, and keep the resulting authorization for later requests.

The MCP server calls the REST API with `Authorization: Bearer <supabase token>`
and sends JSON action envelopes. The default upstream timeout is 25 seconds,
below the REST API function timeout. Write operations are never retried
automatically, preventing duplicate tasks.

The OAuth protected-resource metadata is served at
`/.well-known/oauth-protected-resource`. The API-key headers remain supported
for backward-compatible custom clients, and local stdio still uses
`SHEETMASTER_API_KEY`.

## Tools

- `sheetmaster_add` is the primary single gate for creating a Todo, expense, income, or transfer. It requires an explicit `entryType` so money requests cannot be silently routed to Todo. For expenses without an account, it checks balances and uses the safest sufficient recommended account; if no safe account exists, it returns a confirmation state instead of writing.
- `get_boards`, `get_board`
- `get_task`
- `create_task`, `update_task`, `move_task`, `delete_task`
- `finance_get_overview`, `finance_get_insights`, `finance_get_accounts`, `finance_recommend_account`, `finance_get_categories`
- `finance_list_transactions` (filters, amount bounds, and pagination), `finance_find_possible_duplicates`
- `finance_get_budgets`, `finance_list_recurring_rules`
- `finance_add_account`, `finance_update_account`
- `finance_add_category`, `finance_update_category`
- `finance_add_transaction`, `finance_update_transaction`, `finance_delete_transaction`
- `finance_transfer`, `finance_set_budget`, `finance_update_budget`
- `finance_add_recurring_rule`, `finance_update_recurring_rule`, `finance_delete_recurring_rule`

Finance write tools require `confirm: true` in the MCP schema. The client
should ask for confirmation of the exact account, category, amount, and date
before invoking them. Amounts are integer strings in IDR (rupiah), and should
not contain decimal separators.

The `sheetmaster_add` tool is the recommended entry point for mixed Todo and
Finance requests. Use `entryType=todo` only for tasks, reminders, and work
items; use `expense` for shopping, spending, and payments; `income` for money
received; and `transfer` for moving money between accounts.

For expenses and transfers, the MCP performs a fresh balance preflight through
`finance_recommend_account` before writing. If the selected source account
cannot cover the amount, the write is rejected unless the client explicitly
passes `allowNegativeBalance: true` after the user approves the overdraft.

These tools match the REST API actions currently permitted for SheetMaster API
keys. User-session-only actions are intentionally not exposed by this MCP
server.