# kubera-3p-mcp

Typed TypeScript client for the Kubera (`api.kubera.com`) REST API, plus an MCP server that exposes those endpoints as tools.

## Why does this exist?

Kubera has decided that if you have a white-label account (i.e. run by your financial advisor), you're not allowed to use their MCP Server to access your own financial data. So instead, we make our own and tell them to fly a kite.

## Requirements

- [Bun](https://bun.sh) 1.1+ (for local development / `prepare` build)
- Node.js 18+ (to run the published `bin` bundle)

## Install

```bash
bun install
```

## Auth: `cognito-session.json`

Kubera API calls use:

```http
Authorization: Bearer <Cognito AccessToken>
```

AccessTokens expire in about an hour. You provide a Cognito **session file** (refresh token, device fields, and your white-label `baseUrl`). Derived AccessTokens are cached on disk — same pattern as stonex-mcp — so Cognito refresh is not called on every tool use.

The session file also carries:

| Field | Purpose |
|-------|---------|
| `baseUrl` | White-label host used for `Origin` / `Referer` (required) |
| `apiBaseUrl` | API root (optional; defaults to `https://api.kubera.com/api/v1`) |
| `clientId` | Cognito app client id (from Amplify localStorage) |
| `userPoolId` | Cognito user pool id (from access/id token `iss`) |

### Export session (one paste)

1. Log into your Kubera white-label host in the browser.
2. Open DevTools → **Console**.
3. Paste the contents of [`scripts/export-cognito-session.js`](scripts/export-cognito-session.js) and press Enter.
4. Save the downloaded `cognito-session.json`.
5. Run:

```bash
kubera-3p-mcp --session /path/to/cognito-session.json
```

### AccessToken cache

| OS | Path |
|----|------|
| Windows | `%LOCALAPPDATA%\kubera-3p-mcp\access-token.json` |
| macOS | `~/Library/Caches/kubera-3p-mcp/access-token.json` |
| Linux | `${XDG_CACHE_HOME:-~/.cache}/kubera-3p-mcp/access-token.json` |

Startup / request flow:

1. Prefer a still-valid cached AccessToken.
2. Else, if the session export still has a valid AccessToken, cache that.
3. Else call Cognito `REFRESH_TOKEN_AUTH` once and write the new AccessToken to the cache.
4. On API `401`, clear cache, refresh once, retry; if that fails, re-export the session file.

Treat the session file and cached token like passwords. Do not commit them.

## Run the MCP server

```bash
bun start -- --session /path/to/cognito-session.json
# or after build:
node dist/kubera-3p-mcp.js --session /path/to/cognito-session.json
```

### Cursor / Claude Desktop config

```json
{
  "mcpServers": {
    "kubera": {
      "command": "npx",
      "args": [
        "-y",
        "kubera-3p-mcp",
        "--session",
        "C:/Users/YOU/cognito-session.json"
      ]
    }
  }
}
```

Local equivalent: `"command": "bun", "args": ["run", "/path/to/kubera-3p-mcp/src/cli.ts", "--session", "/path/to/cognito-session.json"]`.

## Typed client

```ts
import { KuberaClient } from "./src/client/index.ts";
import { resolveAuth } from "./src/auth/resolveAuth.ts";
import { writeTokenCache } from "./src/auth/tokenCache.ts";

const { accessToken, session } = await resolveAuth(
  "/path/to/cognito-session.json",
);

const client = new KuberaClient({
  accessToken,
  session,
  onAccessToken: (token) => writeTokenCache(token),
});

const user = await client.getUser();
const portfolios = await client.getPortfolios();
const portfolioId = portfolios.data.portfolio[0]!.id;
const chart = await client.getChartAndCagr({ portfolioId });
```

## Capture fixtures

```bash
bun run capture -- --session ./cognito-session.json
```

## Security note

Local capture files (`kubera-fetch.js`, `kubera-har.json`, `kubera-urls.txt`), `cognito-session.json`, and `fixtures/` can contain live secrets and portfolio data. They are gitignored. Rotate credentials if those files were shared.