Grafana UI MCP Server

Instructions

Implementation Reference

• src/tools.ts:142-318 (handler)

  Primary MCP server.tool registration and handler implementation for the 'grafana_ui' tool. Dispatches to specific actions using axios utilities for fetching Grafana UI components, demos, metadata, etc.
  "grafana_ui", "Unified tool for accessing Grafana UI components, documentation, themes, and metadata", unifiedToolSchemaRaw, async (params) => { try { // Validate parameters based on action const validatedParams = unifiedToolSchema.parse(params); switch (validatedParams.action) { case "get_component": const sourceCode = await axios.getComponentSource( validatedParams.componentName!, ); return createSuccessResponse(sourceCode); case "get_demo": const demoCode = await axios.getComponentDemo( validatedParams.componentName!, ); return createSuccessResponse(demoCode); case "list_components": const components = await axios.getAvailableComponents(); return createSuccessResponse({ components: components.sort(), total: components.length, }); case "get_metadata": const metadata = await axios.getComponentMetadata( validatedParams.componentName!, ); if (!metadata) { throw new McpError( ErrorCode.InvalidRequest, `Metadata not found for component "${validatedParams.componentName}"`, ); } return createSuccessResponse(metadata); case "get_directory": const directoryTree = await axios.buildDirectoryTree( validatedParams.owner || axios.paths.REPO_OWNER, validatedParams.repo || axios.paths.REPO_NAME, validatedParams.path || axios.paths.COMPONENTS_PATH, validatedParams.branch || axios.paths.REPO_BRANCH, ); return createSuccessResponse(directoryTree); case "get_documentation": const mdxContent = await axios.getComponentDocumentation( validatedParams.componentName!, ); const parsedContent = parseMDXContent( validatedParams.componentName!, mdxContent, ); return createSuccessResponse({ title: parsedContent.title, sections: parsedContent.sections.map((section) => ({ title: section.title, level: section.level, content: section.content.substring(0, 500) + (section.content.length > 500 ? "..." : ""), examples: section.examples.length, })), totalExamples: parsedContent.examples.length, imports: parsedContent.imports, components: parsedContent.components, }); case "get_stories": const storyContent = await axios.getComponentDemo( validatedParams.componentName!, ); const storyMetadata = parseStoryMetadata( validatedParams.componentName!, storyContent, ); const examples = extractStoryExamples(storyContent); return createSuccessResponse({ component: storyMetadata.componentName, meta: storyMetadata.meta, totalStories: storyMetadata.totalStories, hasInteractiveStories: storyMetadata.hasInteractiveStories, examples: examples.slice(0, 5), rawStoryCode: storyContent.substring(0, 1000) + (storyContent.length > 1000 ? "..." : ""), }); case "get_tests": const testContent = await axios.getComponentTests( validatedParams.componentName!, ); const testDescriptions = []; const testRegex = /(describe|it|test)\s*\(\s*['`"]([^'`"]+)['`"]/g; let match; while ((match = testRegex.exec(testContent)) !== null) { testDescriptions.push({ type: match[1], description: match[2], }); } return createSuccessResponse({ component: validatedParams.componentName, testDescriptions: testDescriptions.slice(0, 10), totalTests: testDescriptions.filter( (t) => t.type === "it" || t.type === "test", ).length, testCode: testContent.substring(0, 2000) + (testContent.length > 2000 ? "..." : ""), }); case "search": const searchResults = await axios.searchComponents( validatedParams.query!, validatedParams.includeDescription || false, ); return createSuccessResponse({ query: validatedParams.query, includeDescription: validatedParams.includeDescription || false, results: searchResults, totalResults: searchResults.length, }); case "get_theme_tokens": const themeFiles = await axios.getThemeFiles( validatedParams.category, ); const processedThemes: any = {}; for (const [themeName, themeContent] of Object.entries( themeFiles.themes, )) { if (typeof themeContent === "string") { const tokens = extractThemeTokens(themeContent); const themeMetadata = extractThemeMetadata(themeContent); processedThemes[themeName] = { metadata: themeMetadata, tokens: validatedParams.category ? filterTokensByCategory(tokens, validatedParams.category) : tokens, }; } } return createSuccessResponse({ category: validatedParams.category || "all", themes: processedThemes, availableThemes: Object.keys(processedThemes), }); case "get_dependencies": const dependencies = await axios.getComponentDependencies( validatedParams.componentName!, validatedParams.deep || false, ); return createSuccessResponse(dependencies); default: throw new McpError( ErrorCode.InvalidParams, `Unknown action: ${validatedParams.action}`, ); } } catch (error) { if (error instanceof McpError) { throw error; } throw new McpError( ErrorCode.InternalError, `Failed to execute action "${(params as any).action}": ${error instanceof Error ? error.message : String(error)}`, ); } }, );
• src/tools.ts:88-138 (schema)

  Zod validation schema for 'grafana_ui' tool inputs, defining actions and conditional parameters.
  const unifiedToolSchema = z .object({ action: z.enum([ "get_component", "get_demo", "list_components", "get_metadata", "get_directory", "get_documentation", "get_stories", "get_tests", "search", "get_theme_tokens", "get_dependencies", ]), componentName: z.string().optional(), query: z.string().optional(), includeDescription: z.boolean().optional(), category: z.string().optional(), deep: z.boolean().optional(), path: z.string().optional(), owner: z.string().optional(), repo: z.string().optional(), branch: z.string().optional(), }) .refine( (data) => { // Validate required parameters based on action switch (data.action) { case "get_component": case "get_demo": case "get_metadata": case "get_documentation": case "get_stories": case "get_tests": case "get_dependencies": return !!data.componentName; case "search": return !!data.query; case "list_components": case "get_directory": case "get_theme_tokens": return true; default: return false; } }, { message: "Missing required parameters for the specified action", }, );
• src/handler.ts:168-175 (registration)

  Tool schema lookup in request handler, specifically registers schema for 'grafana_ui'.
  function getToolSchema(toolName: string): z.ZodType | undefined { try { switch (toolName) { case "grafana_ui": return unifiedToolSchema; default: return undefined; }
• src/handler.ts:42-44 (registration)

  Registers the list tools handler using exported tools from tools.ts which includes 'grafana_ui'.
  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: Object.values(tools), }));
• src/utils/cache.ts:185-480 (helper)

  Grafana UI specific cache utility used for caching API responses in tool operations.
  export class GrafanaUICache { private cache: Cache; // Cache TTL configurations for different types of data private static readonly TTL = { COMPONENT_LIST: 24 * 60 * 60 * 1000, // 24 hours - component list changes rarely COMPONENT_SOURCE: 12 * 60 * 60 * 1000, // 12 hours - source code changes occasionally COMPONENT_METADATA: 6 * 60 * 60 * 1000, // 6 hours - metadata changes occasionally COMPONENT_STORIES: 6 * 60 * 60 * 1000, // 6 hours - stories change occasionally COMPONENT_DOCS: 6 * 60 * 60 * 1000, // 6 hours - docs change occasionally DIRECTORY_STRUCTURE: 24 * 60 * 60 * 1000, // 24 hours - directory structure changes rarely RATE_LIMIT: 5 * 60 * 1000, // 5 minutes - rate limit info changes frequently PARSED_METADATA: 12 * 60 * 60 * 1000, // 12 hours - parsed metadata is expensive to compute }; constructor(cache: Cache) { this.cache = cache; } /** * Generate cache key for component source code */ componentSourceKey(componentName: string): string { return `component:${componentName}:source`; } /** * Generate cache key for component metadata */ componentMetadataKey(componentName: string): string { return `component:${componentName}:metadata`; } /** * Generate cache key for component stories */ componentStoriesKey(componentName: string): string { return `component:${componentName}:stories`; } /** * Generate cache key for component documentation */ componentDocsKey(componentName: string): string { return `component:${componentName}:docs`; } /** * Generate cache key for component files */ componentFilesKey(componentName: string): string { return `component:${componentName}:files`; } /** * Generate cache key for parsed component metadata */ componentParsedMetadataKey(componentName: string): string { return `component:${componentName}:parsed-metadata`; } /** * Generate cache key for component list */ componentListKey(): string { return "components:list"; } /** * Generate cache key for directory structure */ directoryStructureKey(path?: string): string { return `directory:${path || "components"}:structure`; } /** * Generate cache key for rate limit info */ rateLimitKey(): string { return "github:rate-limit"; } /** * Cache component source code */ async getOrFetchComponentSource( componentName: string, fetchFn: () => Promise<string>, ): Promise<string> { return this.cache.getOrFetch( this.componentSourceKey(componentName), fetchFn, GrafanaUICache.TTL.COMPONENT_SOURCE, ); } /** * Cache component metadata */ async getOrFetchComponentMetadata( componentName: string, fetchFn: () => Promise<any>, ): Promise<any> { return this.cache.getOrFetch( this.componentMetadataKey(componentName), fetchFn, GrafanaUICache.TTL.COMPONENT_METADATA, ); } /** * Cache component stories */ async getOrFetchComponentStories( componentName: string, fetchFn: () => Promise<string>, ): Promise<string> { return this.cache.getOrFetch( this.componentStoriesKey(componentName), fetchFn, GrafanaUICache.TTL.COMPONENT_STORIES, ); } /** * Cache component documentation */ async getOrFetchComponentDocs( componentName: string, fetchFn: () => Promise<string>, ): Promise<string> { return this.cache.getOrFetch( this.componentDocsKey(componentName), fetchFn, GrafanaUICache.TTL.COMPONENT_DOCS, ); } /** * Cache component files */ async getOrFetchComponentFiles( componentName: string, fetchFn: () => Promise<any>, ): Promise<any> { return this.cache.getOrFetch( this.componentFilesKey(componentName), fetchFn, GrafanaUICache.TTL.COMPONENT_METADATA, ); } /** * Cache parsed component metadata */ async getOrFetchParsedMetadata( componentName: string, fetchFn: () => Promise<any>, ): Promise<any> { return this.cache.getOrFetch( this.componentParsedMetadataKey(componentName), fetchFn, GrafanaUICache.TTL.PARSED_METADATA, ); } /** * Cache component list */ async getOrFetchComponentList( fetchFn: () => Promise<string[]>, ): Promise<string[]> { return this.cache.getOrFetch( this.componentListKey(), fetchFn, GrafanaUICache.TTL.COMPONENT_LIST, ); } /** * Cache directory structure */ async getOrFetchDirectoryStructure( path: string, fetchFn: () => Promise<any>, ): Promise<any> { return this.cache.getOrFetch( this.directoryStructureKey(path), fetchFn, GrafanaUICache.TTL.DIRECTORY_STRUCTURE, ); } /** * Cache rate limit info */ async getOrFetchRateLimit(fetchFn: () => Promise<any>): Promise<any> { return this.cache.getOrFetch( this.rateLimitKey(), fetchFn, GrafanaUICache.TTL.RATE_LIMIT, ); } /** * Invalidate all cache entries for a specific component */ invalidateComponent(componentName: string): void { const prefixes = [`component:${componentName}:`]; prefixes.forEach((prefix) => { this.cache.deleteByPrefix(prefix); }); } /** * Invalidate all component-related cache entries */ invalidateAllComponents(): void { this.cache.deleteByPrefix("component:"); this.cache.delete(this.componentListKey()); } /** * Get cache statistics */ getStats(): { totalItems: number; componentSourceCached: number; componentMetadataCached: number; componentStoriesCached: number; componentDocsCached: number; expiredItems: number; } { const totalItems = this.cache.size(); // Count different types of cached items let componentSourceCached = 0; let componentMetadataCached = 0; let componentStoriesCached = 0; let componentDocsCached = 0; // This is a simple approximation - in a real implementation, // we'd iterate through the cache keys to count by pattern const estimatedItemsPerType = Math.floor(totalItems / 4); componentSourceCached = estimatedItemsPerType; componentMetadataCached = estimatedItemsPerType; componentStoriesCached = estimatedItemsPerType; componentDocsCached = estimatedItemsPerType; const expiredItems = this.cache.clearExpired(); return { totalItems, componentSourceCached, componentMetadataCached, componentStoriesCached, componentDocsCached, expiredItems, }; } /** * Warm up cache with commonly used components */ async warmUp( commonComponents: string[], fetchFunctions: { getComponentSource: (name: string) => Promise<string>; getComponentMetadata: (name: string) => Promise<any>; getComponentStories: (name: string) => Promise<string>; getComponentDocs: (name: string) => Promise<string>; }, ): Promise<void> { const promises = commonComponents.flatMap((componentName) => [ this.getOrFetchComponentSource(componentName, () => fetchFunctions.getComponentSource(componentName), ), this.getOrFetchComponentMetadata(componentName, () => fetchFunctions.getComponentMetadata(componentName), ), this.getOrFetchComponentStories(componentName, () => fetchFunctions.getComponentStories(componentName), ), this.getOrFetchComponentDocs(componentName, () => fetchFunctions.getComponentDocs(componentName), ), ]); // Execute all requests in parallel, but catch errors to prevent one failure from stopping others await Promise.allSettled(promises); } } // Export a singleton instance for Grafana UI cache export const grafanaUICache = new GrafanaUICache(cache);