feat: Add tool that creates Integration Card #84
+2,575
−4
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,87 @@ | ||
| # UI5 MCP Server Development Guide | ||
|
|
||
| ## Architecture & Project Structure | ||
|
|
||
| This is a **Model Context Protocol (MCP) server** for UI5 development built on TypeScript with a modular tool-based architecture. The server acts as a **proxy to existing UI5 tools**, not reimplementing functionality. | ||
|
|
||
| ### Key Components | ||
| - **`src/server.ts`**: Main MCP server using `@modelcontextprotocol/sdk` | ||
| - **`src/Context.ts`**: Handles path normalization and security (root path validation) | ||
| - **`src/tools/`**: Modular tool implementations, each in their own directory | ||
| - **`resources/`**: Template files for `create_ui5_app` tool (EJS templates from ui5-community) | ||
| - **`lib/`**: Compiled output (generated, never edit directly) | ||
|
|
||
| ### Tool Architecture Pattern | ||
| Each tool follows this structure: | ||
| ``` | ||
| src/tools/{tool_name}/ | ||
| ├── index.ts # Tool registration with MCP server | ||
| ├── {tool_name}.ts # Core implementation | ||
| ├── schema.ts # JSON schema for parameters | ||
| └── *.ts # Helper modules | ||
| ``` | ||
|
|
||
| Example: `src/tools/create_ui5_app/index.ts` shows the registration pattern. | ||
|
|
||
| ## Development Workflows | ||
|
|
||
| ### Build & Development | ||
| ```bash | ||
| npm run build # Compile TypeScript to lib/ | ||
| npm run build-watch # Watch mode compilation | ||
| npm run start # Run server via tsx (development) | ||
| npm run inspect-mcp-server # Debug with MCP inspector | ||
| ``` | ||
|
|
||
| ### Testing | ||
| - **AVA** framework with snapshot testing | ||
| - **Test files**: `test/lib/**/*.ts` and `test/scripts/**/*.ts` | ||
| - **Try tools manually**: `npm run try-create-ui5-app` | ||
| - **Coverage**: `npm run coverage` (uses NYC with Istanbul) | ||
|
|
||
| ### Code Quality | ||
| - **ESLint**: `npm run lint` / `npm run lint-fix` | ||
| - **Conventional Commits**: Required (see `commitlint.config.mjs`) | ||
| - **Pre-push hooks**: Run linting, commit validation, and dependency checks | ||
|
|
||
| ## Project-Specific Conventions | ||
|
|
||
| ### Path Handling & Security | ||
| - **Always use absolute paths** in tool parameters | ||
| - All paths validated through `Context.normalizePath()` against allowed roots | ||
| - File operations restricted to configured root directories | ||
|
|
||
| ### Environment Configuration | ||
| Key environment variables affecting behavior: | ||
| - `UI5_MCP_SERVER_ALLOWED_ODATA_DOMAINS`: Comma-separated domain allowlist | ||
| - `UI5_MCP_SERVER_RESPONSE_NO_STRUCTURED_CONTENT`: Disable structured responses | ||
| - `UI5_MCP_SERVER_RESPONSE_NO_RESOURCES`: Disable MCP resources (for Cursor/Gemini CLI) | ||
| - `UI5_DATA_DIR`: Cache directory for API docs (default: `~/.ui5/mcp-server/`) | ||
|
|
||
| ### API Documentation Caching | ||
| The `get_api_reference` tool downloads and caches UI5 API JSON files locally: | ||
| - Downloads from SAPUI5/OpenUI5 CDN based on project's `ui5.yaml` | ||
| - Creates searchable index in `{UI5_DATA_DIR}/api_json_files/index.json` | ||
| - Handles 404s gracefully (expected for some libraries) | ||
|
|
||
| ### Template System | ||
| Uses **EJS templating** (same as Yeoman) for UI5 app generation: | ||
| - Templates in `resources/template-{js,ts}/` | ||
| - Extended from ui5-community templates with OData integration | ||
| - Data binding for namespace, framework version, OData configuration | ||
|
|
||
| ## Key Guidelines | ||
|
|
||
| 1. **Follow `docs/architecture.md` and `docs/Guidelines.md`** for detailed requirements | ||
| 2. **Use existing UI5 tools** - don't reimplement, proxy existing functionality | ||
| 3. **Maintain module boundaries** - each tool is independent | ||
| 4. **Validate all inputs** through Context class security model | ||
| 5. **Handle async operations** properly (all tools return promises) | ||
| 6. **Use structured logging** with `@ui5/logger` package | ||
|
|
||
| ## Critical Integration Points | ||
|
|
||
| - **UI5 CLI integration**: Tools detect framework/version from `ui5.yaml` | ||
| - **UI5 Linter integration**: `run_ui5_linter` tool proxies `@ui5/linter` | ||
| - **CDN APIs**: Dynamic API reference fetching from ui5.sap.com/OpenUI5 CDN | ||
| - **MCP Protocol**: Server implements latest MCP specification for AI agent integration |
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
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,15 @@ | ||||||||
| { | ||||||||
| "name": "template-card", | ||||||||
| "version": "1.0.0", | ||||||||
| "description": "A basic template card project", | ||||||||
| "scripts": { | ||||||||
| "start": "npx http-server ./ -c-1 -o test/index.html", | ||||||||
| "test": "echo \"No tests specified\" && exit 0" | ||||||||
| }, | ||||||||
| "devDependencies": { | ||||||||
| "http-server": "^14.1.1" | ||||||||
| }, | ||||||||
| "keywords": [], | ||||||||
| "author": "", | ||||||||
| "license": "ISC" | ||||||||
|
Comment on lines
+12
to
+14
There was a problem hiding this comment.
Suggested change
If you agree, I would propose removing these optional fields from the package.json |
||||||||
| } | ||||||||
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,157 @@ | ||
| "data": { | ||
| "json": { | ||
| "dimensions": { | ||
| "weekLabel": "Weeks" | ||
| }, | ||
| "measures": { | ||
| "revenueLabel": "Revenue", | ||
| "costLabel": "Costs" | ||
| }, | ||
| "legend": { | ||
| "visible": true, | ||
| "position": "bottom", | ||
| "alignment": "topLeft" | ||
| }, | ||
| "list": [ | ||
| { | ||
| "Week": "CW14", | ||
| "Revenue": 431000.22, | ||
| "Cost": 230000, | ||
| "Cost1": 24800.63, | ||
| "Cost2": 205199.37, | ||
| "Cost3": 199999.37, | ||
| "Target": 500000, | ||
| "Budget": 210000 | ||
| }, | ||
| { | ||
| "Week": "CW15", | ||
| "Revenue": 494000.3, | ||
| "Cost": 238000, | ||
| "Cost1": 99200.39, | ||
| "Cost2": 138799.61, | ||
| "Cost3": 200199.37, | ||
| "Target": 500000, | ||
| "Budget": 224000 | ||
| }, | ||
| { | ||
| "Week": "CW16", | ||
| "Revenue": 491000.17, | ||
| "Cost": 221000, | ||
| "Cost1": 70200.54, | ||
| "Cost2": 150799.46, | ||
| "Cost3": 80799.46, | ||
| "Target": 500000, | ||
| "Budget": 238000 | ||
| } | ||
| ], | ||
| "header": { | ||
| "number": "65.34", | ||
| "unit": "K", | ||
| "trend": "Down", | ||
| "state": "Error", | ||
| "target": { | ||
| "number": 100, | ||
| "unit": "K" | ||
| }, | ||
| "deviation": { | ||
| "number": 34.7, | ||
| "unit": "%" | ||
| }, | ||
| "details": "Q1, 2018" | ||
| } | ||
| } | ||
| }, | ||
| "header": { | ||
| "type": "Numeric", | ||
| "title": "{i18n>title}", | ||
| "subtitle": "{i18n>subtitle}", | ||
| "mainIndicator": { | ||
| "number": "{header/number}", | ||
| "unit": "{header/unit}", | ||
| "trend": "{header/trend}", | ||
| "state": "{header/state}" | ||
| }, | ||
| "details": "{header/details}", | ||
| "sideIndicators": [ | ||
| { | ||
| "title": "Target", | ||
| "number": "{header/target/number}", | ||
| "unit": "{header/target/unit}" | ||
| }, | ||
| { | ||
| "title": "Deviation", | ||
| "number": "{header/deviation/number}", | ||
| "unit": "{header/deviation/unit}" | ||
| } | ||
| ] | ||
| }, | ||
| "content": { | ||
| "data": { | ||
| "path": "/list" | ||
| }, | ||
| "chartType": "line", | ||
| "chartProperties": { | ||
| "title": { | ||
| "text": "Line chart", | ||
| "visible": true, | ||
| "alignment": "left" | ||
| }, | ||
| "legend": { | ||
| "visible": "{legend/visible}" | ||
| }, | ||
| "legendGroup": { | ||
| "layout": { | ||
| "position": "{legend/position}", | ||
| "alignment": "{legend/alignment}" | ||
| } | ||
| }, | ||
| "plotArea": { | ||
| "dataLabel": { | ||
| "visible": true | ||
| } | ||
| }, | ||
| "categoryAxis": { | ||
| "title": { | ||
| "visible": false | ||
| } | ||
| }, | ||
| "valueAxis": { | ||
| "title": { | ||
| "visible": false | ||
| } | ||
| } | ||
| }, | ||
| "dimensions": [ | ||
| { | ||
| "name": "{dimensions/weekLabel}", | ||
| "value": "{Week}" | ||
| } | ||
| ], | ||
| "measures": [ | ||
| { | ||
| "name": "{measures/revenueLabel}", | ||
| "value": "{Revenue}" | ||
| }, | ||
| { | ||
| "name": "{measures/costLabel}", | ||
| "value": "{Cost}" | ||
| } | ||
| ], | ||
| "feeds": [ | ||
| { | ||
| "uid": "valueAxis", | ||
| "type": "Measure", | ||
| "values": [ | ||
| "{measures/revenueLabel}", | ||
| "{measures/costLabel}" | ||
| ] | ||
| }, | ||
| { | ||
| "uid": "categoryAxis", | ||
| "type": "Dimension", | ||
| "values": [ | ||
| "{dimensions/weekLabel}" | ||
| ] | ||
| } | ||
| ] | ||
| } |
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,90 @@ | ||
| "data": { | ||
| "json": { | ||
| "item": [ | ||
| { | ||
| "start": "2020-09-18T09:00", | ||
| "end": "2020-09-18T10:00", | ||
| "title": "Payment reminder", | ||
| "icon": "sap-icon://desktop-mobile", | ||
| "type": "Type06", | ||
| "url": "http://sap.com" | ||
| }, | ||
| { | ||
| "start": "2020-09-18T17:00", | ||
| "end": "2020-09-18T17:30", | ||
| "title": "Private appointment", | ||
| "icon": "sap-icon://desktop-mobile", | ||
| "type": "Type07" | ||
| } | ||
| ], | ||
| "specialDate": [ | ||
| { | ||
| "start": "2020-09-13", | ||
| "end": "2020-09-14", | ||
| "type": "Type08" | ||
| }, | ||
| { | ||
| "start": "2020-09-24", | ||
| "end": "2020-09-24", | ||
| "type": "Type13" | ||
| } | ||
| ], | ||
| "legendItem": [ | ||
| { | ||
| "category": "calendar", | ||
| "text": "Team building", | ||
| "type": "Type08" | ||
| }, | ||
| { | ||
| "category": "calendar", | ||
| "text": "Public holiday", | ||
| "type": "Type13" | ||
| } | ||
| ] | ||
| } | ||
| }, | ||
| "header": { | ||
| "title": "{i18n>title}", | ||
| "subtitle": "{i18n>subtitle}" | ||
| }, | ||
| "content": { | ||
| "item": { | ||
| "template": { | ||
| "startDate": "{start}", | ||
| "endDate": "{end}", | ||
| "title": "{title}", | ||
| "text": "{text}", | ||
| "icon": { | ||
| "src": "{icon}", | ||
| "visible": true | ||
| }, | ||
| "type": "{type}", | ||
| "actions": [ | ||
| { | ||
| "type": "Navigation", | ||
| "enabled": "{= ${url}}", | ||
| "parameters": { | ||
| "url": "{url}" | ||
| } | ||
| } | ||
| ] | ||
| }, | ||
| "path": "/item" | ||
| }, | ||
| "specialDate": { | ||
| "template": { | ||
| "startDate": "{start}", | ||
| "endDate": "{end}", | ||
| "type": "{type}" | ||
| }, | ||
| "path": "/specialDate" | ||
| }, | ||
| "legendItem": { | ||
| "template": { | ||
| "category": "{category}", | ||
| "text": "{text}", | ||
| "type": "{type}" | ||
| }, | ||
| "path": "/legendItem" | ||
| } | ||
| } |
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.
No need for npx inside npm scripts since the dependency is correctly maintained