import {
  DocsTitle,
  DocsLead,
  DocsH2,
  DocsP,
  DocsList,
  DocsLi,
  DocsCode,
  Mono,
} from '@/components/docs-page';

export const metadata = { title: 'MCP concepts — BuildMyMCPServer docs' };

export default function Concepts() {
  return (
    <>
      <DocsTitle kicker="Get started">MCP concepts</DocsTitle>
      <DocsLead>
        Model Context Protocol is an open standard from Anthropic for connecting AI assistants to
        external tools, data, and APIs. Three primitives, one transport.
      </DocsLead>

      <DocsH2 id="primitives">The three primitives</DocsH2>
      <DocsList>
        <DocsLi>
          <strong className="text-[--color-fg]">Tools</strong> — functions the AI can invoke.
          Each has a name, a description, an input schema (JSON Schema or Zod), and a server-side
          implementation. The AI decides when to call them based on the description.
        </DocsLi>
        <DocsLi>
          <strong className="text-[--color-fg]">Resources</strong> — read-only data the AI can
          fetch. URI-addressed. Think files, documents, database records.
        </DocsLi>
        <DocsLi>
          <strong className="text-[--color-fg]">Prompts</strong> — parameterized prompt templates
          the server exposes to the client. Used for orchestration patterns the server author
          wants to encourage.
        </DocsLi>
      </DocsList>

      <DocsH2 id="transport">Transport: Streamable HTTP</DocsH2>
      <DocsP>
        Every generated server speaks <Mono>Streamable HTTP</Mono> (MCP spec 2025-11-25). The
        previous SSE transport was deprecated in June 2025 and is not supported here. One HTTP
        endpoint at <Mono>/mcp</Mono>, optionally negotiating a long-lived stream via
        <Mono>text/event-stream</Mono> when the server wants to push updates.
      </DocsP>
      <DocsCode
        label="single request"
        code={`POST /mcp HTTP/1.1
Authorization: Bearer <jwt>
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}`}
      />

      <DocsH2 id="session">Session lifecycle</DocsH2>
      <DocsList>
        <DocsLi>
          <Mono>initialize</Mono> — client sends protocol version + capabilities, server returns
          its info and assigns a session id via the <Mono>mcp-session-id</Mono> header.
        </DocsLi>
        <DocsLi>
          <Mono>notifications/initialized</Mono> — client confirms readiness. Server is now free
          to push notifications.
        </DocsLi>
        <DocsLi>
          <Mono>tools/list</Mono>, <Mono>tools/call</Mono>, <Mono>resources/list</Mono>,
          <Mono>prompts/list</Mono> — the work.
        </DocsLi>
      </DocsList>

      <DocsH2 id="why-mcp">Why MCP and not just REST</DocsH2>
      <DocsP>
        REST APIs need bespoke OpenAPI integration per client. MCP standardizes the discovery,
        invocation, auth and streaming so any spec-compliant client picks up any spec-compliant
        server with zero glue code. That&apos;s the entire point.
      </DocsP>
    </>
  );
}