Skip to content

Add API documentation generation with phpDocumentor - #184

Merged
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom
jonathanhefner:deploy-docs
Feb 1, 2026
Merged

Add API documentation generation with phpDocumentor#184
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom
jonathanhefner:deploy-docs

Conversation

@jonathanhefner

@jonathanhefnerjonathanhefner commented Dec 11, 2025•
edited
Loading

Copy link
Copy Markdown
Member
  • Add phpDocumentor configuration and docs Makefile target
  • Generate docs during CI to catch errors before releases
  • Set up GitHub Pages with Jekyll for hosting generated docs
  • Add GitHub Actions workflow to deploy docs to GitHub Pages on releases

🤖 Generated with Claude Code

This PR also includes a commit to fix existing doc errors from phpDocumentor.

You can preview the generated documentation at http://jonathanhefner.github.io/mcp-php-sdk/api/.

@chr-hertel

chr-hertel commented Dec 11, 2025

Copy link
Copy Markdown
Member

Hi @jonathanhefner - thanks for that proposal, is that related to the discussion we had Tuesday about standardizing SDK docs? Having that on my desk as an open issue to follow up on ...

@jonathanhefner

jonathanhefner commented Dec 11, 2025

Copy link
Copy Markdown
MemberAuthor

@chr-hertel I wasn't aware of a discussion, but it might be. 😄 The context is: I am trying to ensure that all MCP SDKs have documentation available at https://modelcontextprotocol.github.io/*-sdk/.

@chr-hertel

chr-hertel commented Dec 11, 2025

Copy link
Copy Markdown
Member

Yup, that's exactly what we want to look at - awesome!
Don't have time tonight, but will def come back this, thanks!

Nyholm
Nyholm reviewed Dec 16, 2025
View reviewed changes

@NyholmNyholm left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you.

Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json

(Make those changes in a separate PR if you think we should merge them)

@jonathanhefner

jonathanhefner commented Dec 16, 2025

Copy link
Copy Markdown
MemberAuthor

Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json

Those changes are related. The changes to MessageFactory (in commit a97a5dc) are because the previous syntax is incompatible with phpDocumentor, and would cause the build to fail during the documentation generation step.

The changes in composer.json are due to "sort-packages": true, which predates this PR:

php-sdk/composer.json

Lines 70 to 75 in 69cd04f

"config": {
"sort-packages": true,
"allow-plugins": {
"php-http/discovery": false
}
}

How would you like me to proceed?

@Nyholm

Nyholm commented Dec 27, 2025

Copy link
Copy Markdown
Contributor

Those changes are related.

Oh, okey.

Sorry, I did not know they were required.

How would you like me to proceed?

I need to you rebase your PR so I can merge.

Can you also link similar PRs to other SDKs?

@NyholmNyholm added the needs more work Not ready to be merged yet, needs additional follow-up from the author(s). label Dec 27, 2025
@chr-hertel

chr-hertel commented Dec 27, 2025

Copy link
Copy Markdown
Member

Looks like @jonathanhefner was basically already all over the place - awesome!
I also tried to get some overview - and made some notes.

SDK Repos & their docs:

That's what I could find ... no guarantee for completeness :D

My proposal going forward, and to be aligned in sdk-maintainer circle, would rather be a combination of three things - ofc heavily based on what we have right now across the SDKs:

  1. Have a Readme with standardized elements (e.g. SDK Tier, Conformance Score, reference to Spec, GitHub Pages, etc.) but open for more if maintainers would want to
  2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
  3. Package specific documentation, see pkg.go.dev or packagist.org

I don't know about API docs tbh, at least in PHP they are not that relevant anymore, and I would rather not focus on them - might differ for other ecosystems, but could be an optional part of the GitHub Pages maybe.

@jonathanhefner

jonathanhefner commented Dec 29, 2025

Copy link
Copy Markdown
MemberAuthor

I need to you rebase your PR so I can merge.

Rebased!

@jonathanhefner

jonathanhefner commented Dec 31, 2025

Copy link
Copy Markdown
MemberAuthor

2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs

I just pushed a commit that bundles the Markdown guides into the phpDocumentor output. They are accessible via a "Guides" link in the upper right-hand corner:

Guides IndexMCP ElementsExamples
01-index02-mcp-elements03-examples

(Due to the design of phpDocumentor, adding a "Guides" link in the top nav was the most maintainable approach, but I can pursue other options if you are open to maintaining more significant template overrides.)

@chr-hertel

chr-hertel commented Jan 2, 2026

Copy link
Copy Markdown
Member

@jonathanhefner referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?

@jonathanhefner

jonathanhefner commented Jan 2, 2026

Copy link
Copy Markdown
MemberAuthor

referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?

Sounds good! I've added it to my calendar! 😄

@chr-hertelchr-hertel added documentation Improvements or additions to documentation and removed Status: Needs Decision labels Jan 23, 2026
jonathanhefnerand others added 5 commits February 1, 2026 16:14
@jonathanhefner@claude@chr-hertel
Add API documentation generation with phpDocumentor
03fce3f
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix phpDocumentor errors in type annotations
962a0d5
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix CI: pin phar-io/composer-distributor ^1.0.2
5f72f45
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Integrate markdown guides into phpDocumentor output
b0215a5
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@chr-hertel
Fine-tuning for path, config, and layout
5c20aa9
chr-hertel
chr-hertel approved these changes Feb 1, 2026
View reviewed changes

@chr-hertelchr-hertel left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @jonathanhefner for kicking this off 🙏 👍

Rebased, and added some tweaks regarding paths, layout and config.

@chr-hertelchr-hertel removed the needs more work Not ready to be merged yet, needs additional follow-up from the author(s). label Feb 1, 2026
@chr-hertel

chr-hertel commented Feb 1, 2026

Copy link
Copy Markdown
Member

Some known issues regarding the markdown integration, see #232.

