MCP Research

A TypeScript monorepo for incrementally building a financial-data MCP server on Cloudflare. It currently contains a read-only Hono financial API backed by Cloudflare D1 and Drizzle ORM. OAuth and MCP will be added after the financial domain boundary is established.

Requirements and setup

• Node.js 24 LTS or newer

• pnpm 10.33.0 (pinned through packageManager)

• A Cloudflare account only when deploying

corepack enable
pnpm install
cp apps/finance-api/.dev.vars.example apps/finance-api/.dev.vars
pnpm --filter @mcp-research/finance-api db:migrate:local
pnpm --filter @mcp-research/finance-api db:seed:local
pnpm dev

The local Worker is then available at the URL printed by Wrangler. GET / is a public health check. Financial endpoints require one of the development-only bearer tokens configured in .dev.vars:

curl -H 'Authorization: Bearer dev-alice' \
  'http://localhost:8787/v1/transactions?from=2026-06-01&to=2026-06-30'

The development authentication mechanism refuses all requests unless ENVIRONMENT=development. It must be replaced with the OAuth authorization context before production deployment.

Related MCP server: personal-finance-mcp

API

All financial routes derive the user ID from the authenticated principal. No route accepts a caller-supplied user ID.

GET /v1/me
GET /v1/accounts
GET /v1/accounts/:accountId
GET /v1/balances
GET /v1/transactions?account_id=&from=&to=&cursor=&limit=
GET /v1/transactions/:transactionId
GET /v1/analytics/cashflow?from=&to=

Amounts are integers in minor currency units. Transaction listings use an opaque cursor and default to 50 results, with a maximum of 100.

Database

The Drizzle schema lives in apps/finance-api/src/db/schema.ts. After changing it, generate a migration with:

pnpm --filter @mcp-research/finance-api db:generate

The committed D1 identifier is a local placeholder. Before remote deployment, create the database and replace database_id in apps/finance-api/wrangler.jsonc with the returned ID:

pnpm --filter @mcp-research/finance-api exec wrangler d1 create finance-api-db
pnpm --filter @mcp-research/finance-api exec wrangler d1 migrations apply finance-api-db --remote

The deterministic seed file is for local development and integration tests only.

Quality checks

pnpm test
pnpm format:check
pnpm lint
pnpm typecheck
pnpm build

The Worker test suite runs inside Cloudflare's Workers runtime and applies the D1 migrations to isolated local storage.

GET / returns:

{ "service": "mcp-research-finance-api", "status": "ok" }

Run pnpm --filter @mcp-research/finance-api types after changing wrangler.jsonc bindings; Wrangler generates apps/finance-api/worker-configuration.d.ts, which TypeScript consumes through the API tsconfig. Deploy with pnpm --filter @mcp-research/finance-api deploy after configuring a real D1 database and production authentication.

Structure

apps/finance-api/src/         Hono routes, domain repositories, and Drizzle schema
apps/finance-api/migrations/  generated D1 migrations
apps/finance-api/seed/        deterministic development data
apps/finance-api/test/        Worker-runtime integration tests
tsconfig.base.json            shared strict TypeScript settings
turbo.json                    workspace task graph

The initial architecture is deliberately one Worker. As capabilities grow, they should first become route modules inside apps/finance-api; separate Workers or applications should be introduced only when operational or security boundaries justify them.