vcluster-yaml-mcp-server 1.0.8 → 1.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vcluster-yaml-mcp-server",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "MCP server for querying vcluster YAML configurations using jq",
   "main": "src/index.js",
   "type": "module",

package/src/github.js

@@ -10,6 +10,20 @@ const REPO_NAME = 'vcluster';
 const cache = new Map();
 const CACHE_TTL = 15 * 60 * 1000; // 15 minutes
 
+// Fetch timeout configuration
+const FETCH_TIMEOUT_MS = 30000; // 30 seconds - generous for large files
+
+// Helper to create fetch with timeout
+function createFetchWithTimeout(timeoutMs = FETCH_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  return {
+    signal: controller.signal,
+    cleanup: () => clearTimeout(timeoutId)
+  };
+}
+
 class GitHubClient {
   constructor() {
     this.defaultBranch = 'main';
@@ -21,12 +35,15 @@ class GitHubClient {
     const cached = this.getFromCache(cacheKey);
     if (cached) return cached;
 
+    const { signal, cleanup } = createFetchWithTimeout();
+
     try {
       const response = await fetch(`${GITHUB_API_BASE}/repos/${REPO_OWNER}/${REPO_NAME}/tags`, {
         headers: {
           'Accept': 'application/vnd.github.v3+json',
           'User-Agent': 'vcluster-yaml-mcp-server'
-        }
+        },
+        signal
       });
 
       if (!response.ok) {
@@ -35,12 +52,18 @@ class GitHubClient {
 
       const tags = await response.json();
       const tagNames = tags.map(tag => tag.name);
-      
+
       this.setCache(cacheKey, tagNames);
       return tagNames;
     } catch (error) {
+      if (error.name === 'AbortError') {
+        console.error('Request timeout: fetching tags took longer than 30s');
+        return [];
+      }
       console.error('Error fetching tags:', error);
       return [];
+    } finally {
+      cleanup();
     }
   }
 
@@ -50,12 +73,15 @@ class GitHubClient {
     const cached = this.getFromCache(cacheKey);
     if (cached) return cached;
 
+    const { signal, cleanup } = createFetchWithTimeout();
+
     try {
       const response = await fetch(`${GITHUB_API_BASE}/repos/${REPO_OWNER}/${REPO_NAME}/branches`, {
         headers: {
           'Accept': 'application/vnd.github.v3+json',
           'User-Agent': 'vcluster-yaml-mcp-server'
-        }
+        },
+        signal
       });
 
       if (!response.ok) {
@@ -64,12 +90,18 @@ class GitHubClient {
 
       const branches = await response.json();
       const branchNames = branches.map(branch => branch.name);
-      
+
       this.setCache(cacheKey, branchNames);
       return branchNames;
     } catch (error) {
+      if (error.name === 'AbortError') {
+        console.error('Request timeout: fetching branches took longer than 30s');
+        return ['main'];
+      }
       console.error('Error fetching branches:', error);
       return ['main'];
+    } finally {
+      cleanup();
     }
   }
 
@@ -90,12 +122,15 @@ class GitHubClient {
     const cached = this.getFromCache(cacheKey);
     if (cached) return cached;
 
+    const { signal, cleanup } = createFetchWithTimeout();
+
     try {
       const url = `${GITHUB_RAW_BASE}/${REPO_OWNER}/${REPO_NAME}/${actualRef}/${path}`;
       const response = await fetch(url, {
         headers: {
           'User-Agent': 'vcluster-yaml-mcp-server'
-        }
+        },
+        signal
       });
 
       if (!response.ok) {
@@ -109,7 +144,12 @@ class GitHubClient {
       this.setCache(cacheKey, content);
       return content;
     } catch (error) {
+      if (error.name === 'AbortError') {
+        throw new Error(`Timeout: fetching ${path} took longer than 30s`);
+      }
       throw new Error(`Failed to fetch ${path}: ${error.message}`);
+    } finally {
+      cleanup();
     }
   }
 

package/src/http-server.js

@@ -6,6 +6,7 @@ import express from 'express';
 import rateLimit from 'express-rate-limit';
 import { requireApiKey } from './middleware/auth.js';
 import promClient from 'prom-client';
+import { getHealthInfo, getServerInfo } from './server-info.js';
 
 const PORT = process.env.PORT || 3000;
 const REQUIRE_AUTH = process.env.REQUIRE_AUTH === 'true';
@@ -68,12 +69,7 @@ const mcpLimiter = rateLimit({
 
 // Health check endpoint
 app.get('/health', apiLimiter, (_req, res) => {
-  res.json({
-    status: 'ok',
-    name: 'vcluster-yaml-mcp-server',
-    version: '0.1.0',
-    timestamp: new Date().toISOString()
-  });
+  res.json(getHealthInfo());
 });
 
 // Prometheus metrics endpoint
@@ -85,15 +81,12 @@ app.get('/metrics', async (_req, res) => {
 // Root endpoint info
 app.get('/', (_req, res) => {
   res.json({
-    name: 'vcluster-yaml-mcp-server',
-    version: '0.1.0',
-    description: 'MCP server for querying vCluster YAML configurations',
+    ...getServerInfo(),
     endpoints: {
       mcp: '/mcp',
       health: '/health',
       metrics: '/metrics'
-    },
-    documentation: 'https://github.com/Piotr1215/vcluster-yaml-mcp-server'
+    }
   });
 });
 

package/src/server-info.js

@@ -0,0 +1,72 @@
+import { readFile } from 'fs/promises';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+// Load package.json once at module level
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJson = JSON.parse(
+  await readFile(join(__dirname, '../package.json'), 'utf-8')
+);
+
+// Build metadata from environment (injected by Docker/CI)
+const buildInfo = {
+  version: packageJson.version,
+  gitSha: process.env.GIT_SHA || 'unknown',
+  buildDate: process.env.BUILD_DATE || 'unknown',
+  imageVersion: process.env.IMAGE_VERSION || packageJson.version
+};
+
+/**
+ * Get complete server information including version, build info, and runtime details
+ * @returns {Object} Server metadata object
+ */
+export function getServerInfo() {
+  return {
+    name: 'vcluster-yaml-mcp-server',
+    description: packageJson.description,
+    version: buildInfo.version,
+    repository: 'https://github.com/Piotr1215/vcluster-yaml-mcp-server',
+    documentation: 'https://github.com/Piotr1215/vcluster-yaml-mcp-server#readme',
+    license: 'MIT',
+    build: {
+      gitSha: buildInfo.gitSha,
+      buildDate: buildInfo.buildDate,
+      imageVersion: buildInfo.imageVersion
+    },
+    runtime: {
+      nodeVersion: process.version,
+      platform: process.platform,
+      arch: process.arch
+    }
+  };
+}
+
+/**
+ * Get simplified version info for health checks
+ * @returns {Object} Health check metadata
+ */
+export function getHealthInfo() {
+  return {
+    status: 'ok',
+    name: 'vcluster-yaml-mcp-server',
+    version: packageJson.version,
+    image: {
+      version: buildInfo.imageVersion,
+      gitSha: buildInfo.gitSha,
+      buildDate: buildInfo.buildDate
+    },
+    timestamp: new Date().toISOString()
+  };
+}
+
+/**
+ * Get basic server metadata for MCP Server constructor
+ * @returns {Object} MCP server metadata
+ */
+export function getMcpServerInfo() {
+  return {
+    name: 'vcluster-yaml-mcp-server',
+    version: packageJson.version
+  };
+}

package/src/server.js

@@ -1,17 +1,21 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
 import { githubClient } from './github.js';
 import { executeToolHandler } from './tool-registry.js';
+import { getMcpServerInfo, getServerInfo } from './server-info.js';
 
 export function createServer() {
   const server = new Server(
-    {
-      name: 'vcluster-yaml-mcp-server',
-      version: '0.1.0'
-    },
+    getMcpServerInfo(),
     {
       capabilities: {
-        tools: {}
+        tools: {},
+        resources: {}
       }
     }
   );
@@ -128,5 +132,37 @@ export function createServer() {
     return executeToolHandler(name, args, githubClient);
   });
 
+  // Resource handlers
+  server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return {
+      resources: [
+        {
+          uri: 'server://info',
+          name: 'Server Information',
+          description: 'Version, build info, and metadata about this MCP server',
+          mimeType: 'application/json'
+        }
+      ]
+    };
+  });
+
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+
+    if (uri === 'server://info') {
+      return {
+        contents: [
+          {
+            uri: 'server://info',
+            mimeType: 'application/json',
+            text: JSON.stringify(getServerInfo(), null, 2)
+          }
+        ]
+      };
+    }
+
+    throw new Error(`Unknown resource: ${uri}`);
+  });
+
   return server;
 }

package/src/tool-handlers.js

@@ -186,38 +186,48 @@ export async function handleListVersions(args, githubClient) {
 /**
  * Handle: smart-query
  * Pure function except for I/O
+ * CRITICAL: Must never fail - always return helpful results or fallback
  */
 export async function handleSmartQuery(args, githubClient) {
   const { query, version = 'main', file = 'chart/values.yaml' } = args;
 
-  const yamlData = await githubClient.getYamlContent(file, version);
-  const searchTerm = query.toLowerCase();
+  try {
+    const yamlData = await githubClient.getYamlContent(file, version);
+    const searchTerm = query.toLowerCase();
 
-  // Extract all paths (pure function)
-  const allInfo = extractYamlInfo(yamlData);
+    // Extract all paths (pure function)
+    const allInfo = extractYamlInfo(yamlData);
 
-  // Search (pure function)
-  const results = searchYaml(allInfo, searchTerm);
+    // Search (pure function)
+    const results = searchYaml(allInfo, searchTerm);
 
-  // Handle no matches
-  if (results.length === 0) {
-    const similarPaths = findSimilarPaths(allInfo, searchTerm);
-    const formatted = formatNoMatches({ query, fileName: file, version, similarPaths, yamlData });
-    return buildSuccessResponse(formatted);
-  }
+    // Handle no matches
+    if (results.length === 0) {
+      const similarPaths = findSimilarPaths(allInfo, searchTerm);
+      const formatted = formatNoMatches({ query, fileName: file, version, similarPaths, yamlData });
+      return buildSuccessResponse(formatted);
+    }
 
-  // Sort by relevance (pure function)
-  const sorted = sortByRelevance(results, searchTerm);
+    // Sort by relevance (pure function)
+    const sorted = sortByRelevance(results, searchTerm);
 
-  // Format results
-  const formatted = formatQueryResults(sorted, {
-    query,
-    fileName: file,
-    version,
-    maxResults: 50
-  });
+    // Format results
+    const formatted = formatQueryResults(sorted, {
+      query,
+      fileName: file,
+      version,
+      maxResults: 50
+    });
 
-  return buildSuccessResponse(formatted);
+    return buildSuccessResponse(formatted);
+  } catch (error) {
+    // Graceful fallback - always provide helpful message
+    const errorMsg = error.message.includes('Timeout')
+      ? `⏱️ Request timed out while fetching ${file} (version: ${version}).\n\n**Suggestions:**\n- Try a different version (e.g., "v0.29.1")\n- The file might be temporarily unavailable\n- Check if the file path is correct`
+      : `❌ Error searching for "${query}" in ${file} (version: ${version}):\n${error.message}\n\n**Suggestions:**\n- Try "list-versions" to see available versions\n- Verify the file path is correct`;
+
+    return buildSuccessResponse(errorMsg);
+  }
 }
 
 /**
@@ -227,10 +237,24 @@ export async function handleSmartQuery(args, githubClient) {
 export async function handleExtractRules(args, githubClient) {
   const { version = 'main', file = 'chart/values.yaml', section } = args;
 
-  const content = await githubClient.getFileContent(file, version);
-  const rules = extractValidationRulesFromComments(content, section);
-
-  return buildSuccessResponse(JSON.stringify(rules, null, 2));
+  try {
+    const content = await githubClient.getFileContent(file, version);
+    const rules = extractValidationRulesFromComments(content, section);
+
+    // Remove originalComments to reduce response size
+    const optimizedRules = {
+      ...rules,
+      rules: rules.rules.map(r => ({
+        path: r.path,
+        instructions: r.instructions
+      }))
+    };
+
+    // No pretty-printing to reduce size
+    return buildSuccessResponse(JSON.stringify(optimizedRules));
+  } catch (error) {
+    return buildErrorResponse(`Failed to extract validation rules: ${error.message}`);
+  }
 }
 
 /**