@workos/mcp-docs-server 0.1.0

package/.docs/organized/docs/vault/index.mdx

@@ -0,0 +1,38 @@
+---
+title: Vault
+description: 'Encrypt, store, and control access to sensitive data.'
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/vault/index.mdx
+---
+
+# Introduction
+
+WorkOS Vault is a developer-friendly EKM to encrypt and optionally store data including tokens, passwords, certificates, files, and any other customer content. Ideal for scaling encryption in cloud applications, it minimizes key exposure and simplifies compliance.
+
+## Key features
+
+### Encrypted Key-Value Storage
+
+Each secret stored with Vault uses a unique encryption key and is cryptographically isolated based on user-provided context. Envelope encryption enhances security by encrypting data with a data encryption key (DEK), which is then encrypted with a key encryption key (KEK). This approach ensures sensitive data remains protected while allowing secure key management and access control.
+
+### Enterprise Key Management (EKM)
+
+The Enterprise Key Management features of Vault centralize control over encryption keys used for customer data in multi-tenant architectures. It streamlines key lifecycle management, access policies, and auditability while integrating seamlessly with your existing applications. Key segmentation by organization, user, or any provided context ensures cryptographic keys are isolated, reducing risk and enforcing access control at boundaries that make sense for your business.
+
+### Bring-Your-Own-Key (BYOK)
+
+With Vault you can provide keys either from your own environment or directly linked to your customers' cloud environments. BYOK gives you full control over encryption keys while integrating seamlessly with your own security tooling such as cloud SIEMs. It ensures your keys stay protected in your custody while enabling secure access for encryption operations, perfect for compliance-driven workloads. BYOK integration is available for many popular key management services, including Amazon Web Service KMS, Google Cloud Compute KMS, Azure Key Vault, and HashiCorp Vault.
+
+## Common Use Cases
+
+### Organizational secrets
+
+Sensitive data in a B2B application is often linked to specific organization. This can be shared secrets, API keys, OAuth credentials, or even data generated by your application. Vault protects this information and easily links each secret with the organization it belongs to in order to provide full cryptographic separation from other organizations within your application.
+
+### User secrets
+
+User data such as Personally Identifiable Information (PII) or Protected Health Information (PHI) is highly sensitive and can have strict regulatory requirements including strong encryption, access controls, and data minimization. The risk for mishandling this data is very high - both financially and reputationally. Vault lets you store this data using unique encryption keys without needing to manage the complex lifecycle of key hierarchies.
+
+### Application secrets
+
+With short-lived dynamic workloads in the cloud, static credentials represent a huge security risk. Secrets can get spread out across many services, making rotation difficult and the change of a leak high. Vault can encrypt and store application data such as API keys, database credentials, and PKI certificates in a centralized service and provide them to your application at runtime.

package/.docs/organized/docs/vault/key-context.mdx

@@ -0,0 +1,32 @@
+---
+title: Key Context
+description: User-managed cardinality for keys within Vault.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/vault/key-context.mdx
+---
+
+When encrypting data with Vault, a set of key-value metadata pairs called the key context is required. This determines which key or keys will be used to encrypt the data without needing to explicitly list IDs for the keys. The key context is used both when [creating an encrypted object](/reference/vault/object/create) and when [encrypting locally](/reference/vault/key/encrypt-data) with Vault-managed keys.
+
+## Key matching
+
+Each item in the context is used to identify a long-lived key within the WorkOS environment called a key-encrypting key (KEK). The key material lives in a Hardware Security Module (HSM) and cannot be exported to plaintext - it can only be used to generate or decrypt data keys.
+KEKs are created just-in-time and don't require any configuration in advance.
+
+### Bring Your Own Key (BYOK)
+
+When Vault is used with a BYOK setup, the customer-managed key (CMK) is used in place of the WorkOS managed KEK. Matching the encryption operation to the CMK is still done based on the key context.
+
+For example, if Vault is configured to use a CMK called `key_abc` for all data of `organization_abc123`, then that key would automatically be used when the key context is set to `{"organization_id": "organization_abc123"}`. The same operation with a context of `{"organization_id": "organization_xzy987"}` would instead use a WorkOS managed KEK.
+
+## Data keys
+
+Although the KEKs identified by key context are long-lived, they aren't directly used for encrypting data. A random data-encrypting key (DEK) is generated for an encryption operation. The DEK is then encrypted using each KEK from the key context, resulting in a single plaintext key and one or more encrypted keys. The encrypted keys are then stored with the encrypted data for future decryption. This ensures that the data and keys have the same durability while keeping the keys safe. It also means that even if one key is exposed, not all of the data will be at risk since many different data keys are used for the same key context.
+
+## Limitations
+
+The following limitations are enforced by the Vault API for the key context object:
+
+- All values in the context must be strings.
+- A maximum of 10 items can be present in a single context.
+- Each context name has a maximum length of 120 characters.
+- Each context value has a maximum length of 500 characters.

