@adobe/spectrum-design-data-mcp 1.0.5 → 1.0.6

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 (3) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +122 -3
  3. package/package.json +3 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,20 @@
1
1
  # @adobe/spectrum-design-data-mcp
2
2
 
3
+ ## 1.0.6
4
+
5
+ ### Patch Changes
6
+
7
+ - [#595](https://github.com/adobe/spectrum-tokens/pull/595) [`53bc11e`](https://github.com/adobe/spectrum-tokens/commit/53bc11e1bfcc3a839cfc5dfbd63f59cc5e87a1c3) Thanks [@GarthDB](https://github.com/GarthDB)! - Enhanced documentation with security and configuration improvements
8
+ - Add multiple MCP configuration options including recommended npx usage
9
+ - Add npm provenance support for enhanced supply-chain security
10
+ - Improve installation section with package integrity verification
11
+ - Add comprehensive troubleshooting section for common issues
12
+ - Add dedicated security section with best practices
13
+ - Add support section with links to issues and documentation
14
+
15
+ These changes align the documentation with modern MCP server standards
16
+ and improve user experience with better configuration options and security features.
17
+
3
18
  ## 1.0.5
4
19
 
5
20
  ### Patch Changes
package/README.md CHANGED
@@ -10,12 +10,32 @@ This MCP server enables AI assistants to query and interact with Spectrum design
10
10
  - **Component Schemas**: API definitions and validation schemas for Spectrum components
11
11
  - **Future**: Component anatomy, design patterns, and guidelines
12
12
 
13
+ ## Prerequisites
14
+
15
+ - **Node.js 20+**
16
+
13
17
  ## Installation
14
18
 
15
19
  ```bash
16
20
  npm install -g @adobe/spectrum-design-data-mcp
17
21
  ```
18
22
 
23
+ ### Verifying Package Integrity
24
+
25
+ This package is published with npm provenance for enhanced supply-chain security. You can verify the package's attestations:
26
+
27
+ ```bash
28
+ npm audit signatures
29
+ ```
30
+
31
+ Or clone and run locally:
32
+
33
+ ```bash
34
+ git clone https://github.com/adobe/spectrum-tokens.git
35
+ cd spectrum-tokens/tools/spectrum-design-data-mcp
36
+ pnpm install
37
+ ```
38
+
19
39
  ## Usage
20
40
 
21
41
  ### Starting the MCP Server
@@ -49,11 +69,57 @@ The server runs locally and communicates via stdio with MCP-compatible AI client
49
69
  - **`validate-component-props`**: Validate component properties against schemas
50
70
  - **`get-type-schemas`**: Get type definitions used in schemas
51
71
 
52
- ## Configuration with AI Clients
72
+ ## Configuration
73
+
74
+ ### MCP Setup
75
+
76
+ Add to your MCP configuration (e.g., `.cursor/mcp.json` for Cursor IDE):
77
+
78
+ #### Option 1: Using npx (Recommended)
79
+
80
+ ```json
81
+ {
82
+ "mcpServers": {
83
+ "spectrum-design-data": {
84
+ "command": "npx",
85
+ "args": ["@adobe/spectrum-design-data-mcp"]
86
+ }
87
+ }
88
+ }
89
+ ```
90
+
91
+ #### Option 2: Using global installation
53
92
 
54
- ### Claude Desktop
93
+ ```json
94
+ {
95
+ "mcpServers": {
96
+ "spectrum-design-data": {
97
+ "command": "@adobe/spectrum-design-data-mcp"
98
+ }
99
+ }
100
+ }
101
+ ```
55
102
 
56
- Add to your Claude Desktop configuration:
103
+ #### Option 3: Local development
104
+
105
+ ```json
106
+ {
107
+ "mcpServers": {
108
+ "spectrum-design-data": {
109
+ "command": "node",
110
+ "args": [
111
+ "./path/to/spectrum-tokens/tools/spectrum-design-data-mcp/src/index.js"
112
+ ]
113
+ }
114
+ }
115
+ }
116
+ ```
117
+
118
+ > **Note**: Using `npx` (Option 1) is recommended as it avoids PATH issues and ensures you always use the latest version. This approach mirrors other MCP servers like Browser MCP and resolves common NPX availability problems.
119
+
120
+ ### Claude Desktop (Legacy Configuration)
121
+
122
+ For older Claude Desktop configurations:
57
123
 
58
124
  ```json
59
125
  {
@@ -150,6 +216,38 @@ AI: I'll validate those button properties against the Spectrum schema.
150
216
  The configuration is valid! All required properties are present and the types match the expected schema.
151
217
  ```
152
218
 
219
+ ## Troubleshooting
220
+
221
+ ### Installation Issues
222
+
223
+ ```bash
224
+ # Check Node.js version
225
+ node --version # Should be 20+
226
+
227
+ # Clear npm cache if needed
228
+ npm cache clean --force
229
+
230
+ # Verify package installation
231
+ npm list -g @adobe/spectrum-design-data-mcp
232
+ ```
233
+
234
+ ### MCP Connection Issues
235
+
236
+ 1. Verify the MCP configuration file path
237
+ 2. Check that Node.js path is correct
238
+ 3. Ensure the package is installed globally or use npx
239
+ 4. Restart your AI client after configuration changes
240
+
241
+ ### Package Verification
242
+
243
+ ```bash
244
+ # Verify package integrity
245
+ npm audit signatures
246
+
247
+ # Check for security vulnerabilities
248
+ npm audit
249
+ ```
250
+
153
251
  ## Development
154
252
 
155
253
  ### Building from Source
@@ -181,6 +279,21 @@ src/
181
279
  └── schemas.js # Schema data access
182
280
  ```
183
281
 
282
+ ## Security
283
+
284
+ ### Supply Chain Security
285
+
286
+ - **🔐 NPM Provenance**: Published with npm provenance attestations for verifiable builds
287
+ - **🛡️ Security Audits**: Regular dependency security audits
288
+ - **📦 Verified Packages**: All dependencies are audited and verified
289
+
290
+ ### Best Practices
291
+
292
+ - Always verify package integrity using `npm audit signatures`
293
+ - Keep the package updated to the latest version
294
+ - Use npx for the most secure and up-to-date execution
295
+ - Report security issues through the [GitHub security advisory](https://github.com/adobe/spectrum-tokens/security/advisories)
296
+
184
297
  ## License
185
298
 
186
299
  Apache-2.0 © Adobe
@@ -188,3 +301,9 @@ Apache-2.0 © Adobe
188
301
  ## Contributing
189
302
 
190
303
  This project is part of the Spectrum Design System. Please see the main [contribution guidelines](../../CONTRIBUTING.md) for details on how to contribute.
304
+
305
+ ## Support
306
+
307
+ - Create an [issue](https://github.com/adobe/spectrum-tokens/issues) for bug reports or feature requests
308
+ - Check the [documentation](https://github.com/adobe/spectrum-tokens/tree/main/tools/spectrum-design-data-mcp) for detailed guides
309
+ - Review [existing issues](https://github.com/adobe/spectrum-tokens/issues?q=label%3Amcp) for solutions
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adobe/spectrum-design-data-mcp",
3
- "version": "1.0.5",
3
+ "version": "1.0.6",
4
4
  "description": "Model Context Protocol server for Spectrum design data including tokens, schemas, and component anatomy",
5
5
  "keywords": [
6
6
  "mcp",
@@ -42,7 +42,8 @@
42
42
  "homepage": "https://github.com/adobe/spectrum-tokens/tree/main/tools/spectrum-design-data-mcp#readme",
43
43
  "publishConfig": {
44
44
  "access": "public",
45
- "registry": "https://registry.npmjs.org/"
45
+ "registry": "https://registry.npmjs.org/",
46
+ "provenance": true
46
47
  },
47
48
  "dependencies": {
48
49
  "@modelcontextprotocol/sdk": "^0.5.0",