Adding an MCP Connector So Claude & ChatGPT Can Update Your App

npm install mcp-handler

// Public OAuth clients from Dynamic Client Registration — no secret,
// PKCE (S256) protects the code exchange instead.
model McpClient {
  clientId     String   @id @default(uuid()) @map("client_id") @db.Uuid
  clientName   String   @map("client_name")
  redirectUris Json     @map("redirect_uris") // string[]
  createdAt    DateTime @default(now()) @map("created_at") @db.Timestamptz(3)

  @@map("mcp_clients")
}

// One-time authorization codes (10-min expiry, single use).
model McpAuthCode {
  codeHash      String   @id @map("code_hash")
  clientId      String   @map("client_id") @db.Uuid
  userId        String   @map("user_id") @db.Uuid
  codeChallenge String   @map("code_challenge")
  redirectUri   String   @map("redirect_uri")
  expiresAt     DateTime @map("expires_at") @db.Timestamptz(3)

  @@index([userId])
  @@map("mcp_auth_codes")
}

// Bearer access tokens — only the hash is ever stored.
model McpToken {
  id         String    @id @default(uuid()) @db.Uuid
  tokenHash  String    @unique @map("token_hash")
  userId     String    @map("user_id") @db.Uuid
  clientName String    @map("client_name")
  expiresAt  DateTime  @map("expires_at") @db.Timestamptz(3)
  lastUsedAt DateTime? @map("last_used_at") @db.Timestamptz(3)

  @@index([userId])
  @@map("mcp_tokens")
}

import { createHash, randomBytes } from "node:crypto";

export const TOKEN_PREFIX = "sfmcp_";
export const TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days

export function generateSecret(prefix: string = TOKEN_PREFIX): string {
  return prefix + randomBytes(32).toString("base64url"); // 256 bits of entropy
}

export function sha256Hex(value: string): string {
  return createHash("sha256").update(value).digest("hex");
}

/** PKCE S256: base64url(sha256(verifier)) must equal the stored challenge. */
export function verifyPkceS256(verifier: string, challenge: string): boolean {
  const computed = createHash("sha256").update(verifier).digest("base64url");
  return computed === challenge;
}

it("accepts the RFC 7636 test vector", () => {
  const verifier = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk";
  const challenge = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM";
  expect(verifyPkceS256(verifier, challenge)).toBe(true);
});

export type ToolResult = { text: string; isError?: boolean };

export async function addTransaction(
  repos: McpRepos, userId: string, type: "income" | "expense",
  input: { amount: number; category: string; account?: string; note?: string; date?: string },
): Promise<ToolResult> {
  const profile = await repos.profiles.getForUser(userId);
  if (!profile) return { text: "Profile not found.", isError: true };

  if (!Number.isFinite(input.amount) || input.amount <= 0) {
    return { text: "Amount must be a positive number, e.g. 12.50.", isError: true };
  }
  const amountMinor = toMinor(input.amount, profile.currency);

  // Fuzzy-match the category name the model guessed against the real list.
  const cats = await repos.categories.listForUser(userId, type);
  const cat = matchByTitle(cats, input.category);
  if (!cat.ok) {
    // Feed the mismatch back as TEXT — the model reads this and retries
    // with a name from the list, instead of failing silently.
    return {
      text: `Category "${input.category}" not found. Available: ${cat.candidates.join(", ")}.`,
      isError: true,
    };
  }

  const accounts = await repos.accounts.listForUser(userId);
  const account = accounts.find((a) => a.isDefault) ?? accounts[0];

  const tx = await repos.transactions.createForUser(userId, {
    type, amountMinor, categoryId: cat.item.id, accountId: account.id,
    occurredOn: input.date ?? today(), note: input.note ?? null,
  });

  return { text: `Added ${type}: ${formatMoney(tx.amountMinor, profile.currency)} in ${cat.item.title}.` };
}

export type MatchResult<T> =
  | { ok: true; item: T }
  | { ok: false; reason: "none" | "ambiguous"; candidates: string[] };

export function matchByTitle<T extends { title: string }>(items: T[], query: string): MatchResult<T> {
  const q = query.trim().toLowerCase();
  const exact = items.find((i) => i.title.trim().toLowerCase() === q);
  if (exact) return { ok: true, item: exact };

  const prefix = items.filter((i) => i.title.toLowerCase().startsWith(q));
  if (prefix.length === 1) return { ok: true, item: prefix[0] };
  if (prefix.length > 1) return { ok: false, reason: "ambiguous", candidates: prefix.map((i) => i.title) };

  const sub = items.filter((i) => i.title.toLowerCase().includes(q));
  if (sub.length === 1) return { ok: true, item: sub[0] };
  if (sub.length > 1) return { ok: false, reason: "ambiguous", candidates: sub.map((i) => i.title) };

  return { ok: false, reason: "none", candidates: items.map((i) => i.title) };
}

import { createMcpHandler, withMcpAuth } from "mcp-handler";
import { z } from "zod";
import { mcpRepo } from "@/lib/data";
import { sha256Hex, TOKEN_PREFIX } from "@/modules/mcp/domain/oauth";
import { addTransaction } from "@/modules/mcp/domain/tools";

