apache / apache/maka

Adopt Storybook's official MCP addon to give agents a queryable component interface

Open
#3,527 1 comment 0 reactions 0 assignees View on GitHub
good first issue help wanted
Dominant language
TypeScript
Stars
5.4k
Forks
502
Avg merge
1d 2h
Merged PRs (30d)
715

Description

## Problem

When an agent writes frontend code in this repo, it has no machine-readable way to learn which components exist or how to use them. It falls back to reading component source to guess props and patterns, which burns tokens and produces rework: duplicated components, wrong props, hand-rolled values where tokens belong. Humans review out the damage afterwards.

Our existing tooling covers the verification side (visual-contract harness, CDP-based Storybook smoke, a11y tree audit, file-level Astryx surface inventory). The production side — "what can I reuse and how do I use it" — has no agent-facing interface.

External evidence that closing this gap pays off: BILL's A/B experiment grounding agents in their design system cut token usage 31–63% per task and improved first-pass component fidelity (https://www.bill.com/engineering/how-we-made-our-design-system-bilingual).

## Desired outcome

An agent doing UI work queries the design system before writing code: list available components, read props and usage docs, and later run interaction tests on its own stories.

Concretely:

1. Install `@storybook/addon-mcp` (official, self-hosted: it serves our own Storybook at `http://localhost:6006/mcp`, no third-party service).
2. Register the MCP endpoint in our agent configurations and add usage guidance to `AGENTS.md` (query docs before writing frontend code).
3. Start with the docs toolset only.

Follow-up, not in scope: the testing toolset (`run-story-tests`) needs `@storybook/addon-vitest`; adopt once the MCP feature leaves preview.

## Alternatives or workarounds

- Status quo: agents grep source. Works, but this is exactly the expensive path the BILL numbers measure.
- Wrap our own surface-inventory generator as a custom MCP server: same idea, more to build and maintain; the official addon is configuration, not construction.
- Wait until the feature leaves preview: viable; the proposal limits exposure to the docs toolset, and the addon is dev-only tooling that is trivial to remove.

**Risk:** Storybook's MCP/manifests are in preview; the API may change. Exposure is limited to a dev dependency plus agent config.

---

## 中文对照

**问题**:Agent 写前端时没有机器可读的方式了解有哪些现成组件、怎么用,只能翻源码猜,费 token 且产出需要返工(重复造组件、props 用错、绕过 token 手写样式)。现有工具链只覆盖验证侧(契约 harness、CDP 冒烟、a11y 审计、文件级盘点),生产侧(“能复用什么、怎么用”)没有 Agent 接口。外部证据:BILL 的对照实验显示,给 Agent 接上设计系统后 token 省 31–63%,组件一次用对。

**期望结果**:Agent 写前端前先查组件清单和用法文档。具体:装官方 `@storybook/addon-mcp`(自托管,数据全是自己的);在 agent 配置和 AGENTS.md 里登记使用指引;先只开 docs toolset。testing toolset 依赖 `@storybook/addon-vitest`,等 preview 稳定后作为后续跟进。

**备选方案**:维持现状(翻源码,正是被实测为贵的路径);自研 MCP 包装 inventory 生成器(同理但要多建多养);等 preview 结束再接(可行,提案已把暴露面限制在 docs toolset,且只是开发依赖,随时可移除)。

**风险**:Storybook 的 MCP/manifests 处于 preview,API 可能变。

Contributor guide

Open the contributing guide

Research direction

Start with AGENTS.md and locate the repository's agent configurations and Storybook setup. Read the official @storybook/addon-mcp docs for the docs toolset, then verify the local http://localhost:6006/mcp endpoint. Done means the dev-only addon is registered for agents, AGENTS.md explains querying component documentation before frontend work, and the testing toolset remains out of scope.

Written by the indexing model from the issue text.

Assessment

Tech stack
storybook, typescript
Domain
developer-experience, frontend, tooling
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.