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/latest_version.yml for Jekyll template
   • 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 the generated _data/latest_version.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: 63bf877

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

[felixweinberger]

Hi @jonathanhefner thanks for kicking this off!

I think having a documentation page specifically for the TypeScript SDK is good and GH Pages seems like the right way to host this imo.

Looking at the current version of the documentation though this looks like mostly generated docs based on DocStrings / Types. Is the idea for this to be a skeleton that we then fill in with actual guides and How-Tos for doing stuff or is the intention just to be a type reference? I'm not sure if the type reference adds a ton of value over just having the source code on github directly and inspecting the source?

Comparing for example the direction the Python SDK docs are going in which is more of a nicely rendered and navigable guide on how to actually use the SDK: https://modelcontextprotocol.github.io/python-sdk/

Do we need all the generated type docs or should we stick to something closer to what Python is doing?

[jonathanhefner]

Is the idea for this to be a skeleton that we then fill in with actual guides and How-Tos for doing stuff or is the intention just to be a type reference?

There are two possible approaches I had in mind:

1. Include the guides in the generated TypeDoc output via the projectDocuments setting.
2. Create a full-fledged GH Pages site and put the generated TypeDoc documentation at api/.

When I first submitted this PR, there were no other documents, so I tried to allow for either possibility. (See this comment in the script for Option 2.)

Since #1197, there are now some guides in docs/, so I have pushed a commit to include them in the TypeDoc output per Option 1. For example: https://jonathanhefner.github.io/mcp-typescript-sdk/v99.0.1/documents/Server.html.

At the moment, I lean toward staying with Option 1. If we have more sophisticated needs for structure and styling, we can switch to Option 2.

[felixweinberger]

Is the idea for this to be a skeleton that we then fill in with actual guides and How-Tos for doing stuff or is the intention just to be a type reference?

There are two possible approaches I had in mind:

1. Include the guides in the generated TypeDoc output via the projectDocuments setting.
2. Create a full-fledged GH Pages site and put the generated TypeDoc documentation at api/.

When I first submitted this PR, there were no other documents, so I tried to allow for either possibility. (See this comment in the script for Option 2.)

Since #1197, there are now some guides in docs/, so I have pushed a commit to include them in the TypeDoc output per Option 1. For example: https://jonathanhefner.github.io/mcp-typescript-sdk/v99.0.1/documents/Server.html.

At the moment, I lean toward staying with Option 1. If we have more sophisticated needs for structure and styling, we can switch to Option 2.

Yeah I think this is heading more in the direction I was thinking: https://jonathanhefner.github.io/mcp-typescript-sdk/v99.0.1/documents/Server.html

However, I do feel like the navigation might be a little bit confusing / overwhelming? Looking at the side bar:

There's a mix of low level API references that mirror the code structure and more classic tutorial-style guides. By virtue of the code structure for example we're elevating inMemory to a top level thing people might end up clicking on and browsing, but in practice we expect basically nobody to use it given it's not an official transport. It's probably a sign to move that file elsewhere, but more generally wondering if we can move the purely generated code into a visually separate section somehow?

Even just having:

docs
   - Client
   - Server
   - Capabilities
   - FAQ
   
API reference
   - client
   - server
   - inMemory
   - ...

Would be quite helpful potentially to separate the generated class and type docs from the actually written prose and guides?

[sonarqubecloud]

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[jonathanhefner]

@felixweinberger Good point. How does this look: