buildmymcpserver/apps/web/app/docs/faq/page.tsx

import { DocsTitle, DocsLead, DocsH2, DocsP, Mono } from '@/components/docs-page';
import { JsonLd } from '@/components/json-ld';
import { breadcrumbJsonLd, pageMetadata } from '@/lib/seo';

export const metadata = pageMetadata({
  title: 'Docs FAQ',
  description:
    'Answers on generated-code safety, secrets handling, build failures, quotas and self-hosting for BuildMyMCPServer.',
  path: '/docs/faq',
});

const ITEMS: { q: string; a: React.ReactNode }[] = [
  {
    q: 'How does the LLM-generated code stay safe?',
    a: 'Three layers: strict Zod validation of the JSON spec, regex scan for banned tokens (eval, child_process, prompt-injection markers), and a static check on the rendered TypeScript before Docker build. If any layer trips, the build fails with a clear error and nothing is deployed.',
  },
  {
    q: 'What happens if Claude hallucinates a broken tool?',
    a: 'The build fails at the static-check or Docker-build stage. The user sees the exact error in the live log and can refine the prompt and rebuild. No invalid server ever serves traffic.',
  },
  {
    q: 'Do my secrets ever leave my environment?',
    a: 'No. Secrets are AES-256-GCM encrypted at rest in your Postgres, decrypted only when injecting into your container at boot. They never appear in audit logs, build logs, or the prompt sent to Claude.',
  },
  {
    q: 'Why MCP and not OpenAPI?',
    a: 'MCP standardizes the discovery, invocation, auth, and streaming surface in a way OpenAPI never did. The point is that any spec-compliant client picks up any spec-compliant server with zero per-API integration work. OpenAPI requires custom glue for every client.',
  },
  {
    q: 'Can I use my own Claude API key?',
    a: 'Yes — set ANTHROPIC_API_KEY in .env. On self-hosted control planes you can also wire a separate per-org key (Sprint 4).',
  },
  {
    q: 'What if I don\'t set ANTHROPIC_API_KEY?',
    a: <>The generator falls back to a deterministic mock spec (two tools: <Mono>echo</Mono>, <Mono>now</Mono>) so you can verify the full pipeline without burning credits.</>,
  },
  {
    q: 'Cold-start latency?',
    a: 'Generated containers stay warm. After first boot, /mcp responds in sub-50ms in-region.',
  },
  {
    q: 'Rate limits?',
    a: 'Default 100 requests/min/IP per tool. Configurable per server. Quota enforced before hitting your container.',
  },
  {
    q: 'How is OAuth different from API keys?',
    a: 'OAuth 2.1 with PKCE + Dynamic Client Registration + Resource Indicators means the AI client gets a short-lived, audience-bound token. Compromised tokens expire and can\'t be replayed against other servers. API keys are static and replayable forever.',
  },
  {
    q: 'Can the AI client itself get phished into using a malicious server?',
    a: 'The MCP spec mandates user consent on initial server addition. Beyond that, each server\'s scope is opaque to other servers — there\'s no cross-server token leakage because of audience binding.',
  },
  {
    q: 'How do I export my server\'s code?',
    a: 'Every build record stores the rendered TypeScript in Postgres. The /servers/:id detail page exposes it for download (Sprint 4 UI; available now via API).',
  },
  {
    q: 'What about ChatGPT specifically?',
    a: 'ChatGPT supports MCP via Custom Connectors. The wizard\'s install tab gives you the URL + OAuth setting; the handshake runs automatically on first call.',
  },
];

export default function Faq() {
  return (
    <>
      <JsonLd
        data={breadcrumbJsonLd([
          { name: 'Home', path: '/' },
          { name: 'Docs', path: '/docs' },
          { name: 'FAQ', path: '/docs/faq' },
        ])}
      />
      <DocsTitle kicker="Reference">FAQ</DocsTitle>
      <DocsLead>Common questions, direct answers.</DocsLead>
      <div className="space-y-7">
        {ITEMS.map((item) => (
          <div key={item.q}>
            <DocsH2>{item.q}</DocsH2>
            <DocsP>{item.a}</DocsP>
          </div>
        ))}
      </div>
    </>
  );
}