# @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": ["-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
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