[Feat] Hexclave AI integration: skill, MCP SKILL.md route, docs#1434
Merged
Conversation
Adds a hexclave SKILL.md (pointer skill that fetches the live body), an /SKILL.md route on the MCP app that renders the full skill from the docs sidebar, expands the AI-integration docs page with CLI / skill / MCP install paths, and updates the stack-shared init prompt to install both the MCP server and skill file with per-project vs global scoping.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThis PR adds a new Next.js skills app that serves a canonical Stack Auth skill (Markdown/HTML), creates a canonical ChangesStack Auth Skill Server and Setup Integration
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
Greptile SummaryThis PR wires up a new
Confidence Score: 5/5Safe to merge — all previously flagged bugs are fixed and no new functional defects were found. The changes are additive (new apps/skills service, updated MCP handler, expanded docs) with no modifications to auth or data-persistence paths. The three regressions identified in the prior review round are all addressed. Remaining observations are style-level: an unused Accept header and the HEAD-delegates-to-GET pattern that Next.js already handles correctly on the wire. apps/skills/src/app/route.ts — buildDocsSection still throws at module init if the Documentation tab is renamed in docs.json, which would take the skills service down at deploy time. Important Files Changed
Sequence DiagramsequenceDiagram
participant Agent as Coding Agent
participant Skills as skill.stack-auth.com
participant MCP as mcp.stack-auth.com
participant Docs as docs.stack-auth.com
Note over Agent,Skills: Skill install path
Agent->>Skills: GET / (no Sec-Fetch headers)
Skills-->>Agent: "full SKILL.md (Cache-Control: max-age=3600)"
Note over Agent,MCP: MCP resource/prompt path
Agent->>MCP: MCP skill resource or prompt request
MCP->>Skills: fetch(skill.stack-auth.com)
Skills-->>MCP: full SKILL.md markdown
MCP-->>Agent: skill text content
Note over Agent,Docs: Direct doc fetch (from within skill)
Agent->>Docs: WebFetch URL from docs sidebar
Docs-->>Agent: specific doc page content
Note over Agent,Skills: Browser navigation path
Agent->>Skills: GET / (Sec-Fetch-Mode: navigate)
Skills-->>Agent: rendered HTML page with install UI
Prompt To Fix All With AIFix the following 3 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 3
apps/skills/src/app/route.ts:232
**Module-init throw on missing "Documentation" tab**
`buildDocsSection()` is still called eagerly at module-init time. If the `"Documentation"` tab is ever removed or renamed in `docs.json`, the explicit `throw` on line 227–228 fires before any request is handled, and the entire `apps/skills` service fails to start. Wrapping `const DOCS_SECTION = buildDocsSection()` in a try/catch and falling back to an empty string (or returning a 500 at request time) would make the failure mode recoverable without taking the whole deployment down.
### Issue 2 of 3
apps/skills/src/app/route.ts:628-630
**`HEAD` handler returns a full response body**
Delegating `HEAD` to `GET` means the `Response` object carries a body (HTML or markdown) even though HEAD responses must not include one per RFC 9110. Next.js strips it before the wire, so no bytes are actually sent, but the returned `Response` has non-zero `content-length`-style headers that could mislead any middleware inspecting the response object. A standalone `HEAD` handler that returns only the headers — or Next.js's built-in automatic HEAD-from-GET behaviour (available without an explicit export) — would be cleaner.
### Issue 3 of 3
apps/mcp/src/mcp-handler.ts:64-66
The `Accept: text/markdown` header has no effect: `apps/skills/src/app/route.ts`'s `wantsHtml()` only inspects `Sec-Fetch-Mode` and `Sec-Fetch-Dest` and completely ignores the `Accept` header. Server-side fetches never carry `Sec-Fetch-*` headers, so markdown is returned regardless — the header is correct in intent but misleading in that it suggests the server honours content negotiation via `Accept`. Consider either removing it or adding a comment noting that the server uses fetch-mode sniffing instead.
```suggestion
// The skills server uses Sec-Fetch-Mode/Sec-Fetch-Dest for content negotiation,
// not the Accept header. Server-side fetches never include Sec-Fetch-* headers,
// so markdown is always returned from this call site.
const res = await fetch(skillResourceUri, {
headers: { Accept: "text/markdown" },
});
```
Reviews (3): Last reviewed commit: "[Chore] Update TypeScript definitions fo..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@apps/mcp/src/app/SKILL.md/route.ts`:
- Around line 45-48: Replace the unsafe type-cast and boolean falsy check when
resolving the Documentation tab: declare a properly typed variable for docsJson
(with navigation and tabs typed to { tab: string; pages: SidebarPage[] }[]), use
optional chaining when accessing navigation.tabs and call .find(...) to locate
the tab into a typed variable named tab, then check explicitly for
null/undefined using tab == null instead of !tab before passing tab.pages to
renderSidebar; ensure you reference the existing renderSidebar function and
SidebarPage type when updating the variable and checks.
- Around line 32-36: The code builds doc links by interpolating DOCS_BASE with
raw path segments (in the lines.push call and the heading construction that uses
`${DOCS_BASE}/${p}` and `${DOCS_BASE}/${p.root}`), which can produce invalid
URLs for reserved characters; update those constructions to build safe URLs by
encoding path segments (e.g., use encodeURIComponent or create a new URL and
append encoded pathname) when combining DOCS_BASE with p and p.root, and keep
the visible label using humanize(p) and p.group unchanged.
In `@packages/stack-shared/src/helpers/init-prompt.ts`:
- Around line 11-20: Update the project-vs-global detection rule in the init
prompt text block that begins "Install both the Hexclave MCP server..." so it
lists project-scoped MCP config filenames as examples (e.g., add ".claude.json",
".cursor/mcp.json", ".vscode/mcp.json", ".codex/config.toml",
".codex/config.toml" style entries) alongside the agent folders; ensure the
wording for the rule that currently only mentions agent folders and
".vscode/mcp.json" is expanded to include these project-scoped config filenames
so the agent correctly selects per-project scope when those files exist.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 4d03b5d2-72ac-449b-9af5-0b0e9e610768
📒 Files selected for processing (4)
apps/mcp/src/app/SKILL.md/route.tsdocs-mintlify/guides/getting-started/ai-integration.mdxpackages/stack-shared/src/helpers/init-prompt.tsskills/hexclave/SKILL.md
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces “Hexclave AI integration” surfaces by adding a Hexclave skill pointer file, exposing a Markdown skill endpoint in the MCP app, updating the AI integration docs, and extending the CLI init prompt to install Hexclave MCP + skill for the active coding agent.
Changes:
- Added
skills/hexclave/SKILL.mdas a pointer skill that instructs agents to fetch the canonical skill content fromhttps://skill.hexclave.com. - Added an
apps/mcp/SKILL.mdroute that renders a full SKILL.md (including a docs sidebar generated fromdocs-mintlify/docs.json). - Updated the Mintlify AI integration guide and the shared
createInitPromptcontent to include Hexclave MCP + skill installation instructions.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| skills/hexclave/SKILL.md | Adds a Hexclave skill pointer that directs agents to fetch canonical instructions remotely. |
| packages/stack-shared/src/helpers/init-prompt.ts | Updates init prompt text to instruct agents to install Hexclave MCP + skill files with project/global scoping rules. |
| docs-mintlify/guides/getting-started/ai-integration.mdx | Rewrites the AI integration doc to describe CLI/Skill/MCP installation paths and agent config snippets. |
| apps/mcp/src/app/SKILL.md/route.ts | Adds a /SKILL.md route that emits a generated SKILL.md containing a docs sidebar and CLI instructions. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
This commit adds a new Stack Auth skill with a corresponding SKILL.md file, which fetches live documentation. It also updates the MCP handler to serve the skill and modifies the init prompt to install both the Stack Auth skill and MCP server. Additionally, it includes various updates to the pnpm-lock.yaml for dependency management and removes the obsolete MCP setup documentation.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 7
♻️ Duplicate comments (1)
packages/stack-shared/src/helpers/init-prompt.ts (1)
11-11:⚠️ Potential issue | 🟠 Major | ⚡ Quick winProject-scoped MCP config files are missing from the detection rule.
The install scope detection at Line 11 only checks for agent folders and
.vscode/mcp.json. Projects using other project-scoped MCP config files (e.g.,.claude.json,.cursor/mcp.json) without an agent folder would be incorrectly detected as "global" scope.📋 Proposed fix to include project-scoped MCP config files
-Install both the Stack Auth skill and the Stack Auth MCP server for the current coding agent. Pick the install scope using this rule: if the project root already contains an agent folder (e.g. \`.claude/\`, \`.agents/\`, \`.cursor/\`, \`.codex/\`, \`.opencode/\`, \`.windsurf/\`, \`.roo/\`, \`.kilocode/\`, \`.augment/\`, \`.continue/\`, \`.crush/\`, \`.vscode/mcp.json\`), install **per project**; otherwise install **globally** for the detected agent. +Install both the Stack Auth skill and the Stack Auth MCP server for the current coding agent. Pick the install scope using this rule: if the project root already contains an agent folder or project-scoped MCP config file (e.g. \`.claude/\`, \`.claude.json\`, \`.agents/\`, \`.cursor/\`, \`.cursor/mcp.json\`, \`.codex/\`, \`.codex/config.toml\`, \`.opencode/\`, \`.windsurf/\`, \`.roo/\`, \`.kilocode/\`, \`.augment/\`, \`.continue/\`, \`.crush/\`, \`.vscode/mcp.json\`), install **per project**; otherwise install **globally** for the detected agent.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/stack-shared/src/helpers/init-prompt.ts` at line 11, The install-scope detection logic in packages/stack-shared/src/helpers/init-prompt.ts only checks for agent folders and '.vscode/mcp.json', missing other project-scoped MCP config files; update the detection code (the install scope check / detection function) to also look for known project-scoped MCP config paths such as '.claude.json' and '.cursor/mcp.json' (and any other project-specific MCP files you maintain) by adding them to the list/array of projectScopedPaths or patterns and using the same fs.existsSync/glob check used for the existing entries so projects with those config files are detected as per-project installs.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@apps/mcp/src/mcp-handler.ts`:
- Around line 63-68: fetchSkill currently performs an unchecked fetch and can
throw on network errors or non-2xx responses; wrap the fetch in a try/catch,
check response.ok and handle non-200 statuses, log the error (e.g.,
console.error/processLogger) and return a safe fallback string (empty string or
a brief default skill marker) instead of rethrowing so callers of fetchSkill
(the resource and prompt handlers) won't crash the MCP server; update the
function fetchSkill to return the fallback on any error or non-ok response.
In `@apps/skills/package.json`:
- Around line 22-23: The `@types` packages for React are pinned to ^18.2.0 but the
project uses React 19.2.3; update the versions for "@types/react" and
"@types/react-dom" in apps/skills/package.json to match the installed React
version (e.g., ^19.2.3 or the exact 19.2.3) so type definitions align with
"react" and "react-dom", then reinstall dependencies (npm/yarn/pnpm install) and
rebuild to ensure TypeScript uses the updated types.
- Line 16: Update the Next.js dependency in package.json from "next": "16.1.7"
to "next": "16.2.6" to pick up the May 2026 security fixes; locate the "next"
entry in apps/skills package.json (the dependency key "next") and change its
version string to "16.2.6", then run your package manager install and test
startup/build to ensure compatibility.
In `@apps/skills/src/app/route.ts`:
- Around line 10-15: humanizeSegment can throw when a split produces empty
strings; update the logic in humanizeSegment to guard against empty segments
(from leading/trailing or consecutive hyphens) by either filtering out falsy
segments before mapping or handling w === "" inside the map. Specifically,
modify the chain around .split("-").map(...) so it ignores empty strings (e.g.,
.split("-").filter(Boolean).map(...)) or returns an empty string for empty w,
and keep the existing ACRONYMS check and capitalization behavior intact.
- Around line 447-449: The HEAD handler currently returns the full GET response
body; change export function HEAD(req: Request) so it invokes GET(req) to obtain
the same headers/status but returns an empty body: call GET(req) (or the
internal handler) to get the Response, then construct and return a new
Response(null, { status: response.status, headers: response.headers }) so
headers and status match GET while the body is empty; update references in
export function HEAD to use this pattern.
- Around line 399-416: The clipboard writeText call in the click handler
currently swallows all errors in catch (_e) — change it to catch the error as a
variable (e.g., catch (err)) and handle it explicitly: attempt the existing DOM
fallback (selectNode + execCommand) but detect if that fallback fails and then
surface the failure to the user and logs (e.g., set btn.textContent = "Copy
failed" or btn.setAttribute("data-state","error") and call console.error(err)),
and if appropriate rethrow or return a rejected Promise so the error is not
silently dropped; update references in the IIFE where btn,
navigator.clipboard.writeText, and the fallback DOM selection are used.
In `@skills/stack-auth/SKILL.md`:
- Around line 28-30: Add a language identifier to the fenced code block that
contains the URL "https://skill.stack-auth.com" so it renders with proper syntax
highlighting (e.g., change the fence to ```text or ```markdown). Locate the
markdown block in SKILL.md that currently shows the raw URL and update the
opening fence to include the chosen language identifier.
---
Duplicate comments:
In `@packages/stack-shared/src/helpers/init-prompt.ts`:
- Line 11: The install-scope detection logic in
packages/stack-shared/src/helpers/init-prompt.ts only checks for agent folders
and '.vscode/mcp.json', missing other project-scoped MCP config files; update
the detection code (the install scope check / detection function) to also look
for known project-scoped MCP config paths such as '.claude.json' and
'.cursor/mcp.json' (and any other project-specific MCP files you maintain) by
adding them to the list/array of projectScopedPaths or patterns and using the
same fs.existsSync/glob check used for the existing entries so projects with
those config files are detected as per-project installs.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 9ee24b49-ba09-44ee-b411-d56393fe8201
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (12)
apps/mcp/src/mcp-handler.tsapps/skills/.eslintrc.cjsapps/skills/next.config.mjsapps/skills/package.jsonapps/skills/src/app/health/route.tsapps/skills/src/app/route.tsapps/skills/tsconfig.jsondocs-mintlify/docs.jsondocs-mintlify/guides/getting-started/ai-integration.mdxdocs-mintlify/guides/other/mcp-setup.mdxpackages/stack-shared/src/helpers/init-prompt.tsskills/stack-auth/SKILL.md
💤 Files with no reviewable changes (1)
- docs-mintlify/guides/other/mcp-setup.mdx
✅ Files skipped from review due to trivial changes (5)
- apps/skills/tsconfig.json
- apps/skills/.eslintrc.cjs
- apps/skills/next.config.mjs
- docs-mintlify/guides/getting-started/ai-integration.mdx
- docs-mintlify/docs.json
…inks This commit adds error handling to the fetchSkill function, throwing an error when the fetch request fails. Additionally, it refactors the route handling in the skills app to utilize a new docUrl function for generating documentation links, ensuring consistency and clarity. The init prompt in the stack-shared package is also updated to clarify installation instructions for the Stack Auth skill and MCP server.
This commit enhances the documentation for the Stack Auth MCP server by clarifying the usage of the `ask_stack_auth` tool and the skill resource. The instructions now emphasize the importance of using `ask_stack_auth` for accessing official documentation and troubleshooting, while also detailing the role of the `skill` resource for quick references. These updates aim to improve user guidance and streamline the integration process.
This commit updates the TypeScript definitions for React and React DOM in the skills package from version 18.2.0 to 19.2.3. Additionally, it modifies the SKILL.md file for the Stack Auth skill to specify the code block language as 'text' for better formatting. These changes aim to ensure compatibility with the latest React features and improve documentation clarity.
N2D4
approved these changes
May 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
hexclaveSKILL.md pointer skill that fetches the live skill body on every invocation/SKILL.mdroute on the MCP app that renders the full skill (CLI usage + docs sidebar generated fromdocs.json)docs-mintlify/guides/getting-started/ai-integration.mdxwith three install paths (CLI, Skill, MCP) and per-agent config snippetspackages/stack-shared/src/helpers/init-prompt.tsto install both the MCP server and skill file, with per-project vs global scope detectionTest plan
pnpm typecheckpnpm lint/SKILL.mdendpoint locally and verify it returns valid markdown with the full docs sidebarai-integration.mdxin Mintlify preview and confirm tabs/cards renderSummary by CodeRabbit
Documentation
New Features
Chores