Skip to content

Commit 400b818

Browse files
Lukas742Lukas742
authored
docs(mcp-server): restructure README and add CONTRIBUTING.md (#8470)
1 parent 6fecf7b commit 400b818

2 files changed

Lines changed: 164 additions & 143 deletions

File tree

‎packages/mcp-server/CONTRIBUTING.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Contributing
2+
3+
## Scripts
4+
5+
```bash
6+
npm run compile # Build TypeScript + copy JSON assets (fast rebuild)
7+
npm run inspector # Debug with MCP Inspector (opens web UI)
8+
npm run test # Run tests in watch mode (AVA + tsx)
9+
npm run test:ci # Run tests once (CI)
10+
npm run extract:descriptions # Regenerate component metadata from monorepo sources
11+
npm run bundle:docs # Copy documentation files from monorepo into docs/
12+
npm run fetch:skills # Fetch upstream documentation (e.g. accessibility skill)
13+
npm run update # Full pipeline: fetch:skills + extract:descriptions + bundle:docs + compile
14+
npm run clean # Remove dist/, build cache, and all generated files
15+
```
16+
17+
## Updating After a Version Bump
18+
19+
When `@ui5/webcomponents-react` packages are updated, regenerate all data:
20+
21+
```bash
22+
npm run update
23+
```
24+
25+
This runs the full pipeline:
26+
27+
1. Fetch upstream skills (accessibility docs from UI5 Web Components)
28+
2. Extract component descriptions and API data from monorepo TypeScript sources
29+
3. Bundle documentation files (copy MDX/MD from monorepo into `docs/`)
30+
4. Build the TypeScript server and copy JSON assets to `dist/`
31+
32+
## Debug Logging
33+
34+
Enable debug logging by setting the `DEBUG` environment variable:
35+
36+
```bash
37+
DEBUG=true npm run dev
38+
```
39+
40+
## Testing with MCP Inspector
41+
42+
The MCP Inspector provides a web-based UI for testing your MCP server:
43+
44+
```bash
45+
npm run inspector
46+
```
47+
48+
## Architecture
49+
50+
### Overview
51+
52+
The MCP server is a **stdio-based** Node.js process that communicates with AI clients via the [Model Context Protocol](https://modelcontextprotocol.io/). All data is pre-processed at build time and bundled with the server — no network access is required at runtime.
53+
54+
```
55+
┌─────────────────────────────────────────────────────────────────────┐
56+
│ Build Time (npm run update) │
57+
│ │
58+
│ monorepo sources ──► extract-component-descriptions.ts │
59+
│ (TypeScript, ├─► descriptions.json (component summaries) │
60+
│ JSDoc, CEM) └─► component-apis.json (full prop/method │
61+
│ data, event details, CSS parts) │
62+
│ │
63+
│ monorepo docs ──────► bundle-docs.ts │
64+
│ (MDX, MD files) └─► docs/ (local copies for offline access) │
65+
│ │
66+
│ upstream skills ────► fetch-upstream-skills.ts │
67+
│ (GitHub raw) └─► docs/upstream--accessibility.mdx │
68+
└─────────────────────────────────────────────────────────────────────┘
69+
70+
┌─────────────────────────────────────────────────────────────────────┐
71+
│ Runtime (stdio) │
72+
│ │
73+
│ AI Client ◄──► MCP Server (index.ts) │
74+
│ ├─ create_app reads project-templates.json │
75+
│ ├─ list_components reads descriptions.json │
76+
│ ├─ get_component_api reads component-apis.json │
77+
│ ├─ get_documentation reads docs/ + sections.json │
78+
│ ├─ get_public_utils hardcoded documentation │
79+
│ └─ llms.txt resource reads resources/llms.txt │
80+
└─────────────────────────────────────────────────────────────────────┘
81+
```
82+
83+
### Build Pipeline
84+
85+
`npm run update` runs these steps in order:
86+
87+
1. **`fetch:skills`** — Downloads upstream skill documents (e.g. accessibility) from GitHub, adapts HTML examples to React JSX, writes to `docs/`
88+
2. **`extract:descriptions`** — Uses `react-docgen-typescript` to parse component sources and Custom Elements Manifests (CEM). Outputs `descriptions.json` and `component-apis.json`. Also attaches `subTypeDocs` (markdown for complex prop types) and `docUrl` (upstream doc links) from `component-config.ts`
89+
3. **`bundle:docs`** — Copies MDX/MD documentation files from the monorepo into `docs/`. For JSON data sources (e.g. project templates), generates LLM-friendly markdown. Updates `localPath` fields in `documentation_sections.json`
90+
4. **`compile`** — Compiles TypeScript, then `post-build.ts` copies JSON files from `src/` to `dist/` and makes the entry point executable
91+
92+
### Updating Component Data
93+
94+
When components are added or removed, update `src/utils/component-config.ts`:
95+
96+
- **Categories** — Add new components to their category. Uncategorized components trigger a warning during `npm run extract:descriptions`.
97+
- **`SUB_TYPE_DOCS`** — Add markdown paths for complex prop types (e.g. AnalyticalTable column definitions)
98+
- **`UPSTREAM_DOC_URLS`** — Add links for components with complex behavioral logic not captured in props (e.g. Form layout)
99+
100+
### Adding a New Tool
101+
102+
1. Create `src/tools/<tool_name>/<tool_name>.ts` following the existing pattern (name, title, annotations, description, inputSchema, handler)
103+
2. Export it from `src/tools/index.ts` — it will be auto-registered by `index.ts`
104+
105+
### Local Development with Claude Code
106+
107+
Generate all data files (only needed once, or after version bumps):
108+
109+
```bash
110+
npm run update
111+
```
112+
113+
Then add the server to any project using the absolute path to the built entry point:
114+
115+
```bash
116+
claude mcp add --scope project ui5-wcr -- node /path/to/ui5-webcomponents-react/packages/mcp-server/dist/index.js
117+
```
118+
119+
After code changes, `npm run compile` is enough.

‎packages/mcp-server/README.md‎

Lines changed: 45 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,49 @@ MCP server providing development assistance and API documentation for [UI5 Web C
66

77
This MCP server gives AI assistants direct access to UI5 Web Components for React documentation, component APIs, and utility information. It helps developers get accurate, up-to-date information about the library without leaving their IDE.
88

9+
## Setup
10+
11+
This server is available in the [MCP Registry](https://registry.modelcontextprotocol.io), which allows compatible clients to install it directly.
12+
13+
### Claude Code
14+
15+
```bash
16+
claude mcp add ui5-wcr -- npx @ui5/webcomponents-react-mcp@latest
17+
```
18+
19+
### VS Code / Cursor
20+
21+
Add to `.vscode/mcp.json`:
22+
23+
```json
24+
{
25+
"servers": {
26+
"ui5-wcr": {
27+
"command": "npx",
28+
"args": ["@ui5/webcomponents-react-mcp@latest"]
29+
}
30+
}
31+
}
32+
```
33+
34+
### Pinning a Specific Version
35+
36+
The MCP server is available since `@ui5/webcomponents-react@2.21.3`. It shares the same version number and bundles documentation and API data for that specific release. Pinning the version to match your project ensures the AI assistant provides accurate information for the components and APIs you are actually using.
37+
38+
Append `@<version>` to install a specific version. Note that after updating `@ui5/webcomponents-react`, you need to update the pinned MCP server version accordingly.
39+
40+
```bash
41+
npx @ui5/webcomponents-react-mcp@2.21.3
42+
```
43+
44+
To match the version of `@ui5/webcomponents-react` installed in your project, run from the project root:
45+
46+
_This requires `@ui5/webcomponents-react` to be installed in the project's `node_modules`._
47+
48+
```bash
49+
npx @ui5/webcomponents-react-mcp@$(node -p "require('@ui5/webcomponents-react/package.json').version")
50+
```
51+
952
## Features
1053

1154
### Tools
@@ -45,31 +88,6 @@ This MCP server gives AI assistants direct access to UI5 Web Components for Reac
4588

4689
- **`llms.txt`** - LLM-friendly documentation index with scope, key concepts, and quick-reference links
4790

48-
## Setup
49-
50-
This server is available in the [MCP Registry](https://registry.modelcontextprotocol.io), which allows compatible clients to install it directly.
51-
52-
### Claude Code
53-
54-
```bash
55-
claude mcp add ui5-wcr -- npx @ui5/webcomponents-react-mcp
56-
```
57-
58-
### VS Code / Cursor
59-
60-
Add to `.vscode/mcp.json`:
61-
62-
```json
63-
{
64-
"servers": {
65-
"ui5-wcr": {
66-
"command": "npx",
67-
"args": ["@ui5/webcomponents-react-mcp"]
68-
}
69-
}
70-
}
71-
```
72-
7391
## Usage
7492

7593
Once configured, your AI assistant will have access to the tools. You can ask questions like:
@@ -92,122 +110,6 @@ Once configured, your AI assistant will have access to the tools. You can ask qu
92110
- "Show me the API for AnalyticalTable"
93111
- "How do I use the DynamicPage component?"
94112

95-
## Development
96-
97-
### Scripts
98-
99-
```bash
100-
npm run compile # Build TypeScript + copy JSON assets (fast rebuild)
101-
npm run inspector # Debug with MCP Inspector (opens web UI)
102-
npm run test # Run tests in watch mode (AVA + tsx)
103-
npm run test:ci # Run tests once (CI)
104-
npm run extract:descriptions # Regenerate component metadata from monorepo sources
105-
npm run bundle:docs # Copy documentation files from monorepo into docs/
106-
npm run fetch:skills # Fetch upstream documentation (e.g. accessibility skill)
107-
npm run update # Full pipeline: fetch:skills + extract:descriptions + bundle:docs + compile
108-
npm run clean # Remove dist/, build cache, and all generated files
109-
```
110-
111-
### Updating After a Version Bump
112-
113-
When `@ui5/webcomponents-react` packages are updated, regenerate all data:
114-
115-
```bash
116-
npm run update
117-
```
118-
119-
This runs the full pipeline:
120-
121-
1. Fetch upstream skills (accessibility docs from UI5 Web Components)
122-
2. Extract component descriptions and API data from monorepo TypeScript sources
123-
3. Bundle documentation files (copy MDX/MD from monorepo into `docs/`)
124-
4. Build the TypeScript server and copy JSON assets to `dist/`
125-
126-
### Debug Logging
127-
128-
Enable debug logging by setting the `DEBUG` environment variable:
129-
130-
```bash
131-
DEBUG=true npm run dev
132-
```
133-
134-
### Testing with MCP Inspector
135-
136-
The MCP Inspector provides a web-based UI for testing your MCP server:
137-
138-
```bash
139-
npm run inspector
140-
```
141-
142-
## Architecture
143-
144-
### Overview
145-
146-
The MCP server is a **stdio-based** Node.js process that communicates with AI clients via the [Model Context Protocol](https://modelcontextprotocol.io/). All data is pre-processed at build time and bundled with the server — no network access is required at runtime.
147-
148-
```
149-
┌─────────────────────────────────────────────────────────────────────┐
150-
│ Build Time (npm run update) │
151-
│ │
152-
│ monorepo sources ──► extract-component-descriptions.ts │
153-
│ (TypeScript, ├─► descriptions.json (component summaries) │
154-
│ JSDoc, CEM) └─► component-apis.json (full prop/method │
155-
│ data, event details, CSS parts) │
156-
│ │
157-
│ monorepo docs ──────► bundle-docs.ts │
158-
│ (MDX, MD files) └─► docs/ (local copies for offline access) │
159-
│ │
160-
│ upstream skills ────► fetch-upstream-skills.ts │
161-
│ (GitHub raw) └─► docs/upstream--accessibility.mdx │
162-
└─────────────────────────────────────────────────────────────────────┘
163-
164-
┌─────────────────────────────────────────────────────────────────────┐
165-
│ Runtime (stdio) │
166-
│ │
167-
│ AI Client ◄──► MCP Server (index.ts) │
168-
│ ├─ create_app reads project-templates.json │
169-
│ ├─ list_components reads descriptions.json │
170-
│ ├─ get_component_api reads component-apis.json │
171-
│ ├─ get_documentation reads docs/ + sections.json │
172-
│ ├─ get_public_utils hardcoded documentation │
173-
│ └─ llms.txt resource reads resources/llms.txt │
174-
└─────────────────────────────────────────────────────────────────────┘
175-
```
176-
177-
### Build Pipeline
178-
179-
`npm run update` runs these steps in order:
180-
181-
1. **`fetch:skills`** — Downloads upstream skill documents (e.g. accessibility) from GitHub, adapts HTML examples to React JSX, writes to `docs/`
182-
2. **`extract:descriptions`** — Uses `react-docgen-typescript` to parse component sources and Custom Elements Manifests (CEM). Outputs `descriptions.json` and `component-apis.json`. Also attaches `subTypeDocs` (markdown for complex prop types) and `docUrl` (upstream doc links) from `component-config.ts`
183-
3. **`bundle:docs`** — Copies MDX/MD documentation files from the monorepo into `docs/`. For JSON data sources (e.g. project templates), generates LLM-friendly markdown. Updates `localPath` fields in `documentation_sections.json`
184-
4. **`compile`** — Compiles TypeScript, then `post-build.ts` copies JSON files from `src/` to `dist/` and makes the entry point executable
185-
186-
### Updating Component Data
187-
188-
When components are added or removed, update `src/utils/component-config.ts`:
189-
190-
- **Categories** — Add new components to their category. Uncategorized components trigger a warning during `npm run extract:descriptions`.
191-
- **`SUB_TYPE_DOCS`** — Add markdown paths for complex prop types (e.g. AnalyticalTable column definitions)
192-
- **`UPSTREAM_DOC_URLS`** — Add links for components with complex behavioral logic not captured in props (e.g. Form layout)
193-
194-
### Adding a New Tool
195-
196-
1. Create `src/tools/<tool_name>/<tool_name>.ts` following the existing pattern (name, title, annotations, description, inputSchema, handler)
197-
2. Export it from `src/tools/index.ts` — it will be auto-registered by `index.ts`
198-
199-
### Local Development with Claude Code
200-
201-
Generate all data files (only needed once, or after version bumps):
202-
203-
```bash
204-
npm run update
205-
```
206-
207-
Then add the server to any project using the absolute path to the built entry point:
208-
209-
```bash
210-
claude mcp add --scope project ui5-wcr -- node /path/to/ui5-webcomponents-react/packages/mcp-server/dist/index.js
211-
```
113+
## Contributing
212114

213-
After code changes, `npm run compile` is enough.
115+
See [CONTRIBUTING.md](https://github.com/UI5/webcomponents-react/blob/main/packages/mcp-server/CONTRIBUTING.md) for development setup, scripts, architecture, and build pipeline details.

0 commit comments

Comments
 (0)