### OAuth2 Provider Setup Examples

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/infrastructure/authentication.md

Examples of how to configure the Docs MCP Server with different OAuth2 providers using CLI flags.

```APIDOC
## OAuth2 Provider Setup Examples

### Auth0
```bash
npx docs-mcp-server \
  --auth-enabled \
  --auth-issuer-url "https://your-tenant.auth0.com" \
  --auth-audience "https://mcp.your-domain.com"
```

### Clerk
```bash
npx docs-mcp-server \
  --auth-enabled \
  --auth-issuer-url "https://your-app.clerk.accounts.dev" \
  --auth-audience "https://mcp.your-domain.com"
```

### Keycloak
```bash
npx docs-mcp-server \
  --auth-enabled \
  --auth-issuer-url "https://keycloak.your-domain.com/auth/realms/your-realm" \
  --auth-audience "https://mcp.your-domain.com"
```

### Azure AD
```bash
npx docs-mcp-server \
  --auth-enabled \
  --auth-issuer-url "https://login.microsoftonline.com/your-tenant-id/v2.0" \
  --auth-audience "https://mcp.your-domain.com"
```
```

--------------------------------

### Install Dependencies

Source: https://github.com/arabold/docs-mcp-server/blob/main/CONTRIBUTING.md

Installs all necessary project dependencies. Run this after cloning the repository or switching Node.js versions.

```bash
npm install
```

--------------------------------

### Install MCP Server via Smithery CLI

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/guides/mcp-clients.md

Install the docs-mcp-server client using the Smithery CLI. Replace <CLIENT_NAME> with your specific client identifier.

```bash
npx -y @smithery/cli@latest install @arabold/docs-mcp-server --client <CLIENT_NAME>
```

--------------------------------

### Benchmark Output Example

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/guides/benchmarking.md

This is an example of the output generated by a benchmark run, showing various metrics and breakdowns.

```text
=== docs-mcp-server search benchmark ===
judge=openai:gpt-5.4-mini  embedding=...  top_k=5  dataset=...

─ Headline IR metrics (deterministic) ─
MRR         0.612  (baseline 0.605, +1.2% ▲)
Recall@5    0.844  (baseline 0.851, -0.8% ·)
nDCG@5      0.701  (baseline 0.704, -0.4% ·)
Hit@3       0.917  (baseline 0.900, +1.9% ▲)

─ Per-intent breakdown ─
api-lookup       n=19  MRR=0.78 R@5=0.91 nDCG@5=0.82 Hit@3=0.95
conceptual       n=15  MRR=0.55 R@5=0.78 nDCG@5=0.62 Hit@3=0.87
comparison       n=12  MRR=0.41 R@5=0.71 nDCG@5=0.55 Hit@3=0.83
troubleshooting  n=14  MRR=0.59 R@5=0.85 nDCG@5=0.70 Hit@3=0.93

─ Structural checks (deterministic, pass rate) ─
code_block_balance: 96.7%
non_empty_content:  100.0%
url_presence:       100.0%

─ LLM-judged (observational, not gating) ─
chunk_coherence        mean=3.85  n=60
content_faithfulness   mean=4.12  n=60
answerability          mean=3.40  n=60

✅ No regressions. 2 improved, 7 stable.
```

--------------------------------

### Default Configuration File Example

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/setup/configuration.md

This is an example of the default `config.yaml` file. It shows various settings for the app, scraper, and splitter modules. The server automatically updates this file with new defaults on startup.

```yaml
app:
  storePath: ~/.docs-mcp-server
  telemetryEnabled: true
  embeddingModel: text-embedding-3-small

scraper:
  maxPages: 1000
  maxDepth: 3
  preserveHashes: false
  document:
    maxSize: 10485760  # 10MB
  security:
    network:
      mode: open
      allowPrivateNetworks: false
      allowedHosts: []
      allowedCidrs: []
      allowInvalidTls: false
    fileAccess:
      mode: allowedRoots
      allowedRoots:
        - $DOCUMENTS
      followSymlinks: false
      includeHidden: false

splitter:
  preferredChunkSize: 1500
  maxChunkSize: 5000

```

--------------------------------

### Start Docs MCP Server Without Authentication

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/infrastructure/authentication.md

Use this command to start the server for local development when authentication is not required.

```bash
# Start server without authentication
npx docs-mcp-server --port 6280
```

--------------------------------

### Start MCP Server

Source: https://github.com/arabold/docs-mcp-server/blob/main/README.md

Launch the Docs MCP Server to provide a long-running MCP endpoint for AI clients.

```bash
npx @arabold/docs-mcp-server@latest
```

--------------------------------

### Install Dependencies from Lockfile

Source: https://github.com/arabold/docs-mcp-server/blob/main/AGENTS.md

Installs dependencies precisely as defined in the package-lock.json or npm-shrinkwrap.json. Use this for CI/CD or when ensuring exact reproducible builds.

```bash
npm ci
```

--------------------------------

### CLI Usage: Query Index

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/setup/installation.md

