sfluv-mcp

MCP server for SFLUV. Exposes SFLUV workflows, votes, and wallet data to AI agents (Claude, ChatGPT, Cursor, etc.) over the Model Context Protocol, with per-user OAuth authorization handled by Better Auth.

This is a skeleton. See docs/CONTEXT.md for the full design, the decisions baked in, the open questions, and the ordered TODO list.

Quick start

pnpm install
cp .env.example .env
# fill in BETTER_AUTH_URL, SFLUV_BACKEND_URL, SFLUV_BACKEND_SERVICE_TOKEN
pnpm dev

Server runs on http://localhost:4000.

GET /healthz for a liveness check. POST /mcp is the MCP endpoint. The OAuth discovery endpoints (/.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource) proxy to the Better Auth instance.

Layout

src/
  index.ts            Hono entrypoint, MCP route, OAuth discovery proxies
  auth.ts             Better Auth MCP client (Bearer token validation)
  backend.ts          Typed client for the SFLUV Go API (act-as-user)
  server.ts           buildMcpServer(userDid) — McpServer factory
  env.ts              Env validation (zod)
  tools/
    index.ts          Registers all tools on a server instance
    workflows.ts      list_active_workflows, get_workflow
    wallet.ts         list_my_wallets, get_my_user
    contacts.ts       list_my_contacts
docs/
  CONTEXT.md          Handoff: design, decisions, what's next

Stack

• Node 20+ (no Bun-specific APIs; deploys to whatever runs the Go backend).

• Hono for HTTP. Trivial to swap; we use ~five Hono APIs.

• @modelcontextprotocol/sdk — the official MCP TypeScript SDK.

• better-auth — only the better-auth/plugins/mcp/client adapter; the Better Auth server itself runs elsewhere.

• zod for env and tool input validation.

What it does NOT do (yet)

• No on-chain actions. No signing. No token transfers. See docs/CONTEXT.md → "Signing path" before writing any tool that mutates on-chain state.

• No persistent MCP sessions — each POST /mcp builds a fresh server. Fine for stateless tools; revisit when adding long-running streamed tools.

• No rate limiting, no audit log, no per-tool scope checking. All called out in the TODO list.