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:

   • 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/)
   • Creates the gh-pages branch as an orphan branch if it doesn't exist
   • Generates new doc pages while preserving existing versioned directories
   • Generates _data/versions.yml with a list of all versions for Jekyll templates to consume
   • Determines the latest version via semantic version sorting
   • For the latest version only, copies static Jekyll template files from .github/pages/ to the gh-pages root

2. Jekyll template files (see .github/pages/ directory)

   • .github/pages/_config.yml - Jekyll configuration
   • .github/pages/index.html - Landing page 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
• Explicitly excludes test files, mocks, examples, and integration tests

Documentation URL

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

Versioned API documentation will be available at:

• https://modelcontextprotocol.github.io/typescript-sdk/ (redirects to latest)
• https://modelcontextprotocol.github.io/typescript-sdk/v1.2.3/ (specific versions)

Co-Authored-By: Claude noreply@anthropic.com

---

You can see a preview of the documentation at: https://jonathanhefner.github.io/mcp-typescript-sdk/.

Note that the page automatically redirects to the latest version (in the preview, dummy v99.0.1), but it is fully customizable — see .github/pages/index.html — and can be more sophisticated in the future.

Eventually, I intend to link to the 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 backfills docs for old tags.

[pkg-pr-new]

Open in StackBlitz

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

commit: fab0d31

[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.