<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
Enhances the search functionality to now use the MCP server.
Now handles API endpoints and webhooks.
Now looks at what platform the user has selected, and searches based on
that. User can choose to filter differently if needed.
<img width="686" height="608" alt="image"
src="https://github.com/user-attachments/assets/641c9bd2-60d2-44b3-86ca-a4506257b430"
/>
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR enhances the search functionality for Stack Auth documentation
by integrating it with their MCP (Model Control Plane) server. The
implementation replaces the previous client-side search algorithm with a
server-side approach that leverages the MCP's search capabilities. The
changes affect three main files: the MCP handler that now includes a new
`search_docs` tool, the search route handler that now forwards queries
to the MCP server instead of performing local searches, and the search
dialog UI that has been updated to better handle platform-specific
filtering and API documentation. The new implementation provides more
relevant search results and automatically filters based on the user's
current platform context, while allowing users to customize their search
filters as needed.
⏱️ Estimated Review Time: 30-90 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `docs/src/app/api/internal/[transport]/route.ts` |
| 2 | `docs/src/app/api/search/route.ts` |
| 3 | `docs/src/components/layout/custom-search-dialog.tsx` |
</details>
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Enhances search by integrating with MCP server, updating UI for
platform-specific filtering, and improving result presentation.
>
> - **Search Functionality**:
> - Integrates search with MCP server in `route.ts` files, replacing
client-side search.
> - Supports API and platform-specific results, filtering out admin API
endpoints.
> - Sorts results by platform priority.
> - **UI Updates**:
> - Updates `custom-search-dialog.tsx` to support platform-specific
filtering and API results.
> - Adds platform badges and icons for different result types.
> - Auto-detects platform from URL and adjusts search filters
accordingly.
> - **Miscellaneous**:
> - Adds new helper functions for platform extraction and MCP server
communication.
> - Improves error handling and logging for search operations.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 9941d02bd5. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- RECURSEML_ANALYSIS:START -->
## Review by RecurseML
_🔍 Review performed on
[7a0bf86..28264f7](7a0bf86cb3...28264f7f99)_
| Severity | Location | Issue
| Delete |
|:----------:|----------|-------|:--------:|
|  |
[docs/src/app/api/internal/[transport]/route.ts:125](https://github.com/stack-auth/stack-auth/pull/909#discussion_r2368682927)
| API parameter 'query' uses camelCase instead of required snake_case |
[
|
|  |
[docs/src/app/api/internal/[transport]/route.ts:126](https://github.com/stack-auth/stack-auth/pull/909#discussion_r2368683094)
| API parameter 'limit' uses camelCase instead of required snake_case |
[
|
|  |
[docs/src/app/api/internal/[transport]/route.ts:174](https://github.com/stack-auth/stack-auth/pull/909#discussion_r2368683229)
| Async operation not wrapped with runAsynchronously |
[
|
|  |
[docs/src/app/api/search/route.ts:23](https://github.com/stack-auth/stack-auth/pull/909#discussion_r2368683372)
| REST API parameters not using snake_case |
[
|
|  |
[docs/src/app/api/search/route.ts:130](https://github.com/stack-auth/stack-auth/pull/909#discussion_r2368683491)
| Async function call not wrapped in runAsynchronously |
[
|
|  |
[docs/src/app/api/search/route.ts:11](https://github.com/stack-auth/stack-auth/pull/909#discussion_r2368683588)
| Async function definition without proper runAsynchronously usage |
[
|
<details>
<summary>✅ Files analyzed, no issues (1)</summary>
• `docs/src/components/layout/custom-search-dialog.tsx`
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_ANALYSIS:END -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Search now includes API docs as an "API" result type with relevance
snippets, API-specific icons and group titles.
* Platform-aware filtering auto-detects platform on open and adds “API
only” and “Platform + API” views.
* **Improvements**
* Search is powered by a centralized streamed service for more
consistent results, better error handling, and fallbacks.
* Results are ordered with platform-priority, show clearer
counts/footers, and present more resilient, unified result formatting.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
<!--
ONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR changes the default development ports for several background
services to avoid conflicts. PostgreSQL moves from port `5432` to
`8128`, Inbucket SMTP from `2500` to `8129`, Inbucket POP3 from `1100`
to `8130`, and the OpenTelemetry collector from `4318` to `8131`. All
references across configuration files, Docker Compose setups,
environment files, CI/CD workflows, test files, and documentation have
been updated to reflect these new port assignments. A knowledge base
document has been added to document the new port mappings.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
| --- | --- |
| 1 | `claude/CLAUDE-KNOWLEDGE.md` |
| 2 | `apps/dev-launchpad/public/index.html` |
| 3 | `docker/dependencies/docker.compose.yaml` |
| 4 | `docker/emulator/docker.compose.yaml` |
| 5 | `apps/backend/.env` |
| 6 | `apps/backend/.env.development` |
| 7 | `docker/server/.env.example` |
| 8 | `package.json` |
| 9 | `.devcontainer/devcontainer.json` |
| 10 | `apps/e2e/.env.development` |
| 11 | `.github/workflows/check-prisma-migrations.yaml` |
| 12 | `.github/workflows/docker-server-test.yaml` |
| 13 | `.github/workflows/e2e-api-tests.yaml` |
| 14 | `.github/workflows/e2e-source-of-truth-api-tests.yaml` |
| 15 | `.github/workflows/restart-dev-and-test.yaml` |
| 16 |
`apps/e2e/tests/backend/endpoints/api/v1/internal/email-drafts.test.ts`
|
| 17 | `apps/e2e/tests/backend/endpoints/api/v1/internal/email.test.ts`
|
| 18 | `apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts` |
| 19 |
`apps/e2e/tests/backend/endpoints/api/v1/unsubscribe-link.test.ts` |
| 20 | `apps/e2e/tests/backend/workflows.test.ts` |
| 21 | `docs/templates/others/self-host.mdx` |
</details>
[](https://discord.gg/n3SsVDAW6U)
[
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> This PR introduces customizable development ports using
`NEXT_PUBLIC_STACK_PORT_PREFIX`, updating configurations, documentation,
and tests accordingly.
>
> - **Behavior**:
> - Default development ports for services are now customizable via
`NEXT_PUBLIC_STACK_PORT_PREFIX`.
> - PostgreSQL port changed from `5432` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}28`.
> - Inbucket SMTP port changed from `2500` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}29`.
> - Inbucket POP3 port changed from `1100` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}30`.
> - OpenTelemetry collector port changed from `4318` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}31`.
> - **Configuration**:
> - Updated `docker.compose.yaml` to use new port variables for services
like PostgreSQL, Inbucket, and OpenTelemetry.
> - Environment files in `apps/backend`, `apps/dashboard`, and
`apps/e2e` updated to use `NEXT_PUBLIC_STACK_PORT_PREFIX`.
> - `package.json` scripts updated to reflect new port configurations.
> - **Documentation**:
> - Added `CLAUDE-KNOWLEDGE.md` to document new port mappings.
> - Updated `self-host.mdx` to reflect new port configurations.
> - **Testing**:
> - Updated test files in `apps/e2e/tests` to use new port
configurations.
> - Added `helpers/ports.ts` for port-related utilities in tests.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 76ef55f58f. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **New Features**
- Enable configurable development ports via a
NEXT_PUBLIC_STACK_PORT_PREFIX, allowing parallel local environments with
custom port prefixes.
- **Bug Fixes**
- Updated local service port mappings and CI/workflow settings so
tooling and tests use the new prefixed ports consistently.
- **Documentation**
- Added docs and contributor guidance for running multiple parallel
workspaces with custom port prefixes.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: N2D4 <N2D4@users.noreply.github.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
Removes Platform selection, moves docs to single /content folder and no
longer gens docs. Only API docs are generated here.
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR makes significant changes to the documentation structure by
removing platform-specific content organization and consolidating docs
into a single `/content` folder. The primary goal is to simplify the
documentation architecture by eliminating the platform-specific routing
(Next.js, React, JavaScript, Python) and instead organizing content by
topic (guides, SDK, components) regardless of platform. The PR removes
platform selection functionality, platform-specific navigation, and the
automatic generation of platform-specific documentation pages. It
introduces a new docs tree filtering system that organizes content by
section rather than by platform. These changes should make the
documentation more maintainable and easier to navigate while focusing on
the content itself rather than platform-specific variations.
⏱️ Estimated Review Time: 30-90 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `docs/package.json` |
| 2 | `docs/src/lib/docs-tree.ts` |
| 3 | `docs/src/lib/navigation-utils.ts` |
| 4 | `docs/src/components/homepage/iconHover.tsx` |
| 5 | `docs/src/components/sdk/overview.tsx` |
| 6 | `docs/src/components/layouts/shared/section-utils.ts` |
| 7 | `docs/src/components/layout/custom-search-dialog.tsx` |
| 8 | `docs/src/app/api/search/route.ts` |
| 9 | `docs/src/app/docs/[[...slug]]/page.tsx` |
| 10 | `docs/src/components/layouts/docs-header-wrapper.tsx` |
| 11 | `docs/src/components/layouts/docs-layout-router.tsx` |
| 12 | `docs/src/components/layouts/docs.tsx` |
| 13 | `package.json` |
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_SUMMARY:END -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added many new guides (auth providers, OAuth, JWT, API keys, emails,
webhooks, orgs/teams, permissions, onboarding, customization), expanded
SDK & component reference pages, examples, and navigation metadata.
* Switched docs to a simpler section-based, platform-agnostic structure
and improved getting-started and production checklists.
* **Developer Experience**
* Enhanced docs UX: improved code-example UI with platform/framework
selectors, theme-aware highlighted code blocks, image zoom, and a
centralized code-sample registry.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konstantin Wohlwend <n2d4xc@gmail.com>