const handler = createMcpHandler(
  (server) => {
    server.registerTool(
      "add_expense",
      {
        title: "Add expense",
        description: "Record an expense in the user's account.",
        inputSchema: {
          amount: z.number().positive().describe("Amount in major units, e.g. 12.50"),
          category: z.string().min(1).describe("Category name (fuzzy-matched)"),
          account: z.string().optional(),
          note: z.string().max(500).optional(),
          date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
        },
      },
      async (input, extra) => {
        const userId = (extra.authInfo?.extra as { userId?: string })?.userId;
        if (!userId) return { content: [{ type: "text", text: "Unauthorized." }], isError: true };
        const result = await addTransaction(repos, userId, "expense", input);
        return { content: [{ type: "text", text: result.text }], isError: result.isError };
      },
    );
    // ...6 more tools: add_income, list_categories, list_accounts,
    // list_recent_transactions, get_budget_status, get_summary
  },
  { serverInfo: { name: "spendflow", version: "1.0.0" }, capabilities: { tools: {} } },
  { basePath: "/api", maxDuration: 60 },
);

const verifyToken = async (_req: Request, bearerToken?: string) => {
  if (!bearerToken?.startsWith(TOKEN_PREFIX)) return undefined;
  const resolved = await mcpRepo.resolveToken(sha256Hex(bearerToken));
  if (!resolved) return undefined;
  return { token: bearerToken, scopes: ["spendflow"], clientId: "spendflow-mcp",
           extra: { userId: resolved.userId } };
};

const authHandler = withMcpAuth(handler, verifyToken, {
  required: true,
  resourceMetadataPath: "/.well-known/oauth-protected-resource",
});

export { authHandler as GET, authHandler as POST };

export function GET(req: Request) {
  const origin = new URL(req.url).origin;
  return Response.json({
    issuer: origin,
    authorization_endpoint: `${origin}/connect`,
    token_endpoint: `${origin}/api/oauth/token`,
    registration_endpoint: `${origin}/api/oauth/register`,
    response_types_supported: ["code"],
    grant_types_supported: ["authorization_code"],
    code_challenge_methods_supported: ["S256"],
    token_endpoint_auth_methods_supported: ["none"], // public client, PKCE instead
  });
}

const BodySchema = z.object({
  client_name: z.string().min(1).max(200).optional(),
  redirect_uris: z.array(z.string().url()).min(1).max(10),
});

export async function POST(req: Request) {
  const parsed = BodySchema.safeParse(await req.json());
  if (!parsed.success) return Response.json({ error: "invalid_client_metadata" }, { status: 400 });

  const client = await mcpRepo.registerClient(
    parsed.data.client_name ?? "MCP Client",
    parsed.data.redirect_uris,
  );
  return Response.json({
    client_id: client.clientId,
    redirect_uris: client.redirectUris,
    token_endpoint_auth_method: "none",
    grant_types: ["authorization_code"],
  }, { status: 201 });
}

export async function POST(req: Request) {
  const form = await req.formData();
  if (form.get("grant_type") !== "authorization_code") {
    return Response.json({ error: "unsupported_grant_type" }, { status: 400 });
  }

  const stored = await mcpRepo.consumeAuthCode(sha256Hex(String(form.get("code"))));
  if (!stored) return Response.json({ error: "invalid_grant" }, { status: 400 });

  if (!verifyPkceS256(String(form.get("code_verifier")), stored.codeChallenge)) {
    return Response.json({ error: "invalid_grant" }, { status: 400 });
  }

  const token = generateSecret();
  await mcpRepo.createToken(sha256Hex(token), {
    userId: stored.userId, clientId: stored.clientId,
    expiresAt: new Date(Date.now() + TOKEN_TTL_MS),
  });

  return Response.json({
    access_token: token, token_type: "bearer",
    expires_in: Math.floor(TOKEN_TTL_MS / 1000), scope: "spendflow",
  }, { headers: { "Cache-Control": "no-store" } });
}

"use server";
export async function decideConnection(_prev: unknown, formData: FormData) {
  const userId = await getCurrentUserId();
  if (!userId) return { error: "Not signed in" };

  const clientId = String(formData.get("clientId"));
  const redirectUri = String(formData.get("redirectUri"));
  const codeChallenge = String(formData.get("codeChallenge"));
  const decision = formData.get("decision");

  const client = await mcpRepo.getClient(clientId);
  // Redirect URI must be one THIS client registered — never trust a URL
  // that arrives only via the query string.
  if (!client || !client.redirectUris.includes(redirectUri)) {
    return { error: "Unknown client" };
  }

  if (decision === "deny") {
    redirect(`${redirectUri}?error=access_denied`);
  }

  const code = generateSecret();
  await mcpRepo.createAuthCode(sha256Hex(code), { clientId, userId, codeChallenge, redirectUri });
  redirect(`${redirectUri}?code=${encodeURIComponent(code)}`);
}

// modules/mcp/ui/ApproveForm.tsx
const redirectHost = new URL(props.redirectUri).host;
// ...
<p>Access will be sent to: {redirectHost}</p>

export async function revokeMcpConnection(id: string) {
  const userId = await getCurrentUserId();
  if (!userId) return { error: "Not signed in" };
  const parsed = z.string().uuid().safeParse(id);
  if (!parsed.success) return { error: "Invalid request" };

  await mcpRepo.revokeConnection(userId, parsed.data); // ownership-checked delete
  return { ok: true };
}

const WRITE_RATE_LIMIT = 20;
const WRITE_RATE_WINDOW_MS = 60_000;

export async function addTransaction(repos: McpRepos, userId: string, /* ... */) {
  const recentWrites = await repos.transactions.countCreatedSince(
    userId, new Date(Date.now() - WRITE_RATE_WINDOW_MS),
  );
  if (recentWrites >= WRITE_RATE_LIMIT) {
    return { text: "Too many requests. Try again in a minute.", isError: true };
  }
  // ...rest of the function
}