@iress-oss/ids-mcp-server 0.0.1-dev.3 → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (122) hide show
  1. package/LICENSE +193 -0
  2. package/README.md +159 -29
  3. package/build/componentHandlers.js +205 -0
  4. package/{dist → build}/config.js +5 -5
  5. package/build/index.js +51 -0
  6. package/{dist → build}/iressHandlers.js +46 -52
  7. package/{dist → build}/resourceHandlers.js +22 -23
  8. package/{dist → build}/searchHandlers.js +92 -107
  9. package/{dist → build}/toolHandler.js +13 -13
  10. package/build/tools.js +165 -0
  11. package/{dist → build}/utils.js +15 -11
  12. package/docs/api-reference.md +0 -0
  13. package/docs/best-practices.md +0 -0
  14. package/docs/configuration.md +0 -0
  15. package/docs/examples.md +0 -0
  16. package/docs/guidelines.md +269 -0
  17. package/{generated/docs → docs/ids}/components-autocomplete-docs.md +6 -6
  18. package/{generated/docs → docs/ids}/components-autocomplete-recipes-docs.md +51 -17
  19. package/{generated/docs → docs/ids}/components-card-recipes-docs.md +1 -1
  20. package/{generated/docs → docs/ids}/components-checkbox-docs.md +19 -6
  21. package/{generated/docs → docs/ids}/components-checkboxgroup-docs.md +18 -18
  22. package/{generated/docs → docs/ids}/components-checkboxgroup-recipes-docs.md +9 -9
  23. package/{generated/docs → docs/ids}/components-col-docs.md +1 -1
  24. package/{generated/docs → docs/ids}/components-combobox-docs.md +6 -6
  25. package/{generated/docs → docs/ids}/components-container-docs.md +42 -8
  26. package/{generated/docs → docs/ids}/components-filter-docs.md +65 -12
  27. package/{generated/docs → docs/ids}/components-form-docs.md +335 -341
  28. package/{generated/docs → docs/ids}/components-form-recipes-docs.md +1 -198
  29. package/{generated/docs → docs/ids}/components-hide-docs.md +70 -16
  30. package/{generated/docs → docs/ids}/components-icon-docs.md +4 -4
  31. package/{generated/docs → docs/ids}/components-input-recipes-docs.md +2 -2
  32. package/{generated/docs → docs/ids}/components-inputcurrency-recipes-docs.md +40 -6
  33. package/{generated/docs → docs/ids}/components-modal-docs.md +113 -3
  34. package/docs/ids/components-popover-docs.md +4 -0
  35. package/{generated/docs → docs/ids}/components-radiogroup-docs.md +21 -21
  36. package/{generated/docs → docs/ids}/components-richselect-docs.md +111 -149
  37. package/{generated/docs → docs/ids}/components-row-docs.md +4 -4
  38. package/{generated/docs → docs/ids}/components-skeleton-docs.md +3 -3
  39. package/{generated/docs → docs/ids}/components-skeleton-recipes-docs.md +1 -1
  40. package/{generated/docs → docs/ids}/components-skiplink-docs.md +1 -1
  41. package/{generated/docs → docs/ids}/components-slideout-docs.md +113 -3
  42. package/{generated/docs → docs/ids}/components-table-ag-grid-docs.md +137 -109
  43. package/{generated/docs → docs/ids}/components-table-docs.md +597 -92
  44. package/{generated/docs → docs/ids}/components-tabset-docs.md +2 -2
  45. package/{generated/docs → docs/ids}/components-tag-docs.md +1 -1
  46. package/{generated/docs → docs/ids}/components-toaster-docs.md +5 -5
  47. package/{generated/docs → docs/ids}/foundations-colours-docs.md +1 -1
  48. package/{generated/docs → docs/ids}/foundations-typography-docs.md +2 -7
  49. package/{generated/docs → docs/ids}/get-started-develop-docs.md +3 -3
  50. package/{generated/docs → docs/ids}/introduction-docs.md +4 -4
  51. package/{generated/docs → docs/ids}/patterns-loading-docs.md +2 -332
  52. package/docs/ids/resources-migration-guides-from-v4-to-v5-docs.md +639 -0
  53. package/docs/ids/themes-available-themes-docs.md +74 -0
  54. package/docs/ids/themes-tokens-docs.md +4580 -0
  55. package/docs/ids/versions-docs.md +27 -0
  56. package/docs/tutorials/basic-integration.md +0 -0
  57. package/package.json +15 -44
  58. package/LICENSE.txt +0 -201
  59. package/dist/componentHandlers.js +0 -241
  60. package/dist/componentHandlers.test.js +0 -380
  61. package/dist/index.js +0 -53
  62. package/dist/iressHandlers.test.js +0 -316
  63. package/dist/resourceHandlers.test.js +0 -352
  64. package/dist/searchHandlers.test.js +0 -524
  65. package/dist/toolHandler.test.js +0 -369
  66. package/dist/tools.js +0 -165
  67. package/dist/utils.test.js +0 -286
  68. package/generated/docs/components-popover-docs.md +0 -464
  69. package/generated/docs/foundations-accessibility-docs.md +0 -62
  70. package/generated/docs/foundations-consistency-docs.md +0 -52
  71. package/generated/docs/foundations-content-docs.md +0 -23
  72. package/generated/docs/foundations-introduction-docs.md +0 -17
  73. package/generated/docs/foundations-principles-docs.md +0 -70
  74. package/generated/docs/foundations-user-experience-docs.md +0 -63
  75. package/generated/docs/foundations-visual-design-docs.md +0 -46
  76. package/generated/docs/guidelines.md +0 -812
  77. package/generated/docs/resources-migration-guides-from-v4-to-v5-docs.md +0 -437
  78. package/generated/docs/themes-available-themes-docs.md +0 -66
  79. package/generated/docs/themes-tokens-docs.md +0 -1200
  80. package/generated/docs/versions-docs.md +0 -17
  81. /package/{dist → build}/types.js +0 -0
  82. /package/{generated/docs → docs/ids}/components-alert-docs.md +0 -0
  83. /package/{generated/docs → docs/ids}/components-badge-docs.md +0 -0
  84. /package/{generated/docs → docs/ids}/components-button-docs.md +0 -0
  85. /package/{generated/docs → docs/ids}/components-button-recipes-docs.md +0 -0
  86. /package/{generated/docs → docs/ids}/components-buttongroup-docs.md +0 -0
  87. /package/{generated/docs → docs/ids}/components-card-docs.md +0 -0
  88. /package/{generated/docs → docs/ids}/components-divider-docs.md +0 -0
  89. /package/{generated/docs → docs/ids}/components-expander-docs.md +0 -0
  90. /package/{generated/docs → docs/ids}/components-field-docs.md +0 -0
  91. /package/{generated/docs → docs/ids}/components-inline-docs.md +0 -0
  92. /package/{generated/docs → docs/ids}/components-input-docs.md +0 -0
  93. /package/{generated/docs → docs/ids}/components-inputcurrency-docs.md +0 -0
  94. /package/{generated/docs → docs/ids}/components-label-docs.md +0 -0
  95. /package/{generated/docs → docs/ids}/components-menu-docs.md +0 -0
  96. /package/{generated/docs → docs/ids}/components-menu-menuitem-docs.md +0 -0
  97. /package/{generated/docs → docs/ids}/components-navbar-docs.md +0 -0
  98. /package/{generated/docs → docs/ids}/components-navbar-recipes-docs.md +0 -0
  99. /package/{generated/docs → docs/ids}/components-panel-docs.md +0 -0
  100. /package/{generated/docs → docs/ids}/components-placeholder-docs.md +0 -0
  101. /package/{generated/docs → docs/ids}/components-popover-recipes-docs.md +0 -0
  102. /package/{generated/docs → docs/ids}/components-progress-docs.md +0 -0
  103. /package/{generated/docs → docs/ids}/components-radio-docs.md +0 -0
  104. /package/{generated/docs → docs/ids}/components-readonly-docs.md +0 -0
  105. /package/{generated/docs → docs/ids}/components-select-docs.md +0 -0
  106. /package/{generated/docs → docs/ids}/components-slider-docs.md +0 -0
  107. /package/{generated/docs → docs/ids}/components-spinner-docs.md +0 -0
  108. /package/{generated/docs → docs/ids}/components-stack-docs.md +0 -0
  109. /package/{generated/docs → docs/ids}/components-tabset-tab-docs.md +0 -0
  110. /package/{generated/docs → docs/ids}/components-text-docs.md +0 -0
  111. /package/{generated/docs → docs/ids}/components-toaster-toast-docs.md +0 -0
  112. /package/{generated/docs → docs/ids}/components-toggle-docs.md +0 -0
  113. /package/{generated/docs → docs/ids}/components-tooltip-docs.md +0 -0
  114. /package/{generated/docs → docs/ids}/components-validationmessage-docs.md +0 -0
  115. /package/{generated/docs → docs/ids}/contact-us-docs.md +0 -0
  116. /package/{generated/docs → docs/ids}/extensions-editor-docs.md +0 -0
  117. /package/{generated/docs → docs/ids}/extensions-editor-recipes-docs.md +0 -0
  118. /package/{generated/docs → docs/ids}/frequently-asked-questions-docs.md +0 -0
  119. /package/{generated/docs → docs/ids}/get-started-using-storybook-docs.md +0 -0
  120. /package/{generated/docs → docs/ids}/resources-changelog-docs.md +0 -0
  121. /package/{generated/docs → docs/ids}/resources-code-katas-docs.md +0 -0
  122. /package/{generated/docs → docs/ids}/themes-introduction-docs.md +0 -0