package/.docs/organized/docs/vault/quick-start.mdx

@@ -0,0 +1,82 @@
+---
+title: Quick Start
+description: A step-by-step guide on how to start using Vault to manage encrypted objects.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/vault/quick-start.mdx
+---
+
+## Before getting started
+
+To get the most out of these guides, you’ll need:
+
+- A [WorkOS account](https://dashboard.workos.com/)
+
+Sign in to your WorkOS Dashboard account and create a new Organization.
+
+![WorkOS Dashboard UI showing organization creation](https://images.workoscdn.com/images/1c69fd98-01be-491d-9255-58363bc6a983.png?auto=format&fit=clip&q=50)
+
+## What you'll build
+
+In this guide, we will walk you through what you will need to set up Vault for securing and isolating organization-specific data:
+
+- Encrypt and store data linked to an organization
+- Retrieve the encrypted data
+- Delete an object that's no longer in use
+
+## API object definitions
+
+[Object](/reference/vault/object)
+: Represents an encrypted key-value item stored by Vault.
+
+[Organization](/reference/organization)
+: Describes an organization whose users sign in with a SSO Connection, or whose users are synced with a Directory Sync Connection.
+
+## Add Vault to your app
+
+### Install the WorkOS SDK
+
+WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.
+
+<LanguageSelector languages={['js', 'go']}>
+  Install the SDK using the command below.
+
+  <CodeBlock title="Install the WorkOS SDK" file="install-sdk">
+    <CodeBlockTab language="js" file="install-sdk-npm" title="npm" />
+    <CodeBlockTab language="js" file="install-sdk-yarn" title="Yarn" />
+  </CodeBlock>
+</LanguageSelector>
+
+### Set objects
+
+To make calls to WorkOS, provide the API key and, in some cases, the client ID. Store these values as managed secrets, such as `WORKOS_API_KEY` and `WORKOS_CLIENT_ID`, and pass them to the SDKs either as environment variables or directly in your app's configuration based on your preferences.
+
+```plain title="Environment variables"
+WORKOS_API_KEY='sk_example_123456789'
+WORKOS_CLIENT_ID='client_123456789'
+```
+
+> The code examples use your staging API keys when [signed in](https://dashboard.workos.com)
+
+### Create an object
+
+The Vault API and SDKs provide a method to encrypt and store a blob of data linked to a WorkOS organization. The encryption key used will be both unique to the KV item and cryptographically isolated from all other organizations.
+
+<CodeBlock title="Create an object" file="create-object" />
+
+### Update the value of the object
+
+Once created, the key context for an object cannot be changed. Only the value can be updated. The expected version of the object can be provided as a consistency lock when writing to the object.
+
+<CodeBlock title="Update the object" file="update-object" />
+
+### Retrieve the object value
+
+Objects can be listed, returning just the names of the objects. The metadata for each object can be queried - this provides more information about it without needing to decrypt the actual value. Fetching the object value will return the same metadata in addition to the unencrypted value.
+
+<CodeBlock title="Retrieve the object" file="retrieve-object" />
+
+### Delete the object
+
+When an object is no longer needed it can be marked for deletion. This will make the object unavailable to API operations, but the data will not be immediately deleted.
+
+<CodeBlock title="Delete the object" file="delete-object" />

package/README.md

@@ -0,0 +1,252 @@
+# @workos/mcp-docs-server
+
+An MCP server that provides documentation, code examples, and changelogs for WorkOS SDKs and developer tooling.
+
+## Overview
+
+This MCP server provides four main tools:
+
+- **Documentation**: Access WorkOS SDK documentation
+- **Examples**: Browse code examples and implementations
+- **Changelogs**: View package changelogs and version history (includes RSS feed parsing)
+- **Search**: Search all documentation for keywords or phrases (NEW)
+
+The server works both inside the WorkOS monorepo (using local content) and externally (with fallback to hosted content). Changelog data is sourced from both traditional CHANGELOG.md files and the live WorkOS changelog RSS feed.
+
+## Installation
+
+```bash
+npm install @workos/mcp-docs-server
+```
+
+## Usage
+
+### In Cursor/Windsurf
+
+Add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "workos": {
+      "command": "npx",
+      "args": ["@workos/mcp-docs-server"]
+    }
+  }
+}
+```
+
+### Programmatic Usage
+
+```typescript
+import { getTools } from '@workos/mcp-docs-server/get-tools';
+
+const tools = await getTools();
+console.log(tools);
+```
+
+## Development
+
+### Setup
+
+```bash
+npm install
+npm run build
+```
+
+### Prepare Content
+
+#### Production Build (default - using latest WorkOS docs)
+
+```bash
+npm run build
+```
+
+This will:
+
+1. Build the TypeScript code
+2. Clone the latest WorkOS monorepo from GitHub
+3. Extract documentation from `packages/docs/content/`
+4. Extract examples and changelogs from the monorepo
+5. Fetch and parse the latest changelog entries from the WorkOS RSS feed
+6. Clean up the temporary clone
+
+You can also run just the content preparation (pulls latest docs by default):
+
+```bash
+npm run prepare-content
+```
+
+#### Local Development (using local content)
+
+For development when you want to use local content instead of cloning:
+
+```bash
+npm run build:dev
+```
+
+Or just prepare local content:
+
+```bash
+npm run prepare-content:local
+```
+
+This will organize content from local directories:
+
+- Documentation from `docs/` into `.docs/organized/docs/`
+- Code examples from `examples/` into `.docs/organized/examples/`
+- Changelogs from `packages/*/CHANGELOG.md` into `.docs/organized/changelogs/`
+- **Note**: RSS changelog parsing is skipped in local mode
+
+**Note**: The default behavior requires access to the private WorkOS GitHub repository. Use the `:local` variants for development without repo access.
+
+You can access the locally built MCP server by adding the build to your `mcp.json`.
+
+```json
+{
+  "mcpServers": {
+    "workos": {
+      "command": "node",
+      "args": ["/path/to/dist/index.js"]
+    }
+  }
+}
+```
+
+## Publishing
+
+For maintainers who need to build and publish new versions, see the [Operator Guide](./OPERATOR.md) for detailed instructions on:
+
+- Prerequisites and required access
+- Build process and expected output
+- Publishing to npm
+- Troubleshooting common issues
+
+### Available Tools
+
+The MCP server provides a progressive discovery experience. Each tool supports browsing available content before accessing specific items.
+
+#### `workos_search` (Recommended First Step)
+
+Search all WorkOS documentation for keywords, phrases, error messages, or method names. This is the fastest way to find relevant documentation if you don't know the exact path or structure.
+
+**Parameters:**
+
+- `query` (string, required): The search term(s) to look for
+- `maxResults` (number, optional): Maximum number of results to return (default: 10)
+
+**Example Usage:**
+
+```
+// Find docs mentioning SAML errors
+query: "invalid SAML response"
+
+// Find docs about webhooks
+query: "webhook"
+
+// Find docs about a method
+query: "createConnection"
+```
+
+**How it works:**
+
+- Uses pure Node.js (no grep/execSync) to search all documentation files
+- Returns snippets with line numbers and context
+- Shows the document path for each match so you can use `workos_docs` to read the full content
+
+#### `workos_docs`
+
+Get WorkOS SDK documentation content by path. Use this when you know the documentation structure or want to browse hierarchically. If you don't know the exact path, use `workos_search` first to find relevant documents.
+
+**Parameters:**
+
+- `path` (string, required): Documentation path to retrieve. Use forward slashes to navigate folders. Examples: "sso/overview", "directory-sync/introduction", "user-management/authentication". Omit file extensions (.md, .mdx).
+
+**Example Usage:**
+
+```
+// Read a specific document
+path: "sso/overview"
+```
+
+> **Note:** Zero-parameter discovery (listing all categories or directory contents) is not yet implemented. Use `workos_search` to find relevant paths.
+
+#### `workos_examples`
+
+Get WorkOS SDK code examples. Use this after checking documentation to find practical implementation examples.
+
+**Parameters:**
+
+- `example` (string, required): Example name or group to retrieve. Common groups: "sso", "directory-sync", "user-management", "audit-logs", "webhooks".
+
+**Example Usage:**
+
+```
+// Get all examples in the SSO group
+example: "sso"
+```
+
+#### `workos_changelogs`
+
+Get WorkOS package changelogs to check version history, breaking changes, and new features. Useful for migration guides and understanding API evolution.
+
+**Parameters:**
+
+- `package` (string, required): Package name to get changelog for. Use "workos-platform" for general platform updates from the RSS feed, or specific packages like "@workos/node", "@workos/python", "@workos/ruby", "@workos/go", "@workos/php".
+
+**Example Usage:**
+
+```
+// Get general platform changelog (from RSS feed)
+package: "workos-platform"
+
+// Get changelog for workos-node SDK
+package: "@workos/node"
+```
+
+**Data Sources:**
+
+- **RSS Feed**: The `workos-platform` package provides the latest platform updates, feature announcements, and product changes sourced from https://workos.com/changelog/rss.xml
+- **Markdown Files**: SDK-specific packages provide traditional changelog data from CHANGELOG.md files in the monorepo
+
+### User Experience Design
+
+This MCP server follows a **progressive discovery** pattern aligned with MCP best practices:
+
+1. **Search-first workflow**: Use `workos_search` to find relevant documentation paths
+2. **Direct access**: Use `workos_docs`, `workos_examples`, or `workos_changelogs` with the discovered path or name
+3. **Clear navigation hints**: Each result includes hints for further exploration
+4. **Graceful fallbacks**: When content isn't found, the server suggests similar options
+
+This design allows AI assistants to efficiently explore available content without prior knowledge of the structure, making it easier to find relevant documentation, examples, or changelogs.
+
+## Architecture
+
+### File Structure
+
+```
+workos-docs-server/
+├── src/
+│   ├── index.ts          # MCP server entry point
+│   ├── get-tools.ts      # Tool configuration
+│   ├── prepare.ts        # Content preparation script
+│   └── types.ts          # Type definitions
+├── .docs/
+│   └── organized/        # Processed content (generated)
+│       ├── docs/
+│       ├── examples/
+│       └── changelogs/
+├── package.json
+├── tsup.config.ts
+└── README.md
+```
+
+### Runtime Behavior
+
+1. **prepare.ts** (build step): Walks the monorepo and normalizes content into `.docs/organized/`
+2. **get-tools.ts**: Checks for local organized content, falls back to remote URLs if missing
+3. **index.ts**: Provides MCP-compliant server that serves the tools
+
+## License
+
+MIT

package/dist/chunk-64GKEK6G.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+// src/get-tools.ts
+import { promises as fs } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+var DOCS_OUTPUT_DIR = ".docs/organized";
+var REMOTE_BASE_URL = "https://static.workos.dev";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
+var SERVER_ROOT = path.resolve(__dirname, "..");
+async function pathExists(path2) {
+  try {
+    await fs.access(path2);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function getTools() {
+  const docsPath = path.join(SERVER_ROOT, DOCS_OUTPUT_DIR, "docs");
+  const examplesPath = path.join(SERVER_ROOT, DOCS_OUTPUT_DIR, "examples");
+  const changelogsPath = path.join(SERVER_ROOT, DOCS_OUTPUT_DIR, "changelogs");
+  const hasLocalDocs = await pathExists(docsPath);
+  const hasLocalExamples = await pathExists(examplesPath);
+  const hasLocalChangelogs = await pathExists(changelogsPath);
+  return {
+    docs: {
+      type: "DocumentationTool",
+      name: "WorkOS SDK Docs",
+      instructions: "Use these to answer developer questions about integrating WorkOS.",
+      docsPath: hasLocalDocs ? docsPath : `${REMOTE_BASE_URL}/docs/index.md`
+    },
+    examples: {
+      type: "ExamplesTool",
+      examplesPath: hasLocalExamples ? examplesPath : `${REMOTE_BASE_URL}/examples`
+    },
+    changelogs: {
+      type: "ChangeLogTool",
+      changelogsPath: hasLocalChangelogs ? changelogsPath : `${REMOTE_BASE_URL}/changelogs`
+    }
+  };
+}
+
+export {
+  getTools
+};
+//# sourceMappingURL=chunk-64GKEK6G.js.map

package/dist/chunk-64GKEK6G.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/get-tools.ts"],"sourcesContent":["import { promises as fs } from 'fs';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\nimport type { WorkOSTools } from './types.js';\n\nconst DOCS_OUTPUT_DIR = '.docs/organized';\nconst REMOTE_BASE_URL = 'https://static.workos.dev';\n\n// Get the directory where this module is located (the MCP server directory)\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\nconst SERVER_ROOT = path.resolve(__dirname, '..');\n\nasync function pathExists(path: string): Promise<boolean> {\n  try {\n    await fs.access(path);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nexport async function getTools(): Promise<WorkOSTools> {\n  const docsPath = path.join(SERVER_ROOT, DOCS_OUTPUT_DIR, 'docs');\n  const examplesPath = path.join(SERVER_ROOT, DOCS_OUTPUT_DIR, 'examples');\n  const changelogsPath = path.join(SERVER_ROOT, DOCS_OUTPUT_DIR, 'changelogs');\n\n  // Check if organized docs exist locally\n  const hasLocalDocs = await pathExists(docsPath);\n  const hasLocalExamples = await pathExists(examplesPath);\n  const hasLocalChangelogs = await pathExists(changelogsPath);\n\n  return {\n    docs: {\n      type: 'DocumentationTool',\n      name: 'WorkOS SDK Docs',\n      instructions: 'Use these to answer developer questions about integrating WorkOS.',\n      docsPath: hasLocalDocs ? docsPath : `${REMOTE_BASE_URL}/docs/index.md`,\n    },\n    examples: {\n      type: 'ExamplesTool',\n      examplesPath: hasLocalExamples ? examplesPath : `${REMOTE_BASE_URL}/examples`,\n    },\n    changelogs: {\n      type: 'ChangeLogTool',\n      changelogsPath: hasLocalChangelogs ? changelogsPath : `${REMOTE_BASE_URL}/changelogs`,\n    },\n  };\n}\n"],"mappings":";;;AAAA,SAAS,YAAY,UAAU;AAC/B,OAAO,UAAU;AACjB,SAAS,qBAAqB;AAG9B,IAAM,kBAAkB;AACxB,IAAM,kBAAkB;AAGxB,IAAM,aAAa,cAAc,YAAY,GAAG;AAChD,IAAM,YAAY,KAAK,QAAQ,UAAU;AACzC,IAAM,cAAc,KAAK,QAAQ,WAAW,IAAI;AAEhD,eAAe,WAAWA,OAAgC;AACxD,MAAI;AACF,UAAM,GAAG,OAAOA,KAAI;AACpB,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,eAAsB,WAAiC;AACrD,QAAM,WAAW,KAAK,KAAK,aAAa,iBAAiB,MAAM;AAC/D,QAAM,eAAe,KAAK,KAAK,aAAa,iBAAiB,UAAU;AACvE,QAAM,iBAAiB,KAAK,KAAK,aAAa,iBAAiB,YAAY;AAG3E,QAAM,eAAe,MAAM,WAAW,QAAQ;AAC9C,QAAM,mBAAmB,MAAM,WAAW,YAAY;AACtD,QAAM,qBAAqB,MAAM,WAAW,cAAc;AAE1D,SAAO;AAAA,IACL,MAAM;AAAA,MACJ,MAAM;AAAA,MACN,MAAM;AAAA,MACN,cAAc;AAAA,MACd,UAAU,eAAe,WAAW,GAAG,eAAe;AAAA,IACxD;AAAA,IACA,UAAU;AAAA,MACR,MAAM;AAAA,MACN,cAAc,mBAAmB,eAAe,GAAG,eAAe;AAAA,IACpE;AAAA,IACA,YAAY;AAAA,MACV,MAAM;AAAA,MACN,gBAAgB,qBAAqB,iBAAiB,GAAG,eAAe;AAAA,IAC1E;AAAA,EACF;AACF;","names":["path"]}

package/dist/get-tools.d.ts

@@ -0,0 +1,23 @@
+interface DocsTool {
+    type: 'DocumentationTool';
+    name: string;
+    instructions: string;
+    docsPath: string;
+}
+interface ExamplesTool {
+    type: 'ExamplesTool';
+    examplesPath: string;
+}
+interface ChangelogsTool {
+    type: 'ChangeLogTool';
+    changelogsPath: string;
+}
+interface WorkOSTools {
+    docs: DocsTool;
+    examples: ExamplesTool;
+    changelogs: ChangelogsTool;
+}
+
+declare function getTools(): Promise<WorkOSTools>;
+
+export { getTools };

package/dist/get-tools.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import {
+  getTools
+} from "./chunk-64GKEK6G.js";
+export {
+  getTools
+};
+//# sourceMappingURL=get-tools.js.map

package/dist/get-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { getTools } from './get-tools.js';