@chr-hertel
chr-hertel merged commit 940eb90 into modelcontextprotocol:mainFeb 1, 2026
16 checks passed
sveneld pushed a commit to sveneld/php-sdk that referenced this pull request Feb 8, 2026
@jonathanhefner@claude
@chr-hertelVolodymyr Panivko
Add API documentation generation with phpDocumentor (modelcontextprot…
77ae3c4
…ocol#184)
* Add API documentation generation with phpDocumentor
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix phpDocumentor errors in type annotations
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix CI: pin phar-io/composer-distributor ^1.0.2
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Integrate markdown guides into phpDocumentor output
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fine-tuning for path, config, and layout
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@NyholmNyholmNyholm left review comments
@chr-hertelchr-hertelchr-hertel approved these changes
@CodeWithKyrianCodeWithKyrianAwaiting requested review from CodeWithKyrianCodeWithKyrian is a code owner
+1 more reviewer
@scutuatua-cryptoscutuatua-cryptoscutuatua-crypto approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

documentationImprovements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@jonathanhefner@chr-hertel@Nyholm@scutuatua-crypto
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
Add API documentation generation with phpDocumentor by jonathanhefner · Pull Request #184 · modelcontextprotocol/php-sdk · GitHub
Skip to content
Add API documentation generation with phpDocumentor - #184
Merged
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom 
jonathanhefner:deploy-docs
Feb 1, 2026
Merged
Add API documentation generation with phpDocumentor#184
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom 
jonathanhefner:deploy-docs
Conversation
@jonathanhefner
@jonathanhefnerjonathanhefner
commented
Dec 11, 2025•

edited

Loading

Copy link


Copy Markdown

Member
  • Add phpDocumentor configuration and docs Makefile target
  • Generate docs during CI to catch errors before releases
  • Set up GitHub Pages with Jekyll for hosting generated docs
  • Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with Claude Code
This PR also includes a commit to fix existing doc errors from phpDocumentor.
You can preview the generated documentation at http://jonathanhefner.github.io/mcp-php-sdk/api/.
@chr-hertel
chr-hertel
commented
Dec 11, 2025

Copy link


Copy Markdown

Member
Hi @jonathanhefner - thanks for that proposal, is that related to the discussion we had Tuesday about standardizing SDK docs? Having that on my desk as an open issue to follow up on ...
@jonathanhefner
jonathanhefner
commented
Dec 11, 2025

Copy link


Copy Markdown

MemberAuthor
@chr-hertel I wasn't aware of a discussion, but it might be. 😄 The context is: I am trying to ensure that all MCP SDKs have documentation available at https://modelcontextprotocol.github.io/*-sdk/.
@chr-hertel
chr-hertel
commented
Dec 11, 2025

Copy link


Copy Markdown

Member
Yup, that's exactly what we want to look at - awesome!

Don't have time tonight, but will def come back this, thanks!
Nyholm
Nyholm
reviewed
Dec 16, 2025
View reviewed changes
@NyholmNyholm
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you.
Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json
(Make those changes in a separate PR if you think we should merge them)
@jonathanhefner
jonathanhefner
commented
Dec 16, 2025

Copy link


Copy Markdown

MemberAuthor
Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json
Those changes are related. The changes to MessageFactory (in commit a97a5dc) are because the previous syntax is incompatible with phpDocumentor, and would cause the build to fail during the documentation generation step.
The changes in composer.json are due to "sort-packages": true, which predates this PR:
php-sdk/composer.json

Lines 70 to 75
in
69cd04f
"config": { 
"sort-packages": true, 
"allow-plugins": { 
"php-http/discovery": false
 } 
 } 
How would you like me to proceed?
@Nyholm
Nyholm
commented
Dec 27, 2025

Copy link


Copy Markdown

Contributor
Those changes are related.
Oh, okey.
Sorry, I did not know they were required.
How would you like me to proceed?
I need to you rebase your PR so I can merge.
Can you also link similar PRs to other SDKs?
@NyholmNyholm
added
the 
needs more work
Not ready to be merged yet, needs additional follow-up from the author(s).
label
Dec 27, 2025
@chr-hertel
chr-hertel
commented
Dec 27, 2025

Copy link


Copy Markdown

Member
Looks like @jonathanhefner was basically already all over the place - awesome!

I also tried to get some overview - and made some notes.
SDK Repos & their docs:
That's what I could find ... no guarantee for completeness :D
My proposal going forward, and to be aligned in sdk-maintainer circle, would rather be a combination of three things - ofc heavily based on what we have right now across the SDKs:
  1. Have a Readme with standardized elements (e.g. SDK Tier, Conformance Score, reference to Spec, GitHub Pages, etc.) but open for more if maintainers would want to
  2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
  3. Package specific documentation, see pkg.go.dev or packagist.org
I don't know about API docs tbh, at least in PHP they are not that relevant anymore, and I would rather not focus on them - might differ for other ecosystems, but could be an optional part of the GitHub Pages maybe.
@jonathanhefner
jonathanhefner
commented
Dec 29, 2025

Copy link


Copy Markdown

MemberAuthor
I need to you rebase your PR so I can merge.
Rebased!
@jonathanhefner
jonathanhefner
commented
Dec 31, 2025

Copy link


Copy Markdown

MemberAuthor
2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
I just pushed a commit that bundles the Markdown guides into the phpDocumentor output. They are accessible via a "Guides" link in the upper right-hand corner:
Guides IndexMCP ElementsExamples
01-index02-mcp-elements03-examples
(Due to the design of phpDocumentor, adding a "Guides" link in the top nav was the most maintainable approach, but I can pursue other options if you are open to maintaining more significant template overrides.)
@chr-hertel
chr-hertel
commented
Jan 2, 2026

Copy link


Copy Markdown

Member
@jonathanhefner referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?
@jonathanhefner
jonathanhefner
commented
Jan 2, 2026

Copy link


Copy Markdown

MemberAuthor
referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?
Sounds good! I've added it to my calendar! 😄
@chr-hertelchr-hertel
added

documentation
Improvements or additions to documentation
and removed

Status: Needs Decision

labels
Jan 23, 2026
jonathanhefnerand others
added 5 commits
February 1, 2026 16:14
@jonathanhefner@claude@chr-hertel
Add API documentation generation with phpDocumentor
03fce3f
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix phpDocumentor errors in type annotations
962a0d5
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix CI: pin phar-io/composer-distributor ^1.0.2
5f72f45
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Integrate markdown guides into phpDocumentor output
b0215a5
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@chr-hertel
Fine-tuning for path, config, and layout
5c20aa9
chr-hertel
chr-hertel
approved these changes
Feb 1, 2026
View reviewed changes
@chr-hertelchr-hertel
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @jonathanhefner for kicking this off 🙏 👍
Rebased, and added some tweaks regarding paths, layout and config.
@chr-hertelchr-hertel
removed
the 
needs more work
Not ready to be merged yet, needs additional follow-up from the author(s).
label
Feb 1, 2026
@chr-hertel
chr-hertel
commented
Feb 1, 2026

Copy link


Copy Markdown

Member
Some known issues regarding the markdown integration, see #232.
@chr-hertel
chr-hertel
merged commit 940eb90
into
modelcontextprotocol:mainFeb 1, 2026

16 checks passed

sveneld pushed a commit
to sveneld/php-sdk
that referenced
this pull request
Feb 8, 2026
@jonathanhefner@claude
@chr-hertelVolodymyr Panivko
Add API documentation generation with phpDocumentor (modelcontextprot…
77ae3c4
…ocol#184)
* Add API documentation generation with phpDocumentor
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix phpDocumentor errors in type annotations
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix CI: pin phar-io/composer-distributor ^1.0.2
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Integrate markdown guides into phpDocumentor output
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fine-tuning for path, config, and layout
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@NyholmNyholmNyholm left review comments
@chr-hertelchr-hertelchr-hertel approved these changes
@CodeWithKyrianCodeWithKyrianAwaiting requested review from CodeWithKyrianCodeWithKyrian is a code owner

+1 more reviewer

@scutuatua-cryptoscutuatua-cryptoscutuatua-crypto approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels

documentationImprovements or additions to documentation

Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

4 participants

@jonathanhefner@chr-hertel@Nyholm@scutuatua-crypto

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Add API documentation generation with phpDocumentor by jonathanhefner · Pull Request #184 · modelcontextprotocol/php-sdk · GitHub
Skip to content
Add API documentation generation with phpDocumentor - #184
Merged
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom 
jonathanhefner:deploy-docs
Feb 1, 2026
Merged
Add API documentation generation with phpDocumentor#184
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom 
jonathanhefner:deploy-docs
Conversation
@jonathanhefner
@jonathanhefnerjonathanhefner
commented
Dec 11, 2025•

edited

Loading

Copy link


Copy Markdown

Member
  • Add phpDocumentor configuration and docs Makefile target
  • Generate docs during CI to catch errors before releases
  • Set up GitHub Pages with Jekyll for hosting generated docs
  • Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with Claude Code
This PR also includes a commit to fix existing doc errors from phpDocumentor.
You can preview the generated documentation at http://jonathanhefner.github.io/mcp-php-sdk/api/.
@chr-hertel
chr-hertel
commented
Dec 11, 2025

Copy link


Copy Markdown

Member
Hi @jonathanhefner - thanks for that proposal, is that related to the discussion we had Tuesday about standardizing SDK docs? Having that on my desk as an open issue to follow up on ...
@jonathanhefner
jonathanhefner
commented
Dec 11, 2025

Copy link


Copy Markdown

MemberAuthor
@chr-hertel I wasn't aware of a discussion, but it might be. 😄 The context is: I am trying to ensure that all MCP SDKs have documentation available at https://modelcontextprotocol.github.io/*-sdk/.
@chr-hertel
chr-hertel
commented
Dec 11, 2025

Copy link


Copy Markdown

Member
Yup, that's exactly what we want to look at - awesome!

Don't have time tonight, but will def come back this, thanks!
Nyholm
Nyholm
reviewed
Dec 16, 2025
View reviewed changes
@NyholmNyholm
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you.
Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json
(Make those changes in a separate PR if you think we should merge them)
@jonathanhefner
jonathanhefner
commented
Dec 16, 2025

Copy link


Copy Markdown

MemberAuthor
Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json
Those changes are related. The changes to MessageFactory (in commit a97a5dc) are because the previous syntax is incompatible with phpDocumentor, and would cause the build to fail during the documentation generation step.
The changes in composer.json are due to "sort-packages": true, which predates this PR:
php-sdk/composer.json

Lines 70 to 75
in
69cd04f
"config": { 
"sort-packages": true, 
"allow-plugins": { 
"php-http/discovery": false
 } 
 } 
How would you like me to proceed?
@Nyholm
Nyholm
commented
Dec 27, 2025

Copy link


Copy Markdown

Contributor
Those changes are related.
Oh, okey.
Sorry, I did not know they were required.
How would you like me to proceed?
I need to you rebase your PR so I can merge.
Can you also link similar PRs to other SDKs?
@NyholmNyholm
added
the 
needs more work
Not ready to be merged yet, needs additional follow-up from the author(s).
label
Dec 27, 2025
@chr-hertel
chr-hertel
commented
Dec 27, 2025

Copy link


Copy Markdown

Member
Looks like @jonathanhefner was basically already all over the place - awesome!

I also tried to get some overview - and made some notes.
SDK Repos & their docs:
That's what I could find ... no guarantee for completeness :D
My proposal going forward, and to be aligned in sdk-maintainer circle, would rather be a combination of three things - ofc heavily based on what we have right now across the SDKs:
  1. Have a Readme with standardized elements (e.g. SDK Tier, Conformance Score, reference to Spec, GitHub Pages, etc.) but open for more if maintainers would want to
  2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
  3. Package specific documentation, see pkg.go.dev or packagist.org
I don't know about API docs tbh, at least in PHP they are not that relevant anymore, and I would rather not focus on them - might differ for other ecosystems, but could be an optional part of the GitHub Pages maybe.
@jonathanhefner
jonathanhefner
commented
Dec 29, 2025

Copy link


Copy Markdown

MemberAuthor
I need to you rebase your PR so I can merge.
Rebased!
@jonathanhefner
jonathanhefner
commented
Dec 31, 2025

Copy link


Copy Markdown

MemberAuthor
2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
I just pushed a commit that bundles the Markdown guides into the phpDocumentor output. They are accessible via a "Guides" link in the upper right-hand corner:
Guides IndexMCP ElementsExamples
01-index02-mcp-elements03-examples
(Due to the design of phpDocumentor, adding a "Guides" link in the top nav was the most maintainable approach, but I can pursue other options if you are open to maintaining more significant template overrides.)
@chr-hertel
chr-hertel
commented
Jan 2, 2026

Copy link


Copy Markdown

Member
@jonathanhefner referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?
@jonathanhefner
jonathanhefner
commented
Jan 2, 2026

Copy link


Copy Markdown

MemberAuthor
referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?
Sounds good! I've added it to my calendar! 😄
@chr-hertelchr-hertel
added

documentation
Improvements or additions to documentation
and removed

Status: Needs Decision

labels
Jan 23, 2026
jonathanhefnerand others
added 5 commits
February 1, 2026 16:14
@jonathanhefner@claude@chr-hertel
Add API documentation generation with phpDocumentor
03fce3f
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix phpDocumentor errors in type annotations
962a0d5
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix CI: pin phar-io/composer-distributor ^1.0.2
5f72f45
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Integrate markdown guides into phpDocumentor output
b0215a5
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@chr-hertel
Fine-tuning for path, config, and layout
5c20aa9
chr-hertel
chr-hertel
approved these changes
Feb 1, 2026
View reviewed changes
@chr-hertelchr-hertel
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @jonathanhefner for kicking this off 🙏 👍
Rebased, and added some tweaks regarding paths, layout and config.
@chr-hertelchr-hertel
removed
the 
needs more work
Not ready to be merged yet, needs additional follow-up from the author(s).
label
Feb 1, 2026
@chr-hertel
chr-hertel
commented
Feb 1, 2026

Copy link


Copy Markdown

Member
Some known issues regarding the markdown integration, see #232.
@chr-hertel
chr-hertel
merged commit 940eb90
into
modelcontextprotocol:mainFeb 1, 2026

16 checks passed

sveneld pushed a commit
to sveneld/php-sdk
that referenced
this pull request
Feb 8, 2026
@jonathanhefner@claude
@chr-hertelVolodymyr Panivko
Add API documentation generation with phpDocumentor (modelcontextprot…
77ae3c4
…ocol#184)
* Add API documentation generation with phpDocumentor
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix phpDocumentor errors in type annotations
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix CI: pin phar-io/composer-distributor ^1.0.2
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Integrate markdown guides into phpDocumentor output
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fine-tuning for path, config, and layout
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@NyholmNyholmNyholm left review comments
@chr-hertelchr-hertelchr-hertel approved these changes
@CodeWithKyrianCodeWithKyrianAwaiting requested review from CodeWithKyrianCodeWithKyrian is a code owner

+1 more reviewer

@scutuatua-cryptoscutuatua-cryptoscutuatua-crypto approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels

documentationImprovements or additions to documentation

Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

4 participants

@jonathanhefner@chr-hertel@Nyholm@scutuatua-crypto

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Add API documentation generation with phpDocumentor by jonathanhefner · Pull Request #184 · modelcontextprotocol/php-sdk · GitHub
Skip to content
Add API documentation generation with phpDocumentor - #184
Merged
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom 
jonathanhefner:deploy-docs
Feb 1, 2026
Merged
Add API documentation generation with phpDocumentor#184
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom 
jonathanhefner:deploy-docs
Conversation
@jonathanhefner
@jonathanhefnerjonathanhefner
commented
Dec 11, 2025•

edited

Loading

Copy link


Copy Markdown

Member
  • Add phpDocumentor configuration and docs Makefile target
  • Generate docs during CI to catch errors before releases
  • Set up GitHub Pages with Jekyll for hosting generated docs
  • Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with Claude Code
This PR also includes a commit to fix existing doc errors from phpDocumentor.
You can preview the generated documentation at http://jonathanhefner.github.io/mcp-php-sdk/api/.
@chr-hertel
chr-hertel
commented
Dec 11, 2025

Copy link


Copy Markdown

Member
Hi @jonathanhefner - thanks for that proposal, is that related to the discussion we had Tuesday about standardizing SDK docs? Having that on my desk as an open issue to follow up on ...
@jonathanhefner
jonathanhefner
commented
Dec 11, 2025

Copy link


Copy Markdown

MemberAuthor
@chr-hertel I wasn't aware of a discussion, but it might be. 😄 The context is: I am trying to ensure that all MCP SDKs have documentation available at https://modelcontextprotocol.github.io/*-sdk/.
@chr-hertel
chr-hertel
commented
Dec 11, 2025

Copy link


Copy Markdown

Member
Yup, that's exactly what we want to look at - awesome!

Don't have time tonight, but will def come back this, thanks!
Nyholm
Nyholm
reviewed
Dec 16, 2025
View reviewed changes
@NyholmNyholm
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you.
Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json
(Make those changes in a separate PR if you think we should merge them)
@jonathanhefner
jonathanhefner
commented
Dec 16, 2025

Copy link


Copy Markdown

MemberAuthor
Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json
Those changes are related. The changes to MessageFactory (in commit a97a5dc) are because the previous syntax is incompatible with phpDocumentor, and would cause the build to fail during the documentation generation step.
The changes in composer.json are due to "sort-packages": true, which predates this PR:
php-sdk/composer.json

Lines 70 to 75
in
69cd04f
"config": { 
"sort-packages": true, 
"allow-plugins": { 
"php-http/discovery": false
 } 
 } 
How would you like me to proceed?
@Nyholm
Nyholm
commented
Dec 27, 2025

Copy link


Copy Markdown

Contributor
Those changes are related.
Oh, okey.
Sorry, I did not know they were required.
How would you like me to proceed?
I need to you rebase your PR so I can merge.
Can you also link similar PRs to other SDKs?
@NyholmNyholm
added
the 
needs more work
Not ready to be merged yet, needs additional follow-up from the author(s).
label
Dec 27, 2025
@chr-hertel
chr-hertel
commented
Dec 27, 2025

Copy link


Copy Markdown

Member
Looks like @jonathanhefner was basically already all over the place - awesome!

I also tried to get some overview - and made some notes.
SDK Repos & their docs:
That's what I could find ... no guarantee for completeness :D
My proposal going forward, and to be aligned in sdk-maintainer circle, would rather be a combination of three things - ofc heavily based on what we have right now across the SDKs:
  1. Have a Readme with standardized elements (e.g. SDK Tier, Conformance Score, reference to Spec, GitHub Pages, etc.) but open for more if maintainers would want to
  2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
  3. Package specific documentation, see pkg.go.dev or packagist.org
I don't know about API docs tbh, at least in PHP they are not that relevant anymore, and I would rather not focus on them - might differ for other ecosystems, but could be an optional part of the GitHub Pages maybe.
@jonathanhefner
jonathanhefner
commented
Dec 29, 2025

Copy link


Copy Markdown

MemberAuthor
I need to you rebase your PR so I can merge.
Rebased!
@jonathanhefner
jonathanhefner
commented
Dec 31, 2025

Copy link


Copy Markdown

MemberAuthor
2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
I just pushed a commit that bundles the Markdown guides into the phpDocumentor output. They are accessible via a "Guides" link in the upper right-hand corner:
Guides IndexMCP ElementsExamples
01-index02-mcp-elements03-examples
(Due to the design of phpDocumentor, adding a "Guides" link in the top nav was the most maintainable approach, but I can pursue other options if you are open to maintaining more significant template overrides.)
@chr-hertel
chr-hertel
commented
Jan 2, 2026

Copy link


Copy Markdown

Member
@jonathanhefner referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?
@jonathanhefner
jonathanhefner
commented
Jan 2, 2026

Copy link


Copy Markdown

MemberAuthor
referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?
Sounds good! I've added it to my calendar! 😄
@chr-hertelchr-hertel
added

documentation
Improvements or additions to documentation
and removed

Status: Needs Decision

labels
Jan 23, 2026
jonathanhefnerand others
added 5 commits
February 1, 2026 16:14
@jonathanhefner@claude@chr-hertel
Add API documentation generation with phpDocumentor
03fce3f
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix phpDocumentor errors in type annotations
962a0d5
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix CI: pin phar-io/composer-distributor ^1.0.2
5f72f45
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Integrate markdown guides into phpDocumentor output
b0215a5
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@chr-hertel
Fine-tuning for path, config, and layout
5c20aa9
chr-hertel
chr-hertel
approved these changes
Feb 1, 2026
View reviewed changes
@chr-hertelchr-hertel
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @jonathanhefner for kicking this off 🙏 👍
Rebased, and added some tweaks regarding paths, layout and config.
@chr-hertelchr-hertel
removed
the 
needs more work
Not ready to be merged yet, needs additional follow-up from the author(s).
label
Feb 1, 2026
@chr-hertel
chr-hertel
commented
Feb 1, 2026

Copy link


Copy Markdown

Member
Some known issues regarding the markdown integration, see #232.
@chr-hertel
chr-hertel
merged commit 940eb90
into
modelcontextprotocol:mainFeb 1, 2026

16 checks passed

sveneld pushed a commit
to sveneld/php-sdk
that referenced
this pull request
Feb 8, 2026
@jonathanhefner@claude
@chr-hertelVolodymyr Panivko
Add API documentation generation with phpDocumentor (modelcontextprot…
77ae3c4
…ocol#184)
* Add API documentation generation with phpDocumentor
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix phpDocumentor errors in type annotations
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix CI: pin phar-io/composer-distributor ^1.0.2
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Integrate markdown guides into phpDocumentor output
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fine-tuning for path, config, and layout
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@NyholmNyholmNyholm left review comments
@chr-hertelchr-hertelchr-hertel approved these changes
@CodeWithKyrianCodeWithKyrianAwaiting requested review from CodeWithKyrianCodeWithKyrian is a code owner

+1 more reviewer

@scutuatua-cryptoscutuatua-cryptoscutuatua-crypto approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels

documentationImprovements or additions to documentation

Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

4 participants

@jonathanhefner@chr-hertel@Nyholm@scutuatua-crypto

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
Add API documentation generation with phpDocumentor by jonathanhefner · Pull Request #184 · modelcontextprotocol/php-sdk · GitHub
Skip to content
Add API documentation generation with phpDocumentor - #184
Merged
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom 
jonathanhefner:deploy-docs
Feb 1, 2026
Merged
Add API documentation generation with phpDocumentor#184
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom 
jonathanhefner:deploy-docs
Conversation
@jonathanhefner
@jonathanhefnerjonathanhefner
commented
Dec 11, 2025•

edited

Loading

Copy link


Copy Markdown

Member
  • Add phpDocumentor configuration and docs Makefile target
  • Generate docs during CI to catch errors before releases
  • Set up GitHub Pages with Jekyll for hosting generated docs
  • Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with Claude Code
This PR also includes a commit to fix existing doc errors from phpDocumentor.
You can preview the generated documentation at http://jonathanhefner.github.io/mcp-php-sdk/api/.
@chr-hertel
chr-hertel
commented
Dec 11, 2025

Copy link


Copy Markdown

Member
Hi @jonathanhefner - thanks for that proposal, is that related to the discussion we had Tuesday about standardizing SDK docs? Having that on my desk as an open issue to follow up on ...
@jonathanhefner
jonathanhefner
commented
Dec 11, 2025

Copy link


Copy Markdown

MemberAuthor
@chr-hertel I wasn't aware of a discussion, but it might be. 😄 The context is: I am trying to ensure that all MCP SDKs have documentation available at https://modelcontextprotocol.github.io/*-sdk/.
@chr-hertel
chr-hertel
commented
Dec 11, 2025

Copy link


Copy Markdown

Member
Yup, that's exactly what we want to look at - awesome!

Don't have time tonight, but will def come back this, thanks!
Nyholm
Nyholm
reviewed
Dec 16, 2025
View reviewed changes
@NyholmNyholm
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you.
Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json
(Make those changes in a separate PR if you think we should merge them)
@jonathanhefner
jonathanhefner
commented
Dec 16, 2025

Copy link


Copy Markdown

MemberAuthor
Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json
Those changes are related. The changes to MessageFactory (in commit a97a5dc) are because the previous syntax is incompatible with phpDocumentor, and would cause the build to fail during the documentation generation step.
The changes in composer.json are due to "sort-packages": true, which predates this PR:
php-sdk/composer.json

Lines 70 to 75
in
69cd04f
"config": { 
"sort-packages": true, 
"allow-plugins": { 
"php-http/discovery": false
 } 
 } 
How would you like me to proceed?
@Nyholm
Nyholm
commented
Dec 27, 2025

Copy link


Copy Markdown

Contributor
Those changes are related.
Oh, okey.
Sorry, I did not know they were required.
How would you like me to proceed?
I need to you rebase your PR so I can merge.
Can you also link similar PRs to other SDKs?
@NyholmNyholm
added
the 
needs more work
Not ready to be merged yet, needs additional follow-up from the author(s).
label
Dec 27, 2025
@chr-hertel
chr-hertel
commented
Dec 27, 2025

Copy link


Copy Markdown

Member
Looks like @jonathanhefner was basically already all over the place - awesome!

I also tried to get some overview - and made some notes.
SDK Repos & their docs:
That's what I could find ... no guarantee for completeness :D
My proposal going forward, and to be aligned in sdk-maintainer circle, would rather be a combination of three things - ofc heavily based on what we have right now across the SDKs:
  1. Have a Readme with standardized elements (e.g. SDK Tier, Conformance Score, reference to Spec, GitHub Pages, etc.) but open for more if maintainers would want to
  2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
  3. Package specific documentation, see pkg.go.dev or packagist.org
I don't know about API docs tbh, at least in PHP they are not that relevant anymore, and I would rather not focus on them - might differ for other ecosystems, but could be an optional part of the GitHub Pages maybe.
@jonathanhefner
jonathanhefner
commented
Dec 29, 2025

Copy link


Copy Markdown

MemberAuthor
I need to you rebase your PR so I can merge.
Rebased!
@jonathanhefner
jonathanhefner
commented
Dec 31, 2025

Copy link


Copy Markdown

MemberAuthor
2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
I just pushed a commit that bundles the Markdown guides into the phpDocumentor output. They are accessible via a "Guides" link in the upper right-hand corner:
Guides IndexMCP ElementsExamples
01-index02-mcp-elements03-examples
(Due to the design of phpDocumentor, adding a "Guides" link in the top nav was the most maintainable approach, but I can pursue other options if you are open to maintaining more significant template overrides.)
@chr-hertel
chr-hertel
commented
Jan 2, 2026

Copy link


Copy Markdown

Member
@jonathanhefner referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?
@jonathanhefner
jonathanhefner
commented
Jan 2, 2026

Copy link


Copy Markdown

MemberAuthor
referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?
Sounds good! I've added it to my calendar! 😄
@chr-hertelchr-hertel
added

documentation
Improvements or additions to documentation
and removed

Status: Needs Decision

labels
Jan 23, 2026
jonathanhefnerand others
added 5 commits
February 1, 2026 16:14
@jonathanhefner@claude@chr-hertel
Add API documentation generation with phpDocumentor
03fce3f
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix phpDocumentor errors in type annotations
962a0d5
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix CI: pin phar-io/composer-distributor ^1.0.2
5f72f45
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Integrate markdown guides into phpDocumentor output
b0215a5
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@chr-hertel
Fine-tuning for path, config, and layout
5c20aa9
chr-hertel
chr-hertel
approved these changes
Feb 1, 2026
View reviewed changes
@chr-hertelchr-hertel
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @jonathanhefner for kicking this off 🙏 👍
Rebased, and added some tweaks regarding paths, layout and config.
@chr-hertelchr-hertel
removed
the 
needs more work
Not ready to be merged yet, needs additional follow-up from the author(s).
label
Feb 1, 2026
@chr-hertel
chr-hertel
commented
Feb 1, 2026

Copy link


Copy Markdown

Member
Some known issues regarding the markdown integration, see #232.
@chr-hertel
chr-hertel
merged commit 940eb90
into
modelcontextprotocol:mainFeb 1, 2026

16 checks passed

sveneld pushed a commit
to sveneld/php-sdk
that referenced
this pull request
Feb 8, 2026
@jonathanhefner@claude
@chr-hertelVolodymyr Panivko
Add API documentation generation with phpDocumentor (modelcontextprot…
77ae3c4
…ocol#184)
* Add API documentation generation with phpDocumentor
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix phpDocumentor errors in type annotations
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix CI: pin phar-io/composer-distributor ^1.0.2
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Integrate markdown guides into phpDocumentor output
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fine-tuning for path, config, and layout
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@NyholmNyholmNyholm left review comments
@chr-hertelchr-hertelchr-hertel approved these changes
@CodeWithKyrianCodeWithKyrianAwaiting requested review from CodeWithKyrianCodeWithKyrian is a code owner

+1 more reviewer

@scutuatua-cryptoscutuatua-cryptoscutuatua-crypto approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels

documentationImprovements or additions to documentation

Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

4 participants

@jonathanhefner@chr-hertel@Nyholm@scutuatua-crypto

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Add API documentation generation with phpDocumentor by jonathanhefner · Pull Request #184 · modelcontextprotocol/php-sdk · GitHub
Skip to content
Add API documentation generation with phpDocumentor - #184
Merged
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom 
jonathanhefner:deploy-docs
Feb 1, 2026
Merged
Add API documentation generation with phpDocumentor#184
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom 
jonathanhefner:deploy-docs
Conversation
@jonathanhefner
@jonathanhefnerjonathanhefner
commented
Dec 11, 2025•

edited

Loading

Copy link


Copy Markdown

Member
  • Add phpDocumentor configuration and docs Makefile target
  • Generate docs during CI to catch errors before releases
  • Set up GitHub Pages with Jekyll for hosting generated docs
  • Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with Claude Code
This PR also includes a commit to fix existing doc errors from phpDocumentor.
You can preview the generated documentation at http://jonathanhefner.github.io/mcp-php-sdk/api/.
@chr-hertel
chr-hertel
commented
Dec 11, 2025

Copy link


Copy Markdown

Member
Hi @jonathanhefner - thanks for that proposal, is that related to the discussion we had Tuesday about standardizing SDK docs? Having that on my desk as an open issue to follow up on ...
@jonathanhefner
jonathanhefner
commented
Dec 11, 2025

Copy link


Copy Markdown

MemberAuthor
@chr-hertel I wasn't aware of a discussion, but it might be. 😄 The context is: I am trying to ensure that all MCP SDKs have documentation available at https://modelcontextprotocol.github.io/*-sdk/.
@chr-hertel
chr-hertel
commented
Dec 11, 2025

Copy link


Copy Markdown

Member
Yup, that's exactly what we want to look at - awesome!

Don't have time tonight, but will def come back this, thanks!
Nyholm
Nyholm
reviewed
Dec 16, 2025
View reviewed changes
@NyholmNyholm
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you.
Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json
(Make those changes in a separate PR if you think we should merge them)
@jonathanhefner
jonathanhefner
commented
Dec 16, 2025

Copy link


Copy Markdown

MemberAuthor
Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json
Those changes are related. The changes to MessageFactory (in commit a97a5dc) are because the previous syntax is incompatible with phpDocumentor, and would cause the build to fail during the documentation generation step.
The changes in composer.json are due to "sort-packages": true, which predates this PR:
php-sdk/composer.json

Lines 70 to 75
in
69cd04f
"config": { 
"sort-packages": true, 
"allow-plugins": { 
"php-http/discovery": false
 } 
 } 
How would you like me to proceed?
@Nyholm
Nyholm
commented
Dec 27, 2025

Copy link


Copy Markdown

Contributor
Those changes are related.
Oh, okey.
Sorry, I did not know they were required.
How would you like me to proceed?
I need to you rebase your PR so I can merge.
Can you also link similar PRs to other SDKs?
@NyholmNyholm
added
the 
needs more work
Not ready to be merged yet, needs additional follow-up from the author(s).
label
Dec 27, 2025
@chr-hertel
chr-hertel
commented
Dec 27, 2025

Copy link


Copy Markdown

Member
Looks like @jonathanhefner was basically already all over the place - awesome!

I also tried to get some overview - and made some notes.
SDK Repos & their docs:
That's what I could find ... no guarantee for completeness :D
My proposal going forward, and to be aligned in sdk-maintainer circle, would rather be a combination of three things - ofc heavily based on what we have right now across the SDKs:
  1. Have a Readme with standardized elements (e.g. SDK Tier, Conformance Score, reference to Spec, GitHub Pages, etc.) but open for more if maintainers would want to
  2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
  3. Package specific documentation, see pkg.go.dev or packagist.org
I don't know about API docs tbh, at least in PHP they are not that relevant anymore, and I would rather not focus on them - might differ for other ecosystems, but could be an optional part of the GitHub Pages maybe.
@jonathanhefner
jonathanhefner
commented
Dec 29, 2025

Copy link


Copy Markdown

MemberAuthor
I need to you rebase your PR so I can merge.
Rebased!
@jonathanhefner
jonathanhefner
commented
Dec 31, 2025

Copy link


Copy Markdown

MemberAuthor
2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
I just pushed a commit that bundles the Markdown guides into the phpDocumentor output. They are accessible via a "Guides" link in the upper right-hand corner:
Guides IndexMCP ElementsExamples
01-index02-mcp-elements03-examples
(Due to the design of phpDocumentor, adding a "Guides" link in the top nav was the most maintainable approach, but I can pursue other options if you are open to maintaining more significant template overrides.)
@chr-hertel
chr-hertel
commented
Jan 2, 2026

Copy link


Copy Markdown

Member
@jonathanhefner referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?
@jonathanhefner
jonathanhefner
commented
Jan 2, 2026

Copy link


Copy Markdown

MemberAuthor
referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?
Sounds good! I've added it to my calendar! 😄
@chr-hertelchr-hertel
added

documentation
Improvements or additions to documentation
and removed

Status: Needs Decision

labels
Jan 23, 2026
jonathanhefnerand others
added 5 commits
February 1, 2026 16:14
@jonathanhefner@claude@chr-hertel
Add API documentation generation with phpDocumentor
03fce3f
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix phpDocumentor errors in type annotations
962a0d5
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix CI: pin phar-io/composer-distributor ^1.0.2
5f72f45
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Integrate markdown guides into phpDocumentor output
b0215a5
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@chr-hertel
Fine-tuning for path, config, and layout
5c20aa9
chr-hertel
chr-hertel
approved these changes
Feb 1, 2026
View reviewed changes
@chr-hertelchr-hertel
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @jonathanhefner for kicking this off 🙏 👍
Rebased, and added some tweaks regarding paths, layout and config.
@chr-hertelchr-hertel
removed
the 
needs more work
Not ready to be merged yet, needs additional follow-up from the author(s).
label
Feb 1, 2026
@chr-hertel
chr-hertel
commented
Feb 1, 2026

Copy link


Copy Markdown

Member
Some known issues regarding the markdown integration, see #232.
@chr-hertel
chr-hertel
merged commit 940eb90
into
modelcontextprotocol:mainFeb 1, 2026

16 checks passed

sveneld pushed a commit
to sveneld/php-sdk
that referenced
this pull request
Feb 8, 2026
@jonathanhefner@claude
@chr-hertelVolodymyr Panivko
Add API documentation generation with phpDocumentor (modelcontextprot…
77ae3c4
…ocol#184)
* Add API documentation generation with phpDocumentor
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix phpDocumentor errors in type annotations
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix CI: pin phar-io/composer-distributor ^1.0.2
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Integrate markdown guides into phpDocumentor output
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fine-tuning for path, config, and layout
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@NyholmNyholmNyholm left review comments
@chr-hertelchr-hertelchr-hertel approved these changes
@CodeWithKyrianCodeWithKyrianAwaiting requested review from CodeWithKyrianCodeWithKyrian is a code owner

+1 more reviewer

@scutuatua-cryptoscutuatua-cryptoscutuatua-crypto approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels

documentationImprovements or additions to documentation

Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

4 participants

@jonathanhefner@chr-hertel@Nyholm@scutuatua-crypto

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
Add API documentation generation with phpDocumentor by jonathanhefner · Pull Request #184 · modelcontextprotocol/php-sdk · GitHub
Skip to content
Add API documentation generation with phpDocumentor - #184
Merged
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom 
jonathanhefner:deploy-docs
Feb 1, 2026
Merged
Add API documentation generation with phpDocumentor#184
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom 
jonathanhefner:deploy-docs
Conversation
@jonathanhefner
@jonathanhefnerjonathanhefner
commented
Dec 11, 2025•

edited

Loading

Copy link


Copy Markdown

Member
  • Add phpDocumentor configuration and docs Makefile target
  • Generate docs during CI to catch errors before releases
  • Set up GitHub Pages with Jekyll for hosting generated docs
  • Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with Claude Code
This PR also includes a commit to fix existing doc errors from phpDocumentor.
You can preview the generated documentation at http://jonathanhefner.github.io/mcp-php-sdk/api/.
@chr-hertel
chr-hertel
commented
Dec 11, 2025

Copy link


Copy Markdown

Member
Hi @jonathanhefner - thanks for that proposal, is that related to the discussion we had Tuesday about standardizing SDK docs? Having that on my desk as an open issue to follow up on ...
@jonathanhefner
jonathanhefner
commented
Dec 11, 2025

Copy link


Copy Markdown

MemberAuthor
@chr-hertel I wasn't aware of a discussion, but it might be. 😄 The context is: I am trying to ensure that all MCP SDKs have documentation available at https://modelcontextprotocol.github.io/*-sdk/.
@chr-hertel
chr-hertel
commented
Dec 11, 2025

Copy link


Copy Markdown

Member
Yup, that's exactly what we want to look at - awesome!

Don't have time tonight, but will def come back this, thanks!
Nyholm
Nyholm
reviewed
Dec 16, 2025
View reviewed changes
@NyholmNyholm
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you.
Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json
(Make those changes in a separate PR if you think we should merge them)
@jonathanhefner
jonathanhefner
commented
Dec 16, 2025

Copy link


Copy Markdown

MemberAuthor
Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json
Those changes are related. The changes to MessageFactory (in commit a97a5dc) are because the previous syntax is incompatible with phpDocumentor, and would cause the build to fail during the documentation generation step.
The changes in composer.json are due to "sort-packages": true, which predates this PR:
php-sdk/composer.json

Lines 70 to 75
in
69cd04f
"config": { 
"sort-packages": true, 
"allow-plugins": { 
"php-http/discovery": false
 } 
 } 
How would you like me to proceed?
@Nyholm
Nyholm
commented
Dec 27, 2025

Copy link


Copy Markdown

Contributor
Those changes are related.
Oh, okey.
Sorry, I did not know they were required.
How would you like me to proceed?
I need to you rebase your PR so I can merge.
Can you also link similar PRs to other SDKs?
@NyholmNyholm
added
the 
needs more work
Not ready to be merged yet, needs additional follow-up from the author(s).
label
Dec 27, 2025
@chr-hertel
chr-hertel
commented
Dec 27, 2025

Copy link


Copy Markdown

Member
Looks like @jonathanhefner was basically already all over the place - awesome!

I also tried to get some overview - and made some notes.
SDK Repos & their docs:
That's what I could find ... no guarantee for completeness :D
My proposal going forward, and to be aligned in sdk-maintainer circle, would rather be a combination of three things - ofc heavily based on what we have right now across the SDKs:
  1. Have a Readme with standardized elements (e.g. SDK Tier, Conformance Score, reference to Spec, GitHub Pages, etc.) but open for more if maintainers would want to
  2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
  3. Package specific documentation, see pkg.go.dev or packagist.org
I don't know about API docs tbh, at least in PHP they are not that relevant anymore, and I would rather not focus on them - might differ for other ecosystems, but could be an optional part of the GitHub Pages maybe.
@jonathanhefner
jonathanhefner
commented
Dec 29, 2025

Copy link


Copy Markdown

MemberAuthor
I need to you rebase your PR so I can merge.
Rebased!
@jonathanhefner
jonathanhefner
commented
Dec 31, 2025

Copy link


Copy Markdown

MemberAuthor
2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
I just pushed a commit that bundles the Markdown guides into the phpDocumentor output. They are accessible via a "Guides" link in the upper right-hand corner:
Guides IndexMCP ElementsExamples
01-index02-mcp-elements03-examples
(Due to the design of phpDocumentor, adding a "Guides" link in the top nav was the most maintainable approach, but I can pursue other options if you are open to maintaining more significant template overrides.)
@chr-hertel
chr-hertel
commented
Jan 2, 2026

Copy link


Copy Markdown

Member
@jonathanhefner referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?
@jonathanhefner
jonathanhefner
commented
Jan 2, 2026

Copy link


Copy Markdown

MemberAuthor
referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?
Sounds good! I've added it to my calendar! 😄
@chr-hertelchr-hertel
added

documentation
Improvements or additions to documentation
and removed

Status: Needs Decision

labels
Jan 23, 2026
jonathanhefnerand others
added 5 commits
February 1, 2026 16:14
@jonathanhefner@claude@chr-hertel
Add API documentation generation with phpDocumentor
03fce3f
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix phpDocumentor errors in type annotations
962a0d5
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix CI: pin phar-io/composer-distributor ^1.0.2
5f72f45
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Integrate markdown guides into phpDocumentor output
b0215a5
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@chr-hertel
Fine-tuning for path, config, and layout
5c20aa9
chr-hertel
chr-hertel
approved these changes
Feb 1, 2026
View reviewed changes
@chr-hertelchr-hertel
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @jonathanhefner for kicking this off 🙏 👍
Rebased, and added some tweaks regarding paths, layout and config.
@chr-hertelchr-hertel
removed
the 
needs more work
Not ready to be merged yet, needs additional follow-up from the author(s).
label
Feb 1, 2026
@chr-hertel
chr-hertel
commented
Feb 1, 2026

Copy link


Copy Markdown

Member
Some known issues regarding the markdown integration, see #232.
@chr-hertel
chr-hertel
merged commit 940eb90
into
modelcontextprotocol:mainFeb 1, 2026

16 checks passed

sveneld pushed a commit
to sveneld/php-sdk
that referenced
this pull request
Feb 8, 2026
@jonathanhefner@claude
@chr-hertelVolodymyr Panivko
Add API documentation generation with phpDocumentor (modelcontextprot…
77ae3c4
…ocol#184)
* Add API documentation generation with phpDocumentor
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix phpDocumentor errors in type annotations
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix CI: pin phar-io/composer-distributor ^1.0.2
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Integrate markdown guides into phpDocumentor output
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fine-tuning for path, config, and layout
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@NyholmNyholmNyholm left review comments
@chr-hertelchr-hertelchr-hertel approved these changes
@CodeWithKyrianCodeWithKyrianAwaiting requested review from CodeWithKyrianCodeWithKyrian is a code owner

+1 more reviewer

@scutuatua-cryptoscutuatua-cryptoscutuatua-crypto approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels

documentationImprovements or additions to documentation

Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

4 participants

@jonathanhefner@chr-hertel@Nyholm@scutuatua-crypto

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();
Add API documentation generation with phpDocumentor by jonathanhefner · Pull Request #184 · modelcontextprotocol/php-sdk · GitHub
Skip to content
Add API documentation generation with phpDocumentor - #184
Merged
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom 
jonathanhefner:deploy-docs
Feb 1, 2026
Merged
Add API documentation generation with phpDocumentor#184
chr-hertel merged 5 commits into
modelcontextprotocol:mainfrom 
jonathanhefner:deploy-docs
Conversation
@jonathanhefner
@jonathanhefnerjonathanhefner
commented
Dec 11, 2025•

edited

Loading

Copy link


Copy Markdown

Member
  • Add phpDocumentor configuration and docs Makefile target
  • Generate docs during CI to catch errors before releases
  • Set up GitHub Pages with Jekyll for hosting generated docs
  • Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with Claude Code
This PR also includes a commit to fix existing doc errors from phpDocumentor.
You can preview the generated documentation at http://jonathanhefner.github.io/mcp-php-sdk/api/.
@chr-hertel
chr-hertel
commented
Dec 11, 2025

Copy link


Copy Markdown

Member
Hi @jonathanhefner - thanks for that proposal, is that related to the discussion we had Tuesday about standardizing SDK docs? Having that on my desk as an open issue to follow up on ...
@jonathanhefner
jonathanhefner
commented
Dec 11, 2025

Copy link


Copy Markdown

MemberAuthor
@chr-hertel I wasn't aware of a discussion, but it might be. 😄 The context is: I am trying to ensure that all MCP SDKs have documentation available at https://modelcontextprotocol.github.io/*-sdk/.
@chr-hertel
chr-hertel
commented
Dec 11, 2025

Copy link


Copy Markdown

Member
Yup, that's exactly what we want to look at - awesome!

Don't have time tonight, but will def come back this, thanks!
Nyholm
Nyholm
reviewed
Dec 16, 2025
View reviewed changes
@NyholmNyholm
left a comment


Copy link


Copy Markdown

Contributor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you.
Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json
(Make those changes in a separate PR if you think we should merge them)
@jonathanhefner
jonathanhefner
commented
Dec 16, 2025

Copy link


Copy Markdown

MemberAuthor
Can you please remove the unrelated changes? Ie changes to MessageFactory and the style changes in composer.json
Those changes are related. The changes to MessageFactory (in commit a97a5dc) are because the previous syntax is incompatible with phpDocumentor, and would cause the build to fail during the documentation generation step.
The changes in composer.json are due to "sort-packages": true, which predates this PR:
php-sdk/composer.json

Lines 70 to 75
in
69cd04f
"config": { 
"sort-packages": true, 
"allow-plugins": { 
"php-http/discovery": false
 } 
 } 
How would you like me to proceed?
@Nyholm
Nyholm
commented
Dec 27, 2025

Copy link


Copy Markdown

Contributor
Those changes are related.
Oh, okey.
Sorry, I did not know they were required.
How would you like me to proceed?
I need to you rebase your PR so I can merge.
Can you also link similar PRs to other SDKs?
@NyholmNyholm
added
the 
needs more work
Not ready to be merged yet, needs additional follow-up from the author(s).
label
Dec 27, 2025
@chr-hertel
chr-hertel
commented
Dec 27, 2025

Copy link


Copy Markdown

Member
Looks like @jonathanhefner was basically already all over the place - awesome!

I also tried to get some overview - and made some notes.
SDK Repos & their docs:
That's what I could find ... no guarantee for completeness :D
My proposal going forward, and to be aligned in sdk-maintainer circle, would rather be a combination of three things - ofc heavily based on what we have right now across the SDKs:
  1. Have a Readme with standardized elements (e.g. SDK Tier, Conformance Score, reference to Spec, GitHub Pages, etc.) but open for more if maintainers would want to
  2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
  3. Package specific documentation, see pkg.go.dev or packagist.org
I don't know about API docs tbh, at least in PHP they are not that relevant anymore, and I would rather not focus on them - might differ for other ecosystems, but could be an optional part of the GitHub Pages maybe.
@jonathanhefner
jonathanhefner
commented
Dec 29, 2025

Copy link


Copy Markdown

MemberAuthor
I need to you rebase your PR so I can merge.
Rebased!
@jonathanhefner
jonathanhefner
commented
Dec 31, 2025

Copy link


Copy Markdown

MemberAuthor
2. Strong focus though on Markdown-based docs/ folder, to be deployed to GitHub Pages with streamlined layout and cross links between SDKs
I just pushed a commit that bundles the Markdown guides into the phpDocumentor output. They are accessible via a "Guides" link in the upper right-hand corner:
Guides IndexMCP ElementsExamples
01-index02-mcp-elements03-examples
(Due to the design of phpDocumentor, adding a "Guides" link in the top nav was the most maintainable approach, but I can pursue other options if you are open to maintaining more significant template overrides.)
@chr-hertel
chr-hertel
commented
Jan 2, 2026

Copy link


Copy Markdown

Member
@jonathanhefner referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?
@jonathanhefner
jonathanhefner
commented
Jan 2, 2026

Copy link


Copy Markdown

MemberAuthor
referenced this PR in the #general-sdk-dev channel to have a discussion next Friday in the monthly and decide how to move on with a bigger picture here - will you be there?
Sounds good! I've added it to my calendar! 😄
@chr-hertelchr-hertel
added

documentation
Improvements or additions to documentation
and removed

Status: Needs Decision

labels
Jan 23, 2026
jonathanhefnerand others
added 5 commits
February 1, 2026 16:14
@jonathanhefner@claude@chr-hertel
Add API documentation generation with phpDocumentor
03fce3f
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix phpDocumentor errors in type annotations
962a0d5
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Fix CI: pin phar-io/composer-distributor ^1.0.2
5f72f45
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@jonathanhefner@claude@chr-hertel
Integrate markdown guides into phpDocumentor output
b0215a5
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@chr-hertel
Fine-tuning for path, config, and layout
5c20aa9
chr-hertel
chr-hertel
approved these changes
Feb 1, 2026
View reviewed changes
@chr-hertelchr-hertel
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @jonathanhefner for kicking this off 🙏 👍
Rebased, and added some tweaks regarding paths, layout and config.
@chr-hertelchr-hertel
removed
the 
needs more work
Not ready to be merged yet, needs additional follow-up from the author(s).
label
Feb 1, 2026
@chr-hertel
chr-hertel
commented
Feb 1, 2026

Copy link


Copy Markdown

Member
Some known issues regarding the markdown integration, see #232.
@chr-hertel
chr-hertel
merged commit 940eb90
into
modelcontextprotocol:mainFeb 1, 2026

16 checks passed

sveneld pushed a commit
to sveneld/php-sdk
that referenced
this pull request
Feb 8, 2026
@jonathanhefner@claude
@chr-hertelVolodymyr Panivko
Add API documentation generation with phpDocumentor (modelcontextprot…
77ae3c4
…ocol#184)
* Add API documentation generation with phpDocumentor
- Add phpDocumentor configuration and `docs` Makefile target
- Generate docs during CI to catch errors before releases
- Set up GitHub Pages with Jekyll for hosting generated docs
- Add GitHub Actions workflow to deploy docs to GitHub Pages on releases
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix phpDocumentor errors in type annotations
Change class-string union types to use phpDocumentor-compatible syntax
and reorder docblock tags so class descriptions precede `@author` tags.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fix CI: pin phar-io/composer-distributor ^1.0.2
phar-io/composer-distributor 1.0.0 has a bug where it uses the wrong
package version when determining the phpDocumentor download URL,
causing CI to fail with 404 errors when using --prefer-lowest.
Version 1.0.2 fixes this issue.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Integrate markdown guides into phpDocumentor output
Configure phpDocumentor to generate both API documentation and user
guides in a single unified site. This replaces the previous Jekyll-based
approach where API docs were copied into the docs folder.
- Add `<guide>` configuration to `phpdoc.dist.xml`
- Create custom template with "Guides" navigation link
- Replace `docs/index.html` redirect with `docs/index.md` guide index
- Update workflow to publish `build/docs` directly without Jekyll
- Track `.phpdoc/template/` while still ignoring `.phpdoc/cache/`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* Fine-tuning for path, config, and layout
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment

Reviewers

@NyholmNyholmNyholm left review comments
@chr-hertelchr-hertelchr-hertel approved these changes
@CodeWithKyrianCodeWithKyrianAwaiting requested review from CodeWithKyrianCodeWithKyrian is a code owner

+1 more reviewer

@scutuatua-cryptoscutuatua-cryptoscutuatua-crypto approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees


No one assigned


Labels

documentationImprovements or additions to documentation

Projects


None yet


Milestone


No milestone


Development

Successfully merging this pull request may close these issues.

4 participants

@jonathanhefner@chr-hertel@Nyholm@scutuatua-crypto