Repository navigation
docs(mcpx): stand up the mdBook book and .#mcpx-docs flake output (#1939) #2629
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
7530992
docs(mcpx): stand up the mdBook book and .#mcpx-docs flake output (#1…
dezren39 49fe420
docs(mcpx): register SUMMARY.md in the compendium manifest (#1939)
dezren39 684a133
docs(mcpx): rewrite out-of-book links to repository URLs in the .#mcp…
dezren39 43f24bd
ci: retrigger workflows on current head (#1939)
dezren39 4de2f18
Merge remote-tracking branch 'origin/main' into queue/3236-1939-mcpx-…
dezren39 9ca8f80
docs(mcpx): register docs/testing/feature-inventory.md in the compend…
dezren39 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| # mdBook configuration for the mcpx book (#1939, Approach C). | ||
| # The book root is pkgs/mcpx itself so the sources stay where they have | ||
| # always lived: plain markdown under docs/, rendered on GitHub exactly | ||
| # as before, and now also as a book via the .#mcpx-docs flake output. | ||
| [book] | ||
| title = "mcpx" | ||
| authors = ["developing-today"] | ||
| language = "en" | ||
| src = "docs" | ||
|
|
||
| [build] | ||
| build-dir = "book" | ||
| # Every chapter in SUMMARY.md must exist on disk; never invent stubs. | ||
| create-missing = false | ||
|
|
||
| [output.html] | ||
| git-repository-url = "https://github.com/developing-today/code" |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| # The mcpx book (#1939, Approach C): render pkgs/mcpx/docs with mdBook | ||
| # into static HTML, sandboxed, with the flake-pinned mdbook from | ||
| # nixpkgs and no network access. Exposed as the .#mcpx-docs flake | ||
| # output, so CI builds it through the ordinary flake-check path like | ||
| # every other output. | ||
| { | ||
| lib, | ||
| runCommand, | ||
| mdbook, | ||
| }: | ||
| let | ||
| # Only the book inputs enter the store: book.toml plus the docs tree. | ||
| # The Go sources next to them are not book content and stay out. | ||
| src = lib.fileset.toSource { | ||
| root = ./.; | ||
| fileset = lib.fileset.unions [ | ||
| ./book.toml | ||
| ./docs | ||
| ]; | ||
| }; | ||
| in | ||
| runCommand "mcpx-docs" | ||
| { | ||
| nativeBuildInputs = [ mdbook ]; | ||
| meta = { | ||
| description = "mcpx documentation book (mdBook rendering of pkgs/mcpx/docs)"; | ||
| homepage = "https://github.com/developing-today/code"; | ||
| license = with lib.licenses; [ | ||
| mit | ||
| asl20 | ||
| ]; | ||
| }; | ||
| } | ||
| '' | ||
| cp -r ${src} work | ||
| chmod -R u+w work | ||
| cd work | ||
| # Links that escape the book source tree would 404 in the rendered | ||
| # book: from docs/, ../AGENTS.md means pkgs/mcpx/AGENTS.md, which is | ||
| # not part of the artifact. Rewrite those links - in the copied | ||
| # pages only, the sources keep their relative links for GitHub - to | ||
| # the file's repository URL, at the depth where the link escapes: | ||
| # ../ from a top-level page, ../../ from a page one directory down. | ||
| # Links that stay inside docs/ are left for mdBook to resolve. | ||
| repoURL="https://github.com/developing-today/code/blob/main/pkgs/mcpx/" | ||
| find docs -maxdepth 1 -name '*.md' -exec sed -i \ | ||
| "s|](\.\./|](''${repoURL}|g" {} + | ||
| find docs -mindepth 2 -maxdepth 2 -name '*.md' -exec sed -i \ | ||
| "s|](\.\./\.\./|](''${repoURL}|g" {} + | ||
| mdbook build --dest-dir $out | ||
| '' | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,105 @@ | ||
| # Summary | ||
|
|
||
| - [Archive](archive.md) | ||
| - [The binary](binary.md) | ||
| - [The CLI](cli.md) | ||
| - [The compendium: structure and mapping](compendium.md) | ||
| - [Configuration](configuration.md) | ||
| - [mcpx as a consumer](consumer.md) | ||
| - [Running mcpx in a container](container.md) | ||
| - [Declared but never read](declared-but-unread.md) | ||
| - [Dependencies](dependencies.md) | ||
| - [Elicitation: a design](elicitation.md) | ||
| - [The script environment](environment.md) | ||
| - [Examples](examples.md) | ||
| - [exec and artifacts](exec.md) | ||
| - [FAQ](faq.md) | ||
| - [Finding the repository without git](git-discovery.md) | ||
| - [The home-page example: copy it or run it in the page](home-example.md) | ||
| - [The /v1 HTTP API](http-api.md) | ||
| - [Ideas](ideas.md) | ||
| - [In name only](in-name-only.md) | ||
| - [Install](install.md) | ||
| - [Interfaces](interfaces.md) | ||
| - [Landing checklist](landing.md) | ||
| - [mcpx level-2 page map](level-2-page-map.md) | ||
| - [MCP](mcp.md) | ||
| - [Now what](now-what.md) | ||
| - [The opencode v2 plugin — verified API facts and implementation map](opencode-plugin-v2.md) | ||
| - [The opencode plugin](opencode-plugin.md) | ||
| - [Overview](overview.md) | ||
| - [Parity](parity.md) | ||
| - [Finding the daemon without the binary](plugin-discovery.md) | ||
| - [Plugins](plugins.md) | ||
| - [Proposals](proposals.md) | ||
| - [Protocol: every revision, both directions](protocol.md) | ||
| - [Quick start](quick-start.md) | ||
| - [Release runbook](release-runbook.md) | ||
| - [Reaching a daemon on another machine](remote.md) | ||
| - [Script runtimes, permission profiles and presets](runtimes.md) | ||
| - [Schema validation (`internal/schemaval`)](schema-validation.md) | ||
| - [Scripts](scripts.md) | ||
| - [mcpx](story.md) | ||
| - [mcpx Development Strategies & Lessons Learned](work-strategies.md) | ||
| - [Audit]() | ||
| - [Audit: features (end to end)](audit/features.md) | ||
| - [Audit: the MCP specification (area `spec`)](audit/spec.md) | ||
| - [Audit: mcpx's own surface](audit/surface.md) | ||
| - [Catalogue](catalogue/README.md) | ||
| - [Comparisons](compare/README.md) | ||
| - [The comparison chapter](compare/chapter.md) | ||
| - [Communication conflicts](compare/conflicts.md) | ||
| - [Content types through mcpx: did it need them?](compare/content-passthrough.md) | ||
| - [History](compare/history.md) | ||
| - [What `input_required` is](compare/input-required.md) | ||
| - [Code mode capability matrix](compare/matrix-code-mode.md) | ||
| - [mcpx × revisions, both directions](compare/matrix-mcpx.md) | ||
| - [opencode v1 vs v2](compare/matrix-opencode.md) | ||
| - [MCP revisions × features](compare/matrix-revisions.md) | ||
| - [Stateless and every revision: can mcpx do both?](compare/stateless.md) | ||
| - [What each says a server should be](compare/what-a-server-should-be.md) | ||
| - [Register]() | ||
| - [Authorization](compare/register/auth.md) | ||
| - [Capabilities](compare/register/capabilities.md) | ||
| - [Code mode and script execution](compare/register/code-mode.md) | ||
| - [Completion](compare/register/completion.md) | ||
| - [Content types](compare/register/content-types.md) | ||
| - [Elicitation](compare/register/elicitation.md) | ||
| - [Errors](compare/register/errors.md) | ||
| - [Lifecycle and versioning](compare/register/lifecycle-versioning.md) | ||
| - [Logging](compare/register/logging.md) | ||
| - [`_meta`](compare/register/meta.md) | ||
| - [Multi round-trip requests (the 2026 `input_required` mechanism)](compare/register/mrtr.md) | ||
| - [Subscriptions and notifications](compare/register/notifications.md) | ||
| - [Pagination and caching](compare/register/pagination-caching.md) | ||
| - [Plugin APIs (opencode v1 and v2) and harness integration](compare/register/plugin-apis.md) | ||
| - [Process model and statelessness](compare/register/process-model.md) | ||
| - [Progress and cancellation](compare/register/progress-cancellation.md) | ||
| - [Prompts](compare/register/prompts.md) | ||
| - [Resources](compare/register/resources.md) | ||
| - [Roots](compare/register/roots.md) | ||
| - [Sampling](compare/register/sampling.md) | ||
| - [Tasks](compare/register/tasks.md) | ||
| - [Tools](compare/register/tools.md) | ||
| - [Transports](compare/register/transports.md) | ||
| - [Decisions](decisions/README.md) | ||
| - [0001 — One hook vocabulary, and where a hook's output goes in the exec stream](decisions/0001-hook-vocabulary.md) | ||
| - [0002 — One autonomy dial, and a ceiling the daemon sets](decisions/0002-autonomy-dial.md) | ||
| - [0003 — What mcpx declares, and what it enforces](decisions/0003-declared-vs-enforced-capabilities.md) | ||
| - [0004 — Scope-resolved roots: spawn cwd, `${mcpx.root}` substitution, initialize workspace](decisions/0004-scope-resolved-roots.md) | ||
| - [0005 — Release pipeline, version single-sourcing, and the module path](decisions/0005-release-pipeline.md) | ||
| - [0006 — TTLs renew by touch-on-read, bounded by a maxAge ceiling](decisions/0006-ttl-touch-on-read.md) | ||
| - [The home-page example component](home-example/README.md) | ||
| - [docs/spec](spec/README.md) | ||
| - [What the specification asks of a client](spec/client-obligations.md) | ||
| - [mcpx as a client: every revision](spec/client.md) | ||
| - [MCP conformance matrix](spec/conformance-matrix.md) | ||
| - [The conformance matrix](spec/conformance.md) | ||
| - [Upstream era probe](spec/era-probe.md) | ||
| - [Who an MCP request is from](spec/identity.md) | ||
| - [What mcpx sends, per revision](spec/messages.md) | ||
| - [The official conformance suite, run against mcpx](spec/official-suite.md) | ||
| - [MCP normative requirements, every revision, both sides](spec/requirements.md) | ||
| - [Revision conflicts and spec-internal contradictions](spec/revision-conflicts.md) | ||
| - [What the specification asks of a server](spec/server-obligations.md) | ||
| - [mcpx as a server: the transport](spec/transport.md) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When readers use the rendered book, links to files outside
docs/lead outside the generated artifact instead of to their existing repository targets. For example,quick-start.md:49directs readers to../AGENTS.mdto configure their agent, whilestory.mdlinks to../daemon/README.mdand maintenance scripts. Repository-tree inspection confirms those targets exist, but this fileset excludes them and the build provides no link rewriting or corresponding output files. Rewrite these links to repository URLs or explicitly include and publish the referenced resources so the book's onboarding and operational instructions remain usable.Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed in 684a133 (pushed to this PR).
The build in
pkgs/mcpx/docs.nixnow rewrites links that escape the book source tree — in the copied pages only — to the target file's repository URL, at the depth where each link escapes:../from a top-level page and../../from a page one directory down both resolve topkgs/mcpx/<target>, i.e.https://github.com/developing-today/code/blob/main/pkgs/mcpx/<target>. The sources keep their relative links (which keep working on GitHub), and links that stay insidedocs/are left for mdBook to resolve.Verified locally at the pushed head:
nix build .#mcpx-docssucceeds; the renderedstory.htmlcarries 9 rewritten links (including../AGENTS.md),compare/history.htmlcarries 6, nohref="../AGENTS.md"remains, and in-book links such as../story.htmlare untouched.