vcluster-yaml-mcp-server 1.1.1 → 1.2.0

package/README.md

@@ -52,7 +52,7 @@ Run the server locally via npx:
   "mcpServers": {
     "vcluster-yaml": {
       "command": "npx",
-      "args": ["-y", "vcluster-yaml-mcp-server"]
+      "args": ["-y", "vcluster-yaml-mcp-server@latest"]
     }
   }
 }
@@ -287,10 +287,12 @@ npm run start:http
 
 ## Technical Details
 
-- **SDK**: `@modelcontextprotocol/sdk` v1.20.1 (Streamable HTTP transport)
+- **SDK**: `@modelcontextprotocol/sdk` v1.25.2 using `McpServer` high-level API
 - **Node**: >=18
 - **Transport**: Both stdio (local) and HTTP/SSE (remote)
 - **Dependencies**: `js-yaml` for parsing, `node-jq` for querying, `node-fetch` for GitHub API
+- **Tool Annotations**: All tools include `readOnlyHint`/`destructiveHint` for client optimization
+- **Server Instructions**: Includes instructions for MCP tool search auto mode
 
 ## Release Process
 

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "vcluster-yaml-mcp-server",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "MCP server for querying vcluster YAML configurations using jq",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Piotr1215/vcluster-yaml-mcp"
+  },
   "main": "src/index.js",
   "type": "module",
   "bin": {
-    "vcluster-yaml-mcp-server": "./src/cli.js",
-    "vcluster-yaml-mcp": "./src/index.js",
+    "vcluster-yaml-mcp-server": "./src/index.js",
     "vcluster-yaml": "./src/cli.js"
   },
   "files": [
@@ -25,14 +28,14 @@
     "test:ci": "vitest run tests/ci/",
     "test:all": "vitest run",
     "test:watch": "vitest --exclude tests/integration/**/*.test.js",
-    "test:coverage": "vitest run --coverage --exclude tests/integration/**/*.test.js",
+    "test:coverage": "vitest run --coverage --exclude tests/integration/**/*.test.js --exclude tests/ci/**/*.test.js --exclude tests/performance.test.js",
     "test:mutation": "stryker run",
     "complexity": "eslint --config eslint.config.complexity.js src/**/*.js",
     "complexity:json": "eslint --config eslint.config.complexity.js --format json --output-file reports/complexity.json src/**/*.js || true",
     "lint:workflows": "actionlint .github/workflows/*.yml"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.20.1",
+    "@modelcontextprotocol/sdk": "^1.25.2",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/auto-instrumentations-node": "^0.66.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.207.0",

package/src/server-info.js

@@ -70,3 +70,17 @@ export function getMcpServerInfo() {
     version: packageJson.version
   };
 }
+
+/**
+ * Get server options including instructions for MCP clients
+ * @returns {Object} MCP server options
+ */
+export function getMcpServerOptions() {
+  return {
+    capabilities: {
+      tools: {},
+      resources: {}
+    },
+    instructions: "vCluster configuration assistant. Use smart-query for any configuration questions (natural language search). Use create-vcluster-config when generating configs - it auto-validates. Use list-versions first to discover available versions. Use validate-config for user-provided YAML. Use extract-validation-rules to understand semantic constraints."
+  };
+}

package/src/server.js

@@ -1,168 +1,190 @@
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import {
-  ListToolsRequestSchema,
-  CallToolRequestSchema,
-  ListResourcesRequestSchema,
-  ReadResourceRequestSchema
-} from '@modelcontextprotocol/sdk/types.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { githubClient } from './github.js';
-import { executeToolHandler } from './tool-registry.js';
-import { getMcpServerInfo, getServerInfo } from './server-info.js';
+import {
+  handleCreateConfig,
+  handleListVersions,
+  handleSmartQuery,
+  handleExtractRules,
+  handleValidateConfig
+} from './tool-handlers.js';
+import { getMcpServerInfo, getMcpServerOptions, getServerInfo } from './server-info.js';
 
 export function createServer() {
-  const server = new Server(
-    getMcpServerInfo(),
+  const serverInfo = getMcpServerInfo();
+  const serverOptions = getMcpServerOptions();
+
+  const server = new McpServer(serverInfo, serverOptions);
+
+  // Register: list-versions
+  server.registerTool(
+    'list-versions',
     {
-      capabilities: {
-        tools: {},
-        resources: {}
+      description: 'DISCOVERY: Find all available vCluster versions. Returns GitHub tags (stable releases) and branches (development versions). Use this to discover what versions are available before querying specific versions.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+        required: []
+      },
+      annotations: {
+        readOnlyHint: true
       }
+    },
+    async () => {
+      const result = await handleListVersions({}, githubClient);
+      return result;
     }
   );
 
-  // Tool definitions
-  server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return {
-      tools: [
-        {
-          name: 'list-versions',
-          description: 'DISCOVERY: Find all available vCluster versions. Returns GitHub tags (stable releases) and branches (development versions). Use this to discover what versions are available before querying specific versions.',
-          inputSchema: {
-            type: 'object',
-            properties: {},
-            required: []
+  // Register: smart-query
+  server.registerTool(
+    'smart-query',
+    {
+      description: 'UNIVERSAL SEARCH: Your go-to tool for finding ANY vCluster configuration! Understands natural language, searches intelligently, and finds related settings. USE THIS FIRST for any config questions! Examples: "show me namespace settings", "how is etcd configured?", "what networking options exist?", "find service CIDR". Searches chart/values.yaml by default.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description: 'Natural language query (e.g., "namespace syncing", "high availability", "storage options")'
+          },
+          file: {
+            type: 'string',
+            description: 'Optional: specific file to search (default: "chart/values.yaml")'
+          },
+          version: {
+            type: 'string',
+            description: 'Version tag or branch (e.g., "v0.24.0", "main"). Defaults to "main".'
           }
         },
-        {
-          name: 'smart-query',
-          description: 'UNIVERSAL SEARCH: Your go-to tool for finding ANY vCluster configuration! Understands natural language, searches intelligently, and finds related settings. USE THIS FIRST for any config questions! Examples: "show me namespace settings", "how is etcd configured?", "what networking options exist?", "find service CIDR". Searches chart/values.yaml by default.',
-          inputSchema: {
-            type: 'object',
-            properties: {
-              query: {
-                type: 'string',
-                description: 'Natural language query (e.g., "namespace syncing", "high availability", "storage options")'
-              },
-              file: {
-                type: 'string',
-                description: 'Optional: specific file to search (default: "chart/values.yaml")'
-              },
-              version: {
-                type: 'string',
-                description: 'Version tag or branch (e.g., "v0.24.0", "main"). Defaults to "main".'
-              }
-            },
-            required: ['query']
+        required: ['query']
+      },
+      annotations: {
+        readOnlyHint: true
+      }
+    },
+    async ({ query, file, version }) => {
+      const result = await handleSmartQuery({ query, file, version }, githubClient);
+      return result;
+    }
+  );
+
+  // Register: create-vcluster-config
+  server.registerTool(
+    'create-vcluster-config',
+    {
+      description: 'CONFIG CREATION WORKFLOW: Use this when generating vCluster configurations for users. This tool REQUIRES you to provide the YAML you created and automatically validates it before returning to the user. Returns validation result + formatted config. This ensures every config you create is validated.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          yaml_content: {
+            type: 'string',
+            description: 'The vCluster YAML configuration you generated (required)'
+          },
+          description: {
+            type: 'string',
+            description: 'Brief description of what this config does (optional, helpful for user)'
+          },
+          version: {
+            type: 'string',
+            description: 'Version tag or branch (e.g., "v0.24.0", "main"). Defaults to "main".'
           }
         },
-        {
-          name: 'create-vcluster-config',
-          description: 'CONFIG CREATION WORKFLOW: Use this when generating vCluster configurations for users. This tool REQUIRES you to provide the YAML you created and automatically validates it before returning to the user. Returns validation result + formatted config. This ensures every config you create is validated.',
-          inputSchema: {
-            type: 'object',
-            properties: {
-              yaml_content: {
-                type: 'string',
-                description: 'The vCluster YAML configuration you generated (required)'
-              },
-              description: {
-                type: 'string',
-                description: 'Brief description of what this config does (optional, helpful for user)'
-              },
-              version: {
-                type: 'string',
-                description: 'Version tag or branch (e.g., "v0.24.0", "main"). Defaults to "main".'
-              }
-            },
-            required: ['yaml_content']
+        required: ['yaml_content']
+      },
+      annotations: {
+        readOnlyHint: false
+      }
+    },
+    async ({ yaml_content, description, version }) => {
+      const result = await handleCreateConfig({ yaml_content, description, version }, githubClient);
+      return result;
+    }
+  );
+
+  // Register: validate-config
+  server.registerTool(
+    'validate-config',
+    {
+      description: 'VALIDATION ONLY: Validates existing vCluster YAML (full config or partial snippet) against the schema. Use create-vcluster-config for configs you generate. Use this to validate user-provided configs or files from GitHub.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file: {
+            type: 'string',
+            description: 'File path in GitHub repo to validate. Optional if content is provided.'
+          },
+          content: {
+            type: 'string',
+            description: 'YAML content to validate (full config or partial snippet)'
+          },
+          version: {
+            type: 'string',
+            description: 'Version tag or branch (e.g., "v0.24.0", "main"). Defaults to "main".'
           }
         },
-        {
-          name: 'validate-config',
-          description: 'VALIDATION ONLY: Validates existing vCluster YAML (full config or partial snippet) against the schema. Use create-vcluster-config for configs you generate. Use this to validate user-provided configs or files from GitHub.',
-          inputSchema: {
-            type: 'object',
-            properties: {
-              file: {
-                type: 'string',
-                description: 'File path in GitHub repo to validate. Optional if content is provided.'
-              },
-              content: {
-                type: 'string',
-                description: 'YAML content to validate (full config or partial snippet)'
-              },
-              version: {
-                type: 'string',
-                description: 'Version tag or branch (e.g., "v0.24.0", "main"). Defaults to "main".'
-              }
-            },
-            required: []
+        required: []
+      },
+      annotations: {
+        readOnlyHint: true
+      }
+    },
+    async ({ file, content, version }) => {
+      const result = await handleValidateConfig({ file, content, version }, githubClient);
+      return result;
+    }
+  );
+
+  // Register: extract-validation-rules
+  server.registerTool(
+    'extract-validation-rules',
+    {
+      description: 'AI ASSISTANT: Extract validation rules, constraints, and best practices directly from values.yaml comments. Returns structured rules for AI to understand complex relationships and semantic validations that procedural code cannot handle. USE THIS when you need to understand the "why" behind configurations or validate semantic correctness beyond syntax.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file: {
+            type: 'string',
+            description: 'File path in GitHub repo (default: "chart/values.yaml")'
+          },
+          section: {
+            type: 'string',
+            description: 'Focus on specific section (e.g., "controlPlane", "sync", "networking")'
+          },
+          version: {
+            type: 'string',
+            description: 'Version tag or branch (e.g., "v0.24.0", "main"). Defaults to "main".'
           }
         },
-        {
-          name: 'extract-validation-rules',
-          description: 'AI ASSISTANT: Extract validation rules, constraints, and best practices directly from values.yaml comments. Returns structured rules for AI to understand complex relationships and semantic validations that procedural code cannot handle. USE THIS when you need to understand the "why" behind configurations or validate semantic correctness beyond syntax.',
-          inputSchema: {
-            type: 'object',
-            properties: {
-              file: {
-                type: 'string',
-                description: 'File path in GitHub repo (default: "chart/values.yaml")',
-                default: 'chart/values.yaml'
-              },
-              section: {
-                type: 'string',
-                description: 'Focus on specific section (e.g., "controlPlane", "sync", "networking")'
-              },
-              version: {
-                type: 'string',
-                description: 'Version tag or branch (e.g., "v0.24.0", "main"). Defaults to "main".'
-              }
-            },
-            required: []
-          }
-        }
-      ]
-    };
-  });
-
-  // Tool handler
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-    return executeToolHandler(name, args, githubClient);
-  });
+        required: []
+      },
+      annotations: {
+        readOnlyHint: true
+      }
+    },
+    async ({ file, section, version }) => {
+      const result = await handleExtractRules({ file, section, version }, githubClient);
+      return result;
+    }
+  );
 
-  // Resource handlers
-  server.setRequestHandler(ListResourcesRequestSchema, async () => {
-    return {
-      resources: [
+  // Register resource: server://info
+  server.registerResource(
+    'server-info',
+    'server://info',
+    {
+      description: 'Version, build info, and metadata about this MCP server',
+      mimeType: 'application/json'
+    },
+    async (uri) => ({
+      contents: [
         {
-          uri: 'server://info',
-          name: 'Server Information',
-          description: 'Version, build info, and metadata about this MCP server',
-          mimeType: 'application/json'
+          uri: uri.href,
+          mimeType: 'application/json',
+          text: JSON.stringify(getServerInfo(), null, 2)
         }
       ]
-    };
-  });
-
-  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;
 }