package/LICENSE ADDED
@@ -0,0 +1,193 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity granting the License.
13
+
14
+ "Legal Entity" shall mean the union of the acting entity and all
15
+ other entities that control, are controlled by, or are under common
16
+ control with that entity. For the purposes of this definition,
17
+ "control" means (i) the power, direct or indirect, to cause the
18
+ direction or management of such entity, whether by contract or
19
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
20
+ outstanding shares, or (iii) beneficial ownership of such entity.
21
+
22
+ "You" (or "Your") shall mean an individual or Legal Entity
23
+ exercising permissions granted by this License.
24
+
25
+ "Source" form shall mean the preferred form for making modifications,
26
+ including but not limited to software source code, documentation
27
+ source, and configuration files.
28
+
29
+ "Object" form shall mean any form resulting from mechanical
30
+ transformation or translation of a Source form, including but
31
+ not limited to compiled object code, generated documentation,
32
+ and conversions to other media types.
33
+
34
+ "Work" shall mean the work of authorship, whether in Source or
35
+ Object form, made available under the License, as indicated by a
36
+ copyright notice that is included in or attached to the work
37
+ (which shall not include in the License file).
38
+
39
+ "Derivative Works" shall mean any work, whether in Source or Object
40
+ form, that is based upon (or derived from) the Work and for which the
41
+ editorial revisions, annotations, elaborations, or other modifications
42
+ represent, as a whole, an original work of authorship. For the purposes
43
+ of this License, Derivative Works shall not include works that remain
44
+ separable from, or merely link (or bind by name) to the interfaces of,
45
+ the Work and derivative works thereof.
46
+
47
+ "Contribution" shall mean any work of authorship, including
48
+ the original version of the Work and any modifications or additions
49
+ to that Work or Derivative Works thereof, that is intentionally
50
+ submitted to Licensor for inclusion in the Work by the copyright owner
51
+ or by an individual or Legal Entity authorized to submit on behalf of
52
+ the copyright owner. For the purposes of this definition, "submitted"
53
+ means any form of electronic, verbal, or written communication sent
54
+ to the Licensor or its representatives, including but not limited to
55
+ communication on electronic mailing lists, source code control
56
+ systems, and issue tracking systems that are managed by, or on behalf
57
+ of, the Licensor for the purpose of discussing and improving the Work,
58
+ but excluding communication that is conspicuously marked or otherwise
59
+ designated in writing by the copyright owner as "Not a Contribution."
60
+
61
+ "Contributor" shall mean Licensor and any individual or Legal Entity
62
+ on behalf of whom a Contribution has been received by Licensor and
63
+ subsequently incorporated within the Work.
64
+
65
+ 2. Grant of Copyright License. Subject to the terms and conditions of
66
+ this License, each Contributor hereby grants to You a perpetual,
67
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
68
+ copyright license to use, reproduce, modify, merge, publish,
69
+ distribute, sublicense, and/or sell copies of the Work, and to
70
+ permit persons to whom the Work is furnished to do so, subject to
71
+ the following conditions:
72
+
73
+ The above copyright notice and this permission notice shall be
74
+ included in all copies or substantial portions of the Work.
75
+
76
+ 3. Grant of Patent License. Subject to the terms and conditions of
77
+ this License, each Contributor hereby grants to You a perpetual,
78
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
79
+ (except as stated in this section) patent license to make, have made,
80
+ use, offer to sell, sell, import, and otherwise transfer the Work,
81
+ where such license applies only to those patent claims licensable
82
+ by such Contributor that are necessarily infringed by their
83
+ Contribution(s) alone or by combination of their Contribution(s)
84
+ with the Work to which such Contribution(s) was submitted. If You
85
+ institute patent litigation against any entity (including a
86
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
87
+ or a Contribution incorporated within the Work constitutes direct
88
+ or contributory patent infringement, then any patent licenses
89
+ granted to You under this License for that Work shall terminate
90
+ as of the date such litigation is filed.
91
+
92
+ 4. Redistribution. You may reproduce and distribute copies of the
93
+ Work or Derivative Works thereof in any medium, with or without
94
+ modifications, and in Source or Object form, provided that You
95
+ meet the following conditions:
96
+
97
+ (a) You must give any other recipients of the Work or
98
+ Derivative Works a copy of this License; and
99
+
100
+ (b) You must cause any modified files to carry prominent notices
101
+ stating that You changed the files; and
102
+
103
+ (c) You must retain, in the Source form of any Derivative Works
104
+ that You distribute, all copyright, patent, trademark, and
105
+ attribution notices from the Source form of the Work,
106
+ excluding those notices that do not pertain to any part of
107
+ the Derivative Works; and
108
+
109
+ (d) If the Work includes a "NOTICE" text file as part of its
110
+ distribution, then any Derivative Works that You distribute must
111
+ include a readable copy of the attribution notices contained
112
+ within such NOTICE file, excluding those notices that do not
113
+ pertain to any part of the Derivative Works, in at least one
114
+ of the following places: within a NOTICE text file distributed
115
+ as part of the Derivative Works; within the Source form or
116
+ documentation, if provided along with the Derivative Works; or,
117
+ within a display generated by the Derivative Works, if and
118
+ wherever such third-party notices normally appear. The contents
119
+ of the NOTICE file are for informational purposes only and
120
+ do not modify the License. You may add Your own attribution
121
+ notices within Derivative Works that You distribute, alongside
122
+ or as an addendum to the NOTICE text from the Work, provided
123
+ that such additional attribution notices cannot be construed
124
+ as modifying the License.
125
+
126
+ You may add Your own copyright notice to Your modifications and
127
+ may provide additional or different license terms and conditions
128
+ for use, reproduction, or distribution of Your modifications, or
129
+ for any such Derivative Works as a whole, provided Your use,
130
+ reproduction, and distribution of the Work otherwise complies with
131
+ the conditions stated in this License.
132
+
133
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
134
+ any Contribution intentionally submitted for inclusion in the Work
135
+ by You to the Licensor shall be under the terms and conditions of
136
+ this License, without any additional terms or conditions.
137
+ Notwithstanding the above, nothing herein shall supersede or modify
138
+ the terms of any separate license agreement you may have executed
139
+ with Licensor regarding such Contributions.
140
+
141
+ 6. Trademarks. This License does not grant permission to use the trade
142
+ names, trademarks, service marks, or product names of the Licensor,
143
+ except as required for reasonable and customary use in describing the
144
+ origin of the Work and reproducing the content of the NOTICE file.
145
+
146
+ 7. Disclaimer of Warranty. Unless required by applicable law or
147
+ agreed to in writing, Licensor provides the Work (and each
148
+ Contributor provides its Contributions) on an "AS IS" BASIS,
149
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
150
+ implied, including, without limitation, any warranties or conditions
151
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
152
+ PARTICULAR PURPOSE. You are solely responsible for determining the
153
+ appropriateness of using or redistributing the Work and assume any
154
+ risks associated with Your exercise of permissions under this License.
155
+
156
+ 8. Limitation of Liability. In no event and under no legal theory,
157
+ whether in tort (including negligence), contract, or otherwise,
158
+ unless required by applicable law (such as deliberate and grossly
159
+ negligent acts) or agreed to in writing, shall any Contributor be
160
+ liable to You for damages, including any direct, indirect, special,
161
+ incidental, or consequential damages of any character arising as a
162
+ result of this License or out of the use or inability to use the
163
+ Work (including but not limited to damages for loss of goodwill,
164
+ work stoppage, computer failure or malfunction, or any and all
165
+ other commercial damages or losses), even if such Contributor
166
+ has been advised of the possibility of such damages.
167
+
168
+ 9. Accepting Warranty or Additional Liability. When redistributing
169
+ the Work or Derivative Works thereof, You may choose to offer,
170
+ and charge a fee for, acceptance of support, warranty, indemnity,
171
+ or other liability obligations and/or rights consistent with this
172
+ License. However, in accepting such obligations, You may act only
173
+ on Your own behalf and on Your sole responsibility, not on behalf
174
+ of any other Contributor, and only if You agree to indemnify,
175
+ defend, and hold each Contributor harmless for any liability
176
+ incurred by, or claims asserted against, such Contributor by reason
177
+ of your accepting any such warranty or additional liability.
178
+
179
+ END OF TERMS AND CONDITIONS
180
+
181
+ Copyright 2025 Iress
182
+
183
+ Licensed under the Apache License, Version 2.0 (the "License");
184
+ you may not use this file except in compliance with the License.
185
+ You may obtain a copy of the License at
186
+
187
+ http://www.apache.org/licenses/LICENSE-2.0
188
+
189
+ Unless required by applicable law or agreed to in writing, software
190
+ distributed under the License is distributed on an "AS IS" BASIS,
191
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
192
+ See the License for the specific language governing permissions and
193
+ limitations under the License.
package/README.md CHANGED
@@ -14,45 +14,92 @@ A Model Context Protocol (MCP) server specifically designed for the **Iress Desi
14
14
 
15
15
  ## Installation
16
16
 
17
- ### Quick Setup (VS Code)
17
+ 1. Clone or download this repository
18
+ 2. Install dependencies:
19
+ ```bash
20
+ yarn install
21
+ ```
22
+ 3. Build the project:
23
+ ```bash
24
+ yarn build
25
+ ```
18
26
 
19
- **🚀 One-Click Installation**: Click the link below to automatically add the IDS MCP server to your VS Code settings:
27
+ ## Usage
20
28
 
21
- [**Add IDS MCP Server to VS Code**](vscode:mcp/install?%7B%22name%22%3A%22iress-design-system%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22%40iress-oss%2Fids-mcp-server%22%5D%7D)
29
+ ### Development Server
22
30
 
23
- This will automatically configure VS Code to use the IDS Component Library MCP Server with your AI assistant.
31
+ For easy testing during development, use the interactive dev server:
24
32
 
25
- ### Manual Setup (VS Code)
26
-
27
- Alternatively, you can manually add the server to your VS Code settings:
33
+ ```bash
34
+ yarn dev-server
35
+ ```
28
36
 
29
- 1. Open VS Code Settings (⌘/Ctrl + ,)
30
- 2. Search for "MCP"
31
- 3. Add the following server configuration:
37
+ This starts an interactive shell where you can test MCP commands and shows detailed connection information:
32
38
 
33
- ```json
34
- "mcp": {
35
- "servers": {
36
- "iress-design-system": {
37
- "command": "npx",
38
- "args": ["@iress-oss/ids-mcp-server"]
39
- }
39
+ ```
40
+ 🚀 IDS Component Library MCP Server
41
+ ===================================
42
+
43
+ 📍 Server Configuration:
44
+ Protocol: stdio (Model Context Protocol)
45
+ Server Path: /Users/luke.peary/Sandbox/ids-mcp-server/build/index.js
46
+ Docs Directory: /Users/luke.peary/Sandbox/ids-mcp-server/docs/ids
47
+ Working Directory: /Users/luke.peary/Sandbox/ids-mcp-server
48
+
49
+ 🔌 Starting MCP server...
50
+ ✅ MCP server is ready!
51
+ 📡 Connection: stdio transport established
52
+ 🔗 MCP Client Config:
53
+ {
54
+ "command": "node",
55
+ "args": ["/Users/luke.peary/Sandbox/ids-mcp-server/build/index.js"],
56
+ "cwd": "/Users/luke.peary/Sandbox/ids-mcp-server"
57
+ }
58
+
59
+ Available commands:
60
+ find-component <name> - Find IDS components by name or functionality
61
+ get-props <component> - Get component props and API details
62
+ get-examples <component> - Get usage examples and patterns
63
+ search-ids <query> - Search across all IDS documentation
64
+ list-components [category] - List available components
65
+ get-tokens [type] - Get design tokens (colors, spacing, etc.)
66
+ list-resources - List available resources
67
+ help - Show this help
68
+ exit - Exit the dev server
69
+
70
+ > find-component button
71
+ 📤 Request: {"jsonrpc":"2.0","id":123,"method":"tools/call","params":{"name":"find_component","arguments":{"query":"button"}}}
72
+ 📥 Response: {
73
+ "result": {
74
+ "content": [
75
+ {
76
+ "type": "text",
77
+ "text": "Found 3 relevant IDS components:\n\n1. **components-button-docs.md**\n button: A button is a clickable item used to perform an action.\n\n2. **components-buttongroup-docs.md**\n buttongroup: Button group component documentation..."
78
+ }
79
+ ]
40
80
  }
41
81
  }
42
82
  ```
43
83
 
44
- ### Other MCP Clients
84
+ #### Common Dev Server Commands
45
85
 
46
- For other MCP clients or manual configuration, use this server configuration:
86
+ - `find-component button` - Find button-related components
87
+ - `get-props button` - Get IressButton component props and API
88
+ - `get-examples input` - Get IressInput usage examples
89
+ - `search-ids "mode=primary"` - Search for primary mode usage
90
+ - `list-components components` - List all UI components
91
+ - `get-tokens colors` - Get IDS color design tokens
92
+ - `raw {"jsonrpc":"2.0","id":1,"method":"tools/list"}` - Send custom MCP request
47
93
 
48
- ```json
49
- {
50
- "command": "npx",
51
- "args": ["@iress-oss/ids-mcp-server"]
52
- }
94
+ ### Running the Server
95
+
96
+ The server runs on stdio and communicates using the MCP protocol:
97
+
98
+ ```bash
99
+ node build/index.js
53
100
  ```
54
101
 
55
- ## Available Tools
102
+ ### Available Tools
56
103
 
57
104
  1. **find_component**: Find IDS components by name or functionality - perfect for component discovery
58
105
  2. **get_component_props**: Get detailed prop information and API reference for specific components
@@ -61,7 +108,7 @@ For other MCP clients or manual configuration, use this server configuration:
61
108
  5. **list_components**: List all available components organized by category
62
109
  6. **get_design_tokens**: Access IDS design tokens (colors, spacing, typography, etc.)
63
110
 
64
- ## Available Resources
111
+ ### Available Resources
65
112
 
66
113
  All IDS component documentation files are exposed as categorized resources:
67
114
 
@@ -69,9 +116,45 @@ All IDS component documentation files are exposed as categorized resources:
69
116
  - **Foundations**: Colors, Typography, Spacing, etc. (`foundations-*-docs.md`)
70
117
  - **Resources**: Changelog, Guidelines, etc. (`resources-*-docs.md`)
71
118
 
119
+ Resources have URIs like: `file:///absolute/path/to/docs/ids/components-button-docs.md`
120
+
121
+ ## Example Usage
122
+
123
+ ### With MCP Client
124
+
125
+ ```bash
126
+ # List available IDS tools
127
+ echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node build/index.js
128
+
129
+ # Find button components
130
+ echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"find_component","arguments":{"query":"button"}}}' | node build/index.js
131
+
132
+ # Get IressButton props
133
+ echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_component_props","arguments":{"component":"button"}}}' | node build/index.js
134
+
135
+ # Search for primary mode usage
136
+ echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"search_ids_docs","arguments":{"query":"mode=\"primary\""}}}' | node build/index.js
137
+ ```
138
+
139
+ ### Configuration for MCP Clients
140
+
141
+ Add this to your MCP client configuration:
142
+
143
+ ```json
144
+ {
145
+ "mcpServers": {
146
+ "ids-component-library": {
147
+ "command": "node",
148
+ "args": ["/path/to/ids-mcp-server/build/index.js"],
149
+ "cwd": "/path/to/ids-mcp-server"
150
+ }
151
+ }
152
+ }
153
+ ```
154
+
72
155
  ## Documentation Structure
73
156
 
74
- The server works with the IDS component library documentation in the `generated/docs/` directory:
157
+ The server works with the IDS component library documentation in the `docs/ids/` directory:
75
158
 
76
159
  **Components** (50+ UI components):
77
160
 
@@ -81,13 +164,60 @@ The server works with the IDS component library documentation in the `generated/
81
164
  - `components-modal-docs.md` - IressModal component
82
165
  - `components-*-recipes-docs.md` - Usage patterns and recipes
83
166
 
84
- **Foundations** (Guidelines and tokens):
167
+ **Foundations** (Design system basics):
85
168
 
86
169
  - `foundations-colours-docs.md` - Color palette and usage
87
170
  - `foundations-typography-docs.md` - Text styles and hierarchy
88
171
  - `foundations-spacing-docs.md` - Layout and spacing tokens
89
172
 
90
- **Resources** (Supporting documentation):
173
+ **Resources** (Guidelines and tools):
91
174
 
92
175
  - `resources-changelog-docs.md` - Version history and updates
93
176
  - `introduction-docs.md` - Getting started guide
177
+
178
+ ## Development
179
+
180
+ ### Project Structure
181
+
182
+ ```
183
+ ├── src/
184
+ │ └── index.ts # IDS MCP server implementation
185
+ ├── docs/
186
+ │ └── ids/ # IDS component library documentation
187
+ │ ├── components-*-docs.md # Component documentation
188
+ │ ├── foundations-*-docs.md # Design tokens and foundations
189
+ │ └── resources-*-docs.md # Guidelines and resources
190
+ ├── build/ # Compiled JavaScript output
191
+ ├── package.json
192
+ ├── tsconfig.json
193
+ └── README.md
194
+ ```
195
+
196
+ ### Adding Documentation
197
+
198
+ The server automatically discovers all `.md` files in the `docs/ids/` directory. To add new IDS component documentation:
199
+
200
+ 1. Add new component docs as `components-{name}-docs.md`
201
+ 2. Add foundation docs as `foundations-{name}-docs.md`
202
+ 3. Add resource docs as `resources-{name}-docs.md`
203
+
204
+ The server will automatically categorize and expose them through the MCP protocol.
205
+
206
+ ### Customization
207
+
208
+ To use a different documentation directory, modify the `DOCS_DIR` constant in `src/index.ts`:
209
+
210
+ ```typescript
211
+ const DOCS_DIR = path.join(__dirname, "..", "docs", "your-docs-folder");
212
+ ```
213
+
214
+ ## Security
215
+
216
+ - Files are restricted to the configured docs directory
217
+ - Path traversal attacks are prevented
218
+ - Only `.md` files are processed
219
+ - All input parameters are validated
220
+
221
+ ## License
222
+
223
+ [Your License Here]
@@ -0,0 +1,205 @@
1
+ /**
2
+ * Tool handlers for component-related operations
3
+ */
4
+ import { z } from "zod";
5
+ import * as path from "path";
6
+ import { getMarkdownFiles, mapIressComponentToFile, extractIressComponents, readFileContent, } from "./utils.js";
7
+ import { DOCS_DIR } from "./config.js";
8
+ export function handleFindComponent(args) {
9
+ const schema = z.object({
10
+ query: z.string(),
11
+ category: z.enum(["components", "foundations", "resources"]).optional(),
12
+ });
13
+ const { query, category } = schema.parse(args);
14
+ // Check if query is an Iress component name
15
+ if (query.startsWith("Iress")) {
16
+ const componentFile = mapIressComponentToFile(query);
17
+ if (componentFile) {
18
+ return {
19
+ content: [
20
+ {
21
+ type: "text",
22
+ text: `Found exact match for **${query}**:\n\n**${componentFile}**\n ${query} component documentation\n\n*Use \`get_iress_component_info\` with "${query}" for detailed information.*`,
23
+ },
24
+ ],
25
+ };
26
+ }
27
+ }
28
+ const markdownFiles = getMarkdownFiles();
29
+ // Filter files by category if specified
30
+ const filteredFiles = category
31
+ ? markdownFiles.filter((file) => file.startsWith(`${category}-`))
32
+ : markdownFiles;
33
+ const results = [];
34
+ for (const file of filteredFiles) {
35
+ try {
36
+ const filePath = path.join(DOCS_DIR, file);
37
+ const content = readFileContent(filePath);
38
+ const lines = content.split("\n");
39
+ // Score relevance based on query matches in titles and content
40
+ let relevanceScore = 0;
41
+ const queryLower = query.toLowerCase();
42
+ const filenameLower = file.toLowerCase();
43
+ // Check for Iress component mentions in content
44
+ const iressComponents = extractIressComponents(content);
45
+ const hasMatchingIressComponent = iressComponents.some((comp) => comp.toLowerCase().includes(queryLower) ||
46
+ queryLower.includes(comp.toLowerCase().replace("iress", "")));
47
+ if (hasMatchingIressComponent) {
48
+ relevanceScore += 75;
49
+ }
50
+ // High relevance for filename matches
51
+ if (filenameLower.includes(queryLower)) {
52
+ relevanceScore += 100;
53
+ }
54
+ // Medium relevance for title matches
55
+ const title = lines.find((line) => line.startsWith("#"))?.replace(/^#+\s*/, "") || "";
56
+ if (title.toLowerCase().includes(queryLower)) {
57
+ relevanceScore += 50;
58
+ }
59
+ // Lower relevance for content matches
60
+ const contentMatches = content.toLowerCase().split(queryLower).length - 1;
61
+ relevanceScore += contentMatches * 2;
62
+ if (relevanceScore > 0) {
63
+ const componentName = file
64
+ .replace(/^components-/, "")
65
+ .replace("-docs.md", "");
66
+ const description = lines
67
+ .slice(0, 10)
68
+ .find((line) => line.trim() && !line.startsWith("#") && !line.startsWith("<!--"))
69
+ ?.trim() || "IDS component documentation";
70
+ results.push({
71
+ file,
72
+ relevance: relevanceScore,
73
+ description: `${componentName}: ${description}`,
74
+ });
75
+ }
76
+ }
77
+ catch (error) {
78
+ console.error(`Error reading file ${file}:`, error);
79
+ }
80
+ }
81
+ // Sort by relevance
82
+ results.sort((a, b) => b.relevance - a.relevance);
83
+ return {
84
+ content: [
85
+ {
86
+ type: "text",
87
+ text: results.length > 0
88
+ ? `Found ${results.length} relevant IDS components:\n\n${results
89
+ .slice(0, 10) // Limit to top 10 results
90
+ .map((r, index) => `${index + 1}. **${r.file}**\n ${r.description}`)
91
+ .join("\n\n")}`
92
+ : `No IDS components found matching "${query}". Try searching for common component names like "button", "input", "table", or "modal".`,
93
+ },
94
+ ],
95
+ };
96
+ }
97
+ export function handleGetComponentProps(args) {
98
+ const schema = z.object({
99
+ component: z.string(),
100
+ });
101
+ const { component } = schema.parse(args);
102
+ const markdownFiles = getMarkdownFiles();
103
+ // Find the component file
104
+ const componentFile = markdownFiles.find((file) => file.includes(`components-${component.toLowerCase()}`) ||
105
+ file.toLowerCase().includes(component.toLowerCase()));
106
+ if (!componentFile) {
107
+ return {
108
+ content: [
109
+ {
110
+ type: "text",
111
+ text: `Component "${component}" not found. Available components:\n${markdownFiles
112
+ .filter((f) => f.startsWith("components-"))
113
+ .map((f) => `- ${f.replace("components-", "").replace("-docs.md", "")}`)
114
+ .join("\n")}`,
115
+ },
116
+ ],
117
+ };
118
+ }
119
+ try {
120
+ const filePath = path.join(DOCS_DIR, componentFile);
121
+ const content = readFileContent(filePath);
122
+ // Extract prop information, modes, examples
123
+ const lines = content.split("\n");
124
+ const propSections = [];
125
+ let inPropsSection = false;
126
+ let currentSection = "";
127
+ for (const line of lines) {
128
+ if (line.includes("mode") ||
129
+ line.includes("prop") ||
130
+ line.includes("Properties") ||
131
+ line.includes("API") ||
132
+ line.includes("Examples")) {
133
+ if (currentSection) {
134
+ propSections.push(currentSection);
135
+ }
136
+ currentSection = line + "\n";
137
+ inPropsSection = true;
138
+ }
139
+ else if (inPropsSection && line.trim()) {
140
+ currentSection += line + "\n";
141
+ }
142
+ else if (inPropsSection && !line.trim()) {
143
+ if (currentSection) {
144
+ propSections.push(currentSection);
145
+ currentSection = "";
146
+ }
147
+ inPropsSection = false;
148
+ }
149
+ }
150
+ if (currentSection) {
151
+ propSections.push(currentSection);
152
+ }
153
+ return {
154
+ content: [
155
+ {
156
+ type: "text",
157
+ text: `**${component} Component Props & API**\n\n${propSections.length > 0
158
+ ? propSections.join("\n---\n\n")
159
+ : `Props information extracted from ${componentFile}:\n\n${content.slice(0, 2000)}...`}`,
160
+ },
161
+ ],
162
+ };
163
+ }
164
+ catch (error) {
165
+ throw new Error(`Failed to read component file ${componentFile}: ${error}`);
166
+ }
167
+ }
168
+ export function handleListComponents(args) {
169
+ const schema = z.object({
170
+ category: z
171
+ .enum(["components", "foundations", "resources", "all"])
172
+ .default("all"),
173
+ });
174
+ const { category } = schema.parse(args);
175
+ const markdownFiles = getMarkdownFiles();
176
+ const categorized = {
177
+ components: markdownFiles
178
+ .filter((f) => f.startsWith("components-"))
179
+ .map((f) => f.replace("components-", "").replace("-docs.md", "")),
180
+ foundations: markdownFiles
181
+ .filter((f) => f.startsWith("foundations-"))
182
+ .map((f) => f.replace("foundations-", "").replace("-docs.md", "")),
183
+ resources: markdownFiles
184
+ .filter((f) => f.startsWith("resources-"))
185
+ .map((f) => f.replace("resources-", "").replace("-docs.md", "")),
186
+ };
187
+ let output = "**IDS Component Library**\n\n";
188
+ if (category === "all") {
189
+ output += `**Components (${categorized.components.length})**\n${categorized.components.map((c) => `- ${c}`).join("\n")}\n\n`;
190
+ output += `**Foundations (${categorized.foundations.length})**\n${categorized.foundations.map((c) => `- ${c}`).join("\n")}\n\n`;
191
+ output += `**Resources (${categorized.resources.length})**\n${categorized.resources.map((c) => `- ${c}`).join("\n")}`;
192
+ }
193
+ else {
194
+ const items = categorized[category];
195
+ output += `**${category.charAt(0).toUpperCase() + category.slice(1)} (${items.length})**\n${items.map((c) => `- ${c}`).join("\n")}`;
196
+ }
197
+ return {
198
+ content: [
199
+ {
200
+ type: "text",
201
+ text: output,
202
+ },
203
+ ],
204
+ };
205
+ }
@@ -1,14 +1,14 @@
1
1
  /**
2
2
  * Configuration constants for the IDS MCP Server
3
3
  */
4
- import path from 'path';
5
- import { fileURLToPath } from 'url';
4
+ import path from "path";
5
+ import { fileURLToPath } from "url";
6
6
  const __filename = fileURLToPath(import.meta.url);
7
7
  const __dirname = path.dirname(__filename);
8
- export const DOCS_DIR = path.join(__dirname, '..', 'generated', 'docs');
8
+ export const DOCS_DIR = path.join(__dirname, "..", "docs", "ids");
9
9
  export const SERVER_CONFIG = {
10
- name: 'ids-mcp-server',
11
- version: '1.0.0',
10
+ name: "ids-component-library-server",
11
+ version: "1.0.0",
12
12
  };
13
13
  export const CAPABILITIES = {
14
14
  resources: {},