Break down MCP route registrations

Author: IlyaasK

src/app/[transport]/route.ts

@@ -0,0 +1,21 @@
+import { Kernel } from "@onkernel/sdk";
+
+export function createKernelClient(apiKey: string) {
+  const headers: Record<string, string> = {
+    "X-Source": "mcp-server",
+    "X-Referral-Source": "mcp.onkernel.com",
+  };
+
+  const projectId = process.env.KERNEL_PROJECT;
+  if (projectId) {
+    headers["X-Kernel-Project-Id"] = projectId;
+  }
+
+  return new Kernel({
+    apiKey,
+    baseURL: process.env.API_BASE_URL,
+    defaultHeaders: headers,
+  });
+}
+
+export type KernelClient = ReturnType<typeof createKernelClient>;

src/lib/mcp/kernel-client.ts

@@ -0,0 +1,259 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+export function registerKernelPrompts(server: McpServer) {
+  // MCP Prompt explaining Kernel concepts
+  server.prompt(
+    "kernel-concepts",
+    "Explain Kernel's core concepts and capabilities for AI agents working with web automation",
+    {
+      concept: z
+        .enum(["browsers", "apps", "overview"])
+        .describe(
+          "The specific concept to explain: browsers (sessions), apps (code execution), profiles (browser auth), or overview (all concepts)",
+        ),
+    },
+    async ({ concept }) => {
+      const explanations = {
+        browsers: `## 🌐 Browsers (Sessions)
+
+**What they are:** Kernel provides serverless browsers-as-a-service that run in isolated cloud environments. Each browser is a complete, sandboxed instance that can automate any website.
+
+**Key capabilities:**
+- **Instant launch** - Browsers start in seconds, not minutes
+- **Full isolation** - Each browser runs in its own virtual machine
+- **Parallel scaling** - Run hundreds or thousands of concurrent browsers
+- **Live view** - Human-in-the-loop workflows with real-time browser viewing
+- **Replays** - Record and review past browser sessions as videos
+- **CDP integration** - Connect with Playwright, Puppeteer, or any CDP-compatible tool
+- **Profiles** - Save and reuse authentication cookies and login data across sessions
+
+**Use cases:** Web scraping, form automation, testing, data extraction, user journey simulation, and any task requiring browser interaction.
+
+**Session options:**
+- **Timeout** - Configure browser timeout up to 72 hours for long-running sessions
+- **Profiles** - Save and reuse authentication cookies and login data`,
+
+        apps: `## 🚀 Apps (Code Execution Platform)
+
+**What they are:** Kernel's app platform lets you deploy, host, and invoke browser automation code in production without managing infrastructure.
+
+**Key capabilities:**
+- **Serverless execution** - Deploy automation code that runs on-demand
+- **Auto-scaling** - Automatically handles traffic spikes and resource allocation
+- **Seamless integration** - Apps can create and manage browsers programmatically
+- **Production ready** - Built-in monitoring, logging, and error handling
+- **Multiple languages** - Support for Python, TypeScript, and more
+
+**Development workflow:**
+1. Write your automation code
+2. Deploy to Kernel's platform
+3. Invoke via API or MCP tools
+4. Monitor execution and results
+
+**Use cases:** Scheduled web scraping, API endpoints for browser automation, complex multi-step workflows, and production automation services.`,
+
+        overview: `## 🎯 Kernel Platform Overview
+
+**What Kernel is:** A developer platform that provides browsers-as-a-service for AI agents to access websites. Our API and MCP server allows web agents to instantly launch browsers in the cloud and automate anything on the internet.
+
+**Core Concepts:**
+
+### 🌐 Browsers (Sessions)
+Serverless browsers that run in isolated cloud environments. Each browser can automate any website with full CDP compatibility, live viewing, replay capabilities, and profiles for authentication.
+
+### 🚀 Apps (Code Execution)
+Production-ready platform for deploying and hosting browser automation code. Handles auto-scaling, monitoring, and execution without infrastructure management.
+
+**Why developers choose Kernel:**
+- **Performance** - Crazy fast browser launch times
+- **Developer experience** - Simple APIs and comprehensive tooling
+- **Production ready** - Handles bot detection, authentication, scaling, and observability
+- **Cost effective** - Only pay for active browser time
+- **Reliable** - Built for enterprise-scale automation
+
+**Perfect for:** AI agents, web automation, testing, scraping, form filling, and any task requiring browser interaction.`,
+      };
+
+      return {
+        messages: [
+          {
+            role: "assistant",
+            content: {
+              type: "text",
+              text: explanations[concept],
+            },
+          },
+        ],
+      };
+    },
+  );
+
+  // Debug Browser Session Prompt
+  server.prompt(
+    "debug-browser-session",
+    "Comprehensive debugging guide for troubleshooting Kernel browser sessions. Provides a systematic approach to diagnose VM issues, network problems, Chrome errors, and more.",
+    {
+      session_id: z
+        .string()
+        .describe(
+          "The browser session ID to debug (e.g., 'abc123example456xyz')",
+        ),
+      issue_description: z
+        .string()
+        .describe(
+          "Description of the issue you're experiencing (e.g., 'ERR_HTTP2_PROTOCOL_ERROR when navigating to a specific site', 'browser not responding', 'page not loading')",
+        ),
+    },
+    async ({ session_id, issue_description }) => {
+      const debugGuide = `# 🔍 Browser Session Debugging Guide
+
+**Session ID:** \`${session_id}\`
+**Reported Issue:** ${issue_description}
+
+---
+
+## Tools
+
+**Use the Kernel CLI for debugging.** It provides full access to browser sessions, VM logs, and process execution.
+
+Install: \`brew install onkernel/tap/kernel\` or \`npm install -g @onkernel/cli\`
+
+**Explore available commands recursively:**
+\`\`\`bash
+kernel --help
+kernel browsers --help
+kernel browsers fs --help
+kernel browsers process --help
+kernel browsers playwright --help
+\`\`\`
+
+**MCP Exception:** The \`computer_action\` MCP tool with action "screenshot" is useful since it returns images directly to the agent.
+
+---
+
+## Key CLI Commands for Debugging
+
+### Check session status
+\`\`\`bash
+kernel browsers get ${session_id}
+\`\`\`
+
+### Take a screenshot (or use MCP computer_action with action "screenshot")
+\`\`\`bash
+kernel browsers screenshot ${session_id}
+\`\`\`
+
+### Execute Playwright code
+\`\`\`bash
+kernel browsers playwright execute ${session_id} "return { url: page.url(), title: await page.title() }"
+\`\`\`
+
+### Read VM log files
+\`\`\`bash
+kernel browsers fs read-file ${session_id} --path /var/log/supervisord.log
+kernel browsers fs read-file ${session_id} --path /var/log/supervisord/chromium
+kernel browsers fs read-file ${session_id} --path /var/log/supervisord/neko
+\`\`\`
+
+### List files in the VM
+\`\`\`bash
+kernel browsers fs ls ${session_id} --path /var/log
+\`\`\`
+
+### Execute commands inside the VM
+\`\`\`bash
+kernel browsers process exec ${session_id} -- curl -I https://example.com
+kernel browsers process exec ${session_id} -- cat /etc/resolv.conf
+\`\`\`
+
+### Check cookies via Playwright
+\`\`\`bash
+kernel browsers playwright execute ${session_id} "const cookies = await page.context().cookies(); return { count: cookies.length, domains: [...new Set(cookies.map(c => c.domain))] }"
+\`\`\`
+
+---
+
+## Common Issues & Solutions
+
+### Network Errors (ERR_HTTP2_PROTOCOL_ERROR, ERR_CONNECTION_RESET, etc.)
+
+**Bot detection is a common cause of network errors.** Many sites use CDNs like Cloudflare, Imperva, or Akamai that fingerprint browsers and block automation.
+
+**Signs of bot detection:**
+- curl works from the VM but Chrome shows an error
+- "Access Denied", CAPTCHA pages, or "Checking your browser..." messages
+- \`stealth: false\` in browser config (check with manage_browsers action "get")
+
+**Solutions:** Use \`stealth: true\`, use profiles with real auth, or try shorter session lifetimes.
+
+### Browser Not Responding
+**Cause:** Chrome process crashed or hung
+**Check:** Supervisor logs for chromium restart events
+**Solutions:**
+1. Check if timeout was reached
+2. Look for memory issues in logs
+3. Create a new browser session
+
+### Page Not Loading
+**Cause:** Network, DNS, or proxy issues
+**Check:**
+1. Test curl from inside VM
+2. Check /etc/resolv.conf for DNS config
+3. Verify proxy settings if using one
+
+### Live View Not Working
+**Cause:** Neko/WebRTC issues
+**Check:** Neko logs for connection errors
+**Solutions:**
+1. Check for firewall blocking WebRTC
+2. Verify browser is not in headless mode
+
+---
+
+## Expected Log Entries (Normal Operation)
+
+These are **normal** and don't indicate problems:
+- \`Failed to call method: org.freedesktop.DBus.Properties.GetAll\` - DBus permission (expected in container)
+- \`vkCreateInstance: Found no drivers\` - No GPU in VM (expected)
+- \`DEPRECATED_ENDPOINT\` for GCM - Google deprecation (harmless)
+- \`SharedImageManager::ProduceMemory\` errors - GPU-related (not critical)
+
+---
+
+## Debugging Checklist
+
+- [ ] Session exists and is active
+- [ ] Screenshot shows expected content (or reveals error)
+- [ ] Current URL is as expected
+- [ ] Supervisor logs show all services running
+- [ ] Network connectivity works (curl test)
+- [ ] No critical errors in chromium logs
+- [ ] Cookies/session state is correct
+
+---
+
+## Next Steps
+
+Based on your issue "${issue_description}", start with:
+
+1. **Get browser info** to confirm session is active
+2. **Take screenshot** to see current state
+3. **Check page URL** to see if on error page
+4. **Test network** if seeing connection errors
+5. **Review logs** for specific error patterns`;
+
+      return {
+        messages: [
+          {
+            role: "assistant",
+            content: {
+              type: "text",
+              text: debugGuide,
+            },
+          },
+        ],
+      };
+    },
+  );
+}

src/lib/mcp/prompts.ts

@@ -0,0 +1,26 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerKernelPrompts } from "@/lib/mcp/prompts";
+import { registerAppCapabilities } from "@/lib/mcp/tools/apps";
+import { registerBrowserPoolCapabilities } from "@/lib/mcp/tools/browser-pools";
+import { registerBrowserCapabilities } from "@/lib/mcp/tools/browsers";
+import { registerComputerActionTool } from "@/lib/mcp/tools/computer-action";
+import { registerDocsTools } from "@/lib/mcp/tools/docs";
+import { registerExtensionTools } from "@/lib/mcp/tools/extensions";
+import { registerPlaywrightTool } from "@/lib/mcp/tools/playwright";
+import { registerProfileCapabilities } from "@/lib/mcp/tools/profiles";
+import { registerProxyTools } from "@/lib/mcp/tools/proxies";
+import { registerShellTool } from "@/lib/mcp/tools/shell";
+
+export function registerMcpCapabilities(server: McpServer) {
+  registerProfileCapabilities(server);
+  registerKernelPrompts(server);
+  registerDocsTools(server);
+  registerBrowserCapabilities(server);
+  registerBrowserPoolCapabilities(server);
+  registerProxyTools(server);
+  registerExtensionTools(server);
+  registerAppCapabilities(server);
+  registerComputerActionTool(server);
+  registerShellTool(server);
+  registerPlaywrightTool(server);
+}