Use the CLI to search the indexed documentation. This example queries for 'useEffect cleanup' and outputs the results in YAML format.

```bash
# Query the index
npx @arabold/docs-mcp-server@latest search react "useEffect cleanup" --output yaml
```

--------------------------------

### CLI Commands for Configuration Management

Source: https://github.com/arabold/docs-mcp-server/blob/main/openspec/changes/archive/2026-03-16-refactor-config-system/design.md

Illustrates the structure of new CLI commands for interacting with the configuration system. Use `get` to retrieve a value and `set` to modify and persist it.

```bash
docs-mcp-server config                  # Print full config (existing)
docs-mcp-server config get <path>       # Get single value
docs-mcp-server config set <path> <val> # Set and persist value
```

--------------------------------

### Start Docker Compose Services

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/setup/installation.md

Start all the necessary services for the Docs MCP Server using Docker Compose. This command runs the services in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Run Docs MCP Server with Docker

Source: https://github.com/arabold/docs-mcp-server/blob/main/README.md

Start the Docs MCP Server using Docker, mounting volumes for data and configuration, and exposing the server port.

```bash
docker run --rm \
  -v docs-mcp-data:/data \
  -v docs-mcp-config:/config \
  -p 6280:6280 \
  ghcr.io/arabold/docs-mcp-server:latest \
  --protocol http --host 0.0.0.0 --port 6280
```

--------------------------------

### Typical Workflow: Indexing Documentation

Source: https://github.com/arabold/docs-mcp-server/blob/main/skills/docs-manage/SKILL.md

This snippet shows the typical workflow for indexing documentation for the first time using the scrape command.

```bash
# 1. Index documentation for the first time
npx @arabold/docs-mcp-server@latest scrape react https://react.dev/reference/react --version 19.0.0
```

--------------------------------

### Install Archive Dependencies

Source: https://github.com/arabold/docs-mcp-server/blob/main/openspec/changes/archive/2026-03-16-add-zip-support/tasks.md

Installs the necessary npm packages for handling ZIP and TAR archives, along with their TypeScript types.

```bash
npm install yauzl tar
npm install -D @types/yauzl @types/tar
```

--------------------------------

### Typical Documentation Search Workflow

Source: https://github.com/arabold/docs-mcp-server/blob/main/skills/docs-search/SKILL.md

Demonstrates a common workflow for searching documentation: first listing available libraries, then performing a search, and finally indexing if necessary.

```bash
# 1. Check what is indexed
npx @arabold/docs-mcp-server@latest list --output yaml

# 2. Search for relevant docs
npx @arabold/docs-mcp-server@latest search react "server components" --version 19.x --output yaml

# 3. If no results, index the docs first (see docs-manage skill), then retry
```

--------------------------------

### Get Specific Configuration Value with CLI

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/setup/configuration.md

Use `docs-mcp-server config get <key>` to retrieve a specific configuration value or a nested object.

```bash
docs-mcp-server config get scraper.maxPages
# Output: 1000

docs-mcp-server config get scraper.fetcher
# Output: { "maxRetries": 6, ... }

```

--------------------------------

### Clerk JWT Claim Configuration Example

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/infrastructure/authentication.md

Example JSON configuration for a provider's JWT template, demonstrating how to include the resource ID as the audience claim when using Clerk.

```json
{
  "aud": "https://mcp.your-domain.com",
  "sub": "{{user.id}}",
  "email": "{{user.primaryEmailAddress.emailAddress}}",
  "name": "{{user.fullName}}"
}
```

--------------------------------

### Index Documentation via CLI

Source: https://github.com/arabold/docs-mcp-server/blob/main/README.md

Use the CLI to scrape documentation from a given URL. Enable hash preservation for SPA sites.

```bash
npx @arabold/docs-mcp-server@latest scrape react https://react.dev/reference/react
```

```bash
npx @arabold/docs-mcp-server@latest scrape my-spa https://docs.example.com/#/guide --preserve-hashes
```

--------------------------------

### Load Config and Write Back

Source: https://github.com/arabold/docs-mcp-server/blob/main/openspec/changes/archive/2026-05-17-add-subresource-blocklist/design.md

Illustrates the process of loading configuration, potentially merging it, and then writing the merged configuration back to disk, which can overwrite user-specific array configurations.

```typescript
const config = loadConfig();
// ... potentially merge config with defaults ...
config.save();
```

--------------------------------

### GreedySplitter Level Merging Example

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/concepts/splitter-hierarchy.md

Shows how the GreedySplitter selects the lowest (most general) level when merging chunks.

```typescript
// Merging level 1 + level 3 = level 1 (most general)
merge(
  { level: 1, path: ["Section"] },
  { level: 3, path: ["Section", "Sub", "Detail"] }
);
// Result: { level: 1, path: ["Section", "Sub", "Detail"] }
```

--------------------------------

### JSON Document Hierarchy Example

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/concepts/splitter-hierarchy.md

Demonstrates the level and path assignment for chunks within a JSON document.

