You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maka.apache.org by "chinawch007 (via GitHub)" <gi...@apache.org> on 2026/08/24 19:57:37 UTC
[PR] feat(storybook): expose component docs to agents via official MCP addon (#3527) [maka]
chinawch007 opened a new pull request, #3736:
URL: https://github.com/apache/maka/pull/3736
## Summary
Agents writing UI code in this repo had no machine-readable interface to
learn which components exist and how to use them, so they grepped and read
component sources to guess props and usage. This PR self-hosts Storybook's
official MCP addon at `http://localhost:6006/mcp`, exposing the docs
toolset only, so agents can query the existing story catalog before
writing code.
- `apps/desktop`: install `@storybook/addon-mcp` and register it in
`.storybook/main.ts` with `toolsets: { dev: false, test: false, docs: true }`
(test toolset needs `@storybook/addon-vitest` and stays a follow-up per
the issue)
- new root `.mcp.json` registering the endpoint for agent clients
- new root `AGENTS.md`: start Storybook on demand, query
`list-all-documentation` / `get-documentation` before writing UI code,
prefer existing `packages/ui` components
Fixes #3527
## Verification
Manual verification succeeded against a running dev server:
- `npm --workspace @maka/desktop run storybook -- --no-open` boots
unchanged; existing stories render as before
- MCP `initialize` over `POST /mcp` returns a session id
- `tools/list` exposes exactly the three docs tools — `list-all-documentation`,
`get-documentation`, `get-documentation-for-story` — confirming the
dev/test toolsets are off:
```
tool count: 3
- list-all-documentation
- get-documentation
- get-documentation-for-story
```
- all three tools return real content, e.g. `get-documentation` for
`primitives-toast` returns the story list with usage snippets
- `npm run lint` and `npm run format:check` pass
Not run / known gaps: full `npm run build` and `npm test` (config-only
change, no unit suite covers Storybook config); desktop-workspace
typecheck reports 40 pre-existing errors that reproduce identically on
clean `main` in this environment (stale workspace dists) — none touch the
changed files, which typecheck clean.
## Review focus
- `.mcp.json` uses the `"type": "http"` + `"url"` client convention
(Claude Code / Cursor-class agent CLIs), not an MCP spec format; it is
dev-time tooling config, unrelated to `packages/mcp`'s product config.
`$schema` is omitted — no official schema covers this client format.
- `.github/copilot-instructions.md` (code-review guidance only) and the new
`AGENTS.md` cover disjoint topics; `AGENTS.md` is the cross-tool
canonical location. Mirroring into copilot-instructions.md is left as a
maintainer decision.
## AI use
Select exactly one:
- [ ] No generative tool made a substantive contribution
- [x] Generative tooling made a substantive contribution
Tool(s) and scope: ZCode authored the config and documentation changes and
ran the verification above; the human contributor reviewed the result and
performed the final verification on a live server.
## Checklist
- [ ] Tests cover the change and fail without it
- [x] Lint, format, typecheck and the affected suites pass locally
Does this PR entail a change in behavior?
- [ ] Yes — described under Summary above
- [x] No
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org
Re: [PR] feat(storybook): expose component docs to agents via official MCP addon (#3527) [maka]
Posted by "chinawch007 (via GitHub)" <gi...@apache.org>.
chinawch007 commented on PR #3736:
URL: https://github.com/apache/maka/pull/3736#issuecomment-5457085865
Thanks for the depth of this review — the "right seam, wrong authority" framing
is correct, and we independently verified the factual basis of both findings
(the `WORKSPACE_INSTRUCTION_FILES` injection, the addon's instructions string,
and the coverage gap; our count is 5 of 27 story files declaring
`meta.component`). Both P1 and P2 reduce to decisions we don't think this PR
should make unilaterally, so we're laying out the trade-offs and asking for a
maintainer call.
## P1 — AGENTS.md: the issue's ask and the repo's reality are in conflict
Issue #3527 explicitly asks for usage guidance in a root `AGENTS.md` ("query
docs before writing frontend code"). Your two findings explain why that ask
can't be satisfied as written:
- the path is deliberately untracked and maintainers keep local copies — a
tracked file breaks their checkouts;
- via `WORKSPACE_INSTRUCTION_FILES` the file becomes product behavior (injected
into Maka's own system prompt), and our draft restated `DESIGN.md`'s
authority more weakly — `packages/ui`-first, no Astryx — which is exactly
the third, weaker representation the review objects to.
So the dilemma is real: omitting the file leaves the issue's guidance ask
unmet; shipping it creates the checkout collision and installs a competing
authority. We'd rather hand the whole question to maintainers than pick a side
inside this PR: whether this PR ships the file at all, and where the guidance
should live (a tracked `AGENTS.md` after resolving the local-file convention,
an opt-in snippet in CONTRIBUTING, or elsewhere) — and in every case it must
be reconciled with `DESIGN.md` (Astryx first, then `packages/ui`, then new
components) rather than restate it more weakly.
One mitigating fact worth putting on the record: the core propagation the
issue wanted — agents querying the catalog before writing UI — is already
carried by the MCP registration itself. Clients that discover `.mcp.json` get
the addon's server instructions directing them to the docs tools. What an
`AGENTS.md` would additionally carry is when-to-start-Storybook and the
Astryx-first hierarchy, which is precisely the part needing the authority
reconciliation above.
## P2 — the injected instructions vs. our catalog coverage
We confirmed the injected string ("Undocumented props do not exist — ... not
source or types") and that our tree can't back it. On the two in-repo paths:
**Coverage first.** The cost is not writing the stories — it's the judgment
and review inside them:
- `meta.component` + autodocs across the existing stories is mechanical and we
can land it quickly;
- Astryx coverage is the real cost. `@astryxdesign/core` exports 100+
components. Stories that merely render a component are cheap and worthless
here — the catalog needs `DESIGN.md`-canonical usage per primitive
(`isLoading` states, control heights, status vocabulary), which is
per-component design judgment, and every file then needs human design
review. The review queue, not generation, is the long pole. A scoped set
covering the primitives `DESIGN.md` actually names (Button + `isLoading`,
Badge, StatusDot, the Field family, Spinner, Skeleton, …) is ~10–15
components and reviewable; full-library coverage is a multi-cycle effort we
don't think should gate this PR.
- For fairness of accounting: this coverage work stands on its own as
Storybook hygiene (human docs, Astryx upgrade canary) — worth doing for
those reasons regardless of this addon.
**Local patch.** Replacing the injected instructions with a repo-authored
string via the dependency-patch mechanism is small, testable, and does return
authority to the repo (patch mismatch also fails loudly on version bumps,
forcing re-review). The downsides: it carries a fork of vendor behavior
indefinitely — every bump re-derives the patch — and it papers over the
coverage gap rather than closing it.
**The call we'd like from maintainers:** (1) merge the interface with the
injected-instructions risk disclosed and coverage tracked as a follow-up;
(2) require the scoped coverage set first — we'll draft it for review;
(3) require the patch. We're ready to execute whichever is chosen.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org
Re: [PR] feat(storybook): expose component docs to agents via official MCP addon (#3527) [maka]
Posted by "Astro-Han (via GitHub)" <gi...@apache.org>.
Astro-Han commented on code in PR #3736:
URL: https://github.com/apache/maka/pull/3736#discussion_r4192540135
##########
patches/README.md:
##########
@@ -142,6 +142,18 @@ request funnel has no public observer-lifetime hook for a call-site fix.
Delete the patch when upstream releases settled request observers despite transport backpressure.
+## `@storybook/addon-mcp@0.7.0`
+
+The upstream MCP instructions treat Storybook documentation as an exhaustive
+catalog and prohibit consulting source or type declarations. Maka's catalog is
Review Comment:
P3: this patch replaces the server `instructions`, but the addon also registers tools whose descriptions come from `@storybook/mcp@0.8.0` (imported at `preset.js:11`, unpatched). `get-documentation` still says "reading or grepping the component source is not a substitute", and `list-all-documentation` says "discover the relevant IDs here rather than reading component source". Clients inject tool descriptions too, so agents still see a version of the source/types prohibition next to the patched fallback. Either patch those two descriptions in `@storybook/mcp`, or scope this paragraph (and the `LICENSE` entry) to the server instructions and note the residual.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org
Re: [PR] feat(storybook): expose component docs to agents via official MCP addon (#3527) [maka]
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #3736:
URL: https://github.com/apache/maka/pull/3736#issuecomment-5987850748
<!-- maka-lifecycle:stale-warning -->
This pull request has had no new commits for 30 days and has been marked stale. It will be closed in 7 days unless a new commit is pushed.
Comments do not reset this timer: only a new commit does. If the pull request is intentionally long-lived, a maintainer can apply the `pinned` label.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org
Re: [PR] feat(storybook): expose component docs to agents via official MCP addon (#3527) [maka]
Posted by "chinawch007 (via GitHub)" <gi...@apache.org>.
chinawch007 commented on PR #3736:
URL: https://github.com/apache/maka/pull/3736#issuecomment-5522106398
如果我们添加agents.md，会跟开发者自己的agents.md相冲突，当前替代方案是用contribute.md引导开发者agent使用storybook-mcp。
虽然当前maka的storybook覆盖率不够，但仍然可以用local patch的方式使得其立刻发挥有限的效用。
因为前端组件的story描述需要契合design.md的要求，推进需要人工仔细审查，所以没办法用ai机械地修改，所以对于当前未被覆盖的前端组件，建议另开issue来逐步推进覆盖率，不在这个PR中进行。
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org
Re: [PR] feat(storybook): expose component docs to agents via official MCP addon (#3527) [maka]
Posted by "chinawch007 (via GitHub)" <gi...@apache.org>.
chinawch007 commented on PR #3736:
URL: https://github.com/apache/maka/pull/3736#issuecomment-5521572610
Thanks for the detailed review. I agree with the “right seam, wrong authority” framing. I have rebased the branch onto the latest `main` and taken the local-patch path discussed above, with this update focused specifically on the two blocking findings in [your review](https://github.com/apache/maka/pull/3736#pullrequestreview-5037123151).
## Summary of the update
- Removed the root `AGENTS.md`.
- Moved the on-demand Storybook startup workflow into `CONTRIBUTING.md`, with the corresponding update in `CONTRIBUTING.zh-CN.md`.
- Added a repository-owned dependency patch for `@storybook/addon-mcp@0.7.0`.
- Replaced the addon's vendor-authored documentation instructions with instructions that accurately describe Maka's current, incomplete Storybook catalog.
- Documented the reason for the patch, its removal condition, and the third-party MIT-licensed material in `patches/README.md` and `LICENSE`.
- Kept the existing Storybook/MCP integration intact: the addon dependency, Storybook configuration, `.mcp.json`, loopback binding, and `--exact-port`.
- Kept Storybook strictly on demand; this PR does not introduce a background service or automatic startup.
## P1 — root `AGENTS.md`
I resolved this finding by removing the tracked root `AGENTS.md` entirely.
That addresses both problems identified in the review:
1. It no longer collides with the repository's existing convention of keeping maintainer-local `AGENTS.md` files untracked.
2. It no longer becomes implicit product behavior through `WORKSPACE_INSTRUCTION_FILES`, so this PR does not inject a second, weaker description of the project's UI authority into Maka's own system prompt.
The operational guidance that remains useful to contributors now lives in `CONTRIBUTING.md`:
- Storybook is development-only and starts on demand with
`npm --workspace @maka/desktop run storybook -- --no-open`.
- The MCP endpoint is available at `http://localhost:6006/mcp`.
- The root `.mcp.json` registers that endpoint for clients that support repository MCP configuration.
- The Storybook catalog is explicitly described as incremental rather than exhaustive.
- UI work should query Storybook first, then fall back to `DESIGN.md` and Astryx's official API or published type declarations when documentation is missing.
- Props must be verified rather than guessed.
I do not consider `CONTRIBUTING.md` a fully equivalent replacement for an always-injected `AGENTS.md`: it does not auto-start Storybook, and not every agent client is guaranteed to read it. The replacement is deliberately split across two appropriate seams:
- `CONTRIBUTING.md` owns the repository workflow and the on-demand startup command.
- Once Storybook is running and an MCP client connects, the MCP server instructions carry the Storybook-first rule and the correct fallback authority.
Together, these preserve much of the original intent of the issue without creating the checkout collision or installing another competing system-prompt authority.
## P2 — vendor instructions claim authority the catalog cannot support
I used the repository's existing dependency-patch mechanism to replace the addon's documentation instructions.
The upstream addon currently tells agents that undocumented props do not exist and that component API questions must not be answered from source or type definitions. That is unsafe for Maka because the current Storybook catalog does not cover the complete UI surface, particularly Astryx.
The patched MCP instructions now establish the following workflow:
1. Use Storybook documentation tools first to discover documented components, props, and examples.
2. Treat the Storybook catalog as incremental and incomplete; absence from the catalog is not evidence that a component or prop does not exist.
3. For documentation gaps, follow the repository's `DESIGN.md`.
4. Verify Astryx components and props against Astryx's official API or published type declarations.
5. Never infer or guess props from names, conventions, or unrelated libraries.
This specifically fixes the failure mode from the review: if an agent needs the Astryx `Button` loading state and Storybook does not document it, the MCP instructions no longer tell the agent that `isLoading` does not exist. They direct the agent back to `DESIGN.md` and the authoritative Astryx API/types instead.
The patch is version-specific to `@storybook/addon-mcp@0.7.0` and is applied by the existing root postinstall path through `patch-package --error-on-fail`. The installed version is lock-pinned. An incompatible addon update will therefore require the patch to be deliberately regenerated and reviewed rather than silently replacing the repository-owned instructions.
`patches/README.md` records why the patch exists and says to remove it when the addon provides a supported project-owned instructions override. `LICENSE` now records the patched MIT-licensed Storybook source as well.
## Current scope and follow-up coverage
This change intentionally separates “make the existing catalog safe and useful” from “complete the catalog.”
With the patch in place, Storybook can provide useful MCP documentation immediately for the components and stories it already covers. Its usefulness is limited to that documented surface, but the limitation is now stated honestly, and missing documentation no longer pushes agents away from the repository's actual design authority.
This PR does not attempt to create superficial stories for 100+ components merely to increase a coverage number. Useful coverage requires design judgment and human review: stories need to demonstrate `DESIGN.md`-canonical states and usage rather than merely render each export.
I plan to track the remaining Storybook coverage in a separate follow-up issue and grow it incrementally, beginning with the Astryx primitives explicitly governed by `DESIGN.md`, then expanding through the remaining high-value UI surfaces. That work is valuable as human-facing documentation and as an Astryx upgrade canary, but it no longer needs to block this integration.
In short:
- this PR installs and preserves the Storybook/MCP interface;
- the local patch makes the currently documented subset immediately useful without granting it false exclusive authority;
- `CONTRIBUTING.md` plus the MCP instructions replace the safe portion of the removed `AGENTS.md` guidance;
- catalog completeness is acknowledged as follow-up work rather than claimed by this PR.
## Preserved integration behavior
The following parts of the existing PR remain unchanged:
- `@storybook/addon-mcp` remains an `apps/desktop` development dependency;
- the Storybook config enables the docs toolset by default and keeps dev/test off by default;
- `.mcp.json` continues to point to `http://localhost:6006/mcp`;
- Storybook binds to `127.0.0.1`;
- `--exact-port` prevents the hardcoded MCP URL from silently pointing at the wrong port;
- Storybook remains on demand.
## Verification
I verified the revised behavior as follows:
- `npm run lint` passes.
- `npm run format:check` passes.
- `npm --workspace @maka/desktop run typecheck:stories` passes.
- `npx knip --workspace apps/desktop` passes.
- ASF source-header and legal-inventory tests pass.
- The dependency patch passes a reverse/forward application check through `patch-package`.
- A clean install reached postinstall and successfully applied all dependency patches, including `@storybook/addon-mcp@0.7.0`; the overall `npm ci` command subsequently stopped only because the existing Electron installer exhausted its network download retries.
- Storybook starts successfully using the documented on-demand command.
- A live MCP `initialize` request returns the patched instructions, including the incomplete-catalog disclosure, the `DESIGN.md`/Astryx fallback, and the prohibition on guessing props.
The full root typecheck is not being claimed as green locally: after rebasing, it currently reports unrelated errors in unchanged non-Storybook source paths. The Storybook-specific typecheck passes.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org
Re: [PR] feat(storybook): expose component docs to agents via official MCP addon (#3527) [maka]
Posted by "chinawch007 (via GitHub)" <gi...@apache.org>.
chinawch007 commented on PR #3736:
URL: https://github.com/apache/maka/pull/3736#issuecomment-5413114042
Thanks — both P2s are addressed in d9671e01b. Details per finding:
## [P2] Toolset override + LAN exposure
- `storybook dev` now runs with `--host 127.0.0.1 --exact-port`. Verified on a
live server: `lsof` reports `TCP 127.0.0.1:6006` where it previously reported
`*:6006`, and the endpoint still serves the three docs tools (initialize →
tools/list → get-documentation) over both `localhost` and `127.0.0.1`.
- On intersecting the header selection with a configured allowlist: agreed in
principle, but the `X-MCP-Toolsets` handling lives inside
`@storybook/addon-mcp` itself — `getToolsets()` in `dist/preset.js` replaces
the configured selection wholesale whenever the header is present — so the
intersection has to happen upstream in storybookjs/mcp. I've filed
<https://github.com/storybookjs/mcp/issues/406>. With loopback-only binding the residual audience is
local processes, which have no need of an MCP detour to probe the
filesystem, so the attack path you demonstrated is closed.
- The `main.ts` comment now states explicitly that the toolsets config is a
default selection, not an allowlist, so no reader mistakes it for a
boundary. Happy to add a small source-contract test pinning the loopback
flags on the script if you want that locked.
- Header-injection tests would be testing the addon's behavior, which lives
in `node_modules`; once upstream ships the allowlist semantics I'll revisit
what can be asserted from this repo.
## [P2] Root .mcp.json not discovered by Codex
- Went with narrowing the claim, as suggested. AGENTS.md is now client-neutral:
the endpoint URL is stated up front, clients that read the root `.mcp.json`
discover it automatically, and other clients (Codex, Cursor) are pointed at
a one-time registration of the same URL in their own config.
- I did not ship per-client configs: Cursor would need a separate
`.cursor/mcp.json`, and Codex only reads the user-global
`~/.codex/config.toml`, which a repo cannot provision — so per-client files
would be unshippable or untestable from here. Can add `.cursor/mcp.json` on
top if maintainers prefer explicit opt-in files per client.
- On verification: confirmed at the protocol level (initialize / tools/list /
tool call). For discovery I can only vouch for the agent client used to
develop this change, whose native discovery is the root `.mcp.json`; I have
no Codex or Cursor environment available, which is exactly why the claim no
longer extends to them.
## CI
The red run is the CLI-workspace EOF-backoff flake you identified. Nothing in
this PR is consumed by that workspace; re-running now.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org