@abhishek8380/qconsul-mcp-server 1.0.0

package/.env.example

@@ -0,0 +1,12 @@
+# QConsul (Consul) Configuration
+# Copy this file to .env and fill in your credentials
+
+# Your Consul instance URL
+CONSUL_URL=https://qconsul.p19.eng.sjc01.qualys.com
+
+# Consul authentication credentials (HTTP Basic Auth)
+CONSUL_USERNAME=admin
+CONSUL_PASSWORD=admin
+
+# Default datacenter (e.g., eng-sjc01-p19)
+CONSUL_DATACENTER=eng-sjc01-p19

package/README.md

@@ -0,0 +1,433 @@
+# Qualys QConsul MCP Server
+
+A Model Context Protocol (MCP) server for HashiCorp Consul KV store operations. This server enables AI assistants to interact with Consul's key-value store through a standardized interface, allowing you to read, write, update, and delete configuration values directly from your IDE.
+
+**Built for Qualys infrastructure teams** to manage Consul KV configurations seamlessly.
+
+## Features
+
+- 🔍 **Search and list keys** - Discover keys with prefix matching and search
+- 📖 **Read key values** - Get individual or recursive key-value pairs
+- ✏️ **Create/Update keys** - Set or modify key-value pairs
+- 🗑️ **Delete keys** - Remove single keys or entire prefixes recursively
+- 🔐 **HTTP Basic Authentication** - Secure access with username/password
+- 🧠 **Dual naming** - Every tool available under both `*` and `qconsul_*` aliases
+- 🚀 **Zero installation** - Use with npx in your MCP client configuration
+
+## Use Case
+
+This MCP server is designed for teams using Consul KV store for configuration management. It allows you to:
+
+- **Update configuration files** directly from your IDE without switching to the Consul UI
+- **Search and discover** configuration keys across your infrastructure
+- **Bulk operations** on configuration hierarchies
+- **Version control integration** - Make config changes alongside code changes
+
+Perfect for DevOps teams managing microservices configuration in Consul.
+
+## Installation
+
+No installation required! Use with npx in your MCP client configuration.
+
+## Configuration for Windsurf
+
+Add this to your Windsurf MCP configuration file (`~/.codeium/windsurf/mcp_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "qconsul": {
+      "command": "npx",
+      "args": ["-y", "@abhishek8380/qconsul-mcp-server"],
+      "env": {
+        "CONSUL_URL": "https://qconsul.p19.eng.sjc01.qualys.com",
+        "CONSUL_USERNAME": "your-username",
+        "CONSUL_PASSWORD": "your-password",
+        "CONSUL_DATACENTER": "eng-sjc01-p19"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+- `CONSUL_URL` - Your Consul instance URL (e.g., `https://qconsul.p19.eng.sjc01.qualys.com`)
+- `CONSUL_USERNAME` - HTTP Basic Auth username (required)
+- `CONSUL_PASSWORD` - HTTP Basic Auth password (required)
+- `CONSUL_DATACENTER` - Default datacenter to use (e.g., `eng-sjc01-p19`)
+
+## Configuration for Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "qconsul": {
+      "command": "npx",
+      "args": ["-y", "@abhishek8380/qconsul-mcp-server"],
+      "env": {
+        "CONSUL_URL": "https://qconsul.p19.eng.sjc01.qualys.com",
+        "CONSUL_USERNAME": "your-username",
+        "CONSUL_PASSWORD": "your-password",
+        "CONSUL_DATACENTER": "eng-sjc01-p19"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+Every tool below can be called with either its standard name or the `qconsul_*` alias shown in parentheses.
+
+### Read Operations
+
+#### **get_key** (`qconsul_get_key`)
+Retrieve a value from Consul KV store by key path.
+
+**Parameters:**
+- `key` (string, required) - The key path to retrieve (e.g., `cloudview/config/setting`)
+- `raw` (boolean, optional) - Return raw value without metadata (default: `false`)
+- `datacenter` (string, optional) - Datacenter to query
+
+**Example:**
+```javascript
+{
+  "key": "cloudview/config/database",
+  "raw": false
+}
+```
+
+#### **list_keys** (`qconsul_list_keys`)
+List all keys under a prefix in Consul KV store.
+
+**Parameters:**
+- `prefix` (string, optional) - Key prefix to list (empty for all keys)
+- `separator` (string, optional) - Separator for grouping keys (e.g., `/`)
+- `datacenter` (string, optional) - Datacenter to query
+
+**Example:**
+```javascript
+{
+  "prefix": "cloudview/",
+  "separator": "/"
+}
+```
+
+#### **get_keys_recursive** (`qconsul_get_keys_recursive`)
+Retrieve all key-value pairs under a prefix recursively.
+
+**Parameters:**
+- `prefix` (string, optional) - Key prefix to retrieve (empty for all keys)
+- `datacenter` (string, optional) - Datacenter to query
+
+**Example:**
+```javascript
+{
+  "prefix": "cloudview/config/"
+}
+```
+
+#### **search_keys** (`qconsul_search_keys`)
+Search for keys matching a pattern in Consul KV store.
+
+**Parameters:**
+- `searchTerm` (string, required) - Search term to find in key names
+- `prefix` (string, optional) - Optional prefix to narrow search scope
+- `datacenter` (string, optional) - Datacenter to query
+
+**Example:**
+```javascript
+{
+  "searchTerm": "database",
+  "prefix": "cloudview/"
+}
+```
+
+### Write Operations
+
+#### **put_key** (`qconsul_put_key`)
+Create or update a key-value pair in Consul KV store.
+
+**Parameters:**
+- `key` (string, required) - The key path to create/update (e.g., `cloudview/config/setting`)
+- `value` (string, required) - The value to store
+- `datacenter` (string, optional) - Datacenter to use
+- `flags` (number, optional) - Optional flags for the key (default: `0`)
+
+**Example:**
+```javascript
+{
+  "key": "cloudview/config/timeout",
+  "value": "30"
+}
+```
+
+### Delete Operations
+
+#### **delete_key** (`qconsul_delete_key`)
+Delete a key or keys from Consul KV store.
+
+**Parameters:**
+- `key` (string, required) - The key path to delete
+- `recurse` (boolean, optional) - Delete all keys with this prefix (default: `false`)
+- `datacenter` (string, optional) - Datacenter to use
+
+**Example:**
+```javascript
+{
+  "key": "cloudview/config/old-setting",
+  "recurse": false
+}
+```
+
+## How to Use - CRUD Operations Guide
+
+### 1. **CREATE** - Add New Configuration
+
+**Create a single key:**
+```
+Ask: "Create a new key cloudview/config/new-feature with value 'enabled'"
+```
+
+**Create multiple keys (bulk upload):**
+```
+Ask: "Create these keys under cloudview/myapp/:
+- config.yml with database settings
+- kafka-client.yml with broker configs
+- application.properties with app settings"
+```
+
+**What happens:** The MCP server uses `put_key` to create new entries in Consul KV store.
+
+---
+
+### 2. **READ** - Retrieve Configuration
+
+**Read a single key:**
+```
+Ask: "Get the value of cloudview/config/database"
+Ask: "Show me cloudview/gcp-service/application.yml"
+```
+
+**List all keys under a prefix:**
+```
+Ask: "List all keys under cloudview/"
+Ask: "Show me all configuration files in cloudview/myapp/"
+```
+
+**Search for specific keys:**
+```
+Ask: "Search for keys containing 'database' in cloudview"
+Ask: "Find all kafka configuration keys"
+```
+
+**Get all keys recursively with values:**
+```
+Ask: "Get all key-value pairs under cloudview/config/"
+```
+
+**What happens:** The MCP server uses `get_key`, `list_keys`, `search_keys`, or `get_keys_recursive` to fetch data.
+
+---
+
+### 3. **UPDATE** - Modify Existing Configuration
+
+**Update a single value:**
+```
+Ask: "Update cloudview/config/timeout to 60"
+Ask: "Change the version in cloudview/gcp-service/application.yml to 2.8.0"
+```
+
+**Update entire file:**
+```
+Ask: "Update cloudview/config/database.yml with this content:
+host: db.example.com
+port: 5432
+username: dbuser"
+```
+
+**What happens:** The MCP server:
+1. Reads the current value (if needed)
+2. Modifies the specific field or replaces entire content
+3. Uses `put_key` to update the value in Consul
+
+---
+
+### 4. **DELETE** - Remove Configuration
+
+**Delete a single key:**
+```
+Ask: "Delete the key cloudview/config/deprecated-setting"
+```
+
+**Delete all keys under a prefix (recursive):**
+```
+Ask: "Delete all keys under cloudview/old-service/ recursively"
+```
+
+**What happens:** The MCP server uses `delete_key` with optional `recurse` parameter.
+
+---
+
+## Complete Example Workflow
+
+### Scenario: Managing a new microservice configuration
+
+**Step 1: Discover existing structure**
+```
+Ask: "List all keys under cloudview/"
+```
+
+**Step 2: Create new service configuration**
+```
+Ask: "Create cloudview/my-service/application.yml with:
+server:
+  port: 8080
+database:
+  url: jdbc:postgresql://localhost:5432/mydb"
+```
+
+**Step 3: Verify creation**
+```
+Ask: "Get the value of cloudview/my-service/application.yml"
+```
+
+**Step 4: Update a specific value**
+```
+Ask: "Update the port in cloudview/my-service/application.yml to 9090"
+```
+
+**Step 5: Add more configuration files**
+```
+Ask: "Create cloudview/my-service/kafka-client.yml with broker configs"
+```
+
+**Step 6: List all service configs**
+```
+Ask: "List all keys under cloudview/my-service/"
+```
+
+**Step 7: Clean up (if needed)**
+```
+Ask: "Delete cloudview/my-service/old-config.yml"
+```
+
+## Authentication
+
+This server uses **HTTP Basic Authentication** to connect to your Consul instance. The credentials are passed via environment variables:
+
+- Username and password are base64-encoded and sent in the `Authorization` header
+- Ensure your Consul instance is configured to accept Basic Auth
+- For production use, consider using ACL tokens instead of basic auth
+
+## Consul KV Hierarchy
+
+Consul KV uses a hierarchical key structure with `/` as the separator:
+
+```
+cloudview/
+  ├── config/
+  │   ├── database
+  │   ├── timeout
+  │   └── api-key
+  ├── features/
+  │   ├── feature-a
+  │   └── feature-b
+  └── metadata/
+      └── version
+```
+
+Keys are case-sensitive and can contain any UTF-8 characters.
+
+## Local Development
+
+1. Clone the repository
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. Create `.env` file:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your credentials
+   ```
+
+4. Run the server:
+   ```bash
+   npm start
+   ```
+
+## Testing the Server
+
+You can test the server locally using the MCP Inspector or by configuring it in Windsurf/Claude Desktop.
+
+### Example Commands
+
+```bash
+# List all keys
+curl -u username:password https://qconsul.p19.eng.sjc01.qualys.com/v1/kv/?keys=true
+
+# Get a specific key
+curl -u username:password https://qconsul.p19.eng.sjc01.qualys.com/v1/kv/cloudview/config/setting
+
+# Put a key
+curl -u username:password -X PUT -d "value" https://qconsul.p19.eng.sjc01.qualys.com/v1/kv/cloudview/config/setting
+
+# Delete a key
+curl -u username:password -X DELETE https://qconsul.p19.eng.sjc01.qualys.com/v1/kv/cloudview/config/setting
+```
+
+## Security Considerations
+
+- **Never commit credentials** - Use environment variables or secure secret management
+- **Use HTTPS** - Always connect to Consul over HTTPS in production
+- **ACL Tokens** - Consider using Consul ACL tokens instead of basic auth for production
+- **Least Privilege** - Grant only necessary permissions to the MCP server
+
+## Troubleshooting
+
+### Connection Issues
+- Verify `CONSUL_URL` is correct and accessible
+- Check that your credentials are valid
+- Ensure your network allows access to the Consul instance
+
+### Authentication Errors
+- Confirm username and password are correct
+- Check if Consul requires ACL tokens instead of basic auth
+
+### Key Not Found
+- Verify the key path is correct (case-sensitive)
+- Use `list_keys` to discover available keys
+- Check the datacenter parameter if using multiple datacenters
+
+## API Reference
+
+This server implements the Consul KV HTTP API:
+- [Consul KV Store API Documentation](https://developer.hashicorp.com/consul/api-docs/kv)
+- [Consul KV CLI Reference](https://developer.hashicorp.com/consul/commands/kv)
+
+## License
+
+MIT
+
+## Author
+
+Abhishek Bhadane
+
+## Package
+
+https://www.npmjs.com/package/@abhishek8380/qconsul-mcp-server
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
+
+For issues and questions:
+- GitHub Issues: [Create an issue](https://github.com/yourusername/qconsul-mcp-server/issues)
+- Documentation: [Consul KV Store](https://developer.hashicorp.com/consul/docs/automate/kv)

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@abhishek8380/qconsul-mcp-server",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "MCP server for Consul KV store operations (get, put, delete, list keys)",
+  "main": "server.js",
+  "bin": {
+    "qconsul-mcp": "./server.js"
+  },
+  "scripts": {
+    "start": "node server.js"
+  },
+  "keywords": [
+    "mcp",
+    "consul",
+    "qconsul",
+    "kv",
+    "key-value",
+    "stdio",
+    "model-context-protocol",
+    "windsurf",
+    "hashicorp"
+  ],
+  "author": "Abhishek Bhadane",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "node-fetch": "^3.3.2",
+    "dotenv": "^16.3.1",
+    "zod": "^3.22.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "server.js",
+    "README.md",
+    ".env.example"
+  ]
+}

package/server.js

@@ -0,0 +1,500 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import fetch from "node-fetch";
+import { z } from "zod";
+import dotenv from "dotenv";
+import https from "https";
+
+dotenv.config();
+
+const httpsAgent = new https.Agent({
+  rejectUnauthorized: false
+});
+
+const CONSUL_URL = process.env.CONSUL_URL
+const CONSUL_USERNAME = process.env.CONSUL_USERNAME
+const CONSUL_PASSWORD = process.env.CONSUL_PASSWORD
+const CONSUL_DATACENTER = process.env.CONSUL_DATACENTER;
+
+console.error(`🔐 Consul URL: ${CONSUL_URL}`);
+console.error(`🔐 Datacenter: ${CONSUL_DATACENTER}`);
+console.error(`🔐 Username: ${CONSUL_USERNAME}`);
+
+async function makeAuthenticatedRequest(url, options = {}) {
+  const authString = Buffer.from(`${CONSUL_USERNAME}:${CONSUL_PASSWORD}`).toString('base64');
+  
+  const defaultHeaders = {
+    "Accept": "application/json",
+    "Content-Type": "application/json",
+    "Authorization": `Basic ${authString}`,
+  };
+
+  const requestOptions = {
+    ...options,
+    agent: httpsAgent,
+    headers: {
+      ...defaultHeaders,
+      ...options.headers
+    }
+  };
+
+  const response = await fetch(url, requestOptions);
+  return response;
+}
+
+const server = new McpServer({
+  name: "qconsul-mcp-server",
+  version: "1.0.0",
+});
+
+const onboardingTip = [
+  "💡 QConsul (Consul KV) tip:",
+  "Use list_keys to discover available keys before reading or updating.",
+  "Keys are hierarchical (e.g., cloudview/config/setting)."
+].join("\n");
+
+console.error(onboardingTip);
+
+function registerQConsulTool(toolNames, config, handler) {
+  const names = Array.isArray(toolNames) ? toolNames : [toolNames];
+  names.forEach((toolName) => {
+    server.registerTool(toolName, { ...config }, handler);
+  });
+}
+
+registerQConsulTool([
+  "get_key",
+  "qconsul_get_key"
+],
+  {
+    title: "Get Consul KV Key",
+    description: "Retrieve a value from Consul KV store by key path",
+    inputSchema: z.object({
+      key: z.string().describe("The key path to retrieve (e.g., cloudview/config/setting)"),
+      raw: z.boolean().optional().default(false).describe("Return raw value without metadata (default: false)"),
+      datacenter: z.string().optional().describe("Datacenter to query (optional)")
+    }),
+  },
+  async ({ key, raw, datacenter }) => {
+    console.error(`📖 Getting key: ${key}`);
+
+    try {
+      const dc = datacenter || CONSUL_DATACENTER;
+      const rawParam = raw ? "&raw=true" : "";
+      const url = `${CONSUL_URL}/v1/kv/${key}?dc=${dc}${rawParam}`;
+      
+      const response = await makeAuthenticatedRequest(url);
+
+      if (response.status === 404) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `❌ Key not found: ${key}`,
+            },
+          ],
+        };
+      }
+
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+
+      if (raw) {
+        const rawValue = await response.text();
+        return {
+          content: [
+            {
+              type: "text",
+              text: rawValue,
+            },
+          ],
+        };
+      }
+
+      const data = await response.json();
+      const kvData = data[0];
+      
+      const decodedValue = kvData.Value ? Buffer.from(kvData.Value, 'base64').toString('utf-8') : null;
+
+      const keyInfo = {
+        key: kvData.Key,
+        value: decodedValue,
+        createIndex: kvData.CreateIndex,
+        modifyIndex: kvData.ModifyIndex,
+        lockIndex: kvData.LockIndex,
+        flags: kvData.Flags
+      };
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(keyInfo, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      console.error("❌ Error getting key:", error);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error getting key: ${error.message}`,
+          },
+        ],
+      };
+    }
+  }
+);
+
+registerQConsulTool([
+  "put_key",
+  "qconsul_put_key"
+],
+  {
+    title: "Put/Update Consul KV Key",
+    description: "Create or update a key-value pair in Consul KV store",
+    inputSchema: z.object({
+      key: z.string().describe("The key path to create/update (e.g., cloudview/config/setting)"),
+      value: z.string().describe("The value to store"),
+      datacenter: z.string().optional().describe("Datacenter to use (optional)"),
+      flags: z.number().optional().describe("Optional flags for the key (default: 0)")
+    }),
+  },
+  async ({ key, value, datacenter, flags }) => {
+    console.error(`✏️ Putting key: ${key}`);
+
+    try {
+      const dc = datacenter || CONSUL_DATACENTER;
+      const flagsParam = flags !== undefined ? `&flags=${flags}` : "";
+      const url = `${CONSUL_URL}/v1/kv/${key}?dc=${dc}${flagsParam}`;
+      
+      const response = await makeAuthenticatedRequest(url, {
+        method: "PUT",
+        body: value,
+        headers: {
+          "Content-Type": "text/plain"
+        }
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`HTTP error! status: ${response.status}, details: ${errorText}`);
+      }
+
+      const success = await response.json();
+
+      if (success) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `✅ Key updated successfully!\n\nKey: ${key}\nValue: ${value}\nDatacenter: ${dc}`,
+            },
+          ],
+        };
+      } else {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `⚠️ Key update returned false. This may indicate a CAS failure or other issue.`,
+            },
+          ],
+        };
+      }
+    } catch (error) {
+      console.error("❌ Error putting key:", error);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error putting key: ${error.message}`,
+          },
+        ],
+      };
+    }
+  }
+);
+
+registerQConsulTool([
+  "delete_key",
+  "qconsul_delete_key"
+],
+  {
+    title: "Delete Consul KV Key",
+    description: "Delete a key or keys from Consul KV store",
+    inputSchema: z.object({
+      key: z.string().describe("The key path to delete"),
+      recurse: z.boolean().optional().default(false).describe("Delete all keys with this prefix (default: false)"),
+      datacenter: z.string().optional().describe("Datacenter to use (optional)")
+    }),
+  },
+  async ({ key, recurse, datacenter }) => {
+    console.error(`🗑️ Deleting key: ${key}${recurse ? ' (recursive)' : ''}`);
+
+    try {
+      const dc = datacenter || CONSUL_DATACENTER;
+      const recurseParam = recurse ? "&recurse=true" : "";
+      const url = `${CONSUL_URL}/v1/kv/${key}?dc=${dc}${recurseParam}`;
+      
+      const response = await makeAuthenticatedRequest(url, {
+        method: "DELETE"
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+
+      const success = await response.json();
+
+      if (success) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `✅ Key deleted successfully!\n\nKey: ${key}${recurse ? '\nMode: Recursive (all keys with this prefix)' : ''}`,
+            },
+          ],
+        };
+      } else {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `⚠️ Key deletion returned false. Key may not exist.`,
+            },
+          ],
+        };
+      }
+    } catch (error) {
+      console.error("❌ Error deleting key:", error);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error deleting key: ${error.message}`,
+          },
+        ],
+      };
+    }
+  }
+);
+
+registerQConsulTool([
+  "list_keys",
+  "qconsul_list_keys"
+],
+  {
+    title: "List Consul KV Keys",
+    description: "List all keys under a prefix in Consul KV store",
+    inputSchema: z.object({
+      prefix: z.string().optional().default("").describe("Key prefix to list (empty for all keys)"),
+      separator: z.string().optional().describe("Separator for grouping keys (e.g., '/')"),
+      datacenter: z.string().optional().describe("Datacenter to query (optional)")
+    }),
+  },
+  async ({ prefix, separator, datacenter }) => {
+    console.error(`📋 Listing keys with prefix: ${prefix || '(all)'}`);
+
+    try {
+      const dc = datacenter || CONSUL_DATACENTER;
+      const separatorParam = separator ? `&separator=${encodeURIComponent(separator)}` : "";
+      const url = `${CONSUL_URL}/v1/kv/${prefix}?dc=${dc}&keys=true${separatorParam}`;
+      
+      const response = await makeAuthenticatedRequest(url);
+
+      if (response.status === 404) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No keys found with prefix: ${prefix || '(root)'}`,
+            },
+          ],
+        };
+      }
+
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+
+      const keys = await response.json();
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Found ${keys.length} key(s)${prefix ? ` with prefix "${prefix}"` : ''}:\n\n${JSON.stringify(keys, null, 2)}`,
+          },
+        ],
+      };
+    } catch (error) {
+      console.error("❌ Error listing keys:", error);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error listing keys: ${error.message}`,
+          },
+        ],
+      };
+    }
+  }
+);
+
+registerQConsulTool([
+  "get_keys_recursive",
+  "qconsul_get_keys_recursive"
+],
+  {
+    title: "Get All Keys and Values Recursively",
+    description: "Retrieve all key-value pairs under a prefix (recursive)",
+    inputSchema: z.object({
+      prefix: z.string().optional().default("").describe("Key prefix to retrieve (empty for all keys)"),
+      datacenter: z.string().optional().describe("Datacenter to query (optional)")
+    }),
+  },
+  async ({ prefix, datacenter }) => {
+    console.error(`📦 Getting all keys recursively with prefix: ${prefix || '(all)'}`);
+
+    try {
+      const dc = datacenter || CONSUL_DATACENTER;
+      const url = `${CONSUL_URL}/v1/kv/${prefix}?dc=${dc}&recurse=true`;
+      
+      const response = await makeAuthenticatedRequest(url);
+
+      if (response.status === 404) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No keys found with prefix: ${prefix || '(root)'}`,
+            },
+          ],
+        };
+      }
+
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+
+      const data = await response.json();
+      
+      const kvPairs = data.map(item => ({
+        key: item.Key,
+        value: item.Value ? Buffer.from(item.Value, 'base64').toString('utf-8') : null,
+        createIndex: item.CreateIndex,
+        modifyIndex: item.ModifyIndex,
+        flags: item.Flags
+      }));
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Found ${kvPairs.length} key-value pair(s)${prefix ? ` with prefix "${prefix}"` : ''}:\n\n${JSON.stringify(kvPairs, null, 2)}`,
+          },
+        ],
+      };
+    } catch (error) {
+      console.error("❌ Error getting keys recursively:", error);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error getting keys recursively: ${error.message}`,
+          },
+        ],
+      };
+    }
+  }
+);
+
+registerQConsulTool([
+  "search_keys",
+  "qconsul_search_keys"
+],
+  {
+    title: "Search Consul KV Keys",
+    description: "Search for keys matching a pattern in Consul KV store",
+    inputSchema: z.object({
+      searchTerm: z.string().describe("Search term to find in key names"),
+      prefix: z.string().optional().default("").describe("Optional prefix to narrow search scope"),
+      datacenter: z.string().optional().describe("Datacenter to query (optional)")
+    }),
+  },
+  async ({ searchTerm, prefix, datacenter }) => {
+    console.error(`🔍 Searching for keys matching: ${searchTerm}`);
+
+    try {
+      const dc = datacenter || CONSUL_DATACENTER;
+      const url = `${CONSUL_URL}/v1/kv/${prefix}?dc=${dc}&keys=true`;
+      
+      const response = await makeAuthenticatedRequest(url);
+
+      if (response.status === 404) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No keys found`,
+            },
+          ],
+        };
+      }
+
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+
+      const allKeys = await response.json();
+      
+      const searchLower = searchTerm.toLowerCase();
+      const matchingKeys = allKeys.filter(key => 
+        key.toLowerCase().includes(searchLower)
+      );
+
+      if (matchingKeys.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No keys found matching "${searchTerm}"`,
+            },
+          ],
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Found ${matchingKeys.length} key(s) matching "${searchTerm}":\n\n${JSON.stringify(matchingKeys, null, 2)}`,
+          },
+        ],
+      };
+    } catch (error) {
+      console.error("❌ Error searching keys:", error);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error searching keys: ${error.message}`,
+          },
+        ],
+      };
+    }
+  }
+);
+
+console.error("🚀 Starting QConsul MCP Server");
+console.error(`🚀 Consul URL: ${CONSUL_URL}`);
+console.error(`🔐 Authenticated as: ${CONSUL_USERNAME}`);
+console.error(`🌍 Default Datacenter: ${CONSUL_DATACENTER}`);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);