npm - @workos/mcp-docs-server - Versions diffs - 0.1.0 → 0.2.0 - Mend

@workos/mcp-docs-server 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (568) hide show

package/.docs/organized/docs/widgets/localization.mdx ADDED Viewed

@@ -0,0 +1,111 @@
+---
+title: Localization
+description: Learn how to display Widgets in multiple languages.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/widgets/localization.mdx
+---
+Widgets can automatically translate text in your users' preferred language, with support for 90 languages out of the box. If your website is already localized in multiple languages, then Widgets can match the page's language, giving your users a consistent experience.
+![API keys widget translated into Japanese](https://images.workoscdn.com/images/8f52fe99-99b3-4bf3-acd4-ead279b594ff.png?auto=format&fit=clip&q=80)
+Dates are also formatted with respect to the user's locale.
+## Installation
+Localization support is provided through a separate `@workos-inc/widgets-i18n` package. This opt-in approach keeps the core Widgets package lightweight for applications that don't require multilingual behavior.
+Translation dictionaries are loaded lazily, meaning only the language bundle matching the end user's locale is downloaded at runtime.
+Install the package:
+```bash title="Install package"
+npm install @workos-inc/widgets-i18n
+```
+## Setup
+Wrap your application with the `WorkOsLocaleProvider`:
+```tsx title="app/layout.tsx"
+import { WorkOsLocaleProvider } from '@workos-inc/widgets-i18n';
+export default async function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const locale = await getLocale(); // read from request headers
+  const direction = getLocaleDir(locale);
+  return (
+    <WorkOsLocaleProvider locale={locale}>
+      <html dir={direction} lang={locale}>
+        <body>{children}</body>
+      </html>
+    </WorkOsLocaleProvider>
+  );
+}
+```
+The `WorkOsLocaleProvider` should wrap your entire application, similar to other context providers. Pass the user's locale as the `locale` prop.
+## Detecting user locale
+Use the utilities exported from `@workos-inc/widgets-i18n` to detect and validate locales:
+- `getLocaleCodes()` – Set of all supported locale codes
+- `isValidLocale()` – Validates whether a string is a supported locale code
+- `getDir()` – Returns the text direction (`'ltr'` or `'rtl'`) for a locale
+Here's an example on how to detect the user's locale from the `accept-language` header in Next.js:
+```tsx title="utils/locale.ts"
+import {
+  getLocaleCodes,
+  getDir,
+  isValidLocale,
+} from '@workos-inc/widgets-i18n';
+import Negotiator from 'negotiator';
+import { headers } from 'next/headers';
+const DEFAULT_LOCALE = 'en-US';
+export async function getLocale(): Promise<string> {
+  const headersList = await headers();
+  const acceptLanguage = headersList.get('accept-language') ?? '';
+  const negotiator = new Negotiator({
+    headers: { 'accept-language': acceptLanguage },
+  });
+  const locale = negotiator.language(Array.from(getLocaleCodes()));
+  return isValidLocale(locale) ? locale : DEFAULT_LOCALE;
+}
+export function getLocaleDir(locale: string): 'ltr' | 'rtl' {
+  return getDir(locale);
+}
+```
+## RTL language support
+For right-to-left languages like Arabic and Hebrew, set the `dir` attribute on your HTML element. Use the `getDir()` function to determine the appropriate text direction:
+```tsx title="app/layout.tsx"
+import { getDir } from '@workos-inc/widgets-i18n';
+const direction = getDir(locale); // Returns 'ltr' or 'rtl'
+return (
+  <html dir={direction} lang={locale}>
+    {/* ... */}
+  </html>
+);
+```
+Widgets will automatically inherit their text direction based on the nearest ancestor's `dir` attribute.
+## Supported locales
+Widgets support the same locales as the AuthKit hosted UI. See the [AuthKit localization documentation](/authkit/hosted-ui/localization) for the full list of supported locale codes.

package/.docs/organized/docs/widgets/organization-switcher.mdx ADDED Viewed

@@ -0,0 +1,47 @@
+---
+title: Organization Switcher Widget
+description: A widget for switching between organizations in your application.
+originalPath: .tmp-workos-clone/packages/docs/content/widgets/organization-switcher.mdx
+---
+The `<OrganizationSwitcher />` widget allows users to switch between organizations. There are no special permissions required to use this widget as users can switch between organizations they have access to. If an organization requires SSO or MFA, the user will be redirected to reauthorize with the new organization.
+![Organization Switcher screenshot](https://images.workoscdn.com/images/e22cad7a-f11a-4f47-8cc7-fb015a22114f.png?auto=format&fit=clip&q=80)
+### Switching Organizations
+There are multiple ways to integrate with the Organization Switcher widget depending on your library choice. If you are using either the `authkit-js` or `authkit-react` libraries, you can use the `useAuth` hook to get the current organization and pass it to the widget.
+<CodeBlock>
+  <CodeBlockTab
+    language="js"
+    file="widget-organization-switcher-authkit-react"
+    title="React Library"
+  />
+</CodeBlock>
+If you are using one of the backend SDKs, you can build the organization switcher action in the backend and pass it in as a prop to the widget to be called when the user attempts to switch organizations. See the [Switching Organizations](/authkit/sessions/integrating-sessions/switching-organizations) guide for more information to set up the backend actions. This can then be passed in as a prop to the widget.
+<CodeBlock>
+  <CodeBlockTab
+    language="js"
+    file="widget-organization-switcher-backend"
+    title="Backend Handling"
+  />
+</CodeBlock>
+### Creating Organizations
+The widget accepts children components that can be used to either redirect the user to create an organization or to show a modal with a form to create an organization. You can use this to integrate with your existing organization creation flow that uses the WorkOS APIs to create organizations.
+<CodeBlock>
+  <CodeBlockTab
+    language="js"
+    file="widget-organization-switcher-create-authkit-react"
+    title="Create Organization"
+  />
+</CodeBlock>
+## API Reference
+<PropsTable data={widgets.organizationSwitcher.props} />

package/.docs/organized/docs/widgets/pipes.mdx ADDED Viewed

@@ -0,0 +1,27 @@
+---
+title: Pipes Widget
+description: A widget for displaying and managing connected accounts with Pipes.
+originalPath: .tmp-workos-clone/packages/docs/content/widgets/pipes.mdx
+---
+![Pipes widget screenshot](https://images.workoscdn.com/images/e84a33bb-0510-4d85-9041-33b1a0ce938c.png?auto=format&fit=clip&q=50)
+The `<Pipes />` widget allows users to manage their connections to third-party
+providers. Users can view the available providers, connect their
+accounts, reauthorize when needed, and disconnect
+their accounts.
+Read more in the [Pipes guide](/pipes).
+<CodeBlock>
+  <CodeBlockTab language="js" file="widget-pipes-token" title="Widget Token" />
+  <CodeBlockTab
+    language="js"
+    file="widget-pipes-authkit-react"
+    title="Access Token"
+  />
+</CodeBlock>
+## API Reference
+<PropsTable data={widgets.pipes.props} />

package/.docs/organized/docs/widgets/quick-start.mdx ADDED Viewed

@@ -0,0 +1,38 @@
+---
+title: Quick Start
+description: A step-by-step guide for setting up WorkOS Widgets in your application.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/widgets/quick-start.mdx
+---
+## Installation
+First, install the `@workos-inc/widgets` package from the npm registry, along with its peer dependencies:
+```bash title="Install packages"
+npm install @workos-inc/widgets @radix-ui/themes @tanstack/react-query
+```
+WorkOS Widgets uses [Radix Themes](https://www.radix-ui.com/themes) for its UI components and style customization APIs, while [TanStack Query](https://tanstack.com/query/latest) is used for data fetching and caching. Since both libraries are often used in applications, we require them as peer dependencies to avoid duplication, version conflicts, and bloated bundles.
+> Widgets can be used in any client- or server-rendered React application. See our [Widgets examples on GitHub](https://github.com/workos/widgets-examples) to see how they can be integrated in various frameworks.
+## Styles
+WorkOS Widgets are powered by Radix Themes, which provides beautiful default styles with zero configuration. Start by importing styles exported from both Radix Themes and WorkOS Widgets.
+<CodeBlock language="css" file="widgets-import-styles" title="CSS imports" />
+> Widgets can be customized using the `theme` prop or with plain CSS. See the [styling guide](/widgets/styling) for more details.
+## Root component
+The `WorkOsWidgets` component should be rendered at the top of your application. This component is responsible for managing context for data fetching and providing theme styles to all Widgets.
+<CodeBlock language="js" file="widgets-root-component" title="Root component" />
+## CORS configuration
+Because WorkOS widgets issue client-side requests to WorkOS, it is necessary to configure your site as an allowed web origin. Adding this in the [Authentication section of the dashboard](https://dashboard.workos.com/environment/authentication/sessions) will prevent CORS issues when using the widget.
+![CORS configuration](https://images.workoscdn.com/images/deb27664-e2e1-4c3b-afa1-e8ba2578c77c.png?auto=format&fit=clip&q=50)

package/.docs/organized/docs/widgets/styling/css-customization.mdx ADDED Viewed

@@ -0,0 +1,100 @@
+---
+title: CSS Customization
+description: Customize the look and feel of WorkOS Widgets using CSS.
+originalPath: .tmp-workos-clone/packages/docs/content/widgets/styling/css-customization.mdx
+---
+Widgets can be styled using plain CSS using namespaced class and data-attribute selectors.
+While optional, we recommend starting with the `layout.css` stylesheet from Radix Themes, as well as the `base.css` stylesheet from WorkOS Widgets. These styles provide a base level of functional styling without opinionated design choices.
+<CodeBlock
+  language="css"
+  file="widgets-import-base-styles"
+  title="CSS imports"
+/>
+## Universal selectors
+Elements in Widgets are accessible via CSS class selectors prefixed with `woswidgets-`.
+| Selector             | Description                                         |
+| :------------------- | :-------------------------------------------------- |
+| `.woswidgets-root`   | The root element for the Widgets provider           |
+| `.woswidgets-widget` | A selector used on the root element for all Widgets |
+## Element selectors
+### Avatar
+| Selector             | Description                 |
+| :------------------- | :-------------------------- |
+| `.woswidgets-avatar` | Targets all avatar elements |
+### Badge
+| Selector            | Description                |
+| :------------------ | :------------------------- |
+| `.woswidgets-badge` | Targets all badge elements |
+### Button
+| Selector                          | Description                 |
+| :-------------------------------- | :-------------------------- |
+| `.woswidgets-button`              | Targets all button elements |
+| `.woswidgets-button--primary`     | Targets primary buttons     |
+| `.woswidgets-button--secondary`   | Targets secondary buttons   |
+| `.woswidgets-button--destructive` | Targets destructive buttons |
+### Dialog
+| Selector                     | Description                              |
+| :--------------------------- | :--------------------------------------- |
+| `.woswidgets-dialog`         | Targets all dialog elements              |
+| `.woswidgets-dialog-overlay` | Targets the overlay for a dialog element |
+### Dropdown
+| Selector               | Description                   |
+| :--------------------- | :---------------------------- |
+| `.woswidgets-dropdown` | Targets all dropdown elements |
+### Icon Button
+| Selector                  | Description                      |
+| :------------------------ | :------------------------------- |
+| `.woswidgets-button`      | Targets all button elements      |
+| `.woswidgets-icon-button` | Targets all icon button elements |
+### Label
+| Selector            | Description                |
+| :------------------ | :------------------------- |
+| `.woswidgets-label` | Targets all label elements |
+### Menu Item
+| Selector                             | Description                    |
+| :----------------------------------- | :----------------------------- |
+| `.woswidgets-menu-item`              | Targets all menu item elements |
+| `.woswidgets-menu-item--destructive` | Targets destructive menu items |
+### Select
+| Selector                      | Description                                      |
+| :---------------------------- | :----------------------------------------------- |
+| `.woswidgets-select`          | Targets all select elements                      |
+| `.woswidgets-select-dropdown` | Targets dropdown elements belonging to a select  |
+| `.woswidgets-select-item`     | Targets menu item elements belonging to a select |
+### Skeleton
+| Selector               | Description                   |
+| :--------------------- | :---------------------------- |
+| `.woswidgets-skeleton` | Targets all skeleton elements |
+### Text Field
+| Selector                 | Description                     |
+| :----------------------- | :------------------------------ |
+| `.woswidgets-text-field` | Targets all text field elements |

package/.docs/organized/docs/widgets/styling/index.mdx ADDED Viewed

@@ -0,0 +1,29 @@
+---
+title: Styling
+description: Customize the look and feel of WorkOS Widgets.
+originalPath: .tmp-workos-clone/packages/docs/content/widgets/styling/index.mdx
+---
+WorkOS Widgets are powered by Radix Themes, which provides beautiful default styles with zero configuration. The fastest way to style your Widgets is with the [`theme` prop](/widgets/styling/theme-customization).
+This prop is provided to the `WorkOsWidgets` component rendered at the top of your application. All Widgets will inherit styles configured in the `theme` prop.
+<CodeBlock
+  title="Theme customization"
+  file="widgets-theme-customization"
+  language="js"
+/>
+See the [theme customization guide](/widgets/styling/theme-customization) for more details on `theme` prop.
+## Using CSS
+If you choose not to use the theming capabilities in Radix Themes, you can style Widgets using CSS. Individual elements in Widgets are accessible via CSS class selectors prefixed with `woswidgets-`. For example, you can add your own button styles by selecting the `woswidgets-button` class.
+<CodeBlock
+  title="CSS customization"
+  file="widgets-css-customization"
+  language="css"
+/>
+See the [CSS customization guide](/widgets/styling/css-customization) for more details on styling Widgets with CSS.

package/.docs/organized/docs/widgets/styling/theme-customization.mdx ADDED Viewed

@@ -0,0 +1,51 @@
+---
+title: Theme Customization
+description: Customize the look and feel of WorkOS Widgets using Radix Themes.
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/widgets/styling/theme-customization.mdx
+---
+## Using the `theme` prop
+The `theme` prop can be used to customize the overall appearance of WorkOS Widgets.
+`theme` support relies on external stylesheets from Radix Themes and WorkOS Widgets. Start by importing both stylesheets into your application.
+<CodeBlock language="css" file="widgets-import-styles" title="CSS imports" />
+### `theme` properties
+<PropsTable data={widgets.theme.props} />
+See the [Radix Themes API reference](https://www.radix-ui.com/themes/docs/components/theme#api-reference) for more information on theming options.
+## Using the `elements` prop
+Underlying components can be styled using the `elements` prop. This object is a mapping of component names to their respective Radix Theme component props.
+<CodeBlock
+  language="js"
+  file="widgets-elements-customization"
+  title="Elements customization"
+/>
+### `elements` properties
+Each element is mapped to a Radix Theme component and accepts the same props as its respective component. See the Radix Themes documentation for each component for all available props.
+| Component             | Radix component                                                             |
+| :-------------------- | :-------------------------------------------------------------------------- |
+| `avatar`              | [`Avatar`](https://www.radix-ui.com/themes/docs/components/avatar)          |
+| `badge`               | [`Badge`](https://www.radix-ui.com/themes/docs/components/badge)            |
+| `primaryButton`       | [`Button`](https://www.radix-ui.com/themes/docs/components/button)          |
+| `secondaryButton`     | [`Button`](https://www.radix-ui.com/themes/docs/components/button)          |
+| `destructiveButton`   | [`Button`](https://www.radix-ui.com/themes/docs/components/button)          |
+| `dialog`              | [`Dialog`](https://www.radix-ui.com/themes/docs/components/dialog)          |
+| `dropdown`            | [`Dropdown`](https://www.radix-ui.com/themes/docs/components/dropdown)      |
+| `iconButton`          | [`IconButton`](https://www.radix-ui.com/themes/docs/components/icon-button) |
+| `label`               | [`Label`](https://www.radix-ui.com/themes/docs/components/label)            |
+| `primaryMenuItem`     | [`MenuItem`](https://www.radix-ui.com/themes/docs/components/menu-item)     |
+| `destructiveMenuItem` | [`MenuItem`](https://www.radix-ui.com/themes/docs/components/menu-item)     |
+| `select`              | [`Select`](https://www.radix-ui.com/themes/docs/components/select)          |
+| `skeleton`            | [`Skeleton`](https://www.radix-ui.com/themes/docs/components/skeleton)      |
+| `textfield`           | [`TextField`](https://www.radix-ui.com/themes/docs/components/text-field)   |

package/.docs/organized/docs/widgets/tokens.mdx ADDED Viewed

@@ -0,0 +1,17 @@
+---
+title: Authorization Tokens
+description: Ensure Widgets have the appropriate permissions in your application.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/widgets/tokens.mdx
+---
+Widgets must be supplied with an authorization token. The token can be acquired in one of two ways:
+- If you are using the `authkit-js` or `authkit-react` libraries, you can use the provided access token.
+- If you use one of our backend SDKs, use the "get token" method in the SDK to request a token with the appropriate scope for the widget you want to use. Widget tokens expire after one hour.
+<CodeBlock file="widgets-get-token" />
+> New WorkOS accounts are created with an "Admin" role that has all Widget permissions assigned. Existing accounts will need to assign the proper permissions to a role. This can be done on the "Roles" page of the WorkOS Dashboard. See the [Roles and Permissions guide](/authkit/roles-and-permissions) for more information.
+To successfully generate a token, the user must be assigned a role with the correct permissions for the widget.

package/.docs/organized/docs/widgets/user-management.mdx ADDED Viewed

@@ -0,0 +1,28 @@
+---
+title: User Management Widget
+description: A widget for displaying and managing users in your application.
+originalPath: .tmp-workos-clone/packages/docs/content/widgets/user-management.mdx
+---
+![Users Management screenshot](https://images.workoscdn.com/images/20f235c5-c888-48f5-90aa-87ec9189483a.png?auto=format&fit=clip&q=50)
+The `<UsersManagement />` widget allows an organization admin to manage the members in an organization. Admins can invite new users, remove users, and change roles all within the widget.
+In order to use the User Management widget, a user must have a role that has the `widgets:users-table:manage` permission.
+<CodeBlock>
+  <CodeBlockTab
+    language="js"
+    file="widget-usersmanagement-token"
+    title="Widget Token"
+  />
+  <CodeBlockTab
+    language="js"
+    file="widget-usersmanagement-authkit-react"
+    title="Access Token"
+  />
+</CodeBlock>
+## API Reference
+<PropsTable data={widgets.userManagement.props} />

package/.docs/organized/docs/widgets/user-profile.mdx ADDED Viewed

@@ -0,0 +1,30 @@
+---
+title: User Profile Widget
+description: A widget for displaying and managing a user’s profile in your application.
+originalPath: .tmp-workos-clone/packages/docs/content/widgets/user-profile.mdx
+---
+![User Profile Widget screenshot](https://images.workoscdn.com/images/790e97bb-0875-4ca7-8ff4-c01dafce77f4.png?auto=format&fit=clip&q=50)
+The `<UserProfile />` widget allows users to view and manage their personal information.
+Users can see their profile details and edit their display name.
+This widget provides a simple, user-friendly interface for basic profile management.
+No special permissions are required to use this widget.
+<CodeBlock>
+  <CodeBlockTab
+    language="js"
+    file="widget-userprofile-token"
+    title="Widget Token"
+  />
+  <CodeBlockTab
+    language="js"
+    file="widget-userprofile-authkit-react"
+    title="Access Token"
+  />
+</CodeBlock>
+## API Reference
+<PropsTable data={widgets.userProfile.props} />

package/.docs/organized/docs/widgets/user-security.mdx ADDED Viewed

@@ -0,0 +1,31 @@
+---
+title: User Security Widget
+description: A widget for controlling user security settings in your application.
+originalPath: .tmp-workos-clone/packages/docs/content/widgets/user-security.mdx
+---
+![User Security Widget screenshot](https://images.workoscdn.com/images/91c883ca-c3e5-474f-b93f-c2e1d0517380.png?auto=format&fit=clip&q=50)
+The `<UserSecurity />` widget enables users to control their security settings. With this widget, users can:
+- Set or change their password
+- Configure and reset Multi-Factor Authentication
+No special permissions are required to use this widget.
+<CodeBlock>
+  <CodeBlockTab
+    language="js"
+    file="widget-usersecurity-token"
+    title="Widget Token"
+  />
+  <CodeBlockTab
+    language="js"
+    file="widget-usersecurity-authkit-react"
+    title="Access Token"
+  />
+</CodeBlock>
+## API Reference
+<PropsTable data={widgets.userSecurity.props} />

package/.docs/organized/docs/widgets/user-sessions.mdx ADDED Viewed

@@ -0,0 +1,26 @@
+---
+title: User Sessions Widget
+description: A widget for displaying and managing user sessions in your application.
+originalPath: .tmp-workos-clone/packages/docs/content/widgets/user-sessions.mdx
+---
+![User Sessions Widget screenshot](https://images.workoscdn.com/images/c4ff10a8-e0a3-4c9d-b0a7-56bbf93f6862.png?auto=format&fit=clip&q=50)
+The `<UserSessions />` widget provides users with visibility into their active sessions across different devices and browsers. Users can view session details and sign out of individual sessions as needed. No special permissions are required to use this widget.
+<CodeBlock>
+  <CodeBlockTab
+    language="js"
+    file="widget-usersessions-token"
+    title="Widget Token"
+  />
+  <CodeBlockTab
+    language="js"
+    file="widget-usersessions-authkit-react"
+    title="Access Token"
+  />
+</CodeBlock>
+## API Reference
+<PropsTable data={widgets.userSessions.props} />

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025 WorkOS
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -30,12 +30,25 @@ Add to your MCP configuration:
   "mcpServers": {
     "workos": {
       "command": "npx",
-      "args": ["@workos/mcp-docs-server"]
+      "args": ["-y", "@workos/mcp-docs-server"]
     }
   }
 }
 ```
+### In Claude Code
+Use the Claude Code CLI to add the MCP server:
+```bash
+claude mcp add-json workos --scope user '
+    {
+      "command": "npx",
+      "args": ["@workos/mcp-docs-server"]
+    }
+'
+```
 ### Programmatic Usage
 ```typescript

package/dist/prepare.js CHANGED Viewed

@@ -11,7 +11,7 @@ var DOCS_OUTPUT_DIR = ".docs/organized";
 var DOCS_DIR = path.join(DOCS_OUTPUT_DIR, "docs");
 var EXAMPLES_DIR = path.join(DOCS_OUTPUT_DIR, "examples");
 var CHANGELOGS_DIR = path.join(DOCS_OUTPUT_DIR, "changelogs");
-var WORKOS_REPO_URL = "git@github.com:workos/workos.git";
+var WORKOS_REPO_URL = process.env.GITHUB_TOKEN ? `https://${process.env.GITHUB_TOKEN}@github.com/workos/workos.git` : "git@github.com:workos/workos.git";
 var TEMP_CLONE_DIR = ".tmp-workos-clone";
 async function ensureDir(dir) {
   try {