Skip to content

docs: align docs IA with MCP specification structure#1481

Merged
jeffhandley merged 3 commits intomainfrom
copilot/update-docs-folder-for-apis
Apr 2, 2026
Merged

docs: align docs IA with MCP specification structure#1481
jeffhandley merged 3 commits intomainfrom
copilot/update-docs-folder-for-apis

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Mar 31, 2026

Align the information architecture of the concept docs with the MCP specification (2025-11-25) breakdown of Base Protocol, Client Features, and Server Features.

  • Add missing Tasks entry to Base Protocol section in concepts/index.md (already present in toc.yml)
  • Move Pagination from Base Protocol to Server Features in both index.md and toc.yml, matching its placement under server/utilities/ in the MCP spec

Copilot AI linked an issue Mar 31, 2026 that may be closed by this pull request
Copilot AI changed the title [WIP] Update docs folder to reflect updated APIs docs: sync concepts/index.md with toc.yml Mar 31, 2026
Copilot AI requested a review from jeffhandley March 31, 2026 18:45
@jeffhandley jeffhandley marked this pull request as ready for review April 1, 2026 20:15
@jeffhandley jeffhandley force-pushed the copilot/update-docs-folder-for-apis branch from 256ba48 to b14ab85 Compare April 2, 2026 16:47
@jeffhandley jeffhandley changed the title docs: sync concepts/index.md with toc.yml docs: add Tasks entry to the concept index page Apr 2, 2026
@jeffhandley jeffhandley requested a review from mikekistler April 2, 2026 16:51
@jeffhandley
Copy link
Copy Markdown
Contributor

@mikekistler This PR started from running a full audit over the docs compared to the public API surface for Update docs/ folder to reflect updated APIs (#782), but all that audit found was this missing link and an initial suggestion of moving 'Stateless and Stateful' from the server features list into the base protocol list. I disagreed with moving that link so I reverted that change and force-pushed to have this PR be strictly about adding the missing link for Tasks.

mikekistler
mikekistler previously approved these changes Apr 2, 2026
Copy link
Copy Markdown
Contributor

@mikekistler mikekistler left a comment

Choose a reason for hiding this comment

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

Looks good! 👍

@mikekistler
Copy link
Copy Markdown
Contributor

@jeffhandley related to the full audit, it has been my hope that we could keep the IA for our docs consistent with the MCP Spec. Putting "Tasks" under "Base Protocol" aligns with that. But I happened to notice that "Pagination" is in the "Base Protocol" section of our docs but under "Server Features" in the MCP Spec. Just thought I'd mention this to get your thoughts.

@jeffhandley
Copy link
Copy Markdown
Contributor

@copilot Heed the feedback from @mikekistler here about Pagination being more appropriate in "Server Features," and conduct a full audit of the information architecture within our /docs folder compared to the Specification - Model Context Protocol's breakdown of Base Protocol, Client Features, and Server Features. Present your findings and correct any other discrepancies to align with the specification.

Copy link
Copy Markdown
Contributor Author

Copilot AI commented Apr 2, 2026

@copilot Heed the feedback from @mikekistler here about Pagination being more appropriate in "Se...

Audited the IA against the MCP specification (2025-11-25):

MCP spec structure:

  • basic/utilities/: Cancellation, Ping, Progress, Tasks
  • client/: Sampling, Roots, Elicitation
  • server/: Tools, Resources, Prompts; server/utilities/: Completion, Logging, Pagination

Discrepancy found: Pagination was under Base Protocol in our docs but belongs in server/utilities/ in the spec. Moved it to Server Features in both index.md and toc.yml in commit 0eaa35a.

All other items already align — Capabilities, Stateless/Stateful, HTTP Context, and Filters are SDK-specific docs with no direct spec equivalent, so their placement is an editorial choice rather than a spec alignment issue.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • modelcontextprotocol.io
    • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Copilot AI changed the title docs: add Tasks entry to the concept index page docs: align docs IA with MCP specification structure Apr 2, 2026
Copilot AI requested a review from jeffhandley April 2, 2026 20:49
@jeffhandley jeffhandley merged commit dfa9342 into main Apr 2, 2026
@jeffhandley jeffhandley deleted the copilot/update-docs-folder-for-apis branch April 2, 2026 23:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Update docs/ folder to reflect updated APIs

3 participants