Merge pull request 'docs(cache): set Vercel edge Cache-Control for HTML pages (RFC#562 step 1)' (#56) from docs/rfc562-cache-headers into main

docs(cache): set Vercel edge Cache-Control for HTML pages (RFC#562 step 1)

Merged via 2-eye review (core-devops + core-security APPROVED).

content/docs/mcp-server.mdx

@@ -25,8 +25,7 @@ npx @molecule-ai/mcp-server@1.0.0
       "command": "npx",
       "args": ["@molecule-ai/mcp-server@1.0.0"],
       "env": {
-        "MOLECULE_URL": "http://localhost:8080",
-        "MOLECULE_API_KEY": "your-bearer-token"
+        "MOLECULE_URL": "http://localhost:8080"
       }
     }
   }
@@ -37,11 +36,10 @@ npx @molecule-ai/mcp-server@1.0.0
   **Pin the package version.** The examples above use `@1.0.0` — always specify an exact version and omit the `-y` flag. An unpinned `npx -y @molecule-ai/mcp-server` (no version) silently installs whatever npm serves on the next restart; if the package is ever compromised, it runs with your full MCP client permissions. Check [npm](https://www.npmjs.com/package/@molecule-ai/mcp-server) for the latest stable release before upgrading.
 </Callout>
 
-For SaaS deployments, set `MOLECULE_URL` to your tenant URL and add your API key:
+For SaaS deployments, set `MOLECULE_URL` to your tenant URL:
 
 ```json
-"MOLECULE_URL": "https://your-org.moleculesai.app",
-"MOLECULE_API_KEY": "your-bearer-token"
+"MOLECULE_URL": "https://your-org.moleculesai.app"
 ```
 
 ### Verify
@@ -154,8 +152,6 @@ The MCP server exposes tools across these categories:
 | Variable | Default | Description |
 |---|---|---|
 | `MOLECULE_URL` | `http://localhost:8080` | Platform API URL |
-| `MOLECULE_API_KEY` | — | Bearer token for platform authentication |
-| `MCP_SERVER_PORT` | `3000` | TCP port the MCP server listens on (HTTP/SSE transport) |
 
 ## Troubleshooting
 
@@ -163,5 +159,4 @@ The MCP server exposes tools across these categories:
 |---|---|
 | Connection refused | Check `MOLECULE_URL` points to running platform |
 | 401 Unauthorized | Token expired or revoked — create a new one |
-| Port already in use | Set `MCP_SERVER_PORT` to an available port if 3000 is taken |
 | Tools not showing | Run `npx @molecule-ai/mcp-server@1.0.0` standalone to check errors |

next.config.mjs

@@ -2,9 +2,33 @@ import { createMDX } from 'fumadocs-mdx/next';
 
 const withMDX = createMDX();
 
+// HTML pages: short edge cache + long stale-while-revalidate. Lets Vercel Edge
+// serve repeat navigations from cache (~5 min fresh, 24 h stale-while-revalidate
+// in the background) while keeping the browser revalidating on every nav. The
+// negative lookahead leaves Next.js's own _next/static (immutable, hash-named)
+// and _next/image cache headers untouched.
+const HTML_CACHE_CONTROL =
+  'public, max-age=0, s-maxage=300, stale-while-revalidate=86400';
+
 /** @type {import('next').NextConfig} */
 const config = {
   reactStrictMode: true,
+  async headers() {
+    return [
+      {
+        // Match every path except Next.js internals and API routes — those
+        // already have correct cache headers (immutable for hashed assets,
+        // app-controlled for /api).
+        source: '/((?!_next/static|_next/image|api/).*)',
+        headers: [
+          {
+            key: 'Cache-Control',
+            value: HTML_CACHE_CONTROL,
+          },
+        ],
+      },
+    ];
+  },
 };
 
 export default withMDX(config);