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 `docs/_data/versions.yml` with a list of all versions
      for Jekyll templates to consume

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

    - `docs/_config.yml` - Jekyll configuration
    - `docs/index.md` - Landing page template that links to all versions
      based on generated `docs/_data/versions.yml`
    - `docs/latest/index.html` - Redirect page template that redirects
      to the latest version based on generated `docs/_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

@@ -76,3 +76,35 @@ jobs:
             - run: npm publish --provenance --access public ${{ steps.npm-tag.outputs.tag }}
               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

@@ -1579,6 +1579,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>