```typescript
// {"users": [{"name": "Alice"}, {"name": "Bob"}]}
[
  {
    content: '"Alice"',
    section: { level: 4, path: ["root", "users", "[0]", "name"] },
  },
  {
    content: '"Bob"',
    section: { level: 4, path: ["root", "users", "[1]", "name"] },
  },
];
```

--------------------------------

### Markdown Hierarchy Example

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/concepts/splitter-hierarchy.md

Illustrates how Markdown headings and plain text map to level and path in the hierarchy.

```typescript
// # Chapter 1          -> level: 1, path: ["Chapter 1"]
// ## Section 1.1       -> level: 2, path: ["Chapter 1", "Section 1.1"]
// ### Subsection 1.1.1 -> level: 3, path: ["Chapter 1", "Section 1.1", "Subsection 1.1.1"]
// Plain text content   -> level: 0, path: []
```

--------------------------------

### Index Documentation from URL

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/guides/basic-usage.md

Index documentation from a given URL. This command is useful for adding external resources to your library.

```bash
npx @arabold/docs-mcp-server@latest scrape react https://react.dev/reference/react
```

--------------------------------

### Divergent Level and Path Example

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/concepts/splitter-hierarchy.md

Illustrates a scenario where a chunk's conceptual level differs from its path depth.

```typescript
// Example: Content inheriting parent context
{
  content: "Some text under a deep heading",
  section: {
    level: 2,    // Conceptually a level-2 section
    path: ["Chapter", "Section", "Subsection", "Details"]  // But deep path
  }
}
```

--------------------------------

### Launch Web UI for Embedded Server

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/guides/basic-usage.md

Use this command to launch a temporary web UI for an embedded server. Ensure your OpenAI API key is set.

```bash
OPENAI_API_KEY="your-key" npx @arabold/docs-mcp-server@latest web --port 6281
```

--------------------------------

### Source Code Hierarchy Example

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/concepts/splitter-hierarchy.md

Shows how code chunks within a TypeScript file are assigned levels and paths.

```typescript
// File: UserService.ts
[
  {
    content: "class UserService {",
    section: { level: 1, path: ["UserService", "opening"] },
  },
  {
    content: "  getUser(id) { return db.find(id); }",
    section: { level: 2, path: ["UserService", "getUser"] },
  },
  {
    content: "}",
    section: { level: 1, path: ["UserService", "closing"] },
  },
  {
    content: "// Global code or imports",
    section: { level: 0, path: [] },
  },
];
```

--------------------------------

### Configure Continue.dev with Local MCP Server

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/guides/mcp-clients.md

Use this JSON configuration in Continue.dev's config.json to connect to a local Docs MCP Server using stdio. Note the array format for mcpServers.

```json
{
  "mcpServers": [
    {
      "name": "docs-mcp-server",
      "command": "npx",
      "args": ["-y", "@arabold/docs-mcp-server@latest"]
    }
  ]
}
```

--------------------------------

### Clone the Repository

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/setup/installation.md

Clone the Docs MCP Server repository to your local machine. This is the first step before setting up the environment.

```bash
git clone https://github.com/arabold/docs-mcp-server.git
cd docs-mcp-server
```

--------------------------------

### Configuration Flag Example

Source: https://github.com/arabold/docs-mcp-server/blob/main/openspec/changes/archive/2026-05-17-add-subresource-blocklist/design.md

This boolean flag controls whether the subresource blocklist is bypassed. Set to `false` to disable the blocklist.

```yaml
scraper.skipKnownTrackers: boolean
```

--------------------------------

### Resource Type Abort Example

Source: https://github.com/arabold/docs-mcp-server/blob/main/openspec/changes/archive/2026-05-17-add-subresource-blocklist/design.md

Shows how certain resource types like 'image', 'font', and 'media' are categorically dropped to reduce bandwidth usage.

```typescript
if (resourceType === "image" || resourceType === "font" || resourceType === "media") {
  return abort(request, "blockedbyclient");
}
```

--------------------------------

### Configure Claude Desktop with Local MCP Server

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/guides/mcp-clients.md

Use this JSON configuration for Claude Desktop to connect to a local Docs MCP Server using stdio. This spawns the server process directly.

```json
{
  "mcpServers": {
    "docs-mcp-server": {
      "command": "npx",
      "args": ["-y", "@arabold/docs-mcp-server@latest"]
    }
  }
}
```

--------------------------------

### Docker MCP Server Configuration

Source: https://github.com/arabold/docs-mcp-server/blob/main/docs/guides/mcp-clients.md

Configure MCP clients to connect to the docs-mcp-server using a Docker container. This setup mounts a volume for data persistence.

```json
{
  "mcpServers": {
    "docs-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "docs-mcp-data:/data",
        "ghcr.io/arabold/docs-mcp-server:latest"
      ]
    }
  }
}
```

--------------------------------

### Fetch Single Page as Markdown via CLI

Source: https://github.com/arabold/docs-mcp-server/blob/main/README.md

Retrieve a single web page's content as Markdown using the CLI.

```bash
npx @arabold/docs-mcp-server@latest fetch-url https://react.dev/reference/react/useEffect
```