Skip to main content
Glama

SAP Documentation MCP Server

by marianfoo
METADATA-CONSOLIDATION.mdโ€ข10.3 kB
# ๐ŸŽฏ Metadata-Driven Configuration Consolidation ## Overview This document describes the comprehensive consolidation of all hardcoded source configurations into a centralized, metadata-driven system. The changes eliminate scattered configuration values throughout the codebase and provide a single source of truth for all documentation source settings. ## ๐Ÿš€ Key Changes Summary ### 1. **Centralized Metadata System** - **Moved** `data/metadata.json` โ†’ `src/metadata.json` - **Extended** metadata.json with comprehensive source configurations - **Created** type-safe APIs for accessing all configuration data - **Eliminated** all hardcoded configuration values from source code ### 2. **Enhanced Configuration Structure** - **12 documentation sources** with complete metadata - **Source paths, URLs, and anchor styles** for documentation generation - **Context-specific boosts** for intelligent query routing - **Library ID mappings** for source resolution - **Context emojis** for UI presentation - **Synonyms and acronyms** for query expansion ### 3. **Simplified Core Configuration** - **Removed** hardcoded `SOURCE_BOOSTS` from `config.ts` - **Centralized** all source-specific settings in metadata.json - **Maintained** core system settings (RETURN_K, DB_PATH, etc.) ## ๐Ÿ“ Files Modified ### **Core Configuration Files** #### `src/metadata.json` โœจ **NEW LOCATION** ```json { "version": 1, "sources": [ { "id": "sapui5", "libraryId": "/sapui5", "sourcePath": "sapui5-docs/docs", "baseUrl": "https://ui5.sap.com", "pathPattern": "/#/topic/{file}", "anchorStyle": "custom", "boost": 0.1, "tags": ["ui5", "frontend", "javascript"] } // ... 11 more sources ], "contextBoosts": { "UI5": { "/sapui5": 0.9, "/openui5-api": 0.9 }, "CAP": { "/cap": 1.0, "/sapui5": 0.2 } // ... more contexts }, "libraryMappings": { "openui5-api": "sapui5", "openui5-samples": "sapui5" // ... more mappings }, "contextEmojis": { "CAP": "๐Ÿ—๏ธ", "UI5": "๐ŸŽจ", "wdi5": "๐Ÿงช" // ... more emojis } } ``` #### `src/lib/config.ts` ๐Ÿ”ง **SIMPLIFIED** ```typescript // Before: 25 lines with hardcoded SOURCE_BOOSTS export const CONFIG = { RETURN_K: Number(process.env.RETURN_K || 25), DB_PATH: "dist/data/docs.sqlite", METADATA_PATH: "src/metadata.json", // Updated path USE_OR_LOGIC: true, // SOURCE_BOOSTS removed - now in metadata.json }; ``` #### `src/lib/metadata.ts` โœจ **ENHANCED** **New comprehensive API with 12 functions:** ```typescript // Documentation URL configuration export function getDocUrlConfig(libraryId: string): DocUrlConfig | null export function getAllDocUrlConfigs(): Record<string, DocUrlConfig> // Source path management export function getSourcePath(libraryId: string): string | null export function getAllSourcePaths(): Record<string, string> // Context-aware boosts export function getContextBoosts(context: string): Record<string, number> export function getAllContextBoosts(): Record<string, Record<string, number>> // Library mappings export function getLibraryMapping(sourceId: string): string | null export function getAllLibraryMappings(): Record<string, string> // UI presentation export function getContextEmoji(context: string): string export function getAllContextEmojis(): Record<string, string> // Source lookup export function getSourceByLibraryId(libraryId: string): SourceMeta | null export function getSourceById(id: string): SourceMeta | null ``` ### **Updated Implementation Files** #### `src/lib/search.ts` ๐Ÿ”„ **REFACTORED** ```typescript // Before: Hardcoded library mappings (15 lines) const mapping: Record<string, string> = { 'sapui5': 'sapui5', 'openui5-api': 'sapui5', // Map UI5 API to sapui5 source // ... more hardcoded mappings }; // After: Metadata-driven (1 line) const mappings = getAllLibraryMappings(); return mappings[sourceId] || sourceId; ``` #### `src/lib/localDocs.ts` ๐Ÿ”„ **MAJOR REFACTOR** **Removed hardcoded configurations:** - โŒ `DOC_URL_CONFIGS` (45 lines) โ†’ โœ… `getDocUrlConfig()` - โŒ Source path mappings (75 lines ร— 3 locations) โ†’ โœ… `getSourcePath()` - โŒ Context boost logic (50 lines) โ†’ โœ… `getContextBoosts()` - โŒ Context emojis (10 lines) โ†’ โœ… `getContextEmoji()` **Total reduction: ~250+ lines of hardcoded configuration** ### **Deployment Configuration** #### `ecosystem.config.cjs` ๐Ÿš€ **SIMPLIFIED** ```javascript // Before: 9 reranker environment variables per service env: { RERANKER_MODEL: "", SEARCH_K: "100", W_RERANKER: "0.8", W_BM25: "0.2", RERANKER_TIMEOUT_MS: "1000", // ... more } // After: Clean BM25-only configuration env: { NODE_ENV: "production", RETURN_K: "25" // Centralized result limit } ``` #### `.github/workflows/deploy-mcp-sap-docs.yml` ๐Ÿš€ **UPDATED** - Removed transformers cache directory creation - Updated deployment comments for BM25-only system - Added metadata.json existence check ## ๐ŸŽฏ Benefits Achieved ### **1. Single Source of Truth** - All source configurations in one file (`src/metadata.json`) - No more hunting through multiple files for settings - Consistent configuration across all components ### **2. Easy Maintenance** - Add new documentation sources without code changes - Modify boosts, URLs, or paths in metadata.json only - No need to update multiple hardcoded locations ### **3. Type Safety** - Comprehensive TypeScript interfaces for all metadata - Compile-time validation of configuration access - IntelliSense support for all configuration properties ### **4. Cleaner Codebase** - **~250+ lines** of hardcoded configuration removed - Simplified core configuration files - More readable and maintainable code ### **5. Flexible Configuration** - Environment variable overrides still supported - Easy to add new configuration properties - Backward compatibility maintained ## ๐Ÿ”ง Migration Impact ### **Zero Breaking Changes** - All existing functionality preserved - Same search results and behavior - All tests passing (TypeScript + smoke tests) ### **Performance Impact** - Minimal: Metadata loaded once at startup - No runtime performance degradation - Same search speed and accuracy ### **Deployment Impact** - Simplified PM2 configuration - Faster deployment (no model downloads) - Reduced memory usage in production ## ๐Ÿ“Š Configuration Comparison ### **Before: Scattered Configuration** ``` src/lib/config.ts - SOURCE_BOOSTS (9 sources) src/lib/localDocs.ts - DOC_URL_CONFIGS (11 sources) src/lib/localDocs.ts - Source paths (12 sources ร— 3 locations) src/lib/localDocs.ts - Context boosts (7 contexts) src/lib/localDocs.ts - Context emojis (7 emojis) src/lib/search.ts - Library mappings (9 mappings) ecosystem.config.cjs - Reranker env vars (9 vars ร— 3 services) ``` ### **After: Centralized Configuration** ``` src/metadata.json - ALL source configurations src/lib/metadata.ts - Type-safe APIs for access src/lib/config.ts - Core system settings only ecosystem.config.cjs - Essential env vars only ``` ## ๐Ÿš€ Usage Examples ### **Adding a New Documentation Source** ```json // Just add to src/metadata.json - no code changes needed! { "id": "new-docs", "type": "documentation", "libraryId": "/new-docs", "sourcePath": "new-docs/content", "baseUrl": "https://example.com/docs", "pathPattern": "/{file}", "anchorStyle": "github", "boost": 0.05, "tags": ["new", "documentation"] } ``` ### **Modifying Context Boosts** ```json // Adjust in src/metadata.json "contextBoosts": { "New Context": { "/new-docs": 1.0, "/sapui5": 0.3 } } ``` ### **Using the New APIs** ```typescript // Get source path for any library const sourcePath = getSourcePath('/sapui5'); // Returns: "sapui5-docs/docs" // Get URL configuration const urlConfig = getDocUrlConfig('/cap'); // Returns: { baseUrl: "https://cap.cloud.sap", pathPattern: "/docs/{file}", ... } // Get context-specific boosts const boosts = getContextBoosts('UI5'); // Returns: { "/sapui5": 0.9, "/openui5-api": 0.9, ... } ``` ## ๐Ÿงช Testing & Validation ### **Comprehensive Testing** - โœ… TypeScript compilation successful - โœ… All smoke tests passing - โœ… No linting errors - โœ… Functionality preserved - โœ… Performance maintained ### **Validation Steps** 1. **Build Test**: `npm run build:tsc` - No compilation errors 2. **Smoke Test**: `npm run test:smoke` - All search functionality working 3. **Integration Test**: All metadata APIs returning expected values 4. **Deployment Test**: PM2 configuration validated ## ๐Ÿ”ฎ Future Enhancements ### **Easy Extensions** - **New Sources**: Add to metadata.json without code changes - **Custom Boosts**: Modify context boosts per environment - **A/B Testing**: Switch configurations via environment variables - **Dynamic Updates**: Hot-reload metadata without restarts ### **Advanced Features** - **User Preferences**: Per-user source preferences - **Analytics**: Track which sources are most useful - **Caching**: Cache frequently accessed metadata - **Validation**: Schema validation for metadata.json ## ๐Ÿ“ˆ Metrics ### **Code Reduction** - **~250+ lines** of hardcoded configuration removed - **5 files** significantly simplified - **12 new APIs** for type-safe configuration access - **1 centralized** metadata file ### **Maintainability Improvement** - **100%** of source configurations centralized - **0** breaking changes to existing functionality - **12** type-safe APIs for configuration access - **1** single file to modify for source changes ## ๐ŸŽ‰ Conclusion The metadata-driven configuration consolidation successfully transforms the SAP Docs MCP system from a scattered, hardcoded configuration approach to a centralized, maintainable, and type-safe metadata system. **Key Achievements:** - โœ… **Single source of truth** for all configurations - โœ… **Zero breaking changes** to existing functionality - โœ… **Comprehensive APIs** for type-safe configuration access - โœ… **Simplified maintenance** and deployment - โœ… **Future-proof architecture** for easy extensions The system is now significantly more maintainable, flexible, and ready for future enhancements while preserving all existing functionality and performance characteristics.

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/marianfoo/mcp-sap-docs'

If you have feedback or need assistance with the MCP directory API, please join our Discord server