Phase 4: Add Glossary Integration to MCP Server and Static API

[GarthDB]

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: [DRAFT RFC] Spectrum Design System Glossary #661
• MCP Server: tools/spectrum-design-data-mcp