Skip to content

Commit 072e794

Browse files
RandomByteRandomByte
authored
docs(README): Update install instructions (#237)
* Remove example JSON for advanced configuration * This often causes confusion and is rarely helpful * Refer to GitHub MCP server registry * Add instructions for setting up claude code and codex * Sort tools alphabetically
1 parent 9a22531 commit 072e794

1 file changed

Lines changed: 75 additions & 59 deletions

File tree

‎README.md‎

Lines changed: 75 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -23,22 +23,22 @@ The UI5 [Model Context Protocol](https://modelcontextprotocol.io/) server offers
2323
2424
## Available Tools
2525

26+
- `create_integration_card`: Scaffolds a new UI Integration Card.
2627
- `create_ui5_app`: Scaffolds a new UI5 application based on a set of templates.
2728
- `get_api_reference`: Fetches and formats UI5 API documentation.
2829
- `get_guidelines`: Provides access to UI5 development best practices.
30+
- `get_integration_cards_guidelines`: Provides access to UI Integration Cards development best practices.
2931
- `get_project_info`: Extracts metadata and configuration from a UI5 project.
30-
- `get_version_info`: Retrieves version information for the UI5 framework.
31-
- `run_ui5_linter`: Integrates with [`@ui5/linter`](https://github.com/UI5/linter) to analyze and report issues in UI5 code.
3232
- `get_typescript_conversion_guidelines`: Provides guidelines for converting UI5 applications and controls from JavaScript to TypeScript.
33-
- `get_integration_cards_guidelines`: Provides access to UI Integration Cards development best practices.
34-
- `create_integration_card`: Scaffolds a new UI Integration Card.
33+
- `get_version_info`: Retrieves version information for the UI5 framework.
3534
- `run_manifest_validation`: Validates the manifest against the UI5 Manifest schema.
35+
- `run_ui5_linter`: Integrates with [`@ui5/linter`](https://github.com/UI5/linter) to analyze and report issues in the UI5 code.
3636

3737
## Requirements
3838

3939
- [Node.js](https://nodejs.org/) Version v20.17.0, v22.9.0 or higher
4040
- [npm](https://www.npmjs.com/) Version v8.0.0 or higher
41-
- An MCP client such as VS Code, Cline, or any other MCP-compatible client
41+
- An MCP client, such as VS Code (GitHub Copilot), Cline, Claude Code, Codex, or any other MCP-compatible client
4242

4343
## Setup
4444

@@ -48,90 +48,105 @@ This configuration works for most MCP clients:
4848

4949
```json
5050
{
51-
"mcpServers": {
52-
"@ui5/mcp-server": {
53-
"type": "stdio",
54-
"command": "npx",
55-
"args": [
56-
"@ui5/mcp-server"
57-
]
58-
}
59-
}
51+
"mcpServers": {
52+
"@ui5/mcp-server": {
53+
"type": "stdio",
54+
"command": "npx",
55+
"args": [
56+
"-y",
57+
"@ui5/mcp-server"
58+
]
59+
}
60+
}
6061
}
6162
```
6263

63-
### Configuration
64-
65-
The UI5 MCP server can be configured using the following environment variables. It does not accept any command-line arguments.
66-
67-
**Custom Configuration Example:**
64+
<details>
65+
<summary><i>Special configuration for native Windows</i></summary>
66+
On native Windows (not WSL), you might need to prefix npx with `cmd /c`:
6867

6968
```json
7069
{
71-
"mcpServers": {
72-
"@ui5/mcp-server": {
73-
"type": "stdio",
74-
"command": "npx",
75-
"args": [
76-
"@ui5/mcp-server"
77-
],
78-
"env": {
79-
"UI5_MCP_SERVER_ALLOWED_DOMAINS": "localhost, services.odata.org",
80-
"UI5_LOG_LVL": "verbose",
81-
"UI5_DATA_DIR": "/change-me/to/some/other/path",
82-
}
83-
}
84-
}
70+
"mcpServers": {
71+
"@ui5/mcp-server": {
72+
"type": "stdio",
73+
"command": "cmd",
74+
"args": [
75+
"/c",
76+
"npx -y @ui5/mcp-server"
77+
]
78+
}
79+
}
8580
}
8681
```
87-
88-
**Configuration Options:**
89-
90-
* **`UI5_MCP_SERVER_ALLOWED_DOMAINS`**:
91-
* Default Value: `localhost, services.odata.org`
92-
* Description: A comma-separated list of domains that are allowed to be used in various tools, for example: `localhost, example.com, sub.example.com`. Set to an empty string to allow any domains.
93-
For wildcard subdomains, prefix the domain with a dot: `.example.com`. This will match `www.example.com` but not `example.com`.
94-
* **`UI5_MCP_SERVER_RESPONSE_NO_STRUCTURED_CONTENT`**:
95-
* Description: Set to any value to disable structured content in the MCP server responses.
96-
* **`UI5_MCP_SERVER_RESPONSE_NO_RESOURCES`**:
97-
* Description: Set to any value to disable [resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources) in the MCP server responses. This is useful for [clients that do not support resources](https://modelcontextprotocol.io/clients), such as Cursor or the Gemini CLI.
98-
* **`UI5_LOG_LVL`**:
99-
* Default Value: `info`
100-
* Description: Internal [log level](https://ui5.github.io/cli/stable/pages/Troubleshooting/#changing-the-log-level): `silent`, `error`, `warn`, `info`, `perf`, `verbose`, `silly`
101-
* **`UI5_DATA_DIR`**:
102-
* Default Value: The `.ui5` directory in the user's home directory
103-
* Description: Directory where the MCP server stores its data, such as cached API references
104-
82+
</details>
10583

10684
### Specific MCP Clients
10785

86+
Besides the general configuration outlined above, some MCP clients offer shortcuts for installing MCP servers. Below are instructions for some popular clients, but you can also refer to your specific client's documentation for more details.
87+
10888
#### VS Code
10989

110-
Follow the MCP installation [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) using the above configuration.
90+
**Preferred:** Install from the **[GitHub MCP server registry](https://github.com/mcp/UI5/mcp-server)**
11191

112-
Or use the VS Code CLI:
92+
_Alternatively you can use the VS Code CLI:_
11393

11494
```bash
11595
# Using VS Code CLI
116-
code --add-mcp '{"name":"@ui5/mcp-server","type": "stdio","command":"npx","args":["@ui5/mcp-server"]}'
96+
code --add-mcp '{"name":"@ui5/mcp-server","type": "stdio","command":"npx","args":["-y", "@ui5/mcp-server"]}'
11797
```
11898

11999
#### Cline
120100

121101
1. Open the Cline panel in VSCode.
122-
2. Below the prompt/task input field, click on the "Manage MCP servers" icon and select the gear button in the popup.
123-
3. Click "Configure MCP servers" and add the above configuration.
102+
2. Click on the "MCP Servers" icon at the top, next to the "plus" symbol
103+
3. Change to the "Configure" tab, then click "Configure MCP servers"
104+
4. In the editor that opens, insert the above [Standard Configuration for Most Clients](#standard-configuration-for-most-clients)
105+
106+
See [docs.cline.bot/mcp/adding-and-configuring-servers](https://docs.cline.bot/mcp/adding-and-configuring-servers) for details.
124107

125-
## Rules
126-
The following rules help guide the LLM to use the server correctly:
108+
#### Claude Code
109+
110+
```bash
111+
claude mcp add --transport stdio --scope user ui5-mcp-server -- npx -y @ui5/mcp-server
112+
```
113+
114+
#### Codex
115+
116+
```
117+
codex mcp add --transport stdio ui5-mcp-server -- npx -y @ui5/mcp-server
118+
```
119+
120+
## Adding Rules to your Project
121+
122+
The following rules **guide large language models (LLMs) in using the UI5 MCP server correctly**. Add these rules to your existing global or project-specific [`AGENTS.md`](https://agents.md/) file. The exact location may vary depending on the MCP client. For example, Claude Code uses a `CLAUDE.md` file instead of `AGENTS.md`.
127123

128124
```markdown
129125
## Guidelines for UI5
130126

131127
Use the `get_guidelines` tool of the UI5 MCP server to retrieve the latest coding standards and best practices for UI5 development.
132128
```
133129

134-
Add these rules to your existing global or project-specific [`AGENTS.md`](https://agents.md/) (specifics may vary based on respective MCP client).
130+
### Configuration
131+
132+
The UI5 MCP server can be configured using the following environment variables. It does not accept any command-line arguments.
133+
134+
**Configuration Options:**
135+
136+
* **`UI5_MCP_SERVER_ALLOWED_DOMAINS`**:
137+
* Default Value: `localhost, services.odata.org`
138+
* Description: A comma-separated list of domains that are allowed to be used in various tools, for example: `localhost, example.com, sub.example.com`. Set to an empty string to allow any domains.
139+
For wildcard subdomains, prefix the domain with a dot: `.example.com`. This will match `www.example.com` but not `example.com`.
140+
* **`UI5_MCP_SERVER_RESPONSE_NO_STRUCTURED_CONTENT`**:
141+
* Description: Set to any value to disable structured content in the MCP server responses.
142+
* **`UI5_MCP_SERVER_RESPONSE_NO_RESOURCES`**:
143+
* Description: Set to any value to disable [resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources) in the MCP server responses. This is useful for [clients that do not support resources](https://modelcontextprotocol.io/clients), such as Cursor or the Gemini CLI.
144+
* **`UI5_LOG_LVL`**:
145+
* Default Value: `info`
146+
* Description: Internal [log level](https://ui5.github.io/cli/stable/pages/Troubleshooting/#changing-the-log-level): `silent`, `error`, `warn`, `info`, `perf`, `verbose`, `silly`
147+
* **`UI5_DATA_DIR`**:
148+
* Default Value: The `.ui5` directory in the user's home directory
149+
* Description: Directory where the MCP server stores its data, such as cached API references.
135150

136151
## Support, Feedback, Contributing
137152

@@ -140,6 +155,7 @@ This project is open to feature requests/suggestions, bug reports etc. via [GitH
140155
You can also chat with us in the [`#tooling`](https://openui5.slack.com/archives/C0A7QFN6B) channel of the [OpenUI5 Community Slack](https://ui5-slack-invite.cfapps.eu10.hana.ondemand.com/). For public Q&A, use the [`ui5-tooling` tag on Stack Overflow](https://stackoverflow.com/questions/tagged/ui5-tooling).
141156

142157
## Security / Disclosure
158+
143159
If you find any bug that may be a security problem, please follow our instructions at [in our security policy](https://github.com/UI5/mcp-server/security/policy) on how to report it. Please do not create GitHub issues for security-related doubts or problems.
144160

145161
## Code of Conduct

0 commit comments

Comments
 (0)