Skip to content

Commit ec7fbda

Browse files
jonathanhefnerclaude
jonathanhefner
and
claude
committed
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: - 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>
1 parent 5a9de1c commit ec7fbda

File tree

9 files changed

+409
-1
lines changed

9 files changed

+409
-1
lines changed

‎.github/pages/_config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
title: '@modelcontextprotocol/sdk'
2+
3+
# Include generated files and directories which may start with underscores
4+
include:
5+
- '_*'

‎.github/pages/index.html‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
# Empty Jekyll front matter to enable Liquid templating (see {{ ... }} below)
3+
---
4+
5+
<!doctype html>
6+
<html>
7+
<head>
8+
<meta charset="utf-8" />
9+
<title>Redirecting to latest documentation...</title>
10+
<meta http-equiv="refresh" content="0; url=v{{ site.data.versions[0] }}/" />
11+
<link rel="canonical" href="v{{ site.data.versions[0] }}/" />
12+
</head>
13+
<body>
14+
<p>Redirecting to <a href="v{{ site.data.versions[0] }}/">latest documentation</a>...</p>
15+
<script>
16+
window.location.href = 'v{{ site.data.versions[0] }}/';
17+
</script>
18+
</body>
19+
</html>

‎.github/workflows/main.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,3 +87,35 @@ jobs:
8787
- run: npm publish --provenance --access public ${{ steps.npm-tag.outputs.tag }}
8888
env:
8989
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
90+
91+
publish-gh-pages:
92+
runs-on: ubuntu-latest
93+
if: github.event_name == 'release'
94+
needs: [publish]
95+
96+
permissions:
97+
contents: write
98+
99+
steps:
100+
- uses: actions/checkout@v4
101+
with:
102+
fetch-depth: 0 # Fetch all history for all branches
103+
104+
- uses: actions/setup-node@v4
105+
with:
106+
node-version: 24
107+
cache: npm
108+
109+
- name: Install dependencies
110+
run: npm ci
111+
112+
- name: Configure Git
113+
run: |
114+
git config --global user.name "github-actions[bot]"
115+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
116+
117+
- name: Generate documentation
118+
run: ./scripts/generate-gh-pages.sh ${{ github.ref_name }}
119+
120+
- name: Push to gh-pages
121+
run: git push origin gh-pages

‎.prettierignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,6 @@ pnpm-lock.yaml
1111

1212
# Ignore generated files
1313
src/spec.types.ts
14+
15+
# Jekyll/Liquid template files with special formatting requirements
16+
docs/index.md

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,7 @@ For more details on how to run these examples (including recommended commands an
156156
- [docs/capabilities.md](docs/capabilities.md) – sampling, elicitation (form and URL), and experimental task-based execution.
157157
- [docs/faq.md](docs/faq.md) – environment and troubleshooting FAQs (including Node.js Web Crypto support).
158158
- External references:
159+
- [SDK API documentation](https://modelcontextprotocol.github.io/typescript-sdk/)
159160
- [Model Context Protocol documentation](https://modelcontextprotocol.io)
160161
- [MCP Specification](https://spec.modelcontextprotocol.io)
161162
- [Example Servers](https://github.com/modelcontextprotocol/servers)

‎package-lock.json‎

Lines changed: 216 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)