adobe / adobe/spectrum-design-data
Phase 4: Add Glossary Integration to MCP Server and Static API
- Dominant language
- Rust
- Stars
- 153
- Forks
- 35
- Avg merge
- 7h 54m
- Merged PRs (30d)
- 111
Description
## Overview
Make glossary data accessible to AI systems via enhanced MCP server tools and static JSON HTTP API.
**Related**: RFC Discussion #661 - Spectrum Design System Glossary
## Deliverables
### A. MCP Server Enhancement (`tools/spectrum-design-data-mcp`)
#### 1. New Glossary Tools (`src/tools/glossary.js`)
- `query-glossary`: Search terms by keyword
- `get-term-definition`: Get complete definition for a term
- `find-related-terms`: Get related/cross-referenced terms
- `get-platform-terminology`: Get platform-specific term variations
- `validate-terminology`: Check if term is in approved glossary
- `get-naming-guidance`: Get naming methodology recommendations
#### 2. Data Access Layer (`src/data/glossary.js`)
- Import `@adobe/design-system-registry`
- Provide helper functions for glossary queries
- Cache glossary data for performance
#### 3. Package Updates
- Add dependency: `@adobe/design-system-registry`
- Update version (minor bump)
- Update `README.md` with glossary tool documentation
- Add tests for glossary tools
### B. Static JSON API (for HTTP Access)
#### 1. API Structure (`docs/spectrum-glossary/api/`)
- `v1/glossary.json` - Complete glossary dump
- `v1/terms/{termId}.json` - Individual term files
- `v1/categories/{category}.json` - Terms by category
- `v1/platforms/{platform}.json` - Platform-specific terms
#### 2. Build Script (`docs/spectrum-glossary/scripts/build-api.js`)
- Generate API files from registry
- Include CORS headers configuration
- Create index with API documentation
#### 3. Accessible URLs
- `https://adobe.github.io/spectrum-design-data/glossary/api/v1/glossary.json`
- `https://adobe.github.io/spectrum-design-data/glossary/api/v1/terms/button.json`
## Use Cases
### MCP Tools (for AI Assistants)
- Cursor/Claude can query glossary during development
- Validate terminology in code and documentation
- Suggest correct terms based on context
### Static API (for Chatbots)
- MrFluffyJaws can fetch terminology definitions
- Internal tools can validate against approved terms
- Documentation generators can auto-link terms
## Dependencies
- ✅ Phase 1: Enhanced schema and content
- ✅ Phase 2: Platform extensions
## Acceptance Criteria
- [ ] MCP server exposes 6 glossary tools
- [ ] All tools tested and documented
- [ ] Static JSON API accessible via HTTPS
- [ ] API documentation published
- [ ] Both access patterns tested with real clients
- [ ] MCP server version bumped and ready for npm publish
- [ ] Performance: API responses < 100ms
- [ ] Tests passing for all new tools
## Estimated Effort
1-2 weeks
## Related
- RFC: https://github.com/adobe/spectrum-design-data/discussions/661
- MCP Server: `tools/spectrum-design-data-mcp`
Contributor guide
Research direction
Start with the RFC discussion and inspect the existing tools/spectrum-design-data-mcp entry points before scoping the work. The named files are src/tools/glossary.js, src/data/glossary.js, README.md, and docs/spectrum-glossary/scripts/build-api.js; review how tests are organized there. Done means six tested and documented MCP tools, generated static API files, published API documentation, passing tests, and the stated response-time target.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, node.js
- Domain
- api, documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100