[Feat] Hexclave AI integration: skill, MCP SKILL.md route, docs

apps/mcp/src/mcp-handler.ts

@@ -23,7 +23,7 @@ type AiQueryResponse = {
   conversationId?: string,
 };
 
-const setupResourceUri = "stack-auth://mcp/setup";
+const skillResourceUri = "https://skill.stack-auth.com";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
@@ -60,49 +60,45 @@ function parseAiQueryResponse(value: unknown): AiQueryResponse {
   return parsed;
 }
 
+async function fetchSkill(): Promise<string> {
+  const res = await fetch(skillResourceUri, {
+    headers: { Accept: "text/markdown" },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch skill from ${skillResourceUri}: ${res.status} ${res.statusText}`);
+  }
+  return await res.text();
+}
+
 export function createStackMcpHandler(config: { streamableHttpEndpoint: string }) {
   return createMcpHandler(
     async (server) => {
       server.resource(
-        "stack-auth-mcp-setup",
-        setupResourceUri,
+        "skill",
+        skillResourceUri,
         {
-          title: "Stack Auth MCP setup",
-          description: "Setup instructions for the Stack Auth MCP server.",
+          title: "Stack Auth skill",
+          description: "The canonical Stack Auth agent skill (SKILL.md) — how to wire Stack Auth into a project.",
           mimeType: "text/markdown",
         },
-        () => ({
+        async () => ({
           contents: [{
-            uri: setupResourceUri,
+            uri: skillResourceUri,
             mimeType: "text/markdown",
-            text: `# Stack Auth MCP
-
-Use this MCP server to ask Stack Auth documentation questions with the ask_stack_auth tool.
-
-Server URL: ${config.streamableHttpEndpoint}
-
-Tool: ask_stack_auth
-- question: the Stack Auth question to answer
-- reason: why the agent is calling the tool
-- userPrompt: the original user prompt that triggered the call
-- conversationId: optional ID from an earlier response
-`,
+            text: await fetchSkill(),
           }],
         }),
       );
 
       server.prompt(
-        "ask_stack_auth",
-        "Ask the Stack Auth documentation assistant a question.",
-        {
-          question: z.string().describe("The Stack Auth question to ask."),
-        },
-        ({ question }) => ({
+        "skill",
+        "Load the Stack Auth skill (SKILL.md) into the conversation — how to wire Stack Auth into a project.",
+        async () => ({
           messages: [{
             role: "user",
             content: {
               type: "text",
-              text: `Use the ask_stack_auth tool to answer this Stack Auth question: ${question}`,
+              text: await fetchSkill(),
             },
           }],
         }),
@@ -180,6 +176,7 @@ Tool: ask_stack_auth
         name: "stack-auth-mcp",
         version: packageJson.version,
       },
+      instructions: "Stack Auth's official MCP server. Prefer the `ask_stack_auth` tool for any question about Stack Auth — setup, SDKs (Next.js, React, JS), APIs, configuration, OAuth, teams/permissions, or troubleshooting. It searches the official docs and answers with citations, and should be your first stop over web search or training data since Stack Auth changes frequently. The `skill` resource/tool loads SKILL.md (the canonical Stack Auth agent skill) — pull it in when you need a quick reference for project setup, CLI usage, or wiring conventions, but always use `ask_stack_auth` first.",
     },
     {
       streamableHttpEndpoint: config.streamableHttpEndpoint,

apps/skills/.eslintrc.cjs

@@ -0,0 +1,4 @@
+module.exports = {
+  extends: ["../../configs/eslint/defaults.js", "../../configs/eslint/next.js"],
+  ignorePatterns: ["/*", "!/src"],
+};

apps/skills/next.config.mjs

@@ -0,0 +1,6 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  poweredByHeader: false,
+};
+
+export default nextConfig;

apps/skills/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@stackframe/skills",
+  "version": "2.8.89",
+  "repository": "https://github.com/stack-auth/stack-auth",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "clean": "rimraf .next && rimraf node_modules",
+    "typecheck": "tsc --noEmit",
+    "dev": "next dev --turbopack --port ${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}45",
+    "build": "next build",
+    "start": "next start --port ${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}45",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "next": "16.1.7",
+    "react": "19.2.3",
+    "react-dom": "19.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "20.17.6",
+    "@types/react": "^19.2.3",
+    "@types/react-dom": "^19.2.3",
+    "rimraf": "^5.0.5",
+    "typescript": "5.9.3"
+  }
+}

apps/skills/src/app/health/route.ts

@@ -0,0 +1,12 @@
+export function GET() {
+  return Response.json({
+    status: "ok",
+  }, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "*",
+      "Access-Control-Allow-Headers": "*",
+      "Access-Control-Expose-Headers": "*",
+    },
+  });
+}