Add API documentation with GitHub Pages deployment

[jonathanhefner]

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]

---

You can see a preview of the documentation for the 10 most recent minor version tags at: https://jonathan.hefner.pro/mcp-typescript-sdk/. (Ignore the v99.9.9 tag — I created that for testing purposes.)

Note that this page is fully customizable via docs/index.md, and it can link to SDK-specific guides in the future.

Eventually, I intend to link to this page from the modelcontextprotocol.io SDKs page. And, ultimately, I think it would be nice have something like sdks.modelcontextprotocol.io such that https://sdks.modelcontextprotocol.io/typescript-sdk/ resolves to https://modelcontextprotocol.github.io/typescript-sdk/.

If desired, I can also submit a PR for the gh-pages branch that includes whatever tags we want.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/sdk@1109

commit: 5023e06

[mattzcarey]

Hey, thanks for your contribution. This is a great idea but I think these docs should live in the [official docs](https://modelcontextprotocol.io/] under its own section. It probably needs some syncing with that repo more than creating a deployment here.

[jonathanhefner]

@mattzcarey I intend to link to the docs from the SDKs page. Ultimately, I think it would be nice have something like sdks.modelcontextprotocol.io such that https://sdks.modelcontextprotocol.io/typescript-sdk/ resolves to https://modelcontextprotocol.github.io/typescript-sdk/.

However, I strongly feel that the docs files themselves should live in each individual SDK's repo. That way, (1) the docs will be naturally kept in sync with the SDK, and (2) generation of versioned API docs will be tied to an SDK's release via GitHub Actions.