adobe / adobe/spectrum-design-data

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

Open
#663 1 comment 0 reactions 0 assignees View on GitHub
enhancement tooling
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.