Add API documentation with GitHub Pages deployment

This adds automated generation and deployment of versioned API documentation
using TypeDoc and GitHub Pages. Documentation will be generated and published
when a new release is created.

Changes
-------

1. **Documentation generation script** (see `scripts/generate-gh-pages.sh`)

    Generates TypeDoc documentation for a specific version tag and commits it to
    the gh-pages branch. The script uses git worktrees to isolate the
    documentation generation process from the main workspace.

    Documentation for each release is stored in a versioned directory (e.g.,
    `v1.2.3/`) on the gh-pages branch. The script:

    - Creates the gh-pages branch as an orphan branch if it doesn't exist
    - Parses semantic versions from tag names, ignoring arbitrary prefixes
      (e.g., tags `1.2.3`, `v1.2.3`, and `release-1.2.3` all create `v1.2.3/`)
    - Preserves all existing version directories when generating new documentation
    - Determines the latest version using semantic version sorting
    - Copies static Jekyll template files from the `docs/` directory to the
      gh-pages root (for the latest version only)
    - Generates `_data/versions.yml` with a list of all versions for Jekyll
      templates to consume

2. **Jekyll template files** (see `docs/` directory)

    - `_config.yml` - Jekyll configuration (can set title and theme here)
    - `index.md` - Landing page template that links to all versions based on
      generated `_data/versions.yml`
    - `latest/index.html` - Redirect page template that redirects to the latest
      version based on generated `_data/versions.yml`

3. **GitHub Actions workflow** (see `.github/workflows/main.yml`)

    Added a `publish-gh-pages` job that runs after the `publish` job on release
    events. This ensures documentation is generated and published only after the
    npm package is successfully published. The job invokes the generation script
    with the release tag name and pushes the updated gh-pages branch.

4. **CI validation** (see `package.json`)

    Updated the `check` script to include TypeDoc validation with `--emit none`.
    This ensures TypeDoc can successfully parse the codebase (without generating
    output), catching documentation issues early in CI.

5. **Documentation link** (see `README.md`)

    Added a link to the published API documentation in the Documentation section
    of the README.

TypeDoc Configuration
---------------------

TypeDoc is configured via `typedoc.json`:

- Uses the `src` directory as the entry point with the `expand` strategy
- Uses `tsconfig.prod.json` which excludes test files

Documentation URL
-----------------

Custom documentation will be available at:
https://modelcontextprotocol.github.io/typescript-sdk/

Versioned API documentation will be available at:
- https://modelcontextprotocol.github.io/typescript-sdk/latest/ (latest version)
- https://modelcontextprotocol.github.io/typescript-sdk/v1.2.3/ (specific versions)

Co-Authored-By: Claude <[email protected]>

Author: jonathanhefner

.github/workflows/main.yml

@@ -66,3 +66,35 @@ jobs:
             - run: npm publish --provenance --access public
               env:
                   NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+    publish-gh-pages:
+        runs-on: ubuntu-latest
+        if: github.event_name == 'release'
+        needs: [publish]
+
+        permissions:
+            contents: write
+
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0 # Fetch all history for all branches
+
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: 24
+                  cache: npm
+
+            - name: Install dependencies
+              run: npm ci
+
+            - name: Configure Git
+              run: |
+                  git config --global user.name "github-actions[bot]"
+                  git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+            - name: Generate documentation
+              run: ./scripts/generate-gh-pages.sh ${{ github.ref_name }}
+
+            - name: Push to gh-pages
+              run: git push origin gh-pages

.prettierignore

@@ -11,3 +11,6 @@ pnpm-lock.yaml
 
 # Ignore generated files
 src/spec.types.ts
+
+# Jekyll/Liquid template files with special formatting requirements
+docs/index.md

README.md

@@ -1498,6 +1498,7 @@ app.listen(3000);
 
 ## Documentation
 
+- [SDK API documentation](https://modelcontextprotocol.github.io/typescript-sdk/)
 - [Model Context Protocol documentation](https://modelcontextprotocol.io)
 - [MCP Specification](https://spec.modelcontextprotocol.io)
 - [Example Servers](https://github.com/modelcontextprotocol/servers)

docs/_config.yml

@@ -0,0 +1,5 @@
+title: '@modelcontextprotocol/sdk'
+
+# Include generated files and directories which may start with underscores
+include:
+    - '_*'

docs/index.md

@@ -0,0 +1,7 @@
+---
+# Empty Jekyll front matter to enable Liquid templating (see {{ ... }} below)
+---
+
+{% for version in site.data.versions %}
+- [v{{ version }}](v{{ version }}/)
+{% endfor %}

docs/latest/index.html

@@ -0,0 +1,19 @@
+---
+# Empty Jekyll front matter to enable Liquid templating (see {{ ... }} below)
+---
+
+<!doctype html>
+<html>
+    <head>
+        <meta charset="utf-8" />
+        <title>Redirecting to latest documentation...</title>
+        <meta http-equiv="refresh" content="0; url=../v{{ site.data.versions[0] }}/" />
+        <link rel="canonical" href="../v{{ site.data.versions[0] }}/" />
+    </head>
+    <body>
+        <p>Redirecting to <a href="../v{{ site.data.versions[0] }}/">latest documentation</a>...</p>
+        <script>
+            window.location.href = '../v{{ site.data.versions[0] }}/';
+        </script>
+    </body>
+</html>