@raybase/docs 0.0.1 → 0.1.2

package/templates/react-router/content/docs/mcp.mdx

@@ -0,0 +1,121 @@
+---
+title: Connecting to this app with AI
+description: Add this app's MCP server to ChatGPT, Claude, Codex CLI, Claude Code, or another AI agent.
+---
+
+Use this page when you want an AI Agent to work with this app through its MCP server.
+
+Server URL:
+
+<McpServerUrlBlock />
+
+Use the deployed HTTPS URL for ChatGPT and Claude web/desktop connectors. If you are testing from Codex CLI or Claude Code on your own machine, `http://localhost:3000/mcp` can work. For ChatGPT, Claude web, and Claude Desktop remote connectors, expose local development through a secure HTTPS tunnel or deploy first; those products connect from provider infrastructure, not from your laptop.
+
+## ChatGPT web
+
+ChatGPT custom MCP apps are configured from ChatGPT web.
+
+1. Open ChatGPT web and go to **Settings -> Apps & Connectors** or **Settings -> Apps**, depending on the current UI.
+2. Open **Advanced settings** and turn on **Developer mode** if it is available for your account or workspace.
+3. Return to **Apps & Connectors** or **Apps** and click **Create**.
+4. Enter an app name, a short description, and the server URL above.
+5. Choose the authentication option this app uses. For OAuth, complete the authorization prompt when ChatGPT scans tools.
+6. Click **Create** after the tool scan succeeds and the expected tools appear.
+7. In a new chat, click **+** by the composer, choose **More**, select this app, and ask ChatGPT to use it.
+
+For Business, Enterprise, or Edu workspaces, an admin or owner may need to create, enable, publish, or allow this app from **Workspace settings -> Apps** before other members can connect it.
+
+ChatGPT may ask for confirmation before actions that change data, depending on your workspace settings and the action being requested.
+
+## ChatGPT desktop
+
+Create and manage the custom MCP app in ChatGPT web first. There is no separate documented desktop creation flow for custom MCP apps. If this app appears in the desktop app's composer tools menu after web setup, select it there; otherwise use ChatGPT web for MCP conversations with this app.
+
+## Claude web and desktop
+
+Claude custom connectors are remote MCP connectors. The setup is the same in Claude web and Claude Desktop, and the connection to this app comes from Anthropic's cloud. Use the deployed HTTPS URL or an internet-reachable tunnel; `localhost` is only for separate local Claude Desktop or Claude Code configuration.
+
+For individual plans, including Free, Pro, and Max:
+
+1. Open **Customize -> Connectors**.
+2. Click **+**, then **Add custom connector**.
+3. Enter a name and the server URL above.
+4. Open **Advanced settings** only if this app requires a fixed OAuth Client ID or Client Secret.
+5. Click **Add**, then **Connect** and complete authentication.
+6. In a chat, click **+**, choose **Connectors**, and toggle this connector on for the conversation.
+
+For Team or Enterprise plans:
+
+1. An Owner opens **Organization settings -> Connectors**.
+2. Clicks **Add**, hovers **Custom**, selects **Web**, enters the server URL, and clicks **Add**.
+3. Each member opens **Customize -> Connectors**, finds the custom connector, clicks **Connect**, and authenticates before enabling it in a conversation.
+
+## Codex CLI
+
+Codex supports streamable HTTP MCP servers. Add this app:
+
+<CodexMcpAddCommand />
+
+For local development:
+
+```bash
+codex mcp add this-app-local --url http://localhost:3000/mcp
+```
+
+If the server requires OAuth, authenticate after adding it:
+
+```bash
+codex mcp login this-app
+```
+
+Start `codex`, then type `/mcp` at the Codex prompt to confirm the server and tools loaded. Codex CLI and the Codex IDE extension share the same MCP configuration.
+
+## Claude Code CLI
+
+Claude Code's CLI supports remote HTTP MCP servers. Add this app:
+
+<ClaudeMcpAddCommand />
+
+For local development:
+
+```bash
+claude mcp add --transport http this-app-local http://localhost:3000/mcp
+```
+
+Add `--scope user` if every Claude Code project should see the server. Otherwise Claude Code stores it in the current local scope. Then start Claude Code and type `/mcp` at the Claude Code prompt; if the server needs OAuth, select it there and complete the browser authorization flow. Use `claude mcp list`, `claude mcp get this-app`, or `claude mcp remove this-app` to manage the configuration.
+
+## Connect from another AI agent
+
+1. Choose **Add MCP server** or the closest equivalent in your agent.
+2. Use **HTTP** or **Streamable HTTP** transport.
+3. Name the server after this app.
+4. Enter the server URL above.
+5. Complete the sign-in and authorization flow.
+6. Ask the agent to list available tools so you can confirm what it can access.
+
+## What the AI can do
+
+Replace this section before shipping the app.
+
+- **Read access** (`mcp:read`): describe the records, search results, summaries, or workflow context the AI can read for the signed-in member.
+- **Write access** (`mcp:write`): describe the specific actions the AI can perform, such as creating records, updating statuses, or running workflow steps.
+- **Tool-specific access**: note any important per-tool permissions that users may see during authorization.
+- **Not available through AI**: list important boundaries, such as account management, billing, security settings, or destructive workflows that are not exposed.
+
+The detailed tool names and input fields are discoverable by the AI client after connection, so keep this page focused on the scope of access and the workflows a person should expect.
+
+## Headless use: CLIs, CI, and agents without a browser
+
+When the client cannot complete the browser sign-in above, sign in to this app yourself and register a machine credential for it:
+
+```bash
+curl -X POST https://your-app.example/api/auth/oauth/register \
+  -H "content-type: application/json" -b "<your session cookie>" \
+  -d '{"client_name":"CI runner","grant_types":["client_credentials"],"scope":"mcp:read"}'
+```
+
+The response includes a `client_id` and a one-time `client_secret`. Give both to the client; it requests access tokens with `grant_type=client_credentials` and HTTP Basic authentication, and the tokens act as you with only the scope you registered. Revoke the credential at any time with `DELETE /api/auth/oauth/clients/<client_id>` while signed in.
+
+## Disconnect access
+
+Disconnect the app from your AI client when you no longer want it to use these tools. If this app includes a connected AI clients page or integrations settings page, revoke access there as well. Otherwise, contact the app owner to revoke the connection.

package/templates/react-router/content/docs/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Docs",
+  "pages": ["index", "getting-started", "mcp"]
+}

package/templates/react-router/source.config.ts

@@ -0,0 +1,5 @@
+import { defineDocs } from "fumadocs-mdx/config";
+
+export const docs = defineDocs({
+  dir: "content/docs"
+});

package/templates/tanstack-start/content/docs/getting-started.mdx

@@ -0,0 +1,10 @@
+---
+title: Getting started
+description: Replace this page with the first real workflow guide.
+---
+
+Replace this placeholder with the first workflow a real user or operator needs.
+
+Document behavior only after it exists in the app. Avoid promising screens, APIs, permissions, or automations that have not been implemented.
+
+Only invited people can sign in. If extra sign-in buttons are configured for this app, they still require an approved setup or invite link before a new account can be created.

package/templates/tanstack-start/content/docs/index.mdx

@@ -0,0 +1,8 @@
+---
+title: Welcome to the docs
+description: Start here when replacing the placeholder documentation.
+---
+
+Use this space for product, operator, and API documentation once those workflows exist.
+
+Keep docs in `content/docs`, and update the page tree as the documentation grows.

package/templates/tanstack-start/content/docs/mcp.mdx

@@ -0,0 +1,121 @@
+---
+title: Connecting to this app with AI
+description: Add this app's MCP server to ChatGPT, Claude, Codex CLI, Claude Code, or another AI agent.
+---
+
+Use this page when you want an AI Agent to work with this app through its MCP server.
+
+Server URL:
+
+<McpServerUrlBlock />
+
+Use the deployed HTTPS URL for ChatGPT and Claude web/desktop connectors. If you are testing from Codex CLI or Claude Code on your own machine, `http://localhost:3000/mcp` can work. For ChatGPT, Claude web, and Claude Desktop remote connectors, expose local development through a secure HTTPS tunnel or deploy first; those products connect from provider infrastructure, not from your laptop.
+
+## ChatGPT web
+
+ChatGPT custom MCP apps are configured from ChatGPT web.
+
+1. Open ChatGPT web and go to **Settings -> Apps & Connectors** or **Settings -> Apps**, depending on the current UI.
+2. Open **Advanced settings** and turn on **Developer mode** if it is available for your account or workspace.
+3. Return to **Apps & Connectors** or **Apps** and click **Create**.
+4. Enter an app name, a short description, and the server URL above.
+5. Choose the authentication option this app uses. For OAuth, complete the authorization prompt when ChatGPT scans tools.
+6. Click **Create** after the tool scan succeeds and the expected tools appear.
+7. In a new chat, click **+** by the composer, choose **More**, select this app, and ask ChatGPT to use it.
+
+For Business, Enterprise, or Edu workspaces, an admin or owner may need to create, enable, publish, or allow this app from **Workspace settings -> Apps** before other members can connect it.
+
+ChatGPT may ask for confirmation before actions that change data, depending on your workspace settings and the action being requested.
+
+## ChatGPT desktop
+
+Create and manage the custom MCP app in ChatGPT web first. There is no separate documented desktop creation flow for custom MCP apps. If this app appears in the desktop app's composer tools menu after web setup, select it there; otherwise use ChatGPT web for MCP conversations with this app.
+
+## Claude web and desktop
+
+Claude custom connectors are remote MCP connectors. The setup is the same in Claude web and Claude Desktop, and the connection to this app comes from Anthropic's cloud. Use the deployed HTTPS URL or an internet-reachable tunnel; `localhost` is only for separate local Claude Desktop or Claude Code configuration.
+
+For individual plans, including Free, Pro, and Max:
+
+1. Open **Customize -> Connectors**.
+2. Click **+**, then **Add custom connector**.
+3. Enter a name and the server URL above.
+4. Open **Advanced settings** only if this app requires a fixed OAuth Client ID or Client Secret.
+5. Click **Add**, then **Connect** and complete authentication.
+6. In a chat, click **+**, choose **Connectors**, and toggle this connector on for the conversation.
+
+For Team or Enterprise plans:
+
+1. An Owner opens **Organization settings -> Connectors**.
+2. Clicks **Add**, hovers **Custom**, selects **Web**, enters the server URL, and clicks **Add**.
+3. Each member opens **Customize -> Connectors**, finds the custom connector, clicks **Connect**, and authenticates before enabling it in a conversation.
+
+## Codex CLI
+
+Codex supports streamable HTTP MCP servers. Add this app:
+
+<CodexMcpAddCommand />
+
+For local development:
+
+```bash
+codex mcp add this-app-local --url http://localhost:3000/mcp
+```
+
+If the server requires OAuth, authenticate after adding it:
+
+```bash
+codex mcp login this-app
+```
+
+Start `codex`, then type `/mcp` at the Codex prompt to confirm the server and tools loaded. Codex CLI and the Codex IDE extension share the same MCP configuration.
+
+## Claude Code CLI
+
+Claude Code's CLI supports remote HTTP MCP servers. Add this app:
+
+<ClaudeMcpAddCommand />
+
+For local development:
+
+```bash
+claude mcp add --transport http this-app-local http://localhost:3000/mcp
+```
+
+Add `--scope user` if every Claude Code project should see the server. Otherwise Claude Code stores it in the current local scope. Then start Claude Code and type `/mcp` at the Claude Code prompt; if the server needs OAuth, select it there and complete the browser authorization flow. Use `claude mcp list`, `claude mcp get this-app`, or `claude mcp remove this-app` to manage the configuration.
+
+## Connect from another AI agent
+
+1. Choose **Add MCP server** or the closest equivalent in your agent.
+2. Use **HTTP** or **Streamable HTTP** transport.
+3. Name the server after this app.
+4. Enter the server URL above.
+5. Complete the sign-in and authorization flow.
+6. Ask the agent to list available tools so you can confirm what it can access.
+
+## What the AI can do
+
+Replace this section before shipping the app.
+
+- **Read access** (`mcp:read`): describe the records, search results, summaries, or workflow context the AI can read for the signed-in member.
+- **Write access** (`mcp:write`): describe the specific actions the AI can perform, such as creating records, updating statuses, or running workflow steps.
+- **Tool-specific access**: note any important per-tool permissions that users may see during authorization.
+- **Not available through AI**: list important boundaries, such as account management, billing, security settings, or destructive workflows that are not exposed.
+
+The detailed tool names and input fields are discoverable by the AI client after connection, so keep this page focused on the scope of access and the workflows a person should expect.
+
+## Headless use: CLIs, CI, and agents without a browser
+
+When the client cannot complete the browser sign-in above, sign in to this app yourself and register a machine credential for it:
+
+```bash
+curl -X POST https://your-app.example/api/auth/oauth/register \
+  -H "content-type: application/json" -b "<your session cookie>" \
+  -d '{"client_name":"CI runner","grant_types":["client_credentials"],"scope":"mcp:read"}'
+```
+
+The response includes a `client_id` and a one-time `client_secret`. Give both to the client; it requests access tokens with `grant_type=client_credentials` and HTTP Basic authentication, and the tokens act as you with only the scope you registered. Revoke the credential at any time with `DELETE /api/auth/oauth/clients/<client_id>` while signed in.
+
+## Disconnect access
+
+Disconnect the app from your AI client when you no longer want it to use these tools. If this app includes a connected AI clients page or integrations settings page, revoke access there as well. Otherwise, contact the app owner to revoke the connection.

package/templates/tanstack-start/content/docs/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Docs",
+  "pages": ["index", "getting-started", "mcp"]
+}

package/templates/tanstack-start/source.config.ts

@@ -0,0 +1,10 @@
+import { defineDocs } from "fumadocs-mdx/config";
+
+export const docs = defineDocs({
+  dir: "content/docs",
+  docs: {
+    postprocess: {
+      includeProcessedMarkdown: true
+    }
+  }
+});

package/templates/tanstack-start/src/docs/docs-assets.ts

@@ -0,0 +1 @@
+export const docsClientScriptSrc = import.meta.env.DEV ? "/src/docs/docs-client.tsx" : "/assets/raybase-docs-client.js";

package/templates/tanstack-start/src/docs/docs-client.tsx

@@ -0,0 +1,22 @@
+import "@vitejs/plugin-react/preamble";
+import { StrictMode, startTransition } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { DocsRoot, preloadDocsContent, type DocsPageData } from "./docs-page";
+
+const root = document.getElementById("raybase-docs-root");
+const dataScript = document.getElementById("raybase-docs-page-data");
+
+if (root && dataScript?.textContent) {
+  const data = JSON.parse(dataScript.textContent) as DocsPageData;
+
+  startTransition(() => {
+    void preloadDocsContent(data).then(() => {
+      hydrateRoot(
+        root,
+        <StrictMode>
+          <DocsRoot data={data} />
+        </StrictMode>
+      );
+    });
+  });
+}

package/templates/tanstack-start/src/docs/docs-data.ts

@@ -0,0 +1,24 @@
+import type { SerializedPageTree } from "fumadocs-core/source/client";
+import type { DocsPageData } from "./docs-page";
+import { preloadDocsContent } from "./docs-page";
+import { source } from "./source";
+
+export async function loadDocsPageTree(): Promise<SerializedPageTree> {
+  return source.serializePageTree(source.getPageTree());
+}
+
+export async function loadDocsPageData(slugs: string[]): Promise<DocsPageData | null> {
+  const page = source.getPage(slugs);
+  if (!page) return null;
+
+  const data = {
+    path: page.path,
+    url: page.url,
+    title: page.data.title,
+    description: page.data.description,
+    pageTree: await loadDocsPageTree()
+  } satisfies DocsPageData;
+
+  await preloadDocsContent(data);
+  return data;
+}

package/templates/tanstack-start/src/docs/docs-handler.tsx

@@ -0,0 +1,105 @@
+import { createFromSource } from "fumadocs-core/search/server";
+import { renderToReadableStream } from "react-dom/server";
+import docsCss from "../styles-docs.css?inline";
+import { docsClientScriptSrc } from "./docs-assets";
+import { loadDocsPageData, loadDocsPageTree } from "./docs-data";
+import { DocsRoot, type DocsPageData } from "./docs-page";
+import { getDocsMarkdownResponse, getDocsSlugs } from "./llm-text";
+import { source } from "./source";
+
+const docsThemeInitScript =
+  "(function(){try{var t=localStorage.getItem('theme');var d=t==='dark'||((!t||t==='system')&&matchMedia('(prefers-color-scheme: dark)').matches);document.documentElement.classList.toggle('dark',d);}catch(e){}})();";
+
+const search = createFromSource(source, {
+  language: "english"
+});
+
+export async function handleDocsRequest(request: Request): Promise<Response> {
+  const url = new URL(request.url);
+
+  if (url.pathname === "/docs/api/search") {
+    return search.GET(request);
+  }
+
+  if (url.pathname === "/docs/api/markdown") {
+    const response = await getDocsMarkdownResponse(url.searchParams.get("path"));
+    return response ?? new Response("Not found", { status: 404 });
+  }
+
+  if (/\.mdx?$/.test(url.pathname)) {
+    const response = await getDocsMarkdownResponse(url.pathname);
+    return response ?? new Response("Not found", { status: 404 });
+  }
+
+  const data = await loadDocsPageData(getDocsSlugs(url.pathname));
+  if (!data) {
+    return docsHtmlResponse(
+      {
+        path: "",
+        url: url.pathname,
+        title: "Docs page not found",
+        pageTree: await loadDocsPageTree()
+      },
+      "<main class=\"mx-auto flex min-h-screen max-w-3xl flex-col justify-center px-6 py-16\"><p class=\"text-sm font-medium text-fd-muted-foreground\">404</p><h1 class=\"mt-3 text-3xl font-semibold text-fd-foreground\">Docs page not found</h1><p class=\"mt-3 text-fd-muted-foreground\">The requested documentation page does not exist.</p><a class=\"mt-6 inline-flex text-sm font-medium text-fd-primary underline-offset-4 hover:underline\" href=\"/docs\">Back to docs</a></main>",
+      404
+    );
+  }
+
+  return docsHtmlResponse(data, await renderDocsBody(data));
+}
+
+async function renderDocsBody(data: DocsPageData): Promise<string> {
+  const stream = await renderToReadableStream(<DocsRoot data={cloneDocsPageData(data)} />);
+  await stream.allReady;
+  return new Response(stream).text();
+}
+
+function cloneDocsPageData(data: DocsPageData): DocsPageData {
+  return JSON.parse(JSON.stringify(data)) as DocsPageData;
+}
+
+function docsHtmlResponse(data: DocsPageData, body: string, status = 200): Response {
+  const html = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(data.title)}</title>
+    <script>${docsThemeInitScript}</script>
+    <style id="raybase-docs-styles">${docsCss}</style>
+  </head>
+  <body>
+    <div id="raybase-docs-root">${body}</div>
+    <script type="application/json" id="raybase-docs-page-data">${escapeJson(data)}</script>
+    <script type="module" async src="${docsClientScriptSrc}"></script>
+  </body>
+</html>`;
+
+  return new Response(html, {
+    status,
+    headers: {
+      "content-type": "text/html; charset=utf-8"
+    }
+  });
+}
+
+function escapeJson(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+
+function escapeHtml(value: string) {
+  return value.replace(/[&<>"']/g, (char) => {
+    switch (char) {
+      case "&":
+        return "&amp;";
+      case "<":
+        return "&lt;";
+      case ">":
+        return "&gt;";
+      case "\"":
+        return "&quot;";
+      default:
+        return "&#39;";
+    }
+  });
+}

package/templates/tanstack-start/src/docs/docs-layout.tsx

@@ -0,0 +1,56 @@
+import type { DocsLayoutProps } from "fumadocs-ui/layouts/docs";
+import type { ComponentProps } from "react";
+import { ThemeSwitch } from "fumadocs-ui/layouts/shared/slots/theme-switch";
+import { ArrowLeft } from "lucide-react";
+import { appConfig } from "../raybase.config";
+
+const appHomeHref = "/";
+
+export function baseOptions(): Omit<DocsLayoutProps, "children" | "tree"> {
+  return {
+    nav: {
+      title: DocsNavTitle,
+      url: appHomeHref
+    },
+    sidebar: {
+      footer: <DocsSidebarFooter />
+    },
+    themeSwitch: {
+      enabled: false
+    }
+  };
+}
+
+function DocsNavTitle({ className, href = appHomeHref, ...props }: ComponentProps<"a">) {
+  return (
+    <div className={className}>
+      <div className="inline-flex min-w-0 flex-col items-start gap-0.5 leading-none">
+        <a
+          {...props}
+          href={href}
+          title={`Back to ${appConfig.appName}`}
+          className="max-w-44 truncate rounded-sm text-[0.9375rem] font-semibold leading-none text-fd-foreground underline-offset-4 transition-colors hover:text-fd-primary hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fd-ring"
+        >
+          {appConfig.appName}
+        </a>
+        <span className="text-[0.6875rem] font-medium leading-none text-fd-muted-foreground">Docs</span>
+      </div>
+    </div>
+  );
+}
+
+function DocsSidebarFooter() {
+  return (
+    <div className="mt-2 flex min-w-0 items-center justify-between gap-3 border-t pt-3">
+      <a
+        href={appHomeHref}
+        title={`Back to ${appConfig.appName}`}
+        className="inline-flex min-w-0 items-center gap-1.5 rounded-md px-1 py-1 text-xs font-medium text-fd-muted-foreground transition-colors hover:text-fd-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fd-ring"
+      >
+        <ArrowLeft className="size-3.5 shrink-0" aria-hidden="true" />
+        <span className="truncate">Back to app</span>
+      </a>
+      <ThemeSwitch className="shrink-0 p-0" />
+    </div>
+  );
+}

package/templates/tanstack-start/src/docs/docs-mdx.tsx

@@ -0,0 +1,79 @@
+import { CodeBlock, Pre } from "fumadocs-ui/components/codeblock";
+import defaultMdxComponents from "fumadocs-ui/mdx";
+import type { MDXComponents } from "mdx/types";
+
+interface McpServerUrlProps {
+  path?: string;
+}
+
+interface ClaudeMcpAddCommandProps extends McpServerUrlProps {
+  name?: string;
+}
+
+interface CodexMcpAddCommandProps extends McpServerUrlProps {
+  name?: string;
+}
+
+function browserOrigin() {
+  return typeof window === "undefined" ? "" : window.location.origin;
+}
+
+function currentUrl(path = "/mcp") {
+  const origin = browserOrigin();
+  return origin ? new URL(path, origin).toString() : path;
+}
+
+function McpServerUrl(props: McpServerUrlProps) {
+  return <code suppressHydrationWarning>{currentUrl(props.path)}</code>;
+}
+
+function McpServerUrlBlock(props: McpServerUrlProps) {
+  return (
+    <CodeBlock>
+      <Pre>
+        <code suppressHydrationWarning>{currentUrl(props.path)}</code>
+      </Pre>
+    </CodeBlock>
+  );
+}
+
+function ClaudeMcpAddCommand(props: ClaudeMcpAddCommandProps) {
+  const command = `claude mcp add --transport http ${props.name ?? "this-app"} "${currentUrl(props.path)}"`;
+
+  return (
+    <CodeBlock>
+      <Pre>
+        <code suppressHydrationWarning>{command}</code>
+      </Pre>
+    </CodeBlock>
+  );
+}
+
+function CodexMcpAddCommand(props: CodexMcpAddCommandProps) {
+  const command = `codex mcp add ${props.name ?? "this-app"} --url "${currentUrl(props.path)}"`;
+
+  return (
+    <CodeBlock>
+      <Pre>
+        <code suppressHydrationWarning>{command}</code>
+      </Pre>
+    </CodeBlock>
+  );
+}
+
+export function getMDXComponents(components?: MDXComponents) {
+  return {
+    ...defaultMdxComponents,
+    McpServerUrl,
+    McpServerUrlBlock,
+    ClaudeMcpAddCommand,
+    CodexMcpAddCommand,
+    ...components
+  } satisfies MDXComponents;
+}
+
+export const useMDXComponents = getMDXComponents;
+
+declare global {
+  type MDXProvidedComponents = ReturnType<typeof getMDXComponents>